Instruções de integração da API Kling Videos Generation

Este artigo apresentará um tipo de instrução de integração da API Kling Videos Generation, que permite gerar vídeos oficiais do Kling inserindo parâmetros personalizados.

Processo de solicitação

Para usar a API Kling Videos Generation, primeiro acesse o console Ace Data Cloud para obter seu API Token e guarde-o para uso posterior.

Se você ainda não fez login ou se registrou, será automaticamente redirecionado para a página de login para convidá-lo a se registrar e fazer login, e retornará automaticamente à página atual após a conclusão. Um único API Token pode chamar todos os serviços da plataforma, não sendo necessário solicitar separadamente para cada serviço. A primeira solicitação incluirá créditos gratuitos, permitindo uma experiência gratuita; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no console.

📘 Documentação completa: Kling Videos Generation API →

Uso básico

Primeiro, vamos entender o método básico de uso: basta inserir o prompt prompt, a ação de geração action, a imagem de referência do primeiro quadro start_image_url e o modelo model para obter o resultado processado. Primeiro, é necessário simplesmente passar um campo action, cujo valor é text2video. Ele inclui principalmente três ações: texto para vídeo (text2video), imagem para vídeo (image2video) e extensão de vídeo (extend). Em seguida, também precisamos inserir o modelo model. Atualmente, há principalmente os modelos kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-o1; os detalhes são os seguintes:

Aqui podemos ver que configuramos os Request Headers, incluindo:

accept: qual formato de resultado de resposta você deseja receber; aqui, preencha com application/json, ou seja, o formato JSON.
authorization: a chave para chamar a API, que pode ser selecionada diretamente em uma lista suspensa após a solicitação.

Além disso, configuramos o Request Body, incluindo:

model: o modelo para gerar vídeos, incluindo principalmente os modelos kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-o1.
mode: o modo de geração de vídeo; os valores opcionais são modo padrão std, modo ultrarrápido pro e modo nativo 4K 4k. Entre eles, 4k é compatível apenas com kling-v3 e kling-v3-omni, e não é compatível com camera_control (controle de movimento de câmera).
action: a ação desta tarefa de geração de vídeo, incluindo principalmente três ações: texto para vídeo (text2video), imagem para vídeo (image2video) e extensão de vídeo (extend).
start_image_url: o link da imagem de referência do primeiro quadro que deve ser enviado quando a ação de imagem para vídeo image2video é selecionada.
end_image_url: opcional para imagem para vídeo, especifica o quadro final.
duration: duração do vídeo, em segundos. kling-v3 e kling-v3-omni suportam durações inteiras de 3 a 15 segundos; kling-o1 suporta apenas 5 segundos; outros modelos suportam 5 ou 10 segundos.
generate_audio: se deve gerar áudio simultaneamente, opcional, valor booleano. Compatível com kling-v3, kling-v3-omni e kling-v2-6 (somente modo pro). O padrão é false.
aspect_ratio: proporção de aspecto do vídeo, opcional, compatível com 16:9, 9:16, 1:1, o padrão é 16:9.
cfg_scale: intensidade de relevância, intervalo [0,1]; quanto maior, mais fiel ao prompt.
camera_control: opcional, parâmetro de objeto para controlar o movimento da câmera, compatível com predefinições type/simple e configurações como horizontal, vertical, pan, tilt, roll, zoom, entre outras.
negative_prompt: opcional, prompt negativo de elementos que não se deseja que apareçam, com no máximo 200 caracteres.
image_list: lista de imagens de referência Omni, aplicável aos modelos kling-o1 e kling-v3-omni; para o uso, consulte abaixo «Referência universal Omni».
video_list: lista de vídeos de referência Omni (compatível com edição de vídeo), aplicável aos modelos kling-o1 e kling-v3-omni; para o uso, consulte abaixo «Referência universal Omni».
prompt: prompt.
callback_url: URL que precisa receber o resultado de callback.
async: opcional; quando definido como true, a interface retorna imediatamente o task_id, não sendo necessário fornecer callback_url; em seguida, obtenha o resultado por polling através da interface de consulta de tarefa correspondente.

Após selecionar, você pode perceber que o código correspondente também é gerado à direita, como mostrado na imagem:

Clique no botão «Try» para realizar o teste. Conforme mostrado na imagem acima, aqui obtivemos o seguinte resultado:

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4",
  "duration": "5.041",
  "state": "succeed",
  "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5"
}

O resultado retornado possui vários campos, apresentados a seguir:

success, a situação do status da tarefa de geração de vídeo neste momento.
task_id, o ID da tarefa de geração de vídeo neste momento.
video_id, o ID do vídeo da tarefa de geração de vídeo neste momento.
video_url, o link do vídeo da tarefa de geração de vídeo neste momento.
duration, a duração do link de vídeo da tarefa de geração de vídeo neste momento.
state, o status da tarefa de geração de vídeo neste momento.

