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

Gestão de Erros e Implementação em Produção

Aula 12 de 12 Atualizada a 3 de novembro de 2026 Intermediario
Nesta página
  1. Prepare a Sua Aplicação para Produção
  2. Duas Famílias de Erros, Dois Momentos
  3. Tente Novamente com Inteligência
  4. Uma Fila para Manter o Ritmo
  5. Verifique a Sua Chave Antes de Depender Dela
  6. Veja o Que Acontece em Produção
  7. Pontos-chave
  8. Teste os Seus Conhecimentos

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: client.video.generate (não client.videos), resultado em url, falhas reportadas por VideoGenerationError com um código (invalid_argument, service_unavailable…), limite de taxa recebido como grpc.RpcError com código RESOURCE_EXHAUSTED — a classe RateLimitError e o estado expired não existem. Complemento de 3 de novembro de 2026: o limite de taxa conta pedidos por segundo (10 no nível de entrada), não “60 RPM”, e o custo real por geração é lido em usage.cost_in_usd_ticks. Fontes: Geração de Vídeo · Limites de taxa.

Prepare a Sua Aplicação para Produção

Um script que gera um vídeo na sua máquina e um serviço que produz centenas por dia para utilizadores reais não têm quase nada em comum. Este último deve lidar com recusas de moderação, excedentes de quota, incidentes de servidor e URLs expirados sem nunca perder silenciosamente uma geração faturada. Esta lição abrange os mecanismos que fazem a diferença: classificação de erros, estratégia de novas tentativas, arquitetura de filas e observabilidade.

Duas Famílias de Erros, Dois Momentos

A primeira família surge imediatamente, no momento da chamada POST. Estes são erros estritos de pedido, e o código HTTP é suficiente para decidir o que fazer.

Código HTTPCausaSolução
400Parâmetros inválidos (por exemplo, uma voz desconhecida em reference_audios)Corrija o pedido
401Chave de API inválida ou expiradaVerifique a autenticação
429Limite de taxa excedido (pedidos por segundo, dependendo do nível)Implemente backoff
500Erro de servidorTente novamente com backoff exponencial

A segunda família manifesta-se muito mais tarde, durante o polling, depois de o pedido ter sido aceite e a geração ter começado.

EstadoCausa ProvávelAção
failed + invalid_argument ou permission_deniedPedido ou conteúdo recusadoModifique o prompt ou a origem
failed + service_unavailable ou internal_errorServiço sobrecarregado, incidenteTente novamente mais tarde

Esta distinção não é académica: um 400 deve retornar instantaneamente ao chamador porque o erro está no código, enquanto um estado failed ocorre após vários minutos de espera e deve ser tratado no contexto da tarefa (job), não no pedido HTTP que o desencadeou.

Tente Novamente com Inteligência

A base comum é o backoff exponencial com algum jitter (variação aleatória). Dobrar o atraso dá tempo a um incidente transitório para se resolver, e o jitter impede que todos os seus processos tentem novamente no mesmo instante após um pico — um fenómeno que transforma uma microinterrupção numa falha duradoura.

import asyncio
import random

async def call_with_retry(func, max_retries=3, base_delay=2):
    """Executa uma função com novas tentativas e backoff exponencial."""
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                raise

            # Backoff exponencial com jitter
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"Tentativa {attempt + 1} falhou: {e}. Nova tentativa em {delay:.1f}s")
            await asyncio.sleep(delay)

Este esquema genérico não é suficiente, contudo, porque nem todos os erros merecem a mesma paciência. Um excedente de quota resolve-se esperando um minuto inteiro; uma recusa de moderação nunca se resolverá, e tentar novamente equivale a pagar várias vezes pela mesma falha. A função seguinte diferencia os casos.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Códigos de falha que uma nova tentativa não resolverá
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}


