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

API de vídeo do Kling: texto, imagens e controle de movimento

Conecte o Kling 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 ou imagens, ou controlar o movimento com uma imagem de referência de uma pessoa e um vídeo de movimento. O nível de saída do kling-v3 usa provider_options.kling.mode; Omni, Turbo e Motion Control usam seus próprios campos de resoluçã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
kling-3.0-turbotext_to_video5–10, incremento 5720p, 1080p16:9, 9:16, 1:1onNenhum
kling-v3-motion-controlreference_to_videoAcompanha o vídeo de referência de 3–10 s720p, 1080pNão enviaroff, onreference_image, reference_video
kling-v3-omnitext_to_video3–15, incremento 1720p, 1080p, 4k16:9, 9:16, 1:1off, onNenhum
kling-v3image_to_video3–15, incremento 1std, pro, 4kNão enviaroff, onfirst_frame, last_frame
kling-v3text_to_video3–15, incremento 1std, pro, 4k16:9, 9:16, 1:1off, onNenhum

kling-v3 não aceita output.resolution; em imagem para vídeo também não aceita output.aspect_ratio. kling-v3-motion-control não aceita provider_options. O Turbo só gera vídeos de 5 ou 10 segundos, com áudio fixo em on.

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 controle de movimento usa uma imagem de referência de um menino e um vídeo de movimento do mesmo menino. O prompt corresponde a essas mídias. O vídeo tem cerca de 5.04 segundos, 1280 × 720 e 24 fps.

De texto para vídeo

kling-3.0-turbo

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ãoonon
duration.modestringNãofixedfixed
duration.secondsintegerNão5–10, incremento 5 s; apenas com duração fixa5
output.aspect_ratiostringNão16:9, 9:16, 1:116:9
output.formatstringNãomp4mp4
output.resolutionstringNão720p, 1080p720p
promptstringSimStringNenhum
watermarkbooleanNãofalsefalse

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": "kling-3.0-turbo",
"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.

kling-v3-omni

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ãooff, onoff
duration.modestringNãofixedfixed
duration.secondsintegerNão3–15, incremento 1 s; apenas com duração fixa3
output.aspect_ratiostringNão16:9, 9:16, 1:116:9
output.formatstringNãomp4mp4
output.resolutionstringNão720p, 1080p, 4k720p
promptstringSimStringNenhum
watermarkbooleanNãofalsefalse

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 output.resolution="4k", você deve definir audio.mode="off".

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": "kling-v3-omni",
"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.

kling-v3

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ãooff, onoff
duration.modestringNãofixedfixed
duration.secondsintegerNão3–15, incremento 1 s; apenas com duração fixa5
output.aspect_ratiostringNão16:9, 9:16, 1:116:9
output.formatstringNãomp4mp4
promptstringNãoStringNenhum
provider_options.kling.camera_axisstringNãohorizontal, vertical, pan, tilt, roll, zoomNenhum
provider_options.kling.camera_typestringNãosimple, down_back, forward_up, right_turn_forward, left_turn_forwardNenhum
provider_options.kling.camera_valueintegerNão-10–10, incremento 1, não pode ser 0Nenhum
provider_options.kling.modestringNãostd, pro, 4kstd
provider_options.kling.negative_promptstringNãoStringNenhum
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": "kling-v3",
"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": {
"aspect_ratio": "16:9"
},
"provider_options": {
"kling": {
"mode": "std"
}
}
}

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

kling-v3

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ãooff, onoff
duration.modestringNãofixedfixed
duration.secondsintegerNão3–15, incremento 1 s; apenas com duração fixa5
output.formatstringNãomp4mp4
promptstringNãoStringNenhum
provider_options.kling.camera_axisstringNãohorizontal, vertical, pan, tilt, roll, zoomNenhum
provider_options.kling.camera_typestringNãosimple, down_back, forward_up, right_turn_forward, left_turn_forwardNenhum
provider_options.kling.camera_valueintegerNão-10–10, incremento 1, não pode ser 0Nenhum
provider_options.kling.modestringNãostd, pro, 4kstd
provider_options.kling.negative_promptstringNãoStringNenhum
watermarkbooleanNãofalse, truefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
first_frameimage, opcional, no máximo 1jpg, jpeg, pngTamanho máximo: 10 MB; largura: 300–100000 px; altura: 300–100000 px
last_frameimage, opcional, no máximo 1jpg, jpeg, pngTamanho máximo: 10 MB; largura: 300–100000 px; altura: 300–100000 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.
  • Forneça pelo menos uma destas funções: first_frame, last_frame.
  • Se enviar um quadro final last_frame, não defina provider_options.kling.camera_type.

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": "kling-v3",
"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
},
"provider_options": {
"kling": {
"mode": "std"
}
},
"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

kling-v3-motion-control

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ãooff, onoff
duration.modestringNãoautoauto
duration.secondsintegerNãoNão enviar; a duração acompanha o vídeo de referência de 3–10 sNenhum
output.formatstringNãomp4mp4
output.resolutionstringNão720p, 1080p720p
promptstringSimStringNenhum
watermarkbooleanNãofalsefalse

Requisitos das mídias

Função da mídiaTipo e quantidadeFormatosLimites por arquivo
reference_imageimage, 1 (obrigatório)jpg, jpeg, pngTamanho máximo: 10 MB; largura: 300–16384 px; altura: 300–16384 px
reference_videovideo, 1 (obrigatório)mp4, movTamanho máximo: 100 MB; duração: 3–10 s; duração total máxima desta função: 10 s

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

Restrições de combinação

  • Use duração automática; a duração da saída acompanha o vídeo de referência. Não informe duration.seconds.

Você deve fornecer exatamente uma reference_image e um reference_video. Não defina proporção nem provider_options adicionais.

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": "kling-v3-motion-control",
"operation": "reference_to_video",
"prompt": "Animate the boy in the reference image following the motion in the reference video. Preserve his appearance.",
"duration": {
"mode": "auto"
},
"output": {
"resolution": "720p"
},
"media": [
{
"id": "person",
"type": "image",
"role": "reference_image",
"source": "https://bettertoken.ai/video-api/shared/kling-hero-3.0-poster.jpg"
},
{
"id": "motion",
"type": "video",
"role": "reference_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.
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.