Podemos ver que obtivemos informações de vídeo satisfatórias; basta obter o vídeo Kling gerado de acordo com o endereço do link de vídeo em data no resultado. Além disso, se desejar gerar o código de integração correspondente, você pode copiá-lo diretamente. Por exemplo, o código CURL é o seguinte:

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v3",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

Matriz de capacidades dos modelos

O suporte a parâmetros varia consideravelmente entre os diferentes modelos. A matriz abaixo foi compilada a partir da documentação oficial de video models do Kling. Antes de chamar, verifique primeiro se a combinação atual de model / mode / duration oferece suporte à funcionalidade necessária; caso contrário, erros como model/mode/duration(...) is not supported with image_tail serão retornados.

Modelo	Modo	`end_image_url`（primeiro e último quadro）	`generate_audio`（áudio de acompanhamento）	`camera_control`（movimento de câmera）	Observações
`kling-v1`	std / pro	✅ apenas `duration=5`	❌	✅ apenas `duration=5`	`extend` não suporta `negative_prompt` e `cfg_scale`
`kling-v1-6`	std	❌	❌	❌	vídeo a partir de múltiplas imagens, todos os modos de `extend` disponíveis
`kling-v1-6`	pro	✅	❌	❌
`kling-v2-master`	—	❌	❌	❌	modo único, apenas `duration=5/10`
`kling-v2-1-master`	—	❌	❌	❌	modo único, apenas `duration=5/10`
`kling-v2-5-turbo`	std	❌	❌	❌
`kling-v2-5-turbo`	pro	✅	❌	❌
`kling-v2-6`	std	❌	❌	❌
`kling-v2-6`	pro	✅	✅	❌	o único modelo não v3 que também suporta áudio de acompanhamento
`kling-v3`	std / pro	✅	✅	✅	intervalo de `duration` de 3–15 segundos
`kling-v3`	4k	✅	✅	❌	o modo 4K é incompatível com movimento de câmera
`kling-v3-omni`	std / pro / 4k	✅	✅	❌
`kling-o1`	std / pro	✅	❌	❌	suporta apenas `duration=5`

Observações:

mode=4k é suportado apenas por kling-v3 e kling-v3-omni; além disso, é mutuamente exclusivo com camera_control（movimento de câmera）.
end_image_url só pode ser usado junto com start_image_url quando action=image2video. Enviar apenas end_image_url（sem start_image_url）será recusado.
kling-v3 / kling-v3-omni aceitam qualquer duration inteiro de 3–15 segundos; kling-o1 aceita apenas 5; os demais modelos aceitam apenas 5 ou 10.
generate_audio é false por padrão. Apenas kling-v3、kling-v3-omni e kling-v2-6（modo pro）suportam.

Funcionalidade de extensão de vídeo

Se quiser continuar gerando um vídeo Kling já gerado, você pode definir o parâmetro action como extend , e inserir o ID do vídeo que precisa continuar sendo gerado, a obtenção do ID do vídeo é feita com base no uso básico, conforme mostrado na imagem abaixo:

Nesse momento, pode-se ver que o ID do vídeo é:

"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"

Observe que o video_id no vídeo aqui é o ID do vídeo após a geração; se você não sabe como gerar vídeos, pode consultar o uso básico acima para gerar vídeos.

Em seguida, devemos preencher obrigatoriamente o prompt que precisa ser estendido na próxima etapa para personalizar a geração do vídeo, então é possível especificar o seguinte conteúdo:

model：o modelo para gerar vídeos, principalmente os modelos kling-v1 、kling-v1-5 e kling-v1-6.
mode：o modo para gerar vídeos, os valores opcionais são modo padrão std、modo rápido pro e modo 4K nativo 4k（suportado apenas por kling-v3 e kling-v3-omni, incompatível com o controle de movimento de câmera）.
duration：a duração do vídeo desta tarefa de geração de vídeo, incluindo principalmente 5s e 10s.
start_image_url：ao escolher o comportamento de geração de vídeo a partir de imagem image2video, é obrigatório o link da imagem de referência do primeiro quadro que precisa ser enviada.
prompt：prompt.

O exemplo de preenchimento é o seguinte:

Após o preenchimento, o código é gerado automaticamente da seguinte forma:

O código Python correspondente:

import requests

url = "https://api.acedata.cloud/kling/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "model": "kling-v1",
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "duration": 10
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Clique em executar, e você pode descobrir que obterá um resultado, como segue:

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

Pode-se ver que o conteúdo do resultado é consistente com o acima, e assim a funcionalidade de extensão de vídeo é implementada.

Referência Omni completa（edição de vídeo / vídeo de referência / referência de múltiplas imagens）

