Pular para o conteúdo
Cadastre-se grátis
MiniMax H3

API de vídeo do MiniMax H3: geração e regeneração

Conecte o MiniMax H3 com sua BetterToken API Key e escolha campos, mídias e métodos de geração conforme o Model ID e a operação.

Você pode gerar vídeos a partir de texto, quadros inicial e final ou mídias de referência. Também pode regenerar seus próprios vídeos H3 de 768p que atendam aos requisitos para 2k. A regeneração aceita apenas o ID da tarefa de origem, sem novas URLs de mídia.

Prepare sua BetterToken API Key. A Base URL é https://bettertoken.ai/v1 e a autenticação usa Authorization: Bearer YOUR_API_KEY. Copie o Model ID exatamente, respeitando maiúsculas e minúsculas.

Cada request.json desta página segue o mesmo fluxo: solicite a cotação, confirme a criação, consulte o estado e baixe o vídeo. A cotação não inicia a geração; a criação envia uma tarefa paga. Consulte os preços atuais na model plaza.

Modelos e operações

A tabela lista as opções de cada operação. Consulte os valores padrão, as quantidades de mídia e as restrições de combinação em cada seção. Os tamanhos usam 1 MB = 1048576 bytes.

Model IDOperaçãoDuração (segundos)Nível de saídaProporçãoÁudioFunções de mídia
MiniMax-H3image_to_video4–15, incremento 1768p, 2kadaptiveprovider_defaultfirst_frame, last_frame, reference_image, reference_video, reference_audio
MiniMax-H3reference_to_video4–15, incremento 1768p, 2kadaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16provider_defaultreference_image, reference_video, reference_audio
MiniMax-H3text_to_video4–15, incremento 1768p, 2k21:9, 16:9, 4:3, 1:1, 3:4, 9:16provider_defaultNenhum
MiniMax-H3video_editHerdada da tarefa de origem2kadaptive (herdada)provider_defaultID da tarefa de origem

provider_default mantém a configuração de áudio do modelo, sem um seletor on / off. A proporção, a duração e as entradas da regeneração dependem da tarefa de origem.

Mídias de exemplo

Os exemplos de geração a partir de imagens e referências usam uma caneca de cerâmica azul sobre uma mesa branca. Você pode testar com a imagem de exemplo ou substituí-la primeiro por mídias HTTPS públicas que tenha direito de usar e que atendam aos limites desta página.

Imagem de referência para geração de vídeo: caneca de cerâmica azul sobre uma mesa branca

De texto para vídeo

MiniMax-H3

Use esta operação para gerar um vídeo quando tiver apenas uma descrição em texto.

Defina model com o Model ID desta seção e operation como text_to_video. Use apenas os campos de geração da tabela abaixo; coloque as mídias no array media.

CampoTipoObrigatórioOpções ou intervaloPadrão
audio.modestringNãoprovider_defaultprovider_default
duration.modestringNãofixedfixed
duration.secondsintegerNão4–15, incremento 1 s; apenas com duração fixa4
output.aspect_ratiostringSim21:9, 16:9, 4:3, 1:1, 3:4, 9:16Nenhum
output.formatstringNãomp4mp4
output.resolutionstringNão768p, 2k768p
promptstringSimStringNenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Esta operação não aceita mídias.

Restrições de combinação

  • duration.mode="fixed" exige duration.seconds. Ao informar fixed explicitamente, inclua também os segundos.

Exemplo de solicitação

Salve o JSON abaixo como request.json e siga o fluxo geral: solicite a cotação e confirme antes de criar a tarefa.

{
"model": "MiniMax-H3",
"operation": "text_to_video",
"prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "768p",
"aspect_ratio": "16:9"
}
}

Erros 422 comuns

Código de erro 422Solução
enum / range / stepAjuste os valores e o incremento conforme a tabela de campos desta seção.
unsupported_fieldRemova os campos que não constam na tabela desta operação.
requiresComplete os segundos, a proporção, o áudio ou as mídias conforme as restrições desta seção.

De imagem para vídeo

MiniMax-H3

Use esta operação para definir o quadro inicial ou os quadros inicial e final a partir de imagens.

