Como acessar a API do Grok Video 3 por endpoints compatíveis com OpenAI
Modelos alvo:
grok-video-1.5,grok-video-1.0
Endpoint de inferência:https://api.toapis.com/v1/videos/generations
Relacionado: Guia prático do Grok Video · API do canal oficial do Grok Imagine · Configuração compatível com OpenAI no Chatbox · Listar modelos
1. Resumo e visão geral de desempenho
- O que "compatível com OpenAI" significa aqui: a ToAPIs documenta uma única origem
/v1, autenticação Bearer e uma lista de modelos e uma API de conclusões de chat no estilo OpenAI. Os IDs públicos de Grok Video estão registrados na família de endpointsopenai-videodo catálogo. Isso não significa que um IDgrok-video-3não publicado vai funcionar, e por si só não documenta um método do SDK OpenAI Videos. - IDs: use
grok-video-1.5ougrok-video-1.0depois que eles aparecerem para a sua chave emGET /v1/models?type=video. O snapshot público do catálogo datado de 2026-11-10 não listagrok-video-3. - Caminho de vídeo: crie com
POST /v1/videos/generations. Consulte comGET /v1/videos/generations/{id}. Os exemplos oficiais usamhttps://toapis.com(ehttps://toapis.cnpara a China continental). Esta série também usahttps://api.toapis.com. - Autenticação compartilhada: uma chave de API em
Authorization: Bearer. Não existe um documento público separado de escopos OAuth para essas chamadas de vídeo. - Escolha de cliente: use o SDK da OpenAI contra
base_url="https://api.toapis.com/v1"para trabalho no estilo chat e para uma configuração familiar de chave e origem. Para o Grok Video, este guia usa o corpo JSON REST documentado, para quevideo_generation_modee os campos de URL de imagem fiquem explícitos.
2. Origem compatível, lista de modelos e caminhos de vídeo
Mantenha juntos a origem, o prefixo /v1 e a chave. Misturar uma chave da ToAPIs com https://api.openai.com/v1, ou uma origem da ToAPIs com um caminho nativo de Grok do fornecedor, é uma configuração diferente e não documentada.
| Etapa | Caminho documentado | Observações |
|---|---|---|
| Listar modelos | GET /v1/models?type=video | O GET /v1/models padrão retorna apenas modelos de texto. Use type=video ou type=all |
| Enviar uma imagem local | POST /v1/uploads/images (file em multipart) | Leia data.url. Não envie base64 na chamada de geração |
| Criar um trabalho de Grok Video | POST /v1/videos/generations | O corpo inclui model, prompt e os campos de modo e mídia do 1.5 |
| Consultar status | GET /v1/videos/generations/{id} | Os estados finais são completed e failed |
| Chat (não vídeo) | POST /v1/chat/completions | Compartilha apenas a origem e a chave |
No grok-video-1.5, defina video_generation_mode como text_to_video, first_frame_image_to_video ou reference_images_to_video para que o JSON corresponda à mídia enviada. O contrato campo a campo está no guia prático do Grok Video e na referência da API do Grok Video 1.5.

