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

API de vídeo do Wan: texto, imagens, referências e edição

Conecte o Wan 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, um quadro inicial ou mídias de referência, além de editar vídeos existentes. 3.0 e Prime aceitam três operações de geração; em 2.7, escolha um Model ID específico para texto para vídeo, imagem para vídeo, geração com referências ou edição.

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
wan2.7-i2vimage_to_video2–15, incremento 1720p, 1080pNão enviarprovider_defaultfirst_frame, last_frame, driving_audio
wan2.7-r2vreference_to_video2–15, incremento 1720p, 1080p16:9, 9:16, 1:1, 4:3, 3:4provider_defaultreference_image, reference_video
wan2.7-t2vtext_to_video2–15, incremento 1720p, 1080p16:9, 9:16, 1:1, 4:3, 3:4provider_defaultdriving_audio
wan2.7-videoeditvideo_edit2–15, incremento 1; aceita auto720p, 1080pNão enviarprovider_defaultbase_video
wan3.0-video-primeimage_to_video2–30, incremento 1; aceita auto480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, offfirst_frame, last_frame
wan3.0-video-primereference_to_video2–30, incremento 1; aceita auto480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, offreference_image, reference_video, reference_audio
wan3.0-video-primetext_to_video2–30, incremento 1; aceita auto480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, offNenhum
wan3.0-videoimage_to_video2–30, incremento 1; aceita auto480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, offfirst_frame, last_frame
wan3.0-videoreference_to_video2–30, incremento 1; aceita auto480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, offreference_image, reference_video, reference_audio
wan3.0-videotext_to_video2–30, incremento 1; aceita auto480p, 720p, 1080padaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16on, offNenhum

Em imagem para vídeo (wan2.7-i2v, e wan3.0-video / wan3.0-video-prime com adaptive) e em referência para vídeo com adaptive, o resultado segue a proporção da imagem de entrada; o nível de saída define o total de pixels, não dimensões fixas. Com a imagem de exemplo quadrada desta página, 720p retornou 960×960 e 480p retornou 640×640 nos nossos testes. Para um enquadramento horizontal ou vertical fixo, informe output.aspect_ratio explicitamente (wan2.7-i2v não aceita esse campo; use uma imagem de entrada com a proporção desejada).

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

O exemplo de edição usa um vídeo de um menino em uma praça urbana, de cerca de 5.04 segundos, 1280 × 720 e 24 fps. Ele é enviado como base_video, não como imagem de referência.

De texto para vídeo

wan2.7-t2v

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ão2–15, incremento 1 s; apenas com duração fixa5
output.aspect_ratiostringNão16:9, 9:16, 1:1, 4:3, 3:416:9
output.formatstringNãomp4mp4
output.resolutionstringNão720p, 1080p1080p
promptstringSimStringNenhum
provider_options.alibaba.prompt_extendbooleanNãotrue / false; controla a expansão do prompttrue
seedintegerNão0–2147483647, incremento 1; semente aleatória; aceita 0Nenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
driving_audioaudio, opcional, no máximo 1wav, mp3Tamanho máximo: 15 MB; duração: 2–30 s

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

A mídia opcional driving_audio é o áudio que orienta a geração e usa type="audio". É uma função diferente de reference_audio, usada na geração com referências.

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": "wan2.7-t2v",
"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": "720p",
"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.
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.

wan3.0-video-prime

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ãoon, offon
duration.modestringNãofixed, autofixed
duration.secondsintegerNão2–30, incremento 1 s; apenas com duração fixa5
output.aspect_ratiostringNãoadaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstringNãomp4mp4
output.resolutionstringNão480p, 720p, 1080p1080p
promptstringSimStringNenhum
provider_options.alibaba.prompt_extendbooleanNãotrue / false; controla a expansão do prompttrue
seedintegerNão0–2147483647, incremento 1; semente aleatória; aceita 0Nenhum
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.
  • Com duration.mode="auto", não envie duration.seconds.

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": "wan3.0-video-prime",
"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": "720p",
"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.
excludesRemova os campos que entrem em conflito com a duração automática ou o quadro final.

wan3.0-video

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ãoon, offon
duration.modestringNãofixed, autofixed
duration.secondsintegerNão2–30, incremento 1 s; apenas com duração fixa5
output.aspect_ratiostringNãoadaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstringNãomp4mp4
output.resolutionstringNão480p, 720p, 1080p1080p
promptstringSimStringNenhum
provider_options.alibaba.prompt_extendbooleanNãotrue / false; controla a expansão do prompttrue
seedintegerNão0–2147483647, incremento 1; semente aleatória; aceita 0Nenhum
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.
  • Com duration.mode="auto", não envie duration.seconds.

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": "wan3.0-video",
"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": "720p",
"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.
excludesRemova os campos que entrem em conflito com a duração automática ou o quadro final.

