Blogue

Tutorial

Como chamar o minimax-h3-max-turbo de texto para vídeo via API do HiAPI

Nov 12, 2026
Arte de capa: uma seção transversal mineral facetada e plana em tons profundos de petróleo e azul-petróleo, como uma prancha impressa de gemologia, sobre um fundo escuro.
Modelo
minimax-h3-max-turbo
Nesta página

O que este endpoint faz e quando usá-lo

minimax-h3-max-turbo/text-to-video é o endpoint de modelo de texto para vídeo exposto pela API do HiAPI. Você envia um prompt de texto descrevendo a cena desejada, além de alguns parâmetros que controlam o formato da saída, e o HiAPI retorna o vídeo gerado. Este modelo é ideal quando você tem uma descrição textual e nenhum material de origem: clipes de marketing, tomadas de transição para redes sociais, pré-visualização de storyboard, vídeos de fundo em loop para aplicativos ou geração em lote de variações de um mesmo conceito criativo.

Antes de escrever código, algumas características merecem atenção:

  • É um endpoint generativo, não um template. A saída é previsível apenas na estrutura (você recebe um vídeo); o conteúdo em si não é previsível. Trate cada tarefa como uma nova renderização e projete seus prompts pensando em reutilização.
  • É assíncrono. A chamada de envio não retorna diretamente os bytes do vídeo final. Você recebe primeiro um identificador de tarefa e depois consulta o resultado. Qualquer integração que assuma resposta síncrona falhará no primeiro timeout.
  • A saída é determinada pelos parâmetros da requisição. Duração e resolução alteram o custo de renderização e o tempo real de execução, portanto os parâmetros que você escolhe também são decisões de latência e orçamento.
  • Não é necessário mídia de origem. Você não precisa enviar vídeo ou imagem; o prompt e os parâmetros são toda a superfície de entrada.

Quando usar outra solução? Se você já tem material e quer reestilizar ou estender, este não é o endpoint adequado. Se você precisa de controle quadro a quadro sobre movimento de câmera ou composição precisa, um prompt textual será frouxo demais. E se você só precisa de uma imagem estática, o endpoint de texto para imagem é mais barato e mais rápido. Use minimax-h3-max-turbo/text-to-video quando o prompt for suficiente como especificação de cena.

O restante deste guia aborda, em ordem, autenticação, chamada curl executável, chamada equivalente em Python, ciclo de vida da tarefa, parâmetros principais, os erros que você encontrará e as etapas de robustez antes de ir para produção.

Pré-requisitos e autenticação

Antes da primeira requisição, você precisa de três coisas:

  1. Uma chave de API da conta HiAPI. Trate-a como segredo: carregue de variável de ambiente, nunca faça commit no repositório e rotacione imediatamente em caso de vazamento.
  2. A URL base do HiAPI. Todas as chamadas deste guia vão para o mesmo host base; o modelo é selecionado pelo segmento de caminho, não por domínio distinto por modelo.
  3. Um cliente HTTP. curl para testes rápidos, e qualquer biblioteca padrão ou cliente HTTP para o código de serviço.

Como a chave é transmitida

O HiAPI autentica requisições por meio de um bearer token no cabeçalho Authorization. O formato é sempre o mesmo:

export HIAPI_API_KEY="your_api_key_here"
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Dois hábitos economizam muito tempo de depuração:

  • A grafia do cabeçalho deve ser exata. Authorization com A maiúsculo, Bearer seguido de um espaço e então a chave. A falta de um espaço é a causa mais comum de 401 misterioso.
  • Sempre envie Content-Type: application/json. Servidores que esperam JSON rejeitam ou interpretam mal corpos de requisição sem esse cabeçalho, e o erro que você recebe costuma indicar que um campo está ausente, em vez da causa real.

Valide antes de desenvolver

Não comece pelo endpoint de vídeo. Faça primeiro uma chamada barata e rápida para confirmar que a chave e a URL base resolvem corretamente e só depois continue. Se essa verificação de sanidade falhar, nada downstream funcionará, e você estará depurando no nível errado. Mantenha a chave em um único lugar do repositório — um pequeno módulo cliente — para que a rotação futura exija apenas uma linha.

Requisição curl executável

A chamada de envio envia o prompt e os parâmetros como corpo JSON para o caminho do modelo. Segue a chamada mínima executável:

curl -sS -X POST "$HIAPI_BASE_URL/minimax-h3-max-turbo/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Ao amanhecer, um lento travelling aéreo avança sobre uma floresta de pinheiros enevoada, luz volumétrica suave, cinematográfico",
    "duration": 5,
    "resolution": "720p"
  }'

O papel de cada parte:

  • -X POST —— tarefas de geração são criadas via POST.
  • URL —— host base mais o caminho minimax-h3-max-turbo/text-to-video. Mantenha o host base em uma variável para que teste e produção apontem para o mesmo caminho de código.
  • Authorization —— o bearer token descrito na seção anterior.
  • Content-Type —— declara o corpo JSON.
  • prompt —— a única entrada criativa obrigatória. Escreva como descrição de cena: sujeito, comportamento de câmera, iluminação e atmosfera. Frases nominais curtas produzem resultados ambíguos; uma ou duas frases com direção visual concreta funcionam muito melhor.
  • duration e resolution —— parâmetros que controlam o formato da saída, detalhados em seção própria abaixo.

Use -sS para deixar o curl silencioso mas ainda imprimir erros e, na fase de exploração, uma ferramenta de pretty-print para exibir a resposta. A resposta é um JSON contendo o identificador da tarefa; guarde-o, pois será necessário para consultar o vídeo concluído. Não espere que essa resposta contenha os bytes do vídeo.

Se quiser ver exatamente o que foi enviado durante a depuração, adicione -v para saída verbosa, mas remova-a antes de compartilhar logs, pois a saída verbosa pode conter cabeçalhos.

Requisição equivalente em Python

A versão Python é a mesma requisição, apenas carregando a chave do ambiente e interpretando a resposta. Segue um pequeno cliente reutilizável:

import os
import time
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

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

MODEL_PATH = "/minimax-h3-max-turbo/text-to-video"


def submit_video(prompt: str, duration: int = 5, resolution: str = "720p") -> dict:
    payload = {"prompt": prompt, "duration": duration, "resolution": resolution}
    resp = requests.post(
        f"{BASE_URL}{MODEL_PATH}",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    job = submit_video(
        "Ao amanhecer, um lento travelling aéreo avança sobre uma floresta de pinheiros enevoada, luz volumétrica suave, cinematográfico"
    )
    print(job)

Pontos de atenção ao adaptar:

  • json=payload define o corpo e o tipo de conteúdo ao mesmo tempo; não serialize manualmente de novo.
  • timeout=30 limita o tempo da chamada de envio. O envio é rápido, a renderização não, por isso o timeout aqui é curto e a espera fica a cargo da consulta.
  • raise_for_status() converte respostas não 2xx em exceções, fazendo falhas de autenticação e validação aparecerem imediatamente, em vez de retornar silenciosamente um corpo de erro que você depois interpretaria por engano como tarefa.
  • Retorne o JSON interpretado como dicionário e extraia o identificador da tarefa no ponto de chamada. Assim a função auxiliar permanece genérica e o código de orquestração decide o que fazer com ele.

Se você usa uma stack assíncrona, a mesma forma se aplica ao cliente HTTP escolhido: construa os cabeçalhos uma vez, faça POST do corpo, verifique o status e retorne o corpo interpretado.

Gerenciando o ciclo de vida de tarefas assíncronas

A geração leva tempo, por isso o endpoint é dividido em envio e consulta. O ciclo de vida é sempre: enviar, receber o identificador da tarefa, consultar a tarefa até que ela reporte um estado terminal e então obter a saída.

Envio

Envie o POST descrito acima e leia o identificador da tarefa na resposta. Registre-o imediatamente e associe-o ao seu próprio ID de requisição, para que depois, se a consulta falhar, você possa rastrear de volta ao prompt original.

Consulta com backoff

Não consulte em loop apertado. Comece com um intervalo curto e faça backoff:

def wait_for_job(job_id: str, max_wait: int = 600) -> dict:
    deadline = time.time() + max_wait
    interval = 2.0
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}{MODEL_PATH}/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        job = resp.json()
        status = job.get("status")
        if status in ("succeeded", "failed"):
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 15.0)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

Três detalhes tornam esse código confiável. Primeiro, prazo final: sempre desista em algum momento e lance timeout, em vez de consultar para sempre. Segundo, backoff com limite: comece com alguns segundos, multiplique gradualmente e limite o intervalo, assim você continua progredindo sem bombardear a API. Terceiro, tratamento de estados terminais: considere apenas sucesso e falha como terminais e retorne o objeto da tarefa para que o chamador ramifique.

Obtendo o resultado

Quando a tarefa reporta sucesso, a resposta traz a localização do vídeo final. Baixe ou faça streaming para seu próprio armazenamento o quanto antes e registre a URL junto com o ID da tarefa. Não assuma que o link é permanente nem busque o vídeo a cada iteração de consulta. Consulte o status da tarefa e obtenha o vídeo uma única vez ao sucesso.

Parâmetros de duração e resolução

Dois parâmetros da requisição determinam a saída e também o tempo de renderização e o custo da chamada.

duration

O comprimento do clipe gerado. Clipes mais longos aumentam o tempo de renderização proporcionalmente, o que significa janelas de consulta mais longas e maior probabilidade de acionar timeouts do cliente. Recomendações práticas:

  • Faça a duração corresponder ao caso de uso. Tomadas de transição para redes sociais são muito curtas; um fundo em loop só precisa ser longo o suficiente para repetir de forma aceitável. Gerar mais conteúdo do que será exibido é puro desperdício.
  • Comece pequeno ao iterar. Ajuste o prompt em durações curtas e depois renderize novamente o prompt vencedor com o comprimento final.
  • Lembre-se de que o custo cresce com o tamanho da saída. A cobrança é por comprimento de saída, portanto a duração é tanto uma alavanca criativa quanto orçamentária.

resolution

A qualidade espacial da saída. Resoluções mais altas trazem mais detalhe, mas consomem mais tempo de renderização e mais custo. Recomendações:

  • Escolha pela entrega, não pela ficha técnica. Se o vídeo aparecerá em um feed ou player pequeno, gerar acima dessa resolução não traz nenhum ganho.
  • Itere em baixa resolução, entregue em alta. Pré-visualize em resolução menor enquanto ainda ajusta o prompt e reenvie o prompt aprovado na resolução de entrega.
  • Configurações mais altas significam esperas mais longas. Defina o prazo da consulta para a maior combinação que você permite, não para a menor.

Mantenha esses dois valores no mesmo objeto de configuração, em vez de espalhados pelo código, para que a mudança de pré-visualização para produção seja uma edição intencional e visível, não um literal esquecido.

Depurando erros comuns

A maioria das falhas se enquadra em quatro categorias. Antes de alterar o código, associe o sintoma à categoria.

Falha de autenticação

401 significa que o HiAPI não aceita suas credenciais. Verifique em ordem: o cabeçalho Authorization está presente e escrito corretamente; há exatamente um espaço após Bearer; a chave é válida no momento e não pertence a outro projeto; a variável de ambiente foi realmente carregada (um caractere de nova linha no final ao colar a chave é um problema clássico). Confirme exibindo o comprimento da variável, não a chave em si.

Falha de validação

4xx que não seja 401 geralmente significa que o corpo da requisição está errado. Content-Type ausente ou diferente de application/json; prompt ausente ou vazio; duration ou resolution fora do conjunto permitido. Leia a mensagem de erro literalmente; ela normalmente aponta o campo problemático. Reproduza com a versão curl, pois ali nenhuma camada de biblioteca oculta o corpo da requisição.

Timeout

Há dois tipos distintos de timeout. Timeout de envio significa que o próprio POST não retornou, geralmente indicando caminho de rede ou timeout de cliente agressivo demais. Timeout de consulta significa que a tarefa não atingiu estado terminal antes do seu prazo; ou a renderização realmente leva mais tempo, ou seu prazo foi definido com configurações de pré-visualização em vez de produção. Para corrigir o segundo caso, aumente max_wait para durações e resoluções maiores, não reduza o intervalo de consulta.

Erros de consulta

Os mais sutis. Consultar sem dormir desperdiça cota e provoca rate limiting; consultar com intervalo fixo curto tem o mesmo efeito. Consultar um ID de tarefa errado geralmente acontece porque você reutilizou uma variável entre envios. Tratar estados intermediários como erro. E buscar a URL do vídeo a cada iteração em vez de uma vez ao sucesso. Registre o ID da tarefa e cada estado observado; a sequência dirá imediatamente qual desses casos ocorreu.

Lista de verificação de produção antes do lançamento

Passar de um script funcional para um serviço operando sem supervisão significa adicionar algumas camadas em torno da mesma requisição.

  • Retentativas com jitter. Retente erros de rede transitórios e respostas 5xx com backoff exponencial e randomização. Nunca retente erros de validação; eles falharão da mesma forma e consumirão cota.
  • Timeouts limitados em todos os lugares. Timeout curto no envio, prazo mais longo na consulta (definido pela maior duração e resolução que você permite) e timeout também no download do vídeo.
  • Logs estruturados. Registre seu ID de requisição, ID da tarefa, cada transição de estado observada e o resultado final, mas não registre a chave de API nem cabeçalhos completos. Quando algo der errado às três da manhã, esse log será sua única evidência.
  • Idempotência na sua camada. Mantenha um mapeamento do seu próprio ID de requisição para o ID da tarefa, para que retentativas do cliente não gerem silenciosamente uma segunda renderização.
  • Controle de custos. A cobrança é por comprimento de saída, então defina limites máximos de duração e resolução aceitos pelo serviço e mantenha pré-visualizações de prompt em configurações menores até que a renderização final seja aprovada por humano ou regra.
  • Higiene de chaves. Carregue chaves de um armazenamento de segredos, rotacione conforme cronograma e use chaves diferentes para teste e produção, para que uma chave de teste vazada não consuma o orçamento de produção.
  • Posse dos resultados. Assim que a tarefa tiver sucesso, copie o vídeo final imediatamente para armazenamento que você controla e trate a URL de entrega como link temporário.

Com isso implementado, o endpoint se torna uma dependência previsível, em vez de uma fonte de surpresas. Confirme as credenciais com a requisição curl acima, depois introduza o cliente Python no seu serviço e envolva-o com as verificações desta lista.

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