Ir para o conteúdo principal
Português— Escolher um idioma
Menu

xAI SDK e Polling Automático

Aula 11 de 12 Atualizada a 2 de novembro de 2026 Intermediario
Nesta página
  1. Simplifique o polling com o SDK
  2. Uma única chamada em vez de um ciclo
  3. Trate os erros na origem
  4. Edição e extensão, com a mesma facilidade
  5. Nunca deixe um vídeo na nuvem
  6. Gere múltiplos vídeos de uma vez
  7. Deve abandonar o polling manual?
  8. Pontos-chave

Atualizado em 2 de novembro de 2026 com base na documentação de vídeo da xAI e no código xai-sdk 1.21.0: os métodos chamam-se client.video.generate e client.video.extend (a edição usa generate com video_url), o resultado expõe url, o atraso define-se via timedelta e o intervalo de polling padrão é de um segundo. O await requer o cliente assíncrono AsyncClient, e a exceção VideoGenerationError importa-se de xai_sdk.video. A versão antiga invocava métodos e um módulo de exceções que não existem. Fontes: Geração de Vídeo · Edição de Vídeo · Extensão de Vídeo · xai-sdk-python.

Simplifique o polling com o SDK

A lição anterior pediu-lhe para escrever um ciclo de polling manualmente. É um exercício útil para compreender o ciclo de vida da geração, mas são também trinta linhas de código para manter em cada projeto, com o seu próprio tratamento de tempos limite, casos de falha e conversões de estado. O SDK oficial de Python da xAI (pip install xai-sdk) encapsula tudo isto: submete o pedido e gere a espera por si.

Uma única chamada em vez de um ciclo

O método client.video.generate agrupa o envio, o rastreio e a recuperação. Só devolve o controlo quando o vídeo está pronto ou lança uma exceção se algo correr mal.

import os