kling-o1 e kling-v3-omni são dois modelos independentes, ambos suportam a capacidade de 「referência completa」. Com base na geração de vídeo a partir de texto（action=text2video）, é possível transmitir adicionalmente imagens de referência ou vídeos de referência, realizando referência de múltiplas imagens, vídeos de referência e a edição direta de vídeos existentes. Convenção principal：os materiais de referência devem ser citados no prompt na forma de <<<image_1>>>、<<<video_1>>>（a numeração começa em 1）, referenciando os materiais na posição correspondente em image_list / video_list, para que o modelo aplique essas referências. Se apenas os materiais forem enviados sem serem citados no prompt, os materiais serão ignorados.

Explicação de segurança：a API atual não disponibiliza element_list. O ID da Kling Element Library não é isolado por locatário; antes de fornecer a Element Management API com isolamento por locatário, use image_list para transmitir imagens de referência do sujeito.

As solicitações Omni não suportam negative_prompt、cfg_scale ou camera_control, e também não podem usar mode=4k. Quando incluir vídeos de referência, generate_audio deve ser false. video_list é usado para fornecer vídeos de referência, sendo o cenário mais comum desta capacidade. Os campos dos elementos do array são os seguintes:

video_url: link do vídeo de referência, não pode estar vazio. No máximo 1 vídeo MP4/MOV, tamanho do arquivo ≤200MB, taxa de quadros de 24–60fps. kling-o1 exige duração de 3–10 segundos e largura e altura de 700–2160px cada; kling-v3-omni exige duração de 3–15,5 segundos, largura e altura de 700–4553px cada, total de pixels ≤8.294.400, proporção de aspecto de 0,4–2.
refer_type: tipo de referência, opcional base (padrão, vídeo base a ser editado, ou seja, “editar diretamente o vídeo”, podendo adicionar/remover/modificar elementos, alterar a composição, trocar o estilo, trocar as cores, trocar o clima etc.) ou feature (referência de característica, referenciando seu estilo / movimento de câmera / continuação da próxima tomada).
keep_original_sound: se deve manter o áudio do vídeo original, opcional yes (manter) ou no (remover).

Observação: quando houver um vídeo de referência, generate_audio deve ser false. Um vídeo com refer_type=base não pode especificar novamente o primeiro quadro / último quadro.

Um exemplo de CURL para editar um vídeo existente (alterar o vídeo para estilo de anime) é o seguinte:

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "把 <<<video_1>>> 改成电影级动漫风格，保留原有的运动和构图",
  "video_list": [
    {
      "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4",
      "refer_type": "base",
      "keep_original_sound": "no"
    }
  ]
}'

Referência de múltiplas imagens (`image_list`)

image_list é usado para fornecer imagens de referência (elementos / cenários / estilos etc.). Os campos dos elementos do array são os seguintes:

image_url: link da imagem de referência, não pode estar vazio. Requisitos: formato .jpg/.jpeg/.png; tamanho do arquivo ≤10MB; lado mais curto ≥300px; proporção de aspecto de 1:2,5 ~ 2,5:1.
type: opcional. Quando não informado, é usado como imagem de referência pura; quando informado como first_frame / end_frame, é usado respectivamente como primeiro quadro / último quadro (equivalente a start_image_url / end_image_url).

Ao usar, é necessário fazer referência no prompt com <<<image_1>>>, <<<image_2>>>. Limite de quantidade: quando não houver vídeo de referência, imagens de referência ≤ 7; quando houver vídeo de referência, imagens de referência ≤ 4. Ao transmitir apenas o primeiro / último quadro, também é possível usar diretamente start_image_url / end_image_url, mas o último quadro deve ser usado junto com o primeiro quadro.

Observação: se start_image_url / end_image_url e image_list forem enviados ao mesmo tempo, o primeiro / último quadro será posicionado antes de image_list, o que pode afetar a correspondência dos índices de <<<image_N>>>. Recomenda-se escolher um dos dois: quando forem necessários primeiro / último quadro, especifique diretamente o type em image_list; não misture com start_image_url / end_image_url.

Exemplo de CURL para gerar vídeo com referência de múltiplas imagens:

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "让 <<<image_1>>> 里的人物站在 <<<image_2>>> 的场景中，电影感光线",
  "image_list": [
    { "image_url": "https://cdn.acedata.cloud/subject.png" },
    { "image_url": "https://cdn.acedata.cloud/scene.png" }
  ]
}'

Callback assíncrono

