Documentação de Integração da API de Geração de Vídeos Kling

Este documento apresentará uma forma de integração da API de Geração de Vídeos Kling, que pode gerar vídeos oficiais da Kling através da entrada de parâmetros personalizados.

Processo de Solicitação

Para usar a API de Geração de Vídeos Kling, primeiro acesse o Painel de Controle da Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro.

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será redirecionado de volta para a página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço individualmente. A primeira solicitação oferece um crédito gratuito, permitindo uma experiência sem custo; quando o crédito estiver baixo, você pode recarregar o saldo geral no painel de controle.

📘 Documentação Completa: API de Geração de Vídeos Kling →

Uso Básico

Primeiro, entenda a forma básica de uso, que envolve a entrada de uma palavra-chave prompt, uma ação action, uma imagem de referência para o primeiro quadro start_image_url e o modelo model, para obter o resultado processado. Primeiro, é necessário passar um campo action, cujo valor deve ser text2video, que inclui três ações principais: vídeo gerado por texto (text2video), vídeo gerado por imagem (image2video), e vídeo expandido (extend). Em seguida, precisamos inserir o modelo model, que atualmente inclui 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, conforme detalhado abaixo:

Aqui, podemos ver que configuramos os Cabeçalhos da Solicitação, incluindo:

accept: o formato de resposta desejado, que deve ser preenchido como application/json, ou seja, formato JSON.
authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.

Além disso, configuramos o Corpo da Solicitação, que inclui:

model: o modelo para gerar o vídeo, que inclui 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 do vídeo, com opções de modo padrão std, modo rápido pro e modo nativo 4K 4k. O 4k é suportado apenas por kling-v3 e kling-v3-omni, e não é compatível com camera_control (controle de câmera).
action: a ação da tarefa de geração de vídeo, que inclui três ações: vídeo gerado por texto (text2video), vídeo gerado por imagem (image2video), e vídeo expandido (extend).
start_image_url: quando a ação de vídeo gerado por imagem image2video é escolhida, é necessário fornecer o link da imagem de referência para o primeiro quadro.
end_image_url: opcional ao gerar vídeo por imagem, 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 sincronizado, opcional, valor booleano. Suporta kling-v3, kling-v3-omni e kling-v2-6 (apenas no modo pro). O padrão é false.
aspect_ratio: proporção do vídeo, opcional, suportando 16:9, 9:16, 1:1, padrão 16:9.
cfg_scale: intensidade de correlação, intervalo [0,1], quanto maior, mais próximo do prompt.
camera_control: opcional, parâmetros para controlar o movimento da câmera, suportando predefinições type/simple e configurações como horizontal, vertical, pan, tilt, roll, zoom, etc.
negative_prompt: opcional, palavras-chave inversas que não devem aparecer, máximo de 200 caracteres.
image_list: lista de imagens de referência Omni, aplicável aos modelos kling-o1 e kling-v3-omni, consulte a seção “Referência Omni” abaixo.
video_list: lista de vídeos de referência Omni (suporta edição de vídeo), aplicável aos modelos kling-o1 e kling-v3-omni, consulte a seção “Referência Omni” abaixo.
prompt: palavra-chave.
callback_url: URL para onde os resultados devem ser retornados.
async: opcional, se definido como true, a interface retorna imediatamente task_id, sem necessidade de fornecer callback_url, e os resultados podem ser obtidos posteriormente através da interface de consulta de tarefas correspondente.

Após a seleção, você pode notar que o código correspondente também foi gerado à direita, como mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e você receberá o seguinte resultado:

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

O resultado retornado contém vários campos, descritos a seguir:

success, o estado da tarefa de geração de vídeo.
task_id, o ID da tarefa de geração de vídeo.
video_id, o ID do vídeo gerado pela tarefa.
video_url, o link do vídeo gerado pela tarefa.
duration, a duração do vídeo gerado pela tarefa.
state, o estado da tarefa de geração de vídeo.

Podemos ver que recebemos informações satisfatórias sobre o vídeo, e tudo o que precisamos fazer é acessar o link do vídeo gerado na data do resultado para obter o vídeo Kling. Além disso, se você quiser gerar o código de integração correspondente, pode copiá-lo diretamente, como o código CURL abaixo:

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": "Caneca de café de cerâmica branca sobre uma bancada de mármore brilhante com luz da janela da manhã. A câmera gira lentamente 360 graus ao redor da caneca, pausando brevemente na alça."
}'