Defina model com o Model ID desta seção e operation como image_to_video. Use apenas os campos de geração da tabela abaixo; coloque as mídias no array media.

CampoTipoObrigatórioOpções ou intervaloPadrão
audio.modestringNãoprovider_defaultprovider_default
duration.modestringNãofixedfixed
duration.secondsintegerNão4–15, incremento 1 s; apenas com duração fixa4
output.aspect_ratiostringNãoadaptiveadaptive
output.formatstringNãomp4mp4
output.resolutionstringNão768p, 2k768p
promptstringSimStringNenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
first_frameimage, opcional, no máximo 1jpg, jpeg, png, webp, heic, heifTamanho máximo: 30 MB; largura: 256–5760 px; altura: 256–5760 px
last_frameimage, opcional, no máximo 1jpg, jpeg, png, webp, heic, heifTamanho máximo: 30 MB; largura: 256–5760 px; altura: 256–5760 px
reference_imageimage, opcional, no máximo 9jpg, jpeg, png, webp, heic, heifTamanho máximo: 30 MB; largura: 256–5760 px; altura: 256–5760 px
reference_videovideo, opcional, no máximo 3mp4, movTamanho máximo: 50 MB; largura: 256–5760 px; altura: 256–5760 px; duração: 2–15 s; taxa de quadros mínima: 23.976 fps; máxima: 60 fps; duração total máxima desta função: 15 s
reference_audioaudio, opcional, no máximo 3wav, mp3Tamanho máximo: 15 MB; duração: 2–15 s; duração total máxima desta função: 15 s

A obrigatoriedade das mídias também depende das restrições de combinação abaixo.

Restrições de combinação

  • duration.mode="fixed" exige duration.seconds. Ao informar fixed explicitamente, inclua também os segundos.
  • Forneça pelo menos uma destas funções: first_frame, last_frame.
  • Não combine quadros inicial ou final com imagens, vídeos ou áudios de referência. Use a operação de imagem para vídeo para os quadros inicial e final, e a geração com referências para as mídias de referência.

Exemplo de solicitação

Salve o JSON abaixo como request.json e siga o fluxo geral: solicite a cotação e confirme antes de criar a tarefa.

