Blogue

Tutorial

Como usar minimax-h3 pela API HiAPI: curl, Python e requisições executáveis

Nov 10, 2026
Capa geométrica minimalista: sobre um fundo verde-pinheiro escuro, alguns grandes prismas são cortados em blocos de cor planos, com toques de verde-sálvia e verde-neblina.
Nesta página

Como é a integração minimax-h3 de ponta a ponta

A geração de vídeo não é uma operação instantânea. O minimax-h3 precisa receber um prompt ou uma imagem de origem, agendar a tarefa em um pool de GPUs, codificar os quadros e montar o arquivo de saída. Todo o processo, dependendo da duração e da resolução, pode levar de alguns segundos a vários minutos. Se o endpoint da HiAPI bloqueasse até o arquivo ficar pronto, seu cliente HTTP ficaria com uma conexão aberta durante todo o tempo — frágil no caso de novas tentativas, incompatível com limites de tempo de ambientes serverless e inviável em handlers Web baseados em requisição/resposta.

Por isso, a integração segue o formato enviar primeiro, consultar depois, o padrão usual de APIs assíncronas de mídia:

  1. Envio. Você faz um POST com um payload JSON que descreve a tarefa (prompt, imagem opcional, duração, proporção e quaisquer parâmetros específicos do modelo). A API valida e devolve imediatamente um identificador de tarefa e o status inicial.
  2. Consulta. Com intervalos curtos, você chama o endpoint de status da tarefa usando esse identificador. O status passa por fila, processamento e, por fim, sucesso ou falha.
  3. Obtenção. Quando o status chega a um estado terminal, a resposta traz o resultado — normalmente uma URL para baixar o vídeo gerado.

Esse modelo traz três consequências que orientam todo o restante deste guia:

  • O ID da tarefa é seu único handle. Persista-o. Se você o perder, não conseguirá recuperar a tarefa; só poderá reenviar e pagar novamente pelo trabalho.
  • Seu código tem duas superfícies de falha, não uma. O envio pode falhar (autenticação, payload malformado) e a consulta também pode falhar (timeout, erro de rede transitório, tarefa que termina em falha). Trate cada uma separadamente.
  • O ritmo das consultas é uma decisão de projeto. Consultar de forma agressiva desperdiça requisições; consultar devagar demais faz o usuário esperar por um estado que já está pronto.

Neste artigo, todas as chamadas vão para a API unificada da HiAPI. Você precisa obter uma chave de API na sua conta HiAPI e referenciar o modelo como minimax-h3 no payload. Todo o resto — cabeçalho de autenticação, URL base, endpoint de consulta — é compartilhado por toda a plataforma, então o padrão que você aprende aqui pode ser levado para outros modelos sem reescrever o cliente.

Com esse modelo mental, a forma mais rápida de confirmar a configuração é uma única chamada curl.

Sua primeira requisição curl executável

Antes de escrever qualquer código de aplicação, confirme que sua chave é válida e que você consegue acessar a API. Um comando curl avulso é a forma mais barata de separar problemas de autenticação de problemas de payload.

Primeiro, exporte sua chave para que ela não fique registrada literalmente no histórico do shell:

export HIAPI_API_KEY="your-api-key-here"

Em seguida, envie uma tarefa mínima de texto para vídeo:

curl -sS -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A slow aerial shot over a fog-covered pine forest at sunrise",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Uma resposta bem-sucedida retorna um objeto JSON com o identificador da tarefa e o status. A estrutura é mais ou menos assim:

{
  "id": "task_abc123xyz",
  "status": "queued",
  "model": "minimax-h3",
  "created_at": "2024-01-01T00:00:00Z"
}

Observe que ainda não há URL de vídeo. Isso é esperado — a tarefa apenas foi aceita. Os nomes de campo na sua resposta real podem variar um pouco em relação ao exemplo acima; leia o corpo da resposta em vez de presumir, e registre o conteúdo completo durante o desenvolvimento.