Matriz de Capacidades do Modelo

Os diferentes modelos têm suporte variado para os parâmetros. A matriz a seguir foi organizada a partir da documentação oficial de modelos de vídeo da Kling, e antes de chamar, verifique se a combinação atual de model / mode / duration suporta a funcionalidade desejada, caso contrário, retornará erros como model/mode/duration(...) is not supported with image_tail.

Modelo	Modo	`end_image_url` (frame inicial/final)	`generate_audio` (áudio)	`camera_control` (controle 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, `extend` disponível em todos os modos
`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	✅	✅	❌	Único modelo não v3 que suporta áudio simultaneamente
`kling-v3`	std / pro	✅	✅	✅	Faixa de `duration` de 3 a 15 segundos
`kling-v3`	4k	✅	✅	❌	Modo 4K não compatível com controle 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; é incompatível com camera_control (controle 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á rejeitado.
kling-v3 / kling-v3-omni aceitam qualquer duração inteira entre 3 e 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 áudio.

Função de extensão de vídeo

Se desejar continuar gerando um vídeo Kling já criado, defina o parâmetro action como extend e insira o ID do vídeo que deseja continuar gerando. O ID do vídeo pode ser obtido conforme o uso básico, como mostrado na imagem abaixo:

Neste momento, o ID do vídeo é:

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

Atenção, o video_id aqui é o ID do vídeo gerado. Se você não sabe como gerar um vídeo, pode consultar o uso básico descrito anteriormente.

Em seguida, é necessário preencher a próxima etapa com as palavras-chave para personalizar a geração do vídeo, podendo especificar o seguinte:

model: modelo para gerar o vídeo, principalmente kling-v1, kling-v1-5 e kling-v1-6.
mode: modo de geração do vídeo, opções são modo padrão std, modo rápido pro e modo 4K nativo 4k (apenas kling-v3 e kling-v3-omni suportam, incompatível com controle de câmera).
duration: duração do vídeo para esta tarefa, geralmente 5s ou 10s.
start_image_url: quando a ação é image2video, é obrigatório enviar o link da imagem de referência do frame inicial.
prompt: palavras-chave.

Exemplo de preenchimento:

Após preencher, o código gerado automaticamente é o seguinte:

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)

Ao executar, você verá um resultado como este:

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

Pode-se observar que o conteúdo do resultado é consistente com o descrito anteriormente, realizando assim a função de extensão de vídeo.

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

kling-o1 e kling-v3-omni são dois modelos independentes, ambos suportam a capacidade de “referência completa”. Baseado na geração de vídeo a partir de texto (action=text2video), é possível enviar imagens ou vídeos de referência adicionais para realizar referência múltipla de imagens, vídeo de referência e edição direta de vídeos existentes. Regra principal: os materiais de referência devem ser referenciados no prompt na forma <<<image_1>>>, <<<video_1>>> (números iniciando em 1), correspondendo às posições em image_list / video_list, para que o modelo aplique essas referências. Se os materiais forem enviados mas não referenciados no prompt, serão ignorados.

Aviso de segurança: a API atual não expõe element_list. O ID da Kling Element Library não é isolado por locatário; até que a API de gerenciamento de elementos com isolamento seja fornecida, use image_list para enviar imagens principais de referência.

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

video_url: link do vídeo de referência, não pode estar vazio. Máximo de 1 vídeo MP4/MOV, tamanho do arquivo ≤200MB, taxa de quadros 24–60fps. Para kling-o1 o tempo deve ser de 3–10 segundos, largura e altura entre 700–2160px; para kling-v3-omni o tempo deve ser de 3–15,5 segundos, largura e altura entre 700–4553px, total de pixels ≤8.294.400, proporção largura/altura entre 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 composição, estilo, cor, clima, etc.) ou feature (referência de característica, para referência de estilo / movimento de câmera / continuação da próxima cena).
keep_original_sound: se mantém o áudio original do vídeo, opcional yes (manter) ou no (remover).

Atenção: quando houver vídeo de referência, generate_audio deve ser false. Vídeos com refer_type=base não podem especificar primeiro/quadro final.

Exemplo CURL para editar um vídeo existente (transformar o vídeo em estilo anime):

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 múltipla de imagens (`image_list`)

image_list é usado para passar imagens de referência (elementos / cenário / estilo, etc.), os campos dos elementos do array são:

image_url: link da imagem de referência, não pode estar vazio. Requisitos: formato .jpg/.jpeg/.png; tamanho do arquivo ≤10MB; menor lado ≥300px; proporção largura/altura entre 1:2,5 e 2,5:1.
type: opcional. Se não passado, é apenas uma imagem de referência; se passado first_frame / end_frame, será usado como primeiro quadro / quadro final (equivalente a start_image_url / end_image_url).

Ao usar, deve-se referenciar no prompt como <<<image_1>>>, <<<image_2>>>. Limite de quantidade: sem vídeo de referência, até 7 imagens; com vídeo de referência, até 4 imagens. Se passar apenas primeiro/quadro final, pode usar diretamente start_image_url / end_image_url, mas o quadro final deve ser usado junto com o primeiro quadro.

Atenção: se passar start_image_url / end_image_url junto com image_list, os primeiros/quadro final ficarão antes do image_list, o que pode afetar a correspondência dos índices <<<image_N>>>. Recomenda-se escolher um: se precisar de primeiro/quadro final, especifique no image_list com type, não misture com start_image_url / end_image_url.

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

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 geração de vídeos pela API Kling Videos Generation leva relativamente mais tempo, cerca de 1-2 minutos, se a API não responder por muito tempo, a requisição HTTP fica conectada, consumindo recursos do sistema. Por isso, esta API também oferece suporte a callback assíncrono. O fluxo geral é: o cliente faz a requisição e especifica um campo callback_url. Após a requisição, 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 via POST JSON para o callback_url especificado pelo cliente, incluindo o campo task_id, para que o resultado possa ser associado pela ID. A seguir, um exemplo para entender como operar. Primeiro, o callback Webhook é um serviço que pode receber requisições HTTP, o desenvolvedor deve substituir pelo URL do seu servidor HTTP. Para demonstração, usamos um site público de exemplo de Webhook https://webhook.site/, ao abrir o site, você obtém um URL de Webhook, como mostrado na imagem:

Copie este URL para usar como Webhook, o exemplo aqui é https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Depois, podemos configurar o campo callback_url para este URL de Webhook, preenchendo os parâmetros conforme mostrado na imagem:

Ao clicar em executar, verá que recebe um resultado imediatamente, como:

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

Após aguardar um momento, podemos observar o resultado do vídeo gerado em https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, conforme a imagem:

Conteúdo:

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

Note que o resultado contém o campo task_id, os demais campos são similares aos anteriores, e este campo permite associar o resultado à tarefa.

Tratamento de erros

Ao chamar a API, se ocorrer erro, a API retorna o código e a mensagem de erro correspondentes. Por exemplo:

400 token_mismatched: Requisição inválida, possivelmente por parâmetros ausentes ou inválidos.
400 api_not_implemented: Requisição inválida, possivelmente por 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 requisições, limite de taxa excedido.
500 api_error: Erro interno do servidor, algo deu errado no servidor.

Exemplo de resposta de erro

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

Conclusão

Através deste documento, você já entendeu como usar a API de Geração de Vídeos Kling, que pode gerar vídeos através de palavras-chave de entrada e uma imagem de referência do primeiro quadro. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, sinta-se à vontade para entrar em contato com nossa equipe de suporte técnico.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

Coding

Documentação de Integração da API de Geração de Vídeos Kling

Processo de Solicitação

Uso Básico

Matriz de Capacidades do Modelo

Função de extensão de vídeo

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

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

Callback assíncrono

Tratamento de erros

Exemplo de resposta de erro

Conclusão

​Processo de Solicitação

​Uso Básico

​Matriz de Capacidades do Modelo

​Função de extensão de vídeo

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

​Vídeo de referência e edição de vídeo (video_list)

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

​Callback assíncrono

​Tratamento de erros

​Exemplo de resposta de erro

​Conclusão

Processo de Solicitação

Uso Básico

Matriz de Capacidades do Modelo

Função de extensão de vídeo

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

Vídeo de referência e edição de vídeo (`video_list`)

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

Callback assíncrono

Tratamento de erros

Exemplo de resposta de erro

Conclusão