De imagem para vídeo

wan2.7-i2v

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ão2–15, incremento 1 s; apenas com duração fixa5
output.formatstringNãomp4mp4
output.resolutionstringNão720p, 1080p1080p
promptstringSimStringNenhum
provider_options.alibaba.prompt_extendbooleanNãotrue / false; controla a expansão do prompttrue
seedintegerNão0–2147483647, incremento 1; semente aleatória; aceita 0Nenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
first_frameimage, 1 (obrigatório)jpeg, jpg, png, bmp, webpTamanho máximo: 20 MB; largura: 240–8000 px; altura: 240–8000 px
last_frameimage, opcional, no máximo 1jpeg, jpg, png, bmp, webpTamanho máximo: 20 MB; largura: 240–8000 px; altura: 240–8000 px
driving_audioaudio, opcional, no máximo 1wav, mp3Tamanho máximo: 15 MB; duração: 2–30 s

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

A mídia opcional driving_audio é o áudio que orienta a geração e usa type="audio". É uma função diferente de reference_audio, usada na geração com referências.

Restrições de combinação

  • duration.mode="fixed" exige duration.seconds. Ao informar fixed explicitamente, inclua também os segundos.
  • Você deve fornecer first_frame.

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": "wan2.7-i2v",
"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": "720p"
},
"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.
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.

wan3.0-video-prime

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ãoon, offon
duration.modestringNãofixed, autofixed
duration.secondsintegerNão2–30, incremento 1 s; apenas com duração fixa5
output.aspect_ratiostringNãoadaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstringNãomp4mp4
output.resolutionstringNão480p, 720p, 1080p1080p
promptstringSimStringNenhum
provider_options.alibaba.prompt_extendbooleanNãotrue / false; controla a expansão do prompttrue
seedintegerNão0–2147483647, incremento 1; semente aleatória; aceita 0Nenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
first_frameimage, 1 (obrigatório)jpeg, jpg, png, bmp, webpTamanho máximo: 20 MB; largura: 240–8000 px; altura: 240–8000 px
last_frameimage, opcional, no máximo 1jpeg, jpg, png, bmp, webpTamanho máximo: 20 MB; largura: 240–8000 px; altura: 240–8000 px

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.
  • Com duration.mode="auto", não envie duration.seconds.
  • Forneça pelo menos uma destas funções: first_frame, last_frame.

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": "wan3.0-video-prime",
"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": "720p",
"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.
excludesRemova os campos que entrem em conflito com a duração automática ou o quadro final.
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.

wan3.0-video

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ãoon, offon
duration.modestringNãofixed, autofixed
duration.secondsintegerNão2–30, incremento 1 s; apenas com duração fixa5
output.aspect_ratiostringNãoadaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstringNãomp4mp4
output.resolutionstringNão480p, 720p, 1080p1080p
promptstringSimStringNenhum
provider_options.alibaba.prompt_extendbooleanNãotrue / false; controla a expansão do prompttrue
seedintegerNão0–2147483647, incremento 1; semente aleatória; aceita 0Nenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
first_frameimage, 1 (obrigatório)jpeg, jpg, png, bmp, webpTamanho máximo: 20 MB; largura: 240–8000 px; altura: 240–8000 px
last_frameimage, opcional, no máximo 1jpeg, jpg, png, bmp, webpTamanho máximo: 20 MB; largura: 240–8000 px; altura: 240–8000 px

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.
  • Com duration.mode="auto", não envie duration.seconds.
  • Forneça pelo menos uma destas funções: first_frame, last_frame.

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": "wan3.0-video",
"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": "720p",
"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.
excludesRemova os campos que entrem em conflito com a duração automática ou o quadro final.
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

wan2.7-r2v

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ão2–15, incremento 1 s; apenas com duração fixa5
output.aspect_ratiostringNão16:9, 9:16, 1:1, 4:3, 3:416:9
output.formatstringNãomp4mp4
output.resolutionstringNão720p, 1080p1080p
promptstringSimStringNenhum
provider_options.alibaba.prompt_extendbooleanNãotrue / false; controla a expansão do prompttrue
seedintegerNão0–2147483647, incremento 1; semente aleatória; aceita 0Nenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
reference_imageimage, opcional, no máximo 10jpeg, jpg, png, bmp, webpTamanho máximo: 20 MB; largura: 240–8000 px; altura: 240–8000 px
reference_videovideo, opcional, no máximo 5mp4, movTamanho máximo: 100 MB; largura: 240–4096 px; altura: 240–4096 px; duração: 1–15 s; taxa de quadros mínima: 16 fps; 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.

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": "wan2.7-r2v",
"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": "720p",
"aspect_ratio": "16:9"
},
"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.
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.

