API de geração de vídeo Grok Imagine 1.0: endpoints, escopos de autenticação e tratamento de erros
Modelos alvo:
grok-imagine-video-official,grok-imagine-video-1.5-official
Endpoint de inferência:https://api.toapis.com/v1/videos/generations
Relacionado: Guia prático do Grok Video · Acesso compatível com OpenAI · Geração oficial do Imagine · Extend oficial do Imagine
1. Resumo e visão geral de desempenho
- IDs: requisições intituladas em torno de “Grok Imagine 1.0” precisam das strings que a ToAPIs realmente publica. A captura pública do catálogo datada de 2026-11-10 lista
grok-imagine-video-officialegrok-imagine-video-1.5-official(essas duas também aparecem em geração de imagens e emopenai-video). Uma verificação de 2026-11-17 em um caminho de documentaçãogrok-imagine-1.0retornou HTTP 404. - Autenticação: envie
Authorization: Bearer $TOAPIS_API_KEY. As páginas oficiais não documentam escopos OAuth, nomes granulares de permissão nem endpoint de descoberta de escopos para essas chamadas. - Endpoints: crie com
POST /v1/videos/generations. Consulte comGET /v1/videos/generations/{id}. Estenda a saída do canal oficial comPOST /v1/videos/{video_id}/extend, ou comPOST /v1/videos/extendmaisvideo_urlsquando você só tem uma URL pública do vídeo. Envie imagens estáticas comPOST /v1/uploads/images. - Capacidades:
grok-imagine-video-officialcobre texto para vídeo, imagem para vídeo e geração com múltiplas referências em480pou720p, duração de 1–15 segundos e extend de 2–10 segundos.grok-imagine-video-1.5-officialé apenas imagem para vídeo com primeiro quadro, exige exatamente umaimage, permite1080pe não aceita extend. - Forma do preço (não há preço unitário fixo nas páginas de referência): a saída é cobrada por segundo conforme a resolução; cada imagem de entrada é cobrada por imagem; extend também cobra a duração do vídeo de origem. Confirme as tarifas vigentes da conta.
2. Endpoints, autenticação e contratos de modelo
A documentação oficial usa https://toapis.com (e https://toapis.cn para a China continental). Outros guias desta série usam https://api.toapis.com. Escolha uma origem e mantenha a coerência. Todas as rotas abaixo usam o mesmo cabeçalho Bearer.
| Ação | Método e rota | Notas do modelo |
|---|---|---|
| Enviar uma imagem estática | POST /v1/uploads/images | file multipart. JPEG, PNG, WebP ou GIF, máximo 30 MB. Leia data.url |
| Criar um vídeo | POST /v1/videos/generations | Ambos os IDs oficiais do Imagine |
| Consultar status | GET /v1/videos/generations/{id} | Mesma rota para tarefas de geração e de extend |
| Estender a partir de uma tarefa anterior | POST /v1/videos/{video_id}/extend | Apenas grok-imagine-video-official. video_id é o id da tarefa de geração anterior |
| Estender a partir de uma URL pública | POST /v1/videos/extend | Mesmo ID oficial; video_urls é obrigatório quando não há id na rota |
| ID de catálogo | Tarefas documentadas | Duração | Resolução | Imagens | Extend |
|---|---|---|---|---|---|
grok-imagine-video-official | Texto para vídeo, primeiro quadro e múltiplas referências | 1–15 segundos (padrão 8) | 480p, 720p | image opcional mais reference_images; até 7 no total | 2–10 segundos (duration padrão 6) |
grok-imagine-video-1.5-official | Apenas imagem para vídeo com primeiro quadro | 1–15 segundos (padrão 8) | 480p, 720p, 1080p | image é obrigatória (exatamente um primeiro quadro). reference_images adicionais ainda contam para o total de 7 imagens | Não suportado |
Os valores de proporção nas referências oficiais do Imagine incluem 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 e 1:1. Envie um valor que você já confirmou para esse ID e canal.
Não existe string de escopo pública documentada para solicitar “gerar”, “estender” ou “enviar” separadamente. O acesso é o que a chave de API, o grupo de usuários e a configuração do canal já permitem. Se uma chamada falha por permissão ou disponibilidade, verifique a lista de modelos da chave e a referência de erros em vez de acrescentar um parâmetro de consulta scope inventado.

