Prática com a API do Grok-Video-3: tudo o que você precisa saber sobre o motor de vídeo da xAI
Modelos alvo:
grok-video-1.5,grok-video-1.0
Endpoint de inferência:https://api.toapis.com/v1/videos/generations
Relacionado: Acesso compatível com OpenAI · API do canal oficial do Grok Imagine · Guia de vídeo do Hailuo 2.3 · Referência do Grok Video 1.5
1. Resumo e visão geral de desempenho
- Primeiro o catálogo: pedidos de uma integração prática do Grok Video 3 também precisam partir dos IDs que a ToAPIs realmente publica. A captura pública do catálogo de produção datada de 2026-11-10 lista
grok-video-1.0egrok-video-1.5no endpointopenai-video. Uma verificação de 2026-11-17 nas URLs de documentação e de guia de modelo dogrok-video-3retornou HTTP 404. - Contrato: envie de forma assíncrona para
POST /v1/videos/generationse depois consulteGET /v1/videos/generations/{id}atécompletedoufailed. Os exemplos oficiais usamhttps://toapis.com(ehttps://toapis.cnpara a China continental). Outros guias desta série usamhttps://api.toapis.com. Escolha uma origem e mantenha a coerência. - Modos:
grok-video-1.5documentatext_to_video,first_frame_image_to_videoereference_images_to_video. Definavideo_generation_modeexplicitamente para que uma única imagem de referência não seja tratada como tarefa legada de primeiro quadro. - Mídia: envie apenas URLs públicas
http://ouhttps://. Envie arquivos locais comPOST /v1/uploads/imagese use odata.urldevolvido. Não envie base64. - Afirmações não verificadas a descartar: rascunhos de planejamento que citam um ID
grok-video-3, um SLA de 99,95 %, uma tarifa fixa de$0.030–$0.038por segundo ou uma data futura de lançamento de áudio não são documentação atual da ToAPIs. Confirme as tarifas vigentes e o suporte do canal na sua conta.
2. IDs atuais do Grok Video e modos de geração
Use o nome público do modelo no campo model. Não substitua por um nome nativo do fornecedor, um slug de URL nem uma string grok-video-3 não publicada.
| ID de catálogo | Tarefas documentadas | Duração (docs) | Resolução | Entradas de imagem |
|---|---|---|---|---|
grok-video-1.5 | Texto, primeiro quadro ou 1 a 7 imagens de referência, selecionados com video_generation_mode | Inteiro de 1–15 segundos | 480p ou 720p no modo de referência; texto e primeiro quadro podem usar 1080p quando o canal aceitar | Primeiro quadro: exatamente um image ou input_reference. Modo de referência: 1 a 7 reference_images |
grok-video-1.0 | Texto para vídeo e imagem para vídeo | Referência de geração: 1–15 segundos (padrão 8). Guia de modelo / playground: teto de 6 segundos na variante disponível atualmente | 480p, 720p | image opcional mais reference_images; até 8 imagens no total |
Para grok-video-1.5, integrações novas devem definir o modo explicitamente:
video_generation_mode | Entrada obrigatória | O que deve ser omitido |
|---|---|---|
text_to_video | prompt não vazio | Qualquer campo de imagem |
first_frame_image_to_video | Exatamente um primeiro quadro em image ou input_reference | Valores conflitantes nos dois aliases; também não envie uma lista de referências salvo que a referência da sua conta diga o contrário |
reference_images_to_video | prompt mais 1 a 7 reference_images (strings ou objetos {"url":"..."}) | Depender de uma única entrada de reference_images sem este modo: a entrada legada de uma só imagem continua sendo comportamento de primeiro quadro |
Uma cotação de preço correta não garante que o canal de geração esteja aberto. Os modos só ficam disponíveis quando habilitados em um canal compatível; combinações não aceitas podem ser rejeitadas antes de criar a tarefa.
Os valores de proporção comuns nas referências do Grok Video são 16:9, 9:16, 3:2, 2:3 e 1:1. A disponibilidade ainda depende do canal, então envie um valor que você já confirmou para esse ID.

