Fluxo assíncrono e polling
Nesta página
Atualizado em 2 de novembro de 2026. Com base na referência da API de Vídeo da xAI: o URL encontra-se em
video.url(e nãovideo_url), uma geração possui apenas três estados (pending,done,failed, sendo o último acompanhado de um código de erro), e os limites de taxa são expressos em pedidos por segundo com base no nível da equipa. Fontes: Geração de Vídeo · Referência de Vídeos · Limites de taxa.
Compreender o ciclo de vida do vídeo
Todas as operações de vídeo na API da xAI são assíncronas, e esta característica molda a arquitetura da sua aplicação mais do que poderia esperar à primeira vista. Uma chamada de chat ou geração de imagem devolve um resultado imediatamente; a geração de vídeo, no entanto, requer um tempo de processamento significativo e retorna apenas um reconhecimento. Cabe-lhe implementar o acompanhamento: consultar periodicamente o estado da tarefa, detetar a conclusão e recuperar o ficheiro. O ciclo completo consiste em quatro passos.
Submeter pedido
POST para o endpoint de geração, edição ou extensão. Resposta imediata com um request_id.
Polling de estado
GET /v1/videos/{request_id} em intervalos regulares. Campo progress de 0 a 100.
Recuperar resultado
Quando o estado for done (progress = 100), o URL do vídeo está disponível.
Descarregar imediatamente
O URL do vídeo é temporário. Descarregue-o o mais rápido possível.
Verificar o estado da geração
O acompanhamento envolve um simples pedido GET ao endpoint de estado, utilizando o identificador recebido no momento da submissão.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
A resposta expõe as seguintes informações úteis:
- status : o estado atual da geração
- progress : um inteiro de 0 a 100 que indica o progresso
- video.url : o URL do vídeo, dentro do objeto
videopresente quando o estado édone, com a sua duração (video.duration) - video.respect_moderation : um booleano que indica se o conteúdo cumpre a política de moderação
- error : em caso de falha, um código (
invalid_argument,permission_denied,failed_precondition,service_unavailableouinternal_error) e uma mensagem - usage.cost_in_usd_ticks : o custo do pedido, em décimos de mil milionésimos de dólar
O campo progress merece uma nota: não conduz a sua lógica de controlo, que deve depender sempre do status, mas é ouro para uma interface de utilizador. Exibir «62%» em vez de um spinner estático muda completamente a perceção de uma espera que pode durar vários minutos.
Três estados, três ações
| Status | Progress | Significado |
|---|---|---|
pending | 0-99 | Geração em curso |
done | 100 | Concluído, URL disponível |
failed | ausente | Geração falhada |
Enquanto o estado for pending, a geração continua: basta continuar a consultar em intervalos regulares, retransmitindo o progress para a sua interface. Quando mudar para done, o vídeo está pronto, e a única coisa a fazer é ler video.url e descarregar o ficheiro imediatamente — estes URLs são temporários e a documentação não especifica a sua vida útil, o que proíbe armazená-los numa base de dados para uso posterior.
Finalmente, o estado failed indica uma falha de produção, e o campo error diz-lhe qual. A distinção importa para o que se segue: service_unavailable (serviço temporariamente sobrecarregado) ou internal_error justificam tentar novamente mais tarde, enquanto invalid_argument ou permission_denied — prompt rejeitado, imagem ou vídeo de origem inválidos — exigem corrigir o pedido primeiro. O SDK Python, por sua vez, também sinaliza através de um erro um pedido diferido que expirou antes de ser recuperado.
Implementar polling
A versão síncrona cabe numa única função. Faz um loop até ao timeout, sai antecipadamente em caso de falha levantando o seu código e devolve o URL assim que o vídeo estiver pronto.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Wait for video generation completion."""
headers = {"Authorization": f"Bearer {api_key}"}
debut = time.time()
while time.time() - debut < timeout:
resp = httpx.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
).json()
status = resp.get("status")
progress = resp.get("progress", 0)
if status == "done":
return resp["video"]["url"]
elif status == "failed":
erreur = resp.get("error", {})
raise RuntimeError(f"Generation failed [{erreur.get('code')}] : {erreur.get('message')}")
print(f"In progress... {progress}%")
time.sleep(intervalle)
raise TimeoutError(f"Timeout after {timeout} seconds")
Num serviço que gere múltiplos pedidos simultaneamente, esta versão bloqueante torna-se um gargalo: cada espera imobiliza um thread durante minutos. A transposição assíncrona liberta o event loop entre consultas e permite acompanhar dezenas de gerações em paralelo.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Asynchronous version of polling."""
headers = {"Authorization": f"Bearer {api_key}"}
async with httpx.AsyncClient() as client:
debut = asyncio.get_event_loop().time()
while asyncio.get_event_loop().time() - debut < timeout:
resp = await client.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
)
data = resp.json()
if data["status"] == "done":
return data["video"]["url"]
elif data["status"] == "failed":
raise RuntimeError(f"Generation failed : {data.get('error')}")
await asyncio.sleep(intervalle)
raise TimeoutError("Timeout")
Definir o intervalo de polling
Escolher o intervalo equilibra a responsividade contra pedidos desperdiçados. Cinco segundos é um bom compromisso na maioria dos casos. Para gerações longas — dez a quinze segundos de vídeo — dez a quinze segundos entre polls é suficiente e reduz o tráfego. Por outro lado, uma aplicação interativa onde o utilizador observa uma barra de progresso justifica descer para dois ou três segundos. Abaixo de um segundo, no entanto, não vai acelerar nada: a geração prossegue ao seu próprio ritmo, e apenas multiplica pedidos inutilmente.
Pontos-chave
- Todas as operações de vídeo são assíncronas: POST para submeter, GET para recuperar
- Três estados possíveis: pending, done, failed (com um código de erro)
- O campo
progress(0-100) permite acompanhar o avanço - Implemente um timeout e um intervalo de polling adequados ao seu caso de uso
- Os URLs de vídeo são temporários: descarregue imediatamente