Figura 1: uma única chave de API Bearer autoriza upload, geração ou extend e consulta de status; o ID oficial 1.5 não acrescenta uma ramificação de extend.
Para a família Grok Video não oficial (grok-video-1.0 / grok-video-1.5), consulte o guia prático do Grok Video. Esses IDs são outro contrato e não herdam esta rota de extend.
3. Implementação em produção: cURL e Python
Passo 1: cURL, texto para vídeo no canal oficial
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-official",
"prompt": "A golden retriever running on a green field in sunny weather",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Uma tarefa com primeiro quadro no grok-imagine-video-1.5-official usa a mesma rota, exige "image": "https://example.com/portrait.jpg" e pode definir "resolution": "1080p". Substitua a URL de exemplo por um endereço público; envie o arquivo antes se ele for local:
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@/path/to/first-frame.jpg"
Passo 2: Python, gerar, consultar e extend opcional
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_imagine(
prompt: str,
*,
model: str = "grok-imagine-video-official",
duration: int = 10,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-imagine-video-1.5-official" and not image_url:
raise ValueError("grok-imagine-video-1.5-official requires exactly one first-frame image")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if image_url:
payload["image"] = image_url
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(
f"{BASE}/v1/videos/generations",
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) -> dict:
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={"Authorization": f"Bearer {API_KEY}"}, 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
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")
def extend_official(source_task_id: str, prompt: str, duration: int = 6) -> str:
if not (2 <= duration <= 10):
raise ValueError("official extend duration is documented as 2-10 seconds")
res = requests.post(
f"{BASE}/v1/videos/{source_task_id}/extend",
headers=HEADERS,
json={
"model": "grok-imagine-video-official",
"prompt": prompt,
"duration": duration,
},
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 extend envelope: {data}")
return task_id
if __name__ == "__main__":
task_id = dispatch_imagine(
"A golden retriever running on a green field in sunny weather",
duration=10,
resolution="720p",
)
print("Task:", task_id)
result = poll_task(task_id)
print("Video:", result["result"]["data"][0]["url"])
Para estender a partir de um MP4 público em vez de um id de tarefa, use POST /v1/videos/extend com o mesmo modelo oficial, prompt, duration e uma lista video_urls. Não chame extend com grok-imagine-video-1.5-official.
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. A referência de erros distingue erros de requisição, valores de error.reason de tarefas com falha e payloads de webhook.
| Estado HTTP ou de tarefa | Categoria comum | Ação recomendada |
|---|---|---|
400 | Campo inválido, image obrigatória ausente no 1.5-official, excesso de imagens ou extend enviado a um modelo que não o suporta | Verifique o ID oficial exato, a duração (1–15 ao gerar, 2–10 ao estender), a resolução (1080p apenas no 1.5-official) e se todos os valores de mídia são URLs públicas |
401 | Chave de API ausente ou inválida | Rotacione a chave e confirme Authorization: Bearer. Não acrescente um parâmetro scope não documentado como solução |
429 | Limite de taxa ou de concorrência | Respeite Retry-After quando presente; recue com variação aleatória |
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 |
status: failed com content_policy_rejected | Revisão de segurança ou de direitos autorais | Verifique o prompt e cada recurso de referência; uma entrada conforme ainda pode gerar saída rejeitada |
status: failed com insufficient_user_balance ou token_quota_exceeded | Saldo ou cota de tokens | Verifique tanto o saldo quanto os limites periódicos |
status: failed com generation_timeout, model_unavailable ou service_busy | Tempo esgotado ou disponibilidade do upstream | Verifique o id existente primeiro; depois repita com recuo apenas se a tarefa for final |
5. Preços e retorno de FinOps
As páginas oficiais de geração e de extend do Imagine descrevem uma forma de cobrança, não um preço unitário público fixo:
Use as tarifas devolvidas para a sua conta e SKU, não números de rascunho.
grok-imagine-video-1.5-officialsempre inclui uma cobrança de imagem de entrada, porque a imagem de primeiro quadro é obrigatória.- Extend não é continuação gratuita. A cobrança oficial de extend inclui os segundos de extensão gerados e a duração do vídeo de origem. Por isso extends encadeados cobram novamente o comprimento crescente de origem: confirme esse comportamento com uma cotação vigente antes de montar um laço.
- Não reutilize preços unitários nem números de SLA de rascunhos de planejamento. 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 à cobrança da conta.
- Faça rascunhos em
720pcom duração intermediária, mude uma variável por vez e nunca reenvie após um tempo esgotado no cliente até verificar o status da tarefa.
6. Perguntas frequentes
Consulte o bloco de perguntas frequentes do frontmatter. Em resumo: envie grok-imagine-video-official ou grok-imagine-video-1.5-official, não grok-imagine-1.0; a autenticação é uma chave de API Bearer sem matriz pública de escopos OAuth; 1.5-official é apenas primeiro quadro e não pode estender; a duração de extend é de 2 a 10 segundos e também cobra o comprimento de origem; distinga sempre erros HTTP de status: failed.
7. Checklist de ações
- Crie uma chave no Portal de desenvolvedores da ToAPIs.
- Confirme que
grok-imagine-video-officialougrok-imagine-video-1.5-officialaparece para a sua chave viaGET /v1/models?type=video. - Faça um teste rápido de uma geração oficial em
720p, consulteGET /v1/videos/generations/{id}e baixe o arquivo antes deexpires_at. - Se você precisa de uma continuação, estenda apenas com
grok-imagine-video-officiale umadurationde 2 a 10 segundos, e depois confirme que a cotação inclui a cobrança da duração de origem. - Próximo passo: o guia oficial do modelo Imagine e o guia oficial do modelo Imagine 1.5 para o status do catálogo em produção, e o guia prático do Grok Video se você se referia à família não oficial
grok-video-*.







