Blogue

Tutorial

Como usar minimax-h3-max-turbo/image-to-video com a API HiAPI: curl, Python e exemplos de requisição disponíveis

Nov 17, 2026
Arte de capa abstrata com faixas largas e horizontais em degraus, em terracota e castanho-avermelhado, descendo sobre um fundo quente de areia, com bordas de impressão planas.
Nesta página

O que o endpoint faz e quando usá-lo

minimax-h3-max-turbo/image-to-video recebe uma imagem de origem mais um prompt de texto e retorna um vídeo curto que começa a partir dessa imagem. A imagem atua como primeiro quadro (ou âncora visual), de modo que a saída herda sua composição, tonalidade e identidade do sujeito. O prompt então descreve o que deve acontecer em seguida — movimento de câmera, ação do sujeito, atmosfera.

Quando escolhê-lo em vez de text-to-video

Text-to-video é a ferramenta certa quando você não tem uma referência visual e quer que o modelo crie tudo do zero. O image-to-video é a escolha correta quando o primeiro quadro é o ponto central: você já tem uma imagem de produto aprovada, um quadro-chave de storyboard, um design de personagem ou uma foto enviada pelo usuário que precisa ganhar movimento mantendo-se reconhecível. Especificamente, as equipes usam esse endpoint quando:

  • O primeiro quadro é um requisito contratual. A equipe de marketing precisa da imagem principal exata para abrir, não de uma imagem parecida.
  • A consistência entre clipes é importante. Reutilizar a mesma imagem de origem mantém o personagem ou produto estável ao longo de uma série de clipes.
  • Você está animando conteúdo do usuário. Fotos enviadas por usuários finais devem ser animadas, não reimaginadas.
  • Você quer um escopo de prompt mais focado. Descrever movimento é mais fácil do que descrever a cena inteira do zero, então o prompt fica curto e previsível.

O endpoint é assíncrono: você envia uma tarefa e depois recupera o vídeo renderizado. Esse formato se encaixa bem em backends orientados a filas, como detalhado abaixo. Para a superfície completa de parâmetros, consulte a página do modelo.

Pré-requisitos e estrutura da requisição

Antes de chamar o endpoint, confirme que você tem quatro coisas:

  1. Uma chave de API. Criada na sua conta HiAPI e enviada como bearer token. Trate-a como confidencial — nunca a incorpore em código do cliente.
  2. Uma URL base. Todas as requisições vão para o host unificado da API HiAPI; o caminho do endpoint é o identificador do modelo.
  3. Uma imagem de origem, acessível ou codificável — seja uma URL HTTPS pública, seja um payload base64, dependendo do que o schema da requisição aceitar.
  4. Um cliente HTTP — curl para testes rápidos e qualquer biblioteca padrão ou requests em Python para integração real.

Componentes de uma requisição

Independentemente da linguagem, cada envio de tarefa contém as mesmas partes conceituais:

  • Modelo / endpoint — minimax-h3-max-turbo/image-to-video, parte do caminho da requisição e repetido no corpo para clareza.
  • Imagem de origem — o primeiro quadro. É o campo que distingue image-to-video de text-to-video, e também o que mais facilmente gera erros de validação.
  • Prompt — a descrição de movimento e cena. Descreva apenas o que vai mudar, não o que já está na imagem.
  • Dicas de geração opcionais — controles de duração e estilo de resolução, se o endpoint os oferecer. Envie apenas os parâmetros documentados no schema; chaves desconhecidas são uma fonte comum de respostas 4xx.

O envio retorna um identificador de tarefa e um status. O vídeo em si chega depois, por meio de uma segunda requisição — por isso a seção de polling abaixo é tão importante quanto a chamada de envio.

Uma requisição curl que funciona

O comando abaixo envia uma tarefa de image-to-video. Antes de executar, substitua os placeholders — os marcadores em maiúsculas entre colchetes angulares — pelos seus próprios valores.

curl -X POST "https://api.hiapi.ai/v1/<ENDPOINT_PATH>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-max-turbo/image-to-video",
    "image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
    "prompt": "Slow push-in on the product, soft studio light shifting across the surface, shallow depth of field."
  }'

Algumas observações práticas sobre este comando:

  • Leia a chave de uma variável de ambiente. $HIAPI_API_KEY evita que a chave entre no histórico do shell, desde que você a exporte em vez de colá-la inline.
  • Use uma URL de imagem pública no primeiro teste. Isso elimina o fator de codificação base64 enquanto confirma que autenticação e conexão funcionam.
  • Mantenha o corpo JSON enxuto. O payload do -d é a requisição inteira; uma vírgula faltando aqui gera um 400 confuso, em vez de um erro de schema claro.
  • Coloque o prompt entre aspas. Prompts com pontuação quebram strings de shell sem aspas.