Como a API Kling Videos Generation leva um tempo relativamente longo para gerar, aproximadamente 1–2 minutos, se a API não responder por muito tempo, a solicitação HTTP manterá a conexão ativa, resultando em consumo adicional de recursos do sistema. Por isso, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente inicia uma solicitação, ele especifica adicionalmente um campo callback_url. Depois que o cliente inicia a solicitação à API, a API retorna imediatamente um resultado, contendo um campo task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado do vídeo gerado será enviado na forma de POST JSON para o callback_url especificado pelo cliente, incluindo também o campo task_id, para que o resultado da tarefa possa ser associado pelo ID. A seguir, entenderemos por meio de um exemplo como operar especificamente. Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP, e o desenvolvedor deve substituí-lo pela URL do servidor HTTP que construiu. Aqui, para facilitar a demonstração, é usado um site público de exemplo de Webhook, https://webhook.site/. Ao abrir esse site, é possível obter uma URL de Webhook, conforme mostrado na imagem:

Copie esta URL para usá-la como Webhook. O exemplo aqui é https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Em seguida, podemos definir o campo callback_url como a URL de Webhook acima e, ao mesmo tempo, preencher os parâmetros correspondentes. O conteúdo específico é mostrado na imagem:

Clique em executar e será possível ver que um resultado será obtido imediatamente, como segue:

{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Aguarde um momento; podemos observar o resultado do vídeo gerado em https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, conforme mostrado na imagem:

O conteúdo é o seguinte:

{
  "success": true,
  "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
  "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

É possível ver que há um campo task_id no resultado. Os outros campos são semelhantes aos descritos acima, e esse campo permite realizar a associação da tarefa.

Tratamento de erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e as informações de erro correspondentes. Por exemplo:

400 token_mismatched: Solicitação incorreta, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented: Solicitação incorreta, possivelmente devido a parâmetros ausentes ou inválidos.
401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
500 api_error: Erro interno do servidor, algo deu errado no servidor.

Exemplo de resposta de erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusão

Por meio deste documento, você já aprendeu como usar a Kling Videos Generation API para gerar vídeos por meio da inserção de prompts e imagens de referência do primeiro quadro. Esperamos que este documento possa ajudá-lo a integrar e usar melhor esta API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento.

Kling 3.0 Turbo

model="kling-v3-turbo" oferece suporte a vídeo gerado a partir de texto e vídeo gerado a partir da imagem do primeiro quadro, com duração em números inteiros de 3–15 segundos. mode="std" produz 720p, e mode="pro" produz 1080p. Este modelo vem com áudio nativo e não fornece uma opção para desativá-lo; omita generate_audio ou defina-o como true. Este modelo não oferece suporte a quadro final, objeto de movimento de câmera, prompt negativo independente ou cfg_scale. Descreva diretamente no prompt o conteúdo que deseja ou deseja evitar que apareça.

Vídeo com múltiplas tomadas

kling-v3 e kling-v3-omni oferecem suporte a multi_shot=true. shot_type="intelligence" cria automaticamente as tomadas com base no prompt; shot_type="customize" fornece de 1–6 tomadas por meio de multi_prompt, sendo que cada item contém um index que aumenta consecutivamente a partir de 1, um prompt de no máximo 512 caracteres e uma duration inteira de pelo menos 1 segundo. A soma das durações de todas as tomadas deve ser igual à duration total. As tomadas personalizadas não usam o prompt global. Múltiplas tomadas são cobradas de acordo com o modelo selecionado, qualidade de imagem, configuração de áudio e duração total.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Coding

Mais guias

Instruções de integração da API Kling Videos Generation

Processo de solicitação

Uso básico

Matriz de capacidades dos modelos

Funcionalidade de extensão de vídeo

Referência Omni completa（edição de vídeo / vídeo de referência / referência de múltiplas imagens）

Referência de múltiplas imagens (`image_list`)

Callback assíncrono

Tratamento de erros

Exemplo de resposta de erro

Conclusão

Kling 3.0 Turbo

Vídeo com múltiplas tomadas

​Processo de solicitação

​Uso básico

​Matriz de capacidades dos modelos

​Funcionalidade de extensão de vídeo

​Referência Omni completa（edição de vídeo / vídeo de referência / referência de múltiplas imagens）

​Vídeos de referência e edição de vídeo（video_list）

​Referência de múltiplas imagens (image_list)

​Callback assíncrono

​Tratamento de erros

​Exemplo de resposta de erro

​Conclusão

​Kling 3.0 Turbo

​Vídeo com múltiplas tomadas

Processo de solicitação

Uso básico

Matriz de capacidades dos modelos

Funcionalidade de extensão de vídeo

Referência Omni completa（edição de vídeo / vídeo de referência / referência de múltiplas imagens）

Vídeos de referência e edição de vídeo（`video_list`）

Referência de múltiplas imagens (`image_list`)

Callback assíncrono

Tratamento de erros

Exemplo de resposta de erro

Conclusão

Kling 3.0 Turbo

Vídeo com múltiplas tomadas