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. API de geração de vídeo Grok Imagine 1.0: endpoints, escopos de autenticação e tratamento de erros
    Voltar a todos os artigos
    tutorial2026-11-177 min de leitura

    API de geração de vídeo Grok Imagine 1.0: endpoints, escopos de autenticação e tratamento de erros

    O contrato atual do Grok Imagine na ToAPIs usa grok-imagine-video-official e grok-imagine-video-1.5-official: autenticação com chave de API Bearer, endpoints de gerações e extend, e o tratamento documentado de erros e status. Não há um ID grok-imagine-1.0 nem uma matriz de escopos OAuth.

    ToAPIs Engineering & Evaluation Team
    Grok ImagineVideo APIAuthenticationError HandlingTutorial
    TL;DR - Principais conclusões
    • Não existe nenhum ID público de catálogo chamado grok-imagine-1.0. Os IDs documentados do canal oficial são grok-imagine-video-official (texto, imagem e múltiplas referências, mais extend) e grok-imagine-video-1.5-official (apenas imagem para vídeo com primeiro quadro, até 1080p, sem extend).
    • A autenticação documentada é uma chave de API Bearer no cabeçalho Authorization. Este artigo não encontrou matriz pública de escopos OAuth (por exemplo videos:write) para esses endpoints.
    • Crie tarefas com POST /v1/videos/generations e consulte GET /v1/videos/generations/{id}. Estenda clipes do canal oficial com POST /v1/videos/{video_id}/extend ou POST /v1/videos/extend mais video_urls, para 2 a 10 segundos adicionais.
    • Envie imagens locais com POST /v1/uploads/images e use apenas URLs públicas. official permite até 7 imagens entre image e reference_images; 1.5-official exige exatamente uma imagem de primeiro quadro e não documenta extensão de vídeo.
    • A saída é cobrada por segundo conforme a faixa de resolução; imagens de entrada são cobradas por imagem; extend também cobra a duração do vídeo de origem. Confirme as tarifas vigentes da sua conta: não reutilize preços unitários de rascunhos.

    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-official e grok-imagine-video-1.5-official (essas duas também aparecem em geração de imagens e em openai-video). Uma verificação de 2026-11-17 em um caminho de documentação grok-imagine-1.0 retornou 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 com GET /v1/videos/generations/{id}. Estenda a saída do canal oficial com POST /v1/videos/{video_id}/extend, ou com POST /v1/videos/extend mais video_urls quando você só tem uma URL pública do vídeo. Envie imagens estáticas com POST /v1/uploads/images.
    • Capacidades: grok-imagine-video-official cobre texto para vídeo, imagem para vídeo e geração com múltiplas referências em 480p ou 720p, 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 uma image, permite 1080p e 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çãoMétodo e rotaNotas do modelo
    Enviar uma imagem estáticaPOST /v1/uploads/imagesfile multipart. JPEG, PNG, WebP ou GIF, máximo 30 MB. Leia data.url
    Criar um vídeoPOST /v1/videos/generationsAmbos os IDs oficiais do Imagine
    Consultar statusGET /v1/videos/generations/{id}Mesma rota para tarefas de geração e de extend
    Estender a partir de uma tarefa anteriorPOST /v1/videos/{video_id}/extendApenas grok-imagine-video-official. video_id é o id da tarefa de geração anterior
    Estender a partir de uma URL públicaPOST /v1/videos/extendMesmo ID oficial; video_urls é obrigatório quando não há id na rota
    ID de catálogoTarefas documentadasDuraçãoResoluçãoImagensExtend
    grok-imagine-video-officialTexto para vídeo, primeiro quadro e múltiplas referências1–15 segundos (padrão 8)480p, 720pimage opcional mais reference_images; até 7 no total2–10 segundos (duration padrão 6)
    grok-imagine-video-1.5-officialApenas imagem para vídeo com primeiro quadro1–15 segundos (padrão 8)480p, 720p, 1080pimage é obrigatória (exatamente um primeiro quadro). reference_images adicionais ainda contam para o total de 7 imagensNã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.

    Um nó de credenciais atravessando um gateway hexagonal em três blocos de endpoints

    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

    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-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:

    bash
    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

    python
    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 tarefaCategoria comumAção recomendada
    400Campo inválido, image obrigatória ausente no 1.5-official, excesso de imagens ou extend enviado a um modelo que não o suportaVerifique 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
    401Chave de API ausente ou inválidaRotacione a chave e confirme Authorization: Bearer. Não acrescente um parâmetro scope não documentado como solução
    429Limite de taxa ou de concorrênciaRespeite Retry-After quando presente; recue com variação aleatória
    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
    status: failed com content_policy_rejectedRevisão de segurança ou de direitos autoraisVerifique 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_exceededSaldo ou cota de tokensVerifique tanto o saldo quanto os limites periódicos
    status: failed com generation_timeout, model_unavailable ou service_busyTempo esgotado ou disponibilidade do upstreamVerifique o id existente primeiro; depois repita com recuo apenas se a tarefa for final

    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

    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:

    Estimated cost=(output seconds×resolution rate)+(input images×per-image rate)+(extend source seconds×per-second rate)\text{Estimated cost} = (\text{output seconds} \times \text{resolution rate}) + (\text{input images} \times \text{per-image rate}) + (\text{extend source seconds} \times \text{per-second rate})Estimated cost=(output seconds×resolution rate)+(input images×per-image rate)+(extend source seconds×per-second rate)

    Use as tarifas devolvidas para a sua conta e SKU, não números de rascunho.

    • grok-imagine-video-1.5-official sempre 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 720p com 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-official ou grok-imagine-video-1.5-official aparece para a sua chave via GET /v1/models?type=video.
    • Faça um teste rápido de uma geração oficial em 720p, consulte GET /v1/videos/generations/{id} e baixe o arquivo antes de expires_at.
    • Se você precisa de uma continuação, estenda apenas com grok-imagine-video-official e uma duration de 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-*.

    Explore os modelos mencionados neste artigo

    xAIVIDEO

    grok-imagine-video-official

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

    grok-imagine-video-1.5-official

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

    Artigos relacionados

    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:007 min de leitura

    Kling 3.0 Turbo API: Architecting High-Volume Short-Form Video Automation

    A production guide to kling-3.0-turbo on ToAPIs: documented duration and resolution ranges, first-frame-only image input, a bounded poll loop, and high-volume short-form automation without unverified draft prices.

    TO
    ToAPIs Engineering & Evaluation Team
    #Kling Turbo
    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.