ToAPIs
    InícioToAPIs
    Geração de imagensGPT Image 2.6, Gemini, FLUX…Geração de vídeoSeedance, Veo, Kling, Sora…Chat e escritaGPT-5.6, Claude, DeepSeek…Voz e músicaLocuções, TTS, áudio
    NovidadeSeedance 2.5
    PreçosDocumentação da APIMCP
    BlogAlternativas
    EntrarComece grátis
    Todos os modelosPreçosDocumentação da APIMCPBlogAlternativas
    EntrarComece grátis

    Idioma

    Esc
    • Seedance 2.5Geração de vídeo
    • GPT Image 2Geração de imagens
    • GPT Image 2.6Geração de imagens
    • GPT Image 2.5Geração de imagens
    • Veo 3.1 FastGeração de vídeo
    • Kling 3.0 TurboGeração de vídeo
    • Kling V4 FlashGeração de vídeo
    • Grok Video 1.5Geração de vídeo
    • Nano Banana 2Geração de imagens
    • Seedream 5.5Geração de imagens
    • FLUXGeração de imagens
    • Sora 2Geração de vídeo
    • Todos os modelos de imagemCategoria
    • Todos os modelos de vídeoCategoria
    • GPT-5.6 SolChat e código
    • Claude Opus 4.8Chat e código
    • Claude Opus 4.7Chat e código
    • DeepSeek V4 ProDeepSeek · Texto
    • Gemini Omni 1.1 FlashGoogle · Multimodal
    1. Início
    2. Blog
    3. Tutorial
    4. Prática com a API do Grok-Video-3: tudo o que você precisa saber sobre o motor de vídeo da xAI
    Voltar a todos os artigos
    tutorial2026-11-177 min de leitura

    Prática com a API do Grok-Video-3: tudo o que você precisa saber sobre o motor de vídeo da xAI

    Guia prático para chamar hoje o xAI Grok Video na ToAPIs: o catálogo público ainda lista grok-video-1.0 e grok-video-1.5, não grok-video-3, com o contrato atual de gerações, os modos e o caminho de sondagem.

    ToAPIs Engineering & Evaluation Team
    Grok VideoVideo APIxAIText-to-VideoTutorial
    TL;DR - Principais conclusões
    • Conforme a captura pública do catálogo datada de 2026-11-10, e após uma verificação de 2026-11-17 das páginas de documentação e de guia de modelo, não existe nenhum ID de modelo público da ToAPIs chamado grok-video-3. Os IDs documentados do Grok Video são grok-video-1.0 e grok-video-1.5.
    • Envie tarefas para POST /v1/videos/generations com uma chave de API Bearer. Guarde o id da tarefa e consulte GET /v1/videos/generations/{id}. Não chame um caminho /videos/tasks que não esteja documentado.
    • grok-video-1.5 documenta três modos explícitos: text_to_video, first_frame_image_to_video e reference_images_to_video. Defina video_generation_mode conforme a mídia que você realmente envia.
    • Imagens devem ser URLs públicas http(s). Envie arquivos locais primeiro com POST /v1/uploads/images; essas APIs de geração não aceitam base64.
    • Não reutilize preços por segundo nem números de SLA não verificados de rascunhos de planejamento. Confirme a tarifa vigente e o suporte do canal na sua conta antes de prever uma lista de planos.

    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.0 e grok-video-1.5 no endpoint openai-video. Uma verificação de 2026-11-17 nas URLs de documentação e de guia de modelo do grok-video-3 retornou HTTP 404.
    • Contrato: envie de forma assíncrona para POST /v1/videos/generations e depois consulte GET /v1/videos/generations/{id} até completed ou failed. Os exemplos oficiais usam 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.
    • Modos: grok-video-1.5 documenta text_to_video, first_frame_image_to_video e reference_images_to_video. Defina video_generation_mode explicitamente 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:// ou https://. Envie arquivos locais com POST /v1/uploads/images e use o data.url devolvido. 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.038 por 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álogoTarefas documentadasDuração (docs)ResoluçãoEntradas de imagem
    grok-video-1.5Texto, primeiro quadro ou 1 a 7 imagens de referência, selecionados com video_generation_modeInteiro de 1–15 segundos480p ou 720p no modo de referência; texto e primeiro quadro podem usar 1080p quando o canal aceitarPrimeiro quadro: exatamente um image ou input_reference. Modo de referência: 1 a 7 reference_images
    grok-video-1.0Texto para vídeo e imagem para vídeoReferência de geração: 1–15 segundos (padrão 8). Guia de modelo / playground: teto de 6 segundos na variante disponível atualmente480p, 720pimage opcional mais reference_images; até 8 imagens no total

    Para grok-video-1.5, integrações novas devem definir o modo explicitamente:

    video_generation_modeEntrada obrigatóriaO que deve ser omitido
    text_to_videoprompt não vazioQualquer campo de imagem
    first_frame_image_to_videoExatamente um primeiro quadro em image ou input_referenceValores 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_videoprompt 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.

    Quadros de entrada vazios passando por um gateway hexagonal até um único quadro de saída

    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

    bash
    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.

    python
    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 tarefaCategoria comumAção recomendada
    400Campo inválido, descompasso entre modo e mídia ou combinação não aceitaVerifique 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
    401Chave de API ausente ou inválidaRotacione a chave no painel da ToAPIs e confirme o cabeçalho Authorization: Bearer
    429Limite de taxa ou de concorrênciaRespeite Retry-After quando presente; recue com variação aleatória; repita apenas quando for seguro
    5xx ou tempo esgotado no clienteProblema temporário do gateway ou do upstreamConsulte o id de tarefa existente antes de reenviar
    status: queued ou in_progressNão é erroAguarde e consulte novamente; não crie uma segunda tarefa
    status: failedA geração não teve sucessoLeia error.code e error.message (e error.reason quando presente). Não repita um payload rejeitado por política sem alterações

    WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)WaitTime=min(MaxWait,BaseInterval×2attempt)+Uniform(0,1)


    5. Preços e retorno de FinOps

    Estimated cost=successful billable jobs×current account rate for that model, duration, and resolution\text{Estimated cost} = \text{successful billable jobs} \times \text{current account rate for that model, duration, and resolution}Estimated cost=successful billable jobs×current account rate for that model, duration, and resolution

    • Não reutilize preços unitários de rascunhos de planejamento. A referência da API do grok-video-1.5 afirma 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 720p e 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.5 ou grok-video-1.0 aparece para a sua chave via GET /v1/models?type=video; não envie grok-video-3 a 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: 8 e resolution: "720p".
    • Consulte GET /v1/videos/generations/{id} com um prazo limitado e baixe o resultado antes de expires_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.

    Explore os modelos mencionados neste artigo

    xAIVIDEO

    grok-video-1.0

    Taxa atual: 2 credits /second
    Guia do modeloTestar no consoleObter chave de API
    xAIVIDEO

    Grok Video 1.5

    Taxa atual: 3.824 credits /second
    Guia do modeloTestar no consoleObter chave de API

    Artigos relacionados

    tutorial2026-11-17T10:00:00+08:006 min de leitura

    Como acessar a API do Grok Video 3 por endpoints compatíveis com OpenAI

    Aponte um cliente compatível com OpenAI para a ToAPIs e chame os IDs atuais do catálogo Grok Video: autenticação Bearer compartilhada e URL base /v1, com trabalhos de vídeo em POST /v1/videos/generations em vez de um caminho grok-video-3 não publicado.

    TO
    ToAPIs Engineering & Evaluation Team
    #Grok Video
    tutorial2026-11-20T10:00:00+08:008 min de leitura

    Alibaba Wan 3.0 Video API: Getting Started with Next-Gen Video Generation

    A production quickstart for wan3.0-video and wan3.0-video-prime on ToAPIs: one All-in-One endpoint, first and last frames versus reference media, file or link references, video editing constraints, and the documented polling path.

    TO
    ToAPIs Engineering & Evaluation Team
    #Wan 3.0
    tutorial2026-11-18T10:00:00+08:008 min de leitura

    Kling 3.0 Omni API Deep Dive: Multi-Shot Video Generation and Physics Coherence

    A hands-on guide to kling-v3-omni on ToAPIs: official Omni placeholders, image_list, video_list, and element_list, first and end frames, and the documented polling path — without an undocumented shots array.

    TO
    ToAPIs Engineering & Evaluation Team
    #Kling Omni
    ToAPIs
    InícioToAPIs
    Gateway empresarial de API de IA. Acesse GPT-5, Claude, Gemini e mais de 200 modelos por uma única API unificada.

    Modelos populares

    • Seedance 2.5 API
    • Seedance 2.0 API
    • Veo 3.1 Fast API
    • Kling 3.0 Turbo API
    Mostrar maisMostrar menos
    • GPT Image 2 API
    • Claude Opus 4.8 API
    • Nano Banana 2 API
    • Seedance 2 Mini API
    • Todos os modelos

    Categorias de API

    • API de imagem com IA
    • API de vídeo com IA
    • API de texto para vídeo
    • API de imagem para vídeo
    Mostrar maisMostrar menos
    • API de edição de imagens com IA
    • API de LLM e raciocínio
    • Todas as ferramentas de API →

    Alternativas

    Alternativas
    • Alternativa ao Kie.ai
    • Alternativa ao Fal.ai
    • Alternativa ao OpenRouter
    • Alternativa ao Replicate
    • Alternativa ao Wavespeed AI
    • Todas as comparações →

    Guias em destaque

    Guias em destaque
    • Preços do Seedance 2.0 e 2.5
    • Guia da API Seedance mais barata
    • Guia de integração do MiniMax H3
    • Chave de API gratuita do Seedance 2
    • Início rápido da API Seedance 2
    • Todos os artigos técnicos →

    Desenvolvedores e plataforma

    Desenvolvedores e plataforma
    • Documentação da API
    • MCP
    • Preços
    • Playground de modelos
    • LLMs.txt
    • Falar com o suporte
    • Diretório de guias de modelos
    Entidade operadora:
    鯨樞智能科技有限公司
    JINGSHU INTELLIGENT LIMITED
    Sede social:
    ROOM 5042, 5/F, YAU LEE CENTRE, NO.45, HOI YUEN ROAD, KWUN TONG, KOWLOON, HONG KONG
    PrivacidadeTermosUso aceitávelExclusão de dadosRetenção de dadosSubprocessadores e regiõesCobrança e reembolsosPolítica de CookiesMapa do siteSobre

    © 2026 ToAPIs. Todos os direitos reservados.