Figura 1: aponte o cliente para uma origem /v1 da ToAPIs, descubra grok-video-1.5 ou grok-video-1.0 com a lista de modelos e então envie e consulte em /v1/videos/generations — não em chat/completions.
Se você está configurando um cliente de desktop em vez de código de aplicação, o guia de configuração do Chatbox cobre o padrão de campo de host para chat. Não espere que esse mesmo caminho de chat retorne um arquivo de vídeo.
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.
Etapa 1: descubra o ID e então envie com cURL
curl -sS "https://api.toapis.com/v1/models?type=video" \
-H "Authorization: Bearer $TOAPIS_API_KEY"
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"
}'
Inspecione a lista de modelos para ver a string id exata antes de fixá-la no código. Se grok-video-3 estiver ausente, não o envie.
Etapa 2: Python, origem compartilhada e chamadas REST de vídeo
O SDK da OpenAI aparece aqui apenas pela base_url e pela chave de API compartilhadas. A criação e a consulta de vídeo ficam nos caminhos de generations documentados, para que os campos do corpo do 1.5 não se percam em um mapeamento de cliente não oficial.
import os
import time
import requests
from openai import OpenAI
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
# Shared origin and key. Use this client for chat completions; do not assume
# a videos.create mapping unless your account docs define one.
client = OpenAI(base_url=f"{BASE}/v1", api_key=API_KEY)
def list_video_model_ids() -> list[str]:
res = requests.get(
f"{BASE}/v1/models",
headers=HEADERS,
params={"type": "video"},
timeout=30,
)
res.raise_for_status()
data = res.json()
items = data.get("data") or data.get("models") or []
return [item.get("id") or item.get("name") for item in items if item]
def dispatch_grok_video(prompt: str, model: str = "grok-video-1.5") -> str:
available = set(list_video_model_ids())
if available and model not in available:
raise ValueError(f"{model} is not in this key's video model list")
res = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json={
"model": model,
"prompt": prompt,
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
},
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__":
print("Video models (excerpt):", list_video_model_ids()[:20])
task_id = dispatch_grok_video("A cinematic product shot with a slow camera push-in")
print("Task:", task_id)
print("Video:", poll_task(task_id))
Se a chamada de lista retornar um envelope inesperado, registre o JSON bruto e alinhe o parser com a página de Listar modelos da sua conta. Não invente uma alternativa que envie grok-video-3 quando o ID estiver ausente.
4. Tratamento de erros e matriz de status
As categorias abaixo são pontos de partida de 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.
| Estado HTTP ou da tarefa | Categoria comum | Ação recomendada |
|---|---|---|
400 | ID de modelo desconhecido, incompatibilidade entre modo e mídia, ou um corpo de vídeo enviado a um caminho de chat | Confirme o ID em GET /v1/models?type=video, que você enviou para /v1/videos/generations e que os trabalhos 1.5 definem um video_generation_mode compatível |
401 | Chave de API ausente ou inválida | Use uma chave da ToAPIs, não uma chave da plataforma OpenAI, e confirme o cabeçalho Bearer |
404 | Origem errada, /v1 faltando ou um caminho inventado como /videos/tasks/{id} | Mude para GET /v1/videos/generations/{id} na origem que você usou para enviar |
429 | Limite de taxa ou de concorrência | Respeite Retry-After quando presente; recue com jitter |
5xx ou timeout do cliente | Problema temporário de gateway ou upstream | Consulte o id da tarefa existente antes de reenviar |
status: failed | A geração não teve sucesso | Leia error.code e error.message. Não repita um payload rejeitado por política sem alterações |
5. Preços e ROI de FinOps
- Compatibilidade não muda a SKU faturável. Você paga pelo ID de modelo do catálogo que envia (
grok-video-1.5ougrok-video-1.0), não por "usar o SDK da OpenAI". - Não reutilize preços unitários de rascunhos de planejamento. A referência do Grok Video 1.5 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 à cobrança da conta.
- Um descobrimento que falha é barato; uma geração duplicada não é. Faça cache da lista de modelos por um curto período, mas sempre verifique o status da tarefa após um timeout do cliente antes de criar outro trabalho.
- A cobrança da ToAPIs costuma ser por uso: confirme os termos ativos na sua conta.
6. Perguntas frequentes
Veja o bloco de perguntas frequentes no frontmatter. Resumo: uma URL base compatível não libera grok-video-3; inclua /v1 uma vez; consulte /v1/videos/generations/{id}; não presuma um helper videos.create do SDK; conclusões de chat não retornarão um MP4.
7. Lista de ações
- Crie uma chave no Portal do desenvolvedor da ToAPIs.
- Aponte seu cliente para
https://api.toapis.com/v1(ouhttps://toapis.cn/v1na China continental) comAuthorization: Bearer. - Chame
GET /v1/models?type=videoe registre os IDs exatos de Grok Video que a sua chave enxerga. - Faça um teste rápido de
POST /v1/videos/generationscomgrok-video-1.5evideo_generation_mode: "text_to_video", depois consulte o mesmo id. - Próximo passo: o guia prático do Grok Video para detalhes de modo e de campos de imagem, e o guia do modelo Grok Video 1.5 para o status do catálogo em tempo real.