A resposta é um objeto de tarefa, não um vídeo. Capture o ID da tarefa dele — você usará esse ID na requisição de polling. Se a chamada falhar imediatamente, pule para a seção de solução de problemas; erros de autenticação e de payload se manifestam nesta etapa, não depois.

A mesma requisição em Python

Abaixo está o equivalente em Python da chamada de envio, usando requests. Pressupõe que HIAPI_API_KEY esteja definida nas variáveis de ambiente.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1/<ENDPOINT_PATH>"

payload = {
    "model": "minimax-h3-max-turbo/image-to-video",
    "image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
    "prompt": (
        "Slow push-in on the product, soft studio light shifting "
        "across the surface, shallow depth of field."
    ),
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
response.raise_for_status()
job = response.json()
print(job["id"], job.get("status"))

Pontos a preservar ao adaptar este trecho:

  • Timeout não é opcional. O envio é rápido, mas um socket pendurado em um handler de requisição web vai derrubar seu worker junto.
  • Chame raise_for_status() antes de fazer parsing. Isso transforma um 401 silencioso em uma exceção que você pode realmente registrar.
  • Retorne o ID da tarefa, não a resposta. Em um serviço, a função de envio deve retornar o identificador, para que um poller separado — ou uma tarefa em background — cuide da espera.
  • Mantenha o payload em uma variável. Depois que a chamada funcionar, trocar a URL da imagem por uma URL de upload assinada ou uma string base64 exige apenas uma linha alterada.

Aqui usamos deliberadamente um cliente HTTP simples em vez de uma biblioteca wrapper: o formato da requisição é o contrato, e você deve ser capaz de reproduzi-lo em qualquer linguagem que sua stack use.

Preparando a imagem e o primeiro quadro

A maioria das tarefas de image-to-video que falham falha por causa da imagem, não do prompt. Alguns hábitos evitam isso.

Formato e entrega

Use um formato raster padrão e amplamente suportado — JPEG ou PNG — e garanta que a URL seja publicamente acessível, sem cookies, sem redirecionamento para uma página de login e sem dependência de URLs assinadas que expiram logo após o envio. Se seus recursos estiverem em um bucket privado, gere uma URL assinada cujo tempo de vida seja claramente maior que a duração esperada da tarefa. Para payloads base64, remova o prefixo data-URI se o schema esperar bytes codificados crus, e certifique-se de que o tamanho codificado fique bem dentro dos limites documentados.

Dimensões e composição

O modelo renderiza o vídeo em um tamanho de saída fixo, então a imagem de origem é ajustada. Duas consequências:

  • Combine com a proporção desejada. Enviar uma foto retrato vertical para uma renderização horizontal resultará em corte ou barras pretas, e o sujeito pode ficar fora do centro.
  • Deixe margem para o movimento. Se o prompt descreve um push-in de câmera ou um sujeito se movendo para cima, deixe espaço nessa direção na imagem de origem.

Mantenha o primeiro quadro intacto

O quadro de abertura depende principalmente da própria imagem. Escreva o prompt como instruções para o que acontece depois do primeiro quadro: descreva o comportamento da câmera, o movimento do sujeito e as mudanças de iluminação. Evite redescrever a cena — quando a imagem já mostra "uma cadeira vermelha em um piso branco", repetir a descrição tende a aumentar o desvio em vez da fidelidade. Se o resultado se afastar da imagem de origem, encurte o prompt primeiro antes de considerar trocar a imagem.

Não presuma a existência de parâmetros não documentados. Se o controle que você quer não está no schema, obtenha-o por meio do prompt ou da preparação da imagem.

Lidando com o ciclo de vida de tarefas assíncronas

Tarefas de image-to-video não são síncronas. O padrão é enviar → fazer polling → recuperar, e uma integração de produção deve implementar as três etapas explicitamente.

1. Envie e persista

Envie a requisição e armazene imediatamente o ID de tarefa retornado, de preferência junto com seu próprio ID de correlação, hash do payload da requisição e timestamp. Se o processo morrer entre o envio e o armazenamento, você pagou por uma tarefa que não consegue recuperar.

2. Polling com backoff

Use o ID armazenado para consultar o endpoint de status da tarefa. A renderização de vídeo leva bem mais tempo que a geração de imagens, então:

  • Comece com um intervalo moderado — alguns segundos — e aumente à medida que a tarefa demora, em vez de martelar o endpoint a uma taxa fixa.
  • Limite o tempo total de espera a um teto adequado à tarefa e, então, trate a tarefa como expirada e decida se deve tentar novamente.
  • Trate estados terminais como terminais: assim que a tarefa reportar sucesso ou falha, pare o polling.
import time

def wait_for_job(poll_fn, job_id, max_wait=600):
    deadline = time.time() + max_wait
    interval = 5
    while time.time() < deadline:
        job = poll_fn(job_id)
        if job["status"] in ("succeeded", "failed"):
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 30)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

