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

Fluxo assíncrono e polling

Aula 10 de 12 Atualizada a 2 de novembro de 2026 Intermediario
Nesta página
  1. Compreender o ciclo de vida do vídeo
  2. Verificar o estado da geração
  3. Três estados, três ações
  4. Implementar polling
  5. Definir o intervalo de polling
  6. Pontos-chave

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ão video_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.

1

Submeter pedido

POST para o endpoint de geração, edição ou extensão. Resposta imediata com um request_id.

2

Polling de estado

GET /v1/videos/{request_id} em intervalos regulares. Campo progress de 0 a 100.

3

Recuperar resultado

Quando o estado for done (progress = 100), o URL do vídeo está disponível.

4

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 video presente 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_unavailable ou internal_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

StatusProgressSignificado
pending0-99Geração em curso
done100Concluído, URL disponível
failedausenteGeraçã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