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. Como criar um pipeline automatizado de imagem para vídeo (R2V) com a API MiniMax H3
    Voltar a todos os artigos
    tutorial2026-11-106 min de leitura

    Como criar um pipeline automatizado de imagem para vídeo (R2V) com a API MiniMax H3

    Tutorial de engenharia para um pipeline automatizado de Reference-to-Video no MiniMax H3: entradas de primeiro quadro, preparação de recursos, sondagem limitada de tarefas e o contrato de requisição do frontend da ToAPIs.

    ToAPIs Engineering & Evaluation Team
    MiniMax H3R2VVideo AutomationPythonTutorial
    TL;DR - Principais conclusões
    • O R2V em modo de quadros do MiniMax H3 ancora um clipe com first_frame_image (e, opcionalmente, last_frame_image); ambos os campos são listas de no máximo uma imagem cada.
    • Não misture entradas de primeiro e último quadro com reference_images, reference_videos ou reference_audio na mesma requisição.
    • Um worker resiliente prepara um recurso acessível, envia POST /v1/videos/generations e depois consulta o endpoint de status da tarefa com recuo exponencial limitado.
    • Confirme o formato de upload, o envelope de resposta e o preço atual da sua conta antes de executar isso sem supervisão; este não é um benchmark de latência ou de preço.

    Como criar um pipeline automatizado de imagem para vídeo (R2V) com a API MiniMax H3

    Modelo alvo: minimax-h3
    Endpoint de inferência: https://api.toapis.com/v1/videos/generations
    Relacionado: Guia da API MiniMax H3 · Prompts de movimento de câmera · Escolha entre H3 e Turbo


    1. Resumo e visão geral de desempenho

    • Trabalho: animar uma imagem estática em um clipe curto com o modo de quadros do MiniMax H3 e envolver o envio e a sondagem em um worker que você possa rodar sem supervisão.
    • Entradas: first_frame_image como lista de um item; last_frame_image opcional como lista de um item; um prompt que descreva o movimento para fora ou ao redor dessa âncora; duração inteira de 4–15 s no minimax-h3 base.
    • Modos: entradas de quadro e mídia de referência são mutuamente exclusivas. O Turbo (minimax-h3-max-turbo) rejeita mídia de referência; não copie campos de referência para um payload do Turbo.
    • Worker: prepare um recurso acessível, envie uma única vez, guarde o identificador da tarefa, consulte com recuo e um prazo rígido e então armazene a URL do resultado no seu próprio sistema.
    • Escopo: este é um guia de integração para o contrato atual do frontend da ToAPIs. Não é um benchmark de latência, disponibilidade ou preço.

    2. Estrutura do pipeline

    Um worker de R2V sem supervisão deve desacoplar a requisição HTTP de quem chama da renderização de longa duração:

    1. Aceitar a imagem estática de origem e o prompt de movimento do seu produto.
    2. Preparar a imagem pelo fluxo de upload documentado, ou usar uma URL que você tenha autorização para buscar. Prefira armazenamento de objetos com um localizador acessível e de curta duração em vez de um caminho de disco privado.
    3. Enviar uma tarefa POST /v1/videos/generations com model, prompt, duration e first_frame_image.
    4. Consultar o endpoint de status documentado com recuo exponencial limitado e um prazo global.
    5. Entregar a URL do vídeo resultante pela sua própria via de notificação (fila, e-mail ou webhook do produto). Verifique o status da tarefa antes de criar uma segunda tarefa faturável.

    Pipeline R2V abstrato de um quadro estático por um gateway e um laço de sondagem até os quadros de saída

    Figura 1: uma imagem estática é preparada, enviada uma única vez pelo gateway de gerações da ToAPIs e então sondada até um estado final antes de o seu serviço emitir o clipe concluído.

    Verificações prévias que evitam a maioria dos 400:

    • Use o ID de modelo exato habilitado para a conta (minimax-h3, minimax-h3-max ou minimax-h3-max-turbo, não um alias inventado).
    • A duração é um número inteiro: 4–15 s no H3 base e 5–15 s nos IDs da família Max.
    • first_frame_image e last_frame_image são listas de no máximo uma imagem cada.
    • Não envie reference_images, reference_videos ou reference_audio na mesma requisição das entradas de quadro.
    • No frontend atual, o modo de quadros força ratio para adaptive. Ajuste a forma da imagem estática à tela pretendida (por exemplo 1920×1080 para um clipe widescreen e 1080×1920 para um clipe vertical) para reduzir cortes inesperados.
    • O campo do contrato é ratio, não aspect_ratio.

    A redação de câmera no prompt continua valendo no modo de quadros; consulte o guia de prompts de movimento de câmera. Trate as etiquetas entre colchetes como auxílios de prompt, não como comandos nativos.


    3. Implementação em produção: cURL e Python

    Passo 1: requisição de primeiro quadro com cURL

    bash
    curl -X POST "https://api.toapis.com/v1/videos/generations" \
      -H "Authorization: Bearer $TOAPIS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "minimax-h3",
        "prompt": "[Dolly Forward] Rain falling onto neon asphalt, steam rising from grates, cinematic reflections",
        "duration": 6,
        "ratio": "16:9",
        "first_frame_image": ["https://example.com/starting-frame.jpg"]
      }'
    

    Substitua a URL de exemplo por um identificador de recurso ou uma URL do seu fluxo de upload documentado. O contrato publicado do H3 mostra first_frame_image como um array, não como uma string simples.

    Para também guiar um quadro final, adicione "last_frame_image": ["https://example.com/ending-frame.jpg"] na mesma requisição de modo de quadros. Esse é o modo de quadros padrão, não um sinalizador experimental exclusivo do Turbo.

    Passo 2: worker em Python com sondagem limitada

    Ajuste task_id, status e video_url ao esquema de resposta documentado para a sua conta antes de publicar.

    python
    import os
    import time
    import requests
    from typing import Any
    
    API_KEY = os.environ["TOAPIS_API_KEY"]
    BASE_URL = "https://api.toapis.com/v1"
    HEADERS = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    
    
    class MiniMaxR2VPipeline:
        def trigger_r2v(
            self,
            image_ref: str,
            prompt: str,
            duration: int = 6,
            last_frame_ref: str | None = None,
        ) -> str:
            if not 4 <= duration <= 15:
                raise ValueError("Base minimax-h3 accepts integer durations of 4-15 seconds")
            payload: dict[str, Any] = {
                "model": "minimax-h3",
                "prompt": prompt,
                "duration": duration,
                "ratio": "16:9",
                "first_frame_image": [image_ref],
            }
            if last_frame_ref:
                payload["last_frame_image"] = [last_frame_ref]
            res = requests.post(
                f"{BASE_URL}/videos/generations",
                headers=HEADERS,
                json=payload,
                timeout=30,
            )
            res.raise_for_status()
            data = res.json()
            task_id = data.get("task_id") or data.get("id")
            if not task_id:
                raise RuntimeError(f"Unexpected submission envelope: {data}")
            return task_id
    
        def poll_until_complete(self, task_id: str, max_timeout: int = 180) -> dict[str, Any]:
            start = time.time()
            interval = 3.0
            poll_url = f"{BASE_URL}/videos/tasks/{task_id}"
            while time.time() - start < max_timeout:
                res = requests.get(poll_url, headers=HEADERS, timeout=15)
                res.raise_for_status()
                data = res.json()
                status = data.get("status")
                if status in {"succeeded", "success"}:
                    return {
                        "status": "success",
                        "task_id": task_id,
                        "video_url": data.get("video_url"),
                        "elapsed_seconds": round(time.time() - start, 2),
                    }
                if status in {"failed", "error"}:
                    return {
                        "status": "error",
                        "task_id": task_id,
                        "error": data.get("error", "Generation failed"),
                    }
                time.sleep(interval)
                interval = min(interval * 1.1, 6.0)
            return {
                "status": "timeout",
                "task_id": task_id,
                "error": f"Exceeded {max_timeout}s; check task status before retrying",
            }
    
    
    if __name__ == "__main__":
        pipeline = MiniMaxR2VPipeline()
        # Replace with an uploaded asset identifier or a URL you are authorized to fetch.
        image_ref = "https://example.com/starting-frame.jpg"
        prompt = "[Dolly Forward] Rain falling onto neon asphalt, steam rising from grates, cinematic reflections"
        task_id = pipeline.trigger_r2v(image_ref, prompt)
        print("Task:", task_id)
        print("Result:", pipeline.poll_until_complete(task_id))
    

    Um tempo esgotado não é uma falha confirmada. Registre o identificador da tarefa (nunca a chave de API nem URLs de mídia privadas), verifique o status e só então decida se envia novamente.


    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.

    Status HTTPCategoria comumAção recomendada
    400Campo inválido, mídia inacessível ou não aceita, ou modos de quadro e referência misturadosValide o ID de modelo, a duração, first_frame_image como lista de um item e a ausência de campos de referência
    401Chave de API ausente ou inválidaRotacione a chave no painel da ToAPIs
    429Limite de taxa ou de concorrênciaRecue com variação aleatória e enfileire localmente
    5xx ou tempo esgotado na redeProblema temporário do gateway ou do upstreamLeia novamente o status da tarefa antes de criar outra tarefa

    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)

    Trate falhas de upload como parada total: não envie uma requisição de geração sem um identificador de recurso válido.


    5. Preços e retorno de FinOps

    Estimated cost=successful output seconds×current account rate per second\text{Estimated cost} = \text{successful output seconds} \times \text{current account rate per second}Estimated cost=successful output seconds×current account rate per second

    • Cotação a partir de uma fonte datada da conta. Não cole preços por segundo nem percentuais de SLA de rascunhos de planejamento em uma previsão de produção. As tarifas e a cobrança de tarefas com falha podem variar por modelo e por rota.
    • Contratos oficiais de fornecedores podem exigir compromissos ou mínimos de pré-pagamento. Confirme se a sua conta ToAPIs é de pagamento conforme o uso puro e como renderizações com falha no upstream são cobradas.
    • Disciplina de pipeline é a alavanca prática de FinOps: um envio por plano, verificações de status antes de repetir, modelos de prompt guardados com a tarefa e duração limitada ao clipe mais curto que atende ao plano.
    • Precisa de 1080P? Verifique se o ID canônico exato minimax-h3-max está habilitado. Precisa de Turbo? Use minimax-h3-max-turbo e omita os campos de mídia de referência. Os detalhes estão no guia de escolha.

    6. Perguntas frequentes

    Consulte o bloco de perguntas frequentes do frontmatter. Em resumo: ajuste a imagem estática à tela pretendida; a orientação por quadro final é o modo de quadros padrão (no máximo uma imagem cada); use o fluxo de upload documentado em vez de um caminho privado; este guia consulta o status em vez de presumir um webhook da ToAPIs.


    7. Checklist de ações

    • Crie uma chave no Portal de desenvolvedores da ToAPIs.
    • Prepare uma imagem estática pelo fluxo de upload documentado e faça um teste rápido da requisição de primeiro quadro com cURL.
    • Conecte o worker em Python com um prazo de sondagem de 180 s e uma regra de não duplicar envios em tempos esgotados.
    • Revise o contrato de requisição do H3 e o guia de prompts de movimento de câmera antes de disparar tarefas em lote.

    Explore os modelos mencionados neste artigo

    MiniMaxVIDEO

    minimax-h3

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

    minimax-h3-max

    Taxa atual: 8 credits /second
    Guia do modeloTestar no consoleObter chave de API
    ToAPIsAI Model

    minimax-h3-max-turbo

    Taxa atual: Ver preços em tempo real
    Guia do modeloTestar no consoleObter chave de API

    Artigos relacionados

    tutorial2026-10-22T09:00:00+08:0012 min de leitura

    Guia da API MiniMax H3: texto para vídeo e entradas de referência

    Guia prático para chamar os modelos de vídeo MiniMax H3 pela ToAPIs, com exemplos de requisição, modos de entrada aceitos, limites por modelo e orientação para consultar o estado das tarefas.

    TO
    ToAPIs Engineering Team
    #MiniMax H3
    tutorial2026-11-10T10:00:00+08:006 min de leitura

    Guia de prompts do MiniMax H3: como criar movimentos de câmera cinematográficos pela API

    Guia para desenvolvedores sobre como escrever prompts de movimentos de câmera cinematográficos para a API de vídeo MiniMax H3 na ToAPIs: modelos reutilizáveis, exemplos em cURL e Python e o contrato de requisição atual do frontend.

    TO
    ToAPIs Engineering & Evaluation Team
    #MiniMax H3
    tutorial2026-11-11T10:00:00+08:007 min de leitura

    Integração da API MiniMax Hailuo 2.3: gerar movimento humano complexo em vídeo com IA

    Guia para desenvolvedores sobre a API de vídeo MiniMax Hailuo 2.3 na ToAPIs: padrões de prompt para movimento humano, o contrato atual de requisição para trabalhos de 6 e 10 segundos em 768P e 1080P, e exemplos em cURL e Python.

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