O que cada parte da requisição faz

  • URL aponta para o recurso de geração de vídeo na plataforma HiAPI. Todas as chamadas de modelo compartilham essa base, e é por isso que trocar de modelo é só alterar o payload, não reescrever o código.
  • Authorization: Bearer carrega sua chave de API. É a fonte mais comum de falha, então verifique isso primeiro quando algo der errado.
  • Content-Type: application/json é obrigatório. Sem ele, o servidor pode rejeitar ou interpretar mal o corpo da requisição.
  • model seleciona explicitamente o minimax-h3. Nunca o omita — a plataforma roteia com base nesse valor.
  • prompt é a instrução criativa. Seja específico sobre o sujeito, o movimento de câmera e a iluminação; prompts vagos geram vídeos vagos.
  • duration e aspect_ratio restringem a saída. Mantenha-os dentro dos limites suportados pelo modelo; valores fora da faixa são erros de validação de payload, não falhas do servidor.

Confirme que a tarefa existe

Logo após o envio, consulte a tarefa uma vez para provar que o ID é válido:

curl -sS "https://api.hiapi.ai/v1/tasks/task_abc123xyz" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Substitua task_abc123xyz pelo ID da resposta de envio. Se isso retornar um status, então sua chave, o endpoint e o handle da tarefa estão corretos — você já pode passar para o Python.

Vale criar dois hábitos agora: executar curl com -sS para que os erros apareçam em vez de serem silenciosamente engolidos, e sempre colocar aspas na URL. Expansão inesperada do shell em payloads JSON é uma armadilha de depuração que consome muito mais tempo do que as próprias aspas.

Construindo a mesma requisição em Python

A chamada curl provou o contrato; Python é onde você constrói algo reutilizável. Em vez de pular direto para o loop de consulta, comece com uma classe de cliente pequena que trate envio e obtenção de resultado como dois métodos claros. Essa separação mantém a lógica assíncrona fora da sua camada de transporte.

Use requests (ou httpx se preferir assíncrono); o formato é o mesmo nos dois casos.

import os
import time
import requests

BASE_URL = "https://api.hiapi.ai/v1"