import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Geração de texto para vídeo com polling automático
video = client.video.generate(
    prompt="Um nascer do sol sobre os Alpes, time-lapse acelerado",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(video.url)
print(f"Duração: {video.duration} s, modelo: {video.model}")

Por detrás destas poucas linhas, o SDK faz exatamente o que codificou anteriormente: submete o pedido, verifica o estado a cada segundo por padrão e, em seguida, devolve o resultado ou lança uma exceção dependendo do desfecho.

Uma definição merece a sua atenção desde a implementação: por padrão, o SDK espera até 10 minutos antes de desistir. Isso é confortável para um script de produção noturno, mas demasiado longo para um pedido web onde um utilizador aguarda uma resposta. Os parâmetros timeout e interval, ambos objetos timedelta, definem o limite e o ritmo:

from datetime import timedelta

video = client.video.generate(
    prompt="A sua descrição",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # máx. 5 minutos
    interval=timedelta(seconds=5),  # uma verificação a cada 5 segundos
)

Se quiser manter o controlo sobre a espera — para retransmitir o progresso, por exemplo —, client.video.start submete o pedido e devolve o seu request_id, que o client.video.get consulta posteriormente.

Trate os erros na origem

O SDK distingue as falhas, poupando-o a analisar cadeias de caracteres para descobrir o que aconteceu:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="A sua descrição",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Vídeo pronto: {video.url}")
except VideoGenerationError as e:
    print(f"Geração falhou [{e.code}]: {e.message}")
except TimeoutError:
    print("Tempo limite excedido: aumente o timeout ou simplifique o pedido")

Cada erro exige uma reação diferente; confundi-los leva a ciclos de repetição inúteis ou, pior, a gerações faturadas que não produzem nada.

ErroCausaAção recomendada
VideoGenerationErrorFalha sinalizada pela API: prompt recusado, origem inválida, serviço sobrecarregado… (code, message)Leia o código: corrija o pedido ou tente novamente mais tarde se o serviço estiver indisponível
TimeoutErrorTempo de espera do lado do cliente excedidoAumente o timeout ou reduza a duração
RuntimeErrorPedido diferido expirou ou concluído sem resultadoReinicie a geração
grpc.RpcErrorErro de transporte do SDK, incluindo limites de taxa (código RESOURCE_EXHAUSTED) e problemas de chaveEspace os pedidos com backoff ou verifique a chave

O SDK utiliza gRPC: um limite de taxa excedido não aparece aqui como um código HTTP 429, mas como um grpc.RpcError com o código RESOURCE_EXHAUSTED.

Edição e extensão, com a mesma facilidade

A edição não tem um método dedicado: usa-se generate com um vídeo de origem, passado como video_url (vídeo até 8,7 segundos, mesma duração de saída, máx. 720p).

video = client.video.generate(
    prompt="Transforme a cena num estilo de anime japonês",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

A extensão prolonga uma sequência de 2 a 15 segundos com um segmento de 2 a 10 segundos e devolve o vídeo completo:

video = client.video.extend(
    prompt="Continue a cena com um movimento de câmara para a direita",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Note a diferença face à API REST: o SDK aceita o vídeo como parâmetro video_url, enquanto o corpo JSON espera um objeto video com a sua propriedade url.

Nunca deixe um vídeo na nuvem

O SDK não altera nada quanto à natureza temporária dos URLs de resultado. Se o seu código apenas apresentar video.url, pagou por uma geração que desaparecerá em breve. A melhor prática é encadear a geração e a transferência na mesma função, tornando assim impossível esquecer essa etapa.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Gera um vídeo e guarda-o localmente (client: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Transferência imediata
    async with httpx.AsyncClient() as http:
        response = await http.get(video.url)
        response.raise_for_status()
        Path(output_file).write_bytes(response.content)

    print(f"Vídeo guardado: {output_file}")
    return output_file

Para armazenamento sem trânsito pelo seu servidor, o parâmetro storage_options da geração deposita o vídeo na API de Ficheiros da xAI, com uma expiração à sua escolha.

Gere múltiplos vídeos de uma vez

Com o cliente assíncrono, cada chamada é uma corrotina, e asyncio.gather lança todo um lote em paralelo. A opção return_exceptions=True é decisiva aqui: sem ela, um único pedido recusado faria falhar todo o lote e perderia os resultados já obtidos.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Gera múltiplos vídeos em paralelo."""
    client = xai_sdk.AsyncClient(api_key=os.getenv("XAI_API_KEY"))
    tasks = [
        client.video.generate(
            prompt=req["prompt"],
            model="grok-imagine-video-1.5",
            duration=req.get("duration", 5),
            aspect_ratio=req.get("aspect_ratio", "16:9"),
        )
        for req in requests
    ]

    results = await asyncio.gather(*tasks, return_exceptions=True)

    for i, res in enumerate(results, 1):
        if isinstance(res, Exception):
            print(f"Pedido {i} falhou: {res}")
        else:
            print(f"Pedido {i} concluído: {res.url}")

    return results

Duas salvaguardas enquadram esta paralelização. Os envios consomem o seu limite de taxa, contado em pedidos por segundo de acordo com o nível da sua equipa (10 no nível de entrada para modelos de vídeo): para um lote grande, limite a concorrência com um asyncio.Semaphore. Lembre-se também do que o paralelismo faz e não faz: não acelera nenhuma geração individual, apenas reduz o tempo total do lote.

Deve abandonar o polling manual?

Não sistematicamente. A comparação seguinte mostra onde cada abordagem se destaca.

AspetoPolling manualSDK
ComplexidadeElevadaBaixa
Tratamento de errosA implementarIntegrado
Tempo limiteA implementar10 min padrão, configurável
Intervalo de pollingA escolher1 s padrão, configurável
FlexibilidadeTotalPadrão (ou start e get)
DependênciaNenhumaxAI SDK

O polling manual mantém a sua relevância em duas situações: quando necessita de um controlo fino, por exemplo, para retransmitir o progresso para uma interface em tempo real ou para integrar num sistema de filas existente, e quando o seu contexto de implementação proíbe adicionar uma dependência extra.

Pontos-chave

  • client.video.generate submete, espera e devolve o vídeo (url, duration, model); tempo limite de 10 minutos e verificação de um segundo por padrão
  • A edição usa generate com video_url, a extensão usa client.video.extend
  • VideoGenerationError (de xai_sdk.video), TimeoutError e RuntimeError distinguem as falhas; os limites de taxa chegam como grpc.RpcError
  • Transfira sempre o vídeo imediatamente após a geração (URLs temporários)
  • O cliente assíncrono e asyncio.gather paralelizam um lote, dentro do limite de taxa do seu nível