Figura 1: envie um prompt (e URLs públicas de imagem opcionais) para POST /v1/videos/generations, consulte o mesmo id de tarefa e leia result.data[0].url só quando o status for completed.
Se você precisa de recursos do canal oficial do Grok Imagine, como a extensão de vídeo, essa é outra família de IDs: consulte o guia do canal oficial do Imagine. Para um segundo contrato de vídeo com matriz de duração diferente, consulte o guia do Hailuo 2.3.
3. Implementação em produção: cURL e Python
Os exemplos internacionais desta série usam https://api.toapis.com. A documentação oficial orienta usuários da China continental a usar https://toapis.cn. Mantenha uma origem por ambiente. Caminhos, IDs de modelo e cabeçalho Bearer permanecem iguais.
Passo 1: envio com cURL para grok-video-1.5
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-video-1.5",
"prompt": "A cinematic product shot with a slow camera push-in",
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Uma tarefa com primeiro quadro usa o mesmo caminho com "video_generation_mode": "first_frame_image_to_video" e uma URL em image. Uma tarefa com imagens de referência define "video_generation_mode": "reference_images_to_video" e uma lista reference_images, e mantém resolution em 480p ou 720p.
Passo 2: auxílio e sondagem em Python
O trecho segue o caminho de status de tarefa documentado e os estados queued / in_progress / completed / failed. Confirme id, result.data[0].url e o envelope com a referência da API da sua conta antes de publicar.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_grok_video(
prompt: str,
*,
model: str = "grok-video-1.5",
mode: str = "text_to_video",
duration: int = 8,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-video-3":
raise ValueError("grok-video-3 is not a current public catalog ID")
if mode == "reference_images_to_video" and resolution not in {"480p", "720p"}:
raise ValueError("reference mode is documented as 480p or 720p")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if model == "grok-video-1.5":
payload["video_generation_mode"] = mode
if mode == "text_to_video" and (image_url or reference_images):
raise ValueError("text_to_video rejects image fields")
if mode == "first_frame_image_to_video":
if not image_url:
raise ValueError("first-frame mode requires exactly one image URL")
payload["image"] = image_url
if mode == "reference_images_to_video":
refs = reference_images or []
if not (1 <= len(refs) <= 7):
raise ValueError("reference mode requires 1-7 image URLs")
payload["reference_images"] = refs
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_grok_video(
"A cinematic product shot with a slow camera push-in",
mode="text_to_video",
duration=8,
resolution="720p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Guarde a versão do modelo de prompt junto ao registro da tarefa para poder distinguir uma mudança de modelo ou de modo de uma mudança de redação. Baixe o arquivo antes de expires_at; a referência de status documenta uma janela de retenção de 30 dias.
4. Tratamento de erros e matriz de status
As categorias abaixo são pontos de partida para diagnóstico, não uma garantia dos códigos de erro exatos da ToAPIs. Uma consulta HTTP bem-sucedida ainda exige ler o status da tarefa. Veja a referência de erros para distinguir erros de requisição de motivos de status: failed como content_policy_rejected, insufficient_user_balance ou generation_timeout.
| Estado HTTP ou de tarefa | Categoria comum | Ação recomendada |
|---|---|---|
400 | Campo inválido, descompasso entre modo e mídia ou combinação não aceita | Verifique o ID exato do catálogo, se video_generation_mode combina com os campos de imagem, se o modo de referência fica em 480p ou 720p e se os valores de imagem são URLs públicas |
401 | Chave de API ausente ou inválida | Rotacione a chave no painel da ToAPIs e confirme o cabeçalho Authorization: Bearer |
429 | Limite de taxa ou de concorrência | Respeite Retry-After quando presente; recue com variação aleatória; repita apenas quando for seguro |
5xx ou tempo esgotado no cliente | Problema temporário do gateway ou do upstream | Consulte o id de tarefa existente antes de reenviar |
status: queued ou in_progress | Não é erro | Aguarde e consulte novamente; não crie uma segunda tarefa |
status: failed | A geração não teve sucesso | Leia error.code e error.message (e error.reason quando presente). Não repita um payload rejeitado por política sem alterações |
5. Preços e retorno de FinOps
- Não reutilize preços unitários de rascunhos de planejamento. A referência da API do
grok-video-1.5afirma que o preço segue a configuração atual de conta e SKU e que a página não garante um preço fixo por segundo. As linhas de referência oficiais do fornecedor na página de preços da ToAPIs são apenas informativas e podem não corresponder ao que é cobrado da sua conta. - Uma cotação não é garantia de canal. A referência do 1.5 observa que uma cotação de preço bem-sucedida não significa que um canal de geração esteja disponível.
- Controle o gasto na camada de prompt: faça rascunhos em
720pe uma duração intermediária como 8 segundos, mantenha um modelo versionado, mude uma variável por vez e não reenvie após um tempo esgotado no cliente até verificar o status da tarefa. - Contratos oficiais de fornecedores normalmente acrescentam compromissos anuais, cotas por usuário e mínimos de pré-pagamento. A cobrança da ToAPIs costuma ser pagamento conforme o uso: confirme os termos ativos da sua conta.
6. Perguntas frequentes
Consulte o bloco de perguntas frequentes do frontmatter. Em resumo: grok-video-3 não é um ID público de catálogo atual; comece por grok-video-1.5 ou grok-video-1.0; trate o teto de duração do 1.0 como verificação específica do canal; áudio sincronizado não está documentado; consulte sempre o caminho de status de gerações e guarde o id da tarefa.
7. Checklist de ações
- Crie uma chave no Portal de desenvolvedores da ToAPIs.
- Confirme que
grok-video-1.5ougrok-video-1.0aparece para a sua chave viaGET /v1/models?type=video; não enviegrok-video-3a menos que apareça depois nessa lista e na referência da API. - Faça um teste rápido do trecho cURL com
video_generation_mode: "text_to_video",duration: 8eresolution: "720p". - Consulte
GET /v1/videos/generations/{id}com um prazo limitado e baixe o resultado antes deexpires_at. - Próximo passo: o guia de acesso compatível com OpenAI se você está apontando um cliente existente para a ToAPIs, o guia do modelo Grok Video 1.5 para o status do catálogo em produção, e o guia do modelo Grok Video 1.0 antes de contar com duração acima de 6 segundos nesse ID.