wan3.0-video-prime

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ãoon, offon
duration.modestringNãofixed, autofixed
duration.secondsintegerNão2–30, incremento 1 s; apenas com duração fixa5
output.aspect_ratiostringNãoadaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstringNãomp4mp4
output.resolutionstringNão480p, 720p, 1080p1080p
promptstringSimStringNenhum
provider_options.alibaba.prompt_extendbooleanNãotrue / false; controla a expansão do prompttrue
seedintegerNão0–2147483647, incremento 1; semente aleatória; aceita 0Nenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
reference_imageimage, opcional, no máximo 10jpeg, jpg, png, bmp, webpTamanho máximo: 20 MB; largura: 240–8000 px; altura: 240–8000 px
reference_videovideo, opcional, no máximo 5mp4, movTamanho máximo: 100 MB; largura: 240–4096 px; altura: 240–4096 px; duração: 1–15 s; taxa de quadros mínima: 16 fps; duração total máxima desta função: 15 s
reference_audioaudio, opcional, no máximo 5wav, mp3Tamanho máximo: 15 MB; duração: 1–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.
  • Com duration.mode="auto", não envie duration.seconds.
  • Forneça pelo menos uma destas funções: reference_image, reference_video, reference_audio.
  • Com vídeos de referência, a soma da duração total dos vídeos de entrada e da duração de saída não pode ultrapassar 30 segundos. Com duração automática, o limite de saída também depende do tempo restante.

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": "wan3.0-video-prime",
"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": "720p",
"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.
excludesRemova os campos que entrem em conflito com a duração automática ou o quadro final.
sum_lteReduza a duração total dos vídeos de referência ou a duração de saída para que a soma não ultrapasse 30 segundos.
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.

wan3.0-video

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ãoon, offon
duration.modestringNãofixed, autofixed
duration.secondsintegerNão2–30, incremento 1 s; apenas com duração fixa5
output.aspect_ratiostringNãoadaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstringNãomp4mp4
output.resolutionstringNão480p, 720p, 1080p1080p
promptstringSimStringNenhum
provider_options.alibaba.prompt_extendbooleanNãotrue / false; controla a expansão do prompttrue
seedintegerNão0–2147483647, incremento 1; semente aleatória; aceita 0Nenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
reference_imageimage, opcional, no máximo 10jpeg, jpg, png, bmp, webpTamanho máximo: 20 MB; largura: 240–8000 px; altura: 240–8000 px
reference_videovideo, opcional, no máximo 5mp4, movTamanho máximo: 100 MB; largura: 240–4096 px; altura: 240–4096 px; duração: 1–15 s; taxa de quadros mínima: 16 fps; duração total máxima desta função: 15 s
reference_audioaudio, opcional, no máximo 5wav, mp3Tamanho máximo: 15 MB; duração: 1–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.
  • Com duration.mode="auto", não envie duration.seconds.
  • Forneça pelo menos uma destas funções: reference_image, reference_video, reference_audio.
  • Com vídeos de referência, a soma da duração total dos vídeos de entrada e da duração de saída não pode ultrapassar 30 segundos. Com duração automática, o limite de saída também depende do tempo restante.

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": "wan3.0-video",
"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": "720p",
"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.
excludesRemova os campos que entrem em conflito com a duração automática ou o quadro final.
sum_lteReduza a duração total dos vídeos de referência ou a duração de saída para que a soma não ultrapasse 30 segundos.
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.

Edição de vídeo

wan2.7-videoedit

Use esta operação para modificar as imagens de um vídeo existente. Primeiro prepare um vídeo de origem que atenda aos limites.

Defina model com o Model ID desta seção e operation como video_edit. 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ãofixed, autoauto
duration.secondsintegerNão2–15, incremento 1 s; apenas com duração fixaNenhum
output.formatstringNãomp4mp4
output.resolutionstringNão720p, 1080p1080p
promptstringSimStringNenhum
provider_options.alibaba.prompt_extendbooleanNãotrue / false; controla a expansão do prompttrue
seedintegerNão0–2147483647, incremento 1; semente aleatória; aceita 0Nenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
base_videovideo, 1 (obrigatório)mp4, movTamanho máximo: 100 MB; largura: 240–4096 px; altura: 240–4096 px; duração: 1–15 s; taxa de quadros mínima: 16 fps; 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.
  • Você deve fornecer base_video.
  • Com duration.mode="auto", não envie duration.seconds.

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": "wan2.7-videoedit",
"operation": "video_edit",
"prompt": "Keep the boy and his motion in the source video. Give the city plaza warmer evening lighting.",
"duration": {
"mode": "auto"
},
"output": {
"resolution": "720p"
},
"media": [
{
"id": "base",
"type": "video",
"role": "base_video",
"source": "https://bettertoken.ai/video-api/shared/kling-hero-3.0.mp4"
}
]
}

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.
excludesRemova os campos que entrem em conflito com a duração automática ou o quadro final.
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.

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.