3. Recupere e armazene a saída

Após o sucesso, o objeto da tarefa carrega a localização do resultado. Baixe o vídeo em tempo hábil e copie-o para o seu próprio armazenamento — a URL de saída deve ser tratada como um recurso temporário, não como sua biblioteca permanente de ativos. Registre o ID da tarefa junto ao arquivo armazenado, para que o suporte consiga rastrear qualquer clipe de volta à sua requisição.

Para novas tentativas, apenas refaça o polling de tarefas cujos IDs você já armazenou; nunca reenvie às cegas, ou você gerará renderizações duplicadas e cobranças duplicadas.

Solução de problemas comuns

Falhas de autenticação (401 / 403)

Verifique primeiro o cabeçalho Authorization: a palavra Bearer, um espaço, depois a chave, e nenhum caractere de nova linha final trazido da cópia da chave. Confirme que a chave está ativa e pertence à conta que você espera. Se o curl funcionar e o Python não, imprima o comprimento do cabeçalho — uma variável de ambiente vazia produz um token aparentemente válido, mas inútil.

Payload de imagem malformado ou não suportado (400 / 422)

A falha não relacionada à autenticação mais comum. Verifique em ordem:

  • A URL da imagem resolve normalmente e não redireciona para uma página de login HTML.
  • O formato é JPEG ou PNG, não WebP, HEIC ou uma miniatura de PDF.
  • O tamanho após codificação ou download está dentro dos limites documentados.
  • O payload base64 não tem prefixo data: nem espaço em branco gerado por quebras de linha.
  • A imagem não está corrompida — busque e abra você mesmo antes de culpar a API.

Parâmetros desconhecidos ou inválidos

Nomes de campos com erro de digitação, ou parâmetros que o endpoint não expõe, normalmente retornam um erro de validação indicando o campo. Remova parâmetros especulativos e reconstrua a partir do mínimo exigido pela documentação.

Limites de taxa (429)

Use backoff exponencial e respeite qualquer dica de retry presente na resposta. Não repita em um loop apertado; isso aprofunda o limite. Se você encontrar isso com frequência, envie em lote por meio de uma fila em vez de disparar inline a partir de requisições de usuário.

Tempo esgotado da tarefa e polling travado

Se uma tarefa nunca atingir um estado terminal dentro do seu orçamento, registre o ID da tarefa e o histórico de status e pare o polling. Timeouts persistentes normalmente indicam uma imagem excessivamente grande ou anômala no momento do envio, então reveja a seção de preparação da imagem. Não reenvie automaticamente sem um limite de tentativas.

Checklist de produção antes do lançamento

Antes que o endpoint receba tráfego real, verifique cada item abaixo:

  • Timeouts em todos os lugares. O envio usa timeout curto, o polling define um teto total de espera e as tentativas de retry têm limite rígido. Nada de loops while True sem limite.
  • Retries com backoff. Repita 429 e respostas 5xx transitórias; nunca repita erros de validação — eles falharão da mesma forma.
  • IDs de tarefa nos logs. Registre o ID da tarefa, seu ID de correlação e o status final para cada requisição. É o artefato de depuração mais útil que você pode manter.
  • Saídas armazenadas no seu próprio storage. Copie o vídeo concluído da URL retornada para armazenamento persistente e mantenha a referência da imagem de origem para reprodutibilidade.
  • Validação de imagem na borda. Rejeite formatos incorretos e uploads grandes demais antes de chegar à API, para que os usuários recebam um erro claro imediatamente, em vez de uma falha assíncrona minutos depois.
  • Consciência de custo. A geração é cobrada por saída de vídeo renderizado, então acompanhe o volume e a duração das tarefas por usuário ou recurso. Consulte o painel de preços atual em vez de codificar suposições no código ou na documentação.
  • Prompt canário. Mantenha um conjunto de imagens e prompts comprovadamente bons na sua suíte de testes e execute-o após qualquer mudança na integração para confirmar que o contrato da requisição ainda se mantém.

Uma vez que o ciclo de vida assíncrono é tratado corretamente — envio, persistência, polling, armazenamento — o endpoint é direto. Obtenha o schema exato na página do modelo e então implemente os padrões de envio e polling descritos acima.

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API