Tutorial da API MiniMax H3 em chinês: texto para vídeo, primeiro e último quadro e referência multimodal

O MiniMax H3 é o modelo generativo de vídeo multimodal de uso geral da MiniMax. Ele consegue compreender materiais de texto, imagem, vídeo e áudio e gerar vídeos curtos com som nativo. Ao integrar através do HiAPI, o ID do modelo é fixo em minimax-h3, e os modelos de imagem, vídeo e áudio usam a mesma interface de tarefas assíncronas.

Se você só quer criar um vídeo curto a partir de uma frase de comando, basta enviar prompt. Se a aparência do produto, as imagens da marca ou o início e o fim do plano forem mais importantes, os modos de primeiro e último quadro e de referência multimodal do H3 valem mais a pena. O modelo atualmente suporta saídas de 4 a 15 segundos, 2K nativo e proporções como 21:9, 16:9, 4:3, 1:1, 3:4 e 9:16. As opções disponíveis concretas devem ser consultadas na página do modelo MiniMax H3 e na documentação de parâmetros da API.

Que problemas o MiniMax H3 é adequado para resolver

Ele é bastante adequado para tarefas de vídeo curto que exigem controle simultâneo da relação entre imagem, ação e som. Por exemplo, criar um vídeo de apresentação com movimento de câmera para uma página de produto, manter a mesma atmosfera visual dos materiais da marca, ou trazer para um novo plano o ritmo de um vídeo de referência, o sujeito de uma imagem de referência e um áudio de referência ao mesmo tempo.

Para equipes de e-commerce, publicidade e produtos, o valor do H3 não é apenas "fazer a imagem se mover". Quando há materiais de referência, o ponto principal é descrever claramente o que não pode mudar, como o formato do produto, a posição do Logo, a identidade do sujeito, o ângulo da câmera e a iluminação; e descrever separadamente o que precisa mudar, como ações, fundo, avanço de câmera ou diálogo. Assim, na hora da validação posterior, você saberá qual parte saiu do esperado.

Um modelo, três fluxos de trabalho comuns

Fluxo de trabalho	Cenários adequados	Entradas principais
Texto para vídeo	Gerar novas imagens a partir de roteiro, storyboard ou uma ideia	prompt
Controle de primeiro e último quadro	Controlar o estado do produto ou a mudança de cena no início e no fim do plano	first_frame_image, opcionalmente last_frame_image
Vídeo com referência multimodal	Referenciar simultaneamente produto, pessoa, ritmo de câmera ou material de áudio	image_urls, video_urls, audio_urls

O controle de primeiro e último quadro e a referência multimodal são dois modos diferentes e não podem ser misturados em uma mesma requisição. Ao usar o último quadro, é obrigatório fornecer também o primeiro quadro. A referência multimodal permite enviar no máximo 5 imagens, 3 vídeos e 3 áudios; o áudio não pode ser usado como entrada isolada, sendo necessário fornecer ao menos uma imagem ou um vídeo de referência. Cada vídeo e cada áudio de referência tem de 2 a 15 segundos, com total não superior a 15 segundos.

Primeiro, execute uma tarefa mínima com texto para vídeo

Abaixo está um exemplo de plano de produto de 5 segundos em 16:9. A criação bem-sucedida da tarefa significa apenas que o servidor recebeu a requisição; o data.taskId na resposta serve para consultar o status posteriormente.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "input": {
      "prompt": "Uma caneca de café azul-escuro fosco sobre uma mesa de pedra cinza-claro. A câmera avança lentamente a partir de um plano médio, a luz da manhã entra pela esquerda, o corpo da caneca permanece imóvel, o fundo fica desfocado, sem texto.",
      "duration": 5,
      "resolution": "2K",
      "aspect_ratio": "16:9",
      "watermark": false
    }
  }'

Para depuração local, use GET /v1/tasks/{taskId} para consultar o resultado. Em ambiente de produção, é mais adequado definir callback.url no nível superior da requisição e fazer com que seu serviço trate a idempotência por taskId. Avalie o status somente depois que a tarefa atingir o estado final: em success, baixe output[].url; em fail, corrija a entrada com base na mensagem de erro, sem repetir cegamente a mesma requisição inválida.

Como usar materiais de referência de forma significativa

O primeiro e o último quadro são adequados para tarefas em que "a câmera vai de A até B". Por exemplo, um vídeo de lançamento de produto que começa com um abajur apagado e termina com a luz quente iluminando a mesa. Nesse caso, o primeiro quadro fixa o ponto de partida, o último quadro fixa o ponto de chegada, e o prompt só precisa explicar as ações, o movimento de câmera e as mudanças de iluminação que ocorrem no meio.

A referência multimodal é mais adequada para controle contínuo de marca ou personagem. A imagem principal do produto pode ir em image_urls, a referência de ritmo de câmera em video_urls, e a referência de música ou atmosfera em audio_urls. O prompt deve explicitar o papel de cada tipo de material, por exemplo: "Mantenha a aparência da bolsa e a posição do fecho metálico da imagem de referência, siga o ritmo de avanço horizontal do vídeo de referência e gere um vídeo de apresentação de produto tranquilo".

Não empilhe todos os materiais de uma vez. Cada referência adicionada aumenta as restrições que o modelo precisa compreender. Primeiro valide a preservação da aparência com uma imagem do sujeito e depois acrescente referências de câmera ou áudio; assim fica mais fácil localizar problemas.

Que informações o prompt deve esclarecer

Um prompt de vídeo reutilizável normalmente inclui quatro partes: sujeito, ação, câmera e som ou ambiente. O sujeito deve explicitar as informações visuais que não podem mudar, a ação deve descrever o evento que ocorre, a câmera deve descrever o posicionamento e o movimento, e o som deve indicar se há diálogo, som ambiente ou atmosfera musical.

Por exemplo, ao criar um anúncio de produto, você pode escrever: "Mantenha inalterados o estojo branco de fones de ouvido, a carcaça laranja e a marca NOMA da imagem de referência. A câmera avança lentamente a partir de um plano médio sobre a mesa, o estojo se abre e os dois fones permanecem no lugar. Luz natural da janela, som ambiente baixo, sem narração, sem texto adicional." Isso é mais fácil de validar do que escrever apenas "faça um anúncio bonito de fones de ouvido".

Antes de colocar o H3 no fluxo de trabalho de produção

Recomenda-se primeiro fazer uma validação em pequena escala com três casos: um vídeo puramente gerado a partir de texto, um com controle de primeiro e último quadro e um vídeo com referência multimodal. Registre separadamente os materiais de entrada, a duração da saída, a transição de status, as mensagens de falha, as URLs dos produtos e a fatura final. Depois de confirmar que todos os modos funcionam de forma estável no seu produto, expanda para geração em lote.

O preço é calculado com base nos segundos de saída e na faixa atual; a página não fixa um preço unitário. Antes de enviar, consulte o preço atual na página do modelo MiniMax H3 em tempo real; após o lançamento, considere os registros de tarefas e a fatura da conta como referência. Para saber mais sobre tarefas assíncronas, callbacks e solução de erros, continue lendo o tutorial de integração do MiniMax H3.

Perguntas frequentes

Quais entradas o MiniMax H3 suporta?

Ele pode gerar vídeo apenas com texto, ou ser controlado por primeiro quadro, primeiro e último quadros, ou imagens, vídeos e áudios de referência. Os campos de primeiro e último quadro e de referência multimodal não podem ser misturados.

O MiniMax H3 consegue gerar som?

O MiniMax H3 suporta geração de vídeo com som nativo e também permite usar materiais de áudio no modo de referência multimodal. A referência de áudio precisa ser combinada com uma imagem ou um vídeo de referência.

Qual é a duração máxima de um vídeo?

A duração atual da saída é de 4 a 15 segundos. Vídeos longos normalmente devem ser gerados em vários planos e depois montados e concatenados no seu próprio fluxo de trabalho.

Devo usar polling ou callback?

Para depuração local e tarefas de baixa frequência, pode-se usar polling. Em ambiente de produção, recomenda-se usar callback.url para receber a notificação de estado final e manter a consulta de detalhes da tarefa como mecanismo de compensação em caso de falha do callback.

Ver MiniMax H3, ler a documentação de parâmetros da API ou obter uma API Key.