class MiniMaxH3Client:
    def __init__(self, api_key: str | None = None):
        self.api_key = api_key or os.environ["HIAPI_API_KEY"]
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        })

    def submit(self, prompt: str, duration: int = 5,
               aspect_ratio: str = "16:9", **extra) -> str:
        payload = {
            "model": "minimax-h3",
            "prompt": prompt,
            "duration": duration,
            "aspect_ratio": aspect_ratio,
            **extra,
        }
        resp = self.session.post(
            f"{BASE_URL}/video/generations",
            json=payload,
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()
        return data["id"]

Há algumas escolhas deliberadas que vale destacar.

Use uma session, não requests puro. Reutilizar requests.Session mantém a conexão ativa entre as chamadas de envio e de consulta, o que importa quando você consulta repetidamente o mesmo host. Também centraliza os cabeçalhos, então o cabeçalho de autenticação é definido apenas uma vez.

Defina timeout rígido no envio. Para uma requisição que deveria retornar quase imediatamente, trinta segundos é folgado. Sem timeout, oscilações de rede deixam seu processo pendurado indefinidamente. Nunca faça uma chamada remota de API sem timeout.

Chame raise_for_status() antes de fazer parsing. O corpo de uma resposta não-2xx costuma ter formato diferente do de uma resposta de sucesso. Verificar o código de status primeiro significa que seu tratamento de erro lê uma mensagem de erro bem formada, em vez de quebrar ao falta a chave id.

Repasse com **extra. Opções específicas de modelo evoluem. Repassar argumentos nomeados extras permite experimentar novos parâmetros sem editar a assinatura do método a cada vez.

Usando

client = MiniMaxH3Client()
task_id = client.submit(
    "A slow aerial shot over a fog-covered pine forest at sunrise"
)
print(f"submitted: {task_id}")

Esse é todo o caminho de envio. O cliente retorna uma string — o handle da tarefa — e nada mais. Resista à tentação de fazer submit também esperar pelo resultado. Misturar envio e espera em um único método torna as retentativas ambíguas: em caso de falha, você não consegue saber se a tarefa foi criada, então corre o risco de gerar duplicatas. Mantenha-os separados e deixe a política para quem chama.

Consultando resultados sem bombardear a API

A consulta é a parte mais fácil de escrever descuidadamente. Um loop while True ingênuo, sem intervalo, dispara centenas de requisições para uma tarefa que leva dois minutos, e continua fazendo isso mesmo depois que a tarefa já falhou.

Um loop de consulta correto tem quatro responsabilidades: verificar o status, esperar, parar em estado terminal e finalmente desistir.

TERMINAL = {"succeeded", "failed", "cancelled"}

def wait_for(self, task_id: str, interval: float = 3.0,
             max_wait: float = 600.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        resp = self.session.get(f"{BASE_URL}/tasks/{task_id}", timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status", "unknown")
        if status in TERMINAL:
            return data
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish in {max_wait}s")

Escolhendo o intervalo

Para geração de vídeo, um intervalo fixo de alguns segundos é um padrão razoável. Tarefas não ficam prontas nos primeiros segundos — carregar o modelo e codificar quadros leva tempo real — então consultar a cada 200 ms só gera carga sem retorno. Se quiser ser educado e eficiente ao mesmo tempo, use backoff exponencial com teto: comece com um ou dois segundos, multiplique por cerca de 1,5 a cada rodada até chegar a cinco ou dez segundos, e mantenha esse valor. Consultas iniciais capturam falhas rápidas; consultas posteriores mantêm o custo baixo durante renderizações longas.

Parando corretamente

Trate qualquer status não reconhecido como não terminal e continue esperando — mas apenas até certo limite. Dois critérios de parada importam:

  • Estados terminais. Retorne imediatamente em caso de sucesso. Em caso de falha, exponha a mensagem de erro da resposta em vez de retornar um resultado vazio; o motivo importa para seus logs.
  • Orçamento de tempo real. Use um relógio monotônico, não o relógio de parede, para que ajustes do relógio do sistema não façam seu loop sair cedo ou rodar para sempre. Escolha um teto confortavelmente acima da tarefa mais longa realista para a duração e resolução que você usa, e trate atingi-lo como um erro operacional que exige alerta.

Retornando o resultado

Quando o status é termina com sucesso, a resposta traz a URL do vídeo gerado. Baixe-a logo — URLs de resultado costumam ter prazo de validade — e, se precisar de acesso persistente, armazene-a no seu próprio object storage. Não entregue a URL do fornecedor diretamente ao usuário final presumindo que ela existirá para sempre.

Uma dica prática: registre em nível de debug o ID da tarefa, o status e o tempo decorrido de cada consulta, e em nível de info o resultado terminal. Quando uma tarefa demorar mais que o esperado, essa linha do tempo é a diferença entre cinco minutos de diagnóstico e uma hora de adivinhação.

Formatos de requisição para texto para vídeo e imagem para vídeo

Os dois modos de geração compartilham a maior parte do payload. A diferença está na entrada criativa, e essa diferença tem impacto posterior no tipo de falha que você deve esperar.

Texto para vídeo

Este é o formato mostrado nas seções anteriores: prompt mais restrições de saída. O modelo inventa tudo — composição, movimento, iluminação e detalhes do sujeito. Seu payload carrega:

  • model: minimax-h3
  • prompt: descrição da cena
  • duration, aspect_ratio e quaisquer outros controles de saída

Como não há nada que ancore a geração, a qualidade do prompt domina o resultado. Descreva o comportamento da câmera ("dolly-in lento", "plano fixo em tripé") e a iluminação ("luz de fundo na hora dourada"), em vez de empilhar adjetivos sobre qualidade. Adjetivos vagos de alto nível ajudam pouco; descrições físicas específicas ajudam muito.

Imagem para vídeo

A variante imagem para vídeo adiciona uma referência de imagem de origem à mesma requisição. Normalmente você fornece uma URL de imagem ou um identificador de recurso enviado em um campo de imagem ao lado do prompt, e o modelo anima a partir desse quadro inicial.

client.submit(
    "Gentle wind moves the hair, subtle camera push forward",
    duration=5,
    image_url="https://example.com/portraits/source.jpg",
)

O prompt agora desempenha um papel diferente: orienta movimento e câmera, não conteúdo, porque o conteúdo visual já foi fixado pela imagem. Escrever uma descrição completa da cena costuma ser contraproducente — o modelo não consegue adicionar elementos que não estão na imagem. Mantenha o prompt de movimento curto e específico.

Consulte a referência de requisição para saber os nomes exatos de campos e formatos de imagem aceitos no modo imagem, bem como as faixas válidas de duração e proporção nos dois modos. Essas restrições são exatamente as que geram erros de validação de payload, então lê-las uma vez economiza uma rodada de depuração depois.

Uma regra prática útil

Escolha texto para vídeo quando precisar de cenas novas — B-roll, trechos de clima, visualização de conceitos. Escolha imagem para vídeo quando a consistência importar: animar fotos de produto, dar vida a retratos de personagens ou transformar quadros de storyboard em planos em movimento. O modo é uma diferença de payload, não de integração, então uma única classe de cliente que aceita um parâmetro opcional de imagem atende aos dois.

Depurando erros comuns

Quando uma chamada minimax-h3 dá errado, a causa quase sempre está em um de quatro lugares. Investigue nesta ordem.

1. Autenticação

Sintoma: resposta 401 ou 403, ou corpo de erro dizendo que as credenciais são inválidas.

  • Confirme que o cabeçalho Authorization existe e está no formato Bearer <key>, com um espaço no meio.
  • Verifique se a variável de ambiente realmente tem um valor — uma quebra de linha acidental colada na variável quebra o cabeçalho de um jeito invisível nos logs.
  • Verifique se a chave pertence ao mesmo projeto HiAPI que você espera e se não foi rotacionada.

O teste mais rápido: rode de novo o curl bruto anterior. Se o curl funciona e o Python não, o bug está no seu cliente, não na sua conta.

2. Payload malformado

Sintoma: resposta 400 ou 422, ou mensagem de validação nomeando um parâmetro.

  • Confirme Content-Type: application/json e que o corpo é JSON válido — vírgula final sobrando é o culpado clássico.
  • Verifique se model é exatamente minimax-h3.
  • Confirme que duration e aspect_ratio estão dentro das faixas suportadas pelo modelo.
  • No modo imagem, confirme que a referência de imagem está acessível e em formato aceito.

Leia a mensagem de erro literalmente. Erros de validação normalmente indicam o campo infrator; desenvolvedores muitas vezes passam por cima disso e começam a reescrever partes irrelevantes do payload.

3. Consulta que nunca termina

Sintoma: status continua em fila ou processando depois de um tempo razoável, ou o loop roda para sempre.

  • Registre a resposta completa de status — o valor de status pode não ser o que seu código presume.
  • Verifique o campo que você lê. Se seu conjunto de estados terminais verifica "completed", mas a API retorna "succeeded", seu loop roda eternamente. Imprima uma resposta bruta no início do desenvolvimento.
  • Confirme que o ID da tarefa foi copiado exatamente, sem truncamento ou espaços.
  • Adicione um prazo de tempo real; um loop travado sem teto é bug do seu código, não da API.

4. Timeouts e erros de rede transitórios

Sintoma: erros de conexão, timeouts de leitura ou respostas 5xx no envio ou na consulta.

  • Garanta que toda chamada passe um timeout explícito — em muitos clientes o padrão é nenhum, o que significa que um socket pendurado pode bloquear para sempre.
  • Distinga timeout de conexão de timeout de leitura; um envio que estourou no timeout de leitura pode na verdade ter criado a tarefa. Se houver um request ID retornado, registre-o a partir dos cabeçalhos da resposta e verifique se a tarefa apareceu antes de reenviar às cegas.
  • Para 5xx na consulta, tente novamente — provavelmente a tarefa está bem. Para 5xx no envio, verifique se a tarefa não foi criada para evitar geração duplicada.

Um hábito rápido de triagem: mantenha um arquivo curl de rascunho ao lado do projeto, com comandos de envio e consulta pré-preenchidos a partir de variáveis de ambiente. Reproduzir qualquer bug fora do código da aplicação leva segundos e mostra imediatamente se o problema é de transporte ou de lógica.

Deixando pronto para produção

Um script executável não é um serviço executável. Tarefas de vídeo são lentas o bastante para que o tráfego de produção se sobreponha, faça retentativas e, ocasionalmente, falhe de formas que uma execução manual nunca revela. Quatro padrões carregam a maior parte do peso.

Retentativas com backoff — mas só onde é seguro

A política de retentativa depende de qual chamada falhou:

  • Consulta é segura para retentar por natureza. Uma verificação de status que falha não tem efeitos colaterais, então retente com backoff exponencial e jitter, limitado a algumas tentativas.
  • Envio não pode ser retentado às cegas. Um timeout não significa que a tarefa não foi criada. Antes de reenviar, verifique se já existe uma tarefa para aquela requisição (usando o request ID dos cabeçalhos de resposta, se disponível, ou uma janela curta de reconciliação). Alternativamente, torne seus envios idempotentes cacheando o ID da tarefa por hash do payload, para que uma requisição repetida retorne a tarefa existente em vez de iniciar uma nova renderização.
  • Falhas de nível de modelo — estado terminal failed — normalmente não devem ser retentadas automaticamente com o mesmo payload. Entradas iguais tendem a falhar do mesmo jeito. Registre, alerte e deixe uma pessoa ou um prompt revisado assumir.

Adicione jitter a cada espera de backoff. Sem ele, um grupo de workers retentando em sincronia cria picos sincronizados, piorando uma situação ruim.

Registre o ID da tarefa em todo lugar

O ID da tarefa é o único vínculo persistente entre o seu sistema e o vídeo gerado. No momento em que o envio é bem-sucedido, grave-o nos logs com campos estruturados — task_id, modelo, duração, timestamp de envio. Quando um usuário relatar um vídeo perdido, buscar pelo task ID localiza o histórico completo em segundos. Registre também o status terminal e o tempo decorrido, para responder "quanto tempo isso costuma levar?" com dados, não com memória.

Defina um orçamento explícito de timeout

Pense em termos de orçamento total da operação, não apenas no timeout de cada requisição. A tarefa tem três fases — envio, espera e download — e cada uma precisa de limites. Uma estrutura razoável:

  • Timeouts curtos nas requisições de envio e consulta, para detectar conexões mortas rapidamente.
  • Um teto total de tempo real para a consulta, dimensionado para a duração e a resolução mais longas que você suporta, com folga.
  • Download limitado com escrita em streaming, para que arquivos grandes não esgotem a memória nem travem o worker.

Quando o orçamento acabar, faça a tarefa falhar de forma limpa, libere a vaga de concorrência e reporte um erro claro. Falhas previsíveis são melhores do que requisições penduradas até a plataforma reiniciar o contêiner.

Separe envio de consumo

O design de enviar primeiro e consultar depois mapeia naturalmente para uma arquitetura de filas: seu handler Web envia e retorna o ID da tarefa, um worker em background consulta e armazena o resultado, e o cliente consulta seu endpoint de status. Isso desacopla a latência voltada ao usuário do tempo de renderização, facilita impor limites de concorrência e garante que picos de envio não esgotem o pool de threads da sua camada Web.

Acertando esses quatro pontos, o formato assíncrono do minimax-h3 trabalha a seu favor em vez de contra: tarefas são rastreadas, retentativas são seguras, falhas são visíveis e nada fica pendurado indefinidamente.

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