xAI SDK e Polling Automático
Nesta página
Atualizado em 2 de novembro de 2026 com base na documentação de vídeo da xAI e no código
xai-sdk1.21.0: os métodos chamam-seclient.video.generateeclient.video.extend(a edição usageneratecomvideo_url), o resultado expõeurl, o atraso define-se viatimedeltae o intervalo de polling padrão é de um segundo. Oawaitrequer o cliente assíncronoAsyncClient, e a exceçãoVideoGenerationErrorimporta-se dexai_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.
| Erro | Causa | Ação recomendada |
|---|---|---|
VideoGenerationError | Falha 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 |
TimeoutError | Tempo de espera do lado do cliente excedido | Aumente o timeout ou reduza a duração |
RuntimeError | Pedido diferido expirou ou concluído sem resultado | Reinicie a geração |
grpc.RpcError | Erro de transporte do SDK, incluindo limites de taxa (código RESOURCE_EXHAUSTED) e problemas de chave | Espace 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.
| Aspeto | Polling manual | SDK |
|---|---|---|
| Complexidade | Elevada | Baixa |
| Tratamento de erros | A implementar | Integrado |
| Tempo limite | A implementar | 10 min padrão, configurável |
| Intervalo de polling | A escolher | 1 s padrão, configurável |
| Flexibilidade | Total | Padrão (ou start e get) |
| Dependência | Nenhuma | xAI 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.generatesubmete, 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
generatecomvideo_url, a extensão usaclient.video.extend VideoGenerationError(dexai_sdk.video),TimeoutErroreRuntimeErrordistinguem as falhas; os limites de taxa chegam comogrpc.RpcError- Transfira sempre o vídeo imediatamente após a geração (URLs temporários)
- O cliente assíncrono e
asyncio.gatherparalelizam um lote, dentro do limite de taxa do seu nível