async def generate_with_retry(client, params, max_retries=3):
    """Geração de vídeo com novas tentativas direcionadas (client: xai_sdk.AsyncClient)."""
    for attempt in range(max_retries + 1):
        is_last = attempt == max_retries
        try:
            return await client.video.generate(**params)
        except VideoGenerationError as e:
            if e.code.lower() in REQUIRES_FIX or is_last:
                raise  # pedido ou conteúdo recusado: corrija antes de relançar
            await asyncio.sleep(5 * (attempt + 1))  # serviço sobrecarregado, incidente
        except grpc.RpcError as e:
            if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
                raise
            await asyncio.sleep(2 ** attempt)  # limite de taxa: backoff
        except TimeoutError:
            if is_last:
                raise
            # Permita mais tempo para a próxima tentativa
            params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)

Uma Fila para Manter o Ritmo

Assim que o seu serviço receber pedidos de múltiplos utilizadores, deve desacoplar a receção do pedido da sua execução e, acima de tudo, limitar a concorrência para se manter abaixo do limite de taxa do seu nível. Uma fila emparelhada com um semáforo satisfaz ambas as necessidades: as tarefas acumulam-se livremente, mas apenas dez, no máximo, são executadas de cada vez.

import asyncio
from collections import deque

class VideoGenerationQueue:
    def __init__(self, client, max_concurrent=10):
        self.client = client
        self.queue = deque()
        self.semaphore = asyncio.Semaphore(max_concurrent)
        self.results = {}

    async def add(self, job_id, params):
        """Adiciona uma geração à fila."""
        self.queue.append((job_id, params))

    async def process(self):
        """Processa todas as gerações pendentes."""
        tasks = []
        while self.queue:
            job_id, params = self.queue.popleft()
            task = asyncio.create_task(
                self._execute(job_id, params)
            )
            tasks.append(task)
        await asyncio.gather(*tasks, return_exceptions=True)

    async def _execute(self, job_id, params):
        """Executa uma geração com controlo de concorrência."""
        async with self.semaphore:
            try:
                result = await generate_with_retry(
                    self.client, params
                )
                self.results[job_id] = {
                    "status": "done",
                    "url": result.url
                }
            except Exception as e:
                self.results[job_id] = {
                    "status": "failed",
                    "error": str(e)
                }

Note que cada tarefa mantém o seu resultado em results, sucesso ou falha: uma geração que desaparece sem deixar rasto é um incidente que ninguém consegue diagnosticar.

O segundo reflexo de arquitetura diz respeito ao armazenamento. Como os URLs de vídeo são temporários, o download deve ser automático e imediato, com uma nomeação carimbada com data e hora que garanta que não há colisão entre duas gerações simultâneas.

import httpx
from pathlib import Path
from datetime import datetime

async def save_video(video_url, output_dir="./videos"):
    """Descarrega e guarda um vídeo gerado."""
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    file_path = f"{output_dir}/video_{timestamp}.mp4"

    async with httpx.AsyncClient() as client:
        resp = await client.get(video_url)
        resp.raise_for_status()
        Path(file_path).write_bytes(resp.content)

    return file_path

Verifique a Sua Chave Antes de Depender Dela

O endpoint GET /v1/api-key informa-o sobre o estado da sua chave. Chamá-lo no arranque do serviço evita descobrir uma chave bloqueada após vinte pedidos falhados, enquanto os seus utilizadores esperam.

resp = httpx.get(
    "https://api.x.ai/v1/api-key",
    headers={"Authorization": f"Bearer {api_key}"}
).json()

if resp.get("api_key_blocked") or resp.get("api_key_disabled") or resp.get("team_blocked"):
    raise RuntimeError("Chave de API ou equipa bloqueada, ou chave desativada")

Veja o Que Acontece em Produção

Cinco indicadores são suficientes para pilotar um serviço de geração de vídeo. A taxa de sucesso, ou seja, a percentagem de gerações que terminam em done, mede a saúde geral. O tempo médio de geração, medido entre o envio e o estado done, serve para calibrar os seus tempos limite e informar os seus utilizadores. A taxa de erro desagregada por tipo — failed por código de erro, tempo limite, limite de taxa — indica onde focar esforços: um aumento nos tempos limite sem um aumento em failed sinaliza gerações mais lentas do que o seu prazo de espera, por exemplo, e não falhas. O custo cumulativo, obtido somando o campo usage.cost_in_usd_ticks de cada resultado (um dólar equivale a 10 mil milhões de ticks), ou alternativamente multiplicando as durações geradas pelo preço do modelo por segundo, deve ser monitorizado diariamente. Finalmente, a utilização da quota, em pedidos por segundo relativamente ao limite do seu nível (10 no nível de entrada para modelos de vídeo), antecipa a saturação antes que esta se traduza em erros 429.

Estas métricas constroem-se naturalmente a partir de um registo estruturado, onde cada geração deixa uma linha utilizável pela sua ferramenta de análise.

import logging
import json

logger = logging.getLogger("video-generation")

def log_generation(request_id, status, duration_s, cost, time_ms):
    logger.info(json.dumps({
        "event": "video_generation",
        "request_id": request_id,
        "status": status,
        "duration_seconds": duration_s,
        "cost_usd": cost,
        "processing_time_ms": time_ms
    }))

Antes de abrir o seu serviço ao público, reveja tudo desde o início. As novas tentativas com backoff exponencial e jitter devem estar implementadas, e a concorrência limitada por um semáforo para se manter abaixo do limite de taxa. Os downloads de vídeo devem ser acionados automaticamente assim que estiverem prontos, sem depender de ação humana. Cada geração deve deixar uma linha de registo contendo o seu request_id, estado e custo; caso contrário, a taxa de erro e o tempo médio de geração permanecerão inverificáveis. Verifique o estado da chave de API no arranque em vez de aguardar a primeira falha. E defina um orçamento com alertas de excedente: a 0,05 $ por segundo, um ciclo de novas tentativas ilimitado consome recursos mais depressa do que imagina.

Preços verificados em 3 de novembro de 2026 — os preços evoluem regularmente: antes de qualquer cálculo de orçamento, verifique a grelha atual na página oficial de modelos e preços da xAI.

Pontos-chave

  • Os erros dividem-se em síncronos (pedido) e assíncronos (geração)
  • Nem todos os erros merecem uma nova tentativa: a moderação é definitiva
  • Utilize um semáforo para limitar gerações concorrentes
  • URLs temporários exigem download imediato e sistemático
  • Acompanhe métricas de custo, sucesso e tempo de geração para pilotar o seu serviço

Teste os Seus Conhecimentos

Vídeo generativo em produção: valide o fluxo de trabalho completo.

1. Quais são as particularidades de um prompt de vídeo?

Resposta: Descreva a ação e o movimento, não apenas a cena: sujeito, deslocamento, ambiente, enquadramento — a dimensão temporal é o que distingue o prompt de vídeo do prompt de imagem.

2. O que permite a funcionalidade imagem-para-vídeo?

Resposta: Animar uma imagem existente ou trazer pessoas e produtos específicos para uma nova cena utilizando imagens de referência — e, no grok-imagine-video-1.5, fixar a primeira, a última ou imagens-chave: a sua identidade visual torna-se um ponto de partida, não um acaso.

3. Edição e extensão: quais as utilizações?

Resposta: /videos/edits modifica um vídeo gerado, /videos/extensions prolonga-o — e ambos combinam-se para construir sequências longas por iterações.

4. Por que razão o fluxo de trabalho é assíncrono?

Resposta: A geração de vídeo demora tempo: submete uma tarefa, consulta o seu estado e, depois, recupera o resultado — o SDK da xAI automatiza esta consulta (polling).

5. O que planear para produção?

Resposta: Gestão de erros e tarefas falhadas, download imediato dos resultados e acompanhamento de custos (resolução, duração, iterações) — o vídeo é a modalidade mais dispendiosa: deve ser orçamentada.

Prompt temporal, referência visual, assincronia dominada: o vídeo generativo torna-se um pipeline — não uma lotaria.