{
"model": "MiniMax-H3",
"operation": "image_to_video",
"prompt": "Slowly move the camera closer to the blue ceramic mug. Preserve its shape and the white table.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "768p",
"aspect_ratio": "adaptive"
},
"media": [
{
"id": "first",
"type": "image",
"role": "first_frame",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

Erros 422 comuns

Código de erro 422Solução
enum / range / stepAjuste os valores e o incremento conforme a tabela de campos desta seção.
unsupported_fieldRemova os campos que não constam na tabela desta operação.
requiresComplete os segundos, a proporção, o áudio ou as mídias conforme as restrições desta seção.
mutually_exclusive_rolesUse os quadros inicial e final separadamente das mídias de referência.
count / media_roleAjuste as funções e quantidades conforme a tabela de mídias desta seção.
video_input_unsupportedVerifique a URL HTTPS pública, o Content-Type e o formato do arquivo e solicite uma nova cotação.

Geração com referências

MiniMax-H3

Use esta operação para preservar características do sujeito ou do movimento com mídias de referência.

Defina model com o Model ID desta seção e operation como reference_to_video. Use apenas os campos de geração da tabela abaixo; coloque as mídias no array media.

CampoTipoObrigatórioOpções ou intervaloPadrão
audio.modestringNãoprovider_defaultprovider_default
duration.modestringNãofixedfixed
duration.secondsintegerNão4–15, incremento 1 s; apenas com duração fixa4
output.aspect_ratiostringNãoadaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstringNãomp4mp4
output.resolutionstringNão768p, 2k768p
promptstringSimStringNenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
reference_imageimage, opcional, no máximo 9jpg, jpeg, png, webp, heic, heifTamanho máximo: 30 MB; largura: 256–5760 px; altura: 256–5760 px
reference_videovideo, opcional, no máximo 3mp4, movTamanho máximo: 50 MB; largura: 256–5760 px; altura: 256–5760 px; duração: 2–15 s; taxa de quadros mínima: 23.976 fps; máxima: 60 fps; duração total máxima desta função: 15 s
reference_audioaudio, opcional, no máximo 3wav, mp3Tamanho máximo: 15 MB; duração: 2–15 s; duração total máxima desta função: 15 s

A obrigatoriedade das mídias também depende das restrições de combinação abaixo.

Restrições de combinação

  • duration.mode="fixed" exige duration.seconds. Ao informar fixed explicitamente, inclua também os segundos.
  • Forneça pelo menos uma destas funções: reference_image, reference_video, reference_audio.
  • Não combine quadros inicial ou final com imagens, vídeos ou áudios de referência. Use a operação de imagem para vídeo para os quadros inicial e final, e a geração com referências para as mídias de referência.

Exemplo de solicitação

Salve o JSON abaixo como request.json e siga o fluxo geral: solicite a cotação e confirme antes de criar a tarefa.

{
"model": "MiniMax-H3",
"operation": "reference_to_video",
"prompt": "Create a product video of the blue ceramic mug in the reference image. Keep its shape and color.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "768p",
"aspect_ratio": "adaptive"
},
"media": [
{
"id": "reference",
"type": "image",
"role": "reference_image",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

Erros 422 comuns

Código de erro 422Solução
enum / range / stepAjuste os valores e o incremento conforme a tabela de campos desta seção.
unsupported_fieldRemova os campos que não constam na tabela desta operação.
requiresComplete os segundos, a proporção, o áudio ou as mídias conforme as restrições desta seção.
mutually_exclusive_rolesUse os quadros inicial e final separadamente das mídias de referência.
count / media_roleAjuste as funções e quantidades conforme a tabela de mídias desta seção.
video_input_unsupportedVerifique a URL HTTPS pública, o Content-Type e o formato do arquivo e solicite uma nova cotação.

Regenerar um vídeo

MiniMax-H3

Use esta operação se já tiver seu próprio vídeo H3 de 768p e quiser regenerá-lo para 2k mantendo o conteúdo original. Ela não aceita arquivos de vídeo arbitrários.

A tarefa de origem deve atender a todos estes requisitos:

  • Pertence à sua conta e tem o Model ID MiniMax-H3.
  • A geração foi concluída com sucesso e o vídeo ainda está disponível para download.
  • A saída está configurada como 768p.
  • Não passaram mais de 7 dias desde a criação da tarefa de origem.

O servidor também verifica o formato do vídeo de origem e retorna 422 video_regeneration_source_invalid se ele não atender aos requisitos. Solicite a cotação com o ID da tarefa de origem; não modifique o arquivo de vídeo para substituir essa tarefa.

Campo da solicitaçãoTipoObrigatórioValor
modelstringSimMiniMax-H3
operationstringSimvideo_edit
provider_options.hailuo.source_task_idstringSimID da sua tarefa de origem que atenda aos requisitos
watermarkbooleanNãofalse / true, padrão: false

Não envie prompt, duration, output, audio nem media. A regeneração herda o conteúdo e as entradas da tarefa de origem e produz 2k, adaptive, MP4.

Primeiro substitua REPLACE_WITH_YOUR_H3_TASK_ID pelo ID da sua tarefa de origem; depois solicite a cotação e crie a tarefa. Isso cria uma nova tarefa paga; use um novo arquivo de estado.

{
"model": "MiniMax-H3",
"operation": "video_edit",
"provider_options": {
"hailuo": {
"source_task_id": "REPLACE_WITH_YOUR_H3_TASK_ID"
}
}
}

Se a tarefa de origem não atender aos requisitos ou não existir, a cotação retorna 422 video_regeneration_source_invalid, com field_path igual a provider_options.hailuo.source_task_id. O exemplo abaixo demonstra esse erro e não serve para gerar vídeos:

{
"model": "MiniMax-H3",
"operation": "video_edit",
"provider_options": {
"hailuo": {
"source_task_id": "video_DOES_NOT_EXIST"
}
}
}

Documentação oficial

Ao chamar a BetterToken, use os campos desta página e a operação correspondente do catálogo de modelos em tempo real.