Tutorial
Como chamar o minimax-h3-max-turbo de texto para vídeo via API do HiAPI
- 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:
- 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.
- 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.
- 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.
Authorizationcom A maiúsculo,Bearerseguido 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.durationeresolution—— 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=payloaddefine o corpo e o tipo de conteúdo ao mesmo tempo; não serialize manualmente de novo.timeout=30limita 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 →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio