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 Console 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 fazer login. 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 para que você possa experimentar; quando o crédito estiver baixo, você pode recarregar o saldo geral no console.

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

Uso Básico

Primeiro, entenda a forma básica de uso, que consiste em inserir a palavra-chave prompt, a açã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 passar um campo action, cujo valor é 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 Headers da Requisiçã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 Requisição, incluindo:

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 do 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, suporta 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, suporta 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, conforme descrito abaixo:

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 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": "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 do Modelo

Os diferentes modelos têm suporte variado para os parâmetros. A matriz abaixo 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, a API retornará erros como model/mode/duration(...) is not supported with image_tail.

Modelo	Modo	`end_image_url` (quadro 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	❌	❌	❌	Geração de 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	✅	✅	✅	Intervalo 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	✅	❌	❌	Apenas suporta `duration=5`

Observações:

mode=4k apenas suportado por kling-v3 e kling-v3-omni; e é incompatível com camera_control (controle de câmera).
end_image_url só pode ser usado em action=image2video em conjunto com start_image_url. Apenas passar end_image_url (sem start_image_url) será rejeitado.
kling-v3 / kling-v3-omni aceita qualquer duration inteiro de 3 a 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.

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

Se você deseja continuar gerando um vídeo Kling já criado, pode definir o parâmetro action como extend e inserir o ID do vídeo que precisa ser continuado. O ID do vídeo é obtido com base no uso básico, como mostrado na imagem abaixo:

Neste momento, você pode ver que o ID do vídeo é:

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

Nota: O video_id aqui é o ID do vídeo gerado. Se você não souber como gerar um vídeo, pode consultar o uso básico mencionado acima.

Em seguida, precisamos preencher os próximos prompts necessários para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo:

model: o modelo para gerar o vídeo, principalmente kling-v1, kling-v1-5 e kling-v1-6.
mode: o modo de geração do vídeo, com valores opcionais sendo o modo padrão std, modo rápido pro e modo nativo 4K 4k (apenas suportado por kling-v3 e kling-v3-omni, incompatível com controle de câmera).
duration: a duração do vídeo para esta tarefa de geração, principalmente 5s e 10s.
start_image_url: quando a ação escolhida é image2video, é necessário fazer o upload do link da imagem de referência do quadro inicial.
prompt: palavras-chave.

Um exemplo de preenchimento é mostrado abaixo:

Após o preenchimento, 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": "Caneca de café de cerâmica branca sobre balcão de mármore brilhante com luz da janela da manhã. A câmera gira lentamente 360 graus ao redor da caneca, parando brevemente na alça.",
    "duration": 10
}

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

Ao clicar em executar, você pode ver que obterá um resultado, como mostrado abaixo:

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.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 mencionado acima, o que também realiza a função de extensão do vídeo.

Referência Omni (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 total”. Com base na geração de vídeo a partir de texto (action=text2video), é possível passar imagens de referência ou vídeos de referência adicionais, permitindo referência de múltiplas imagens, vídeos de referência e edição direta de vídeos existentes. Convenção central: O material de referência deve ser referenciado no prompt na forma <<<image_1>>>, <<<video_1>>> (números começando de 1) para os materiais correspondentes na image_list / video_list, caso contrário, o modelo não aplicará essas referências. Se apenas passar o material sem referenciá-lo nas palavras-chave, o material será ignorado.

Aviso de segurança: A API atual não abre element_list. O ID do Kling Element Library pertence ao namespace da conta do fornecedor, e antes de fornecer uma API de gerenciamento de elementos com isolamento de inquilinos, os clientes devem usar image_list para passar a imagem de referência principal.

A solicitação Omni não suporta negative_prompt, cfg_scale ou camera_control, e não pode usar mode=4k. Quando inclui vídeos 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 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. Requisitos: formato MP4/MOV; resolução 720px–2160px; duração 3–10 segundos; taxa de quadros 24–60fps; tamanho do arquivo ≤200MB; no máximo 1 vídeo.
refer_type: tipo de referência, pode ser 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, mudar o estilo, mudar a cor, mudar o clima, etc.) ou feature (referência de características, referindo-se ao seu estilo / movimento da câmera / continuidade da próxima cena).
keep_original_sound: se deve manter o áudio original do vídeo, pode ser yes (manter) ou no (remover).

Nota: Quando há um vídeo de referência, generate_audio deve ser false. Vídeos com refer_type=base não podem ter o primeiro quadro / último quadro especificados.

Exemplo de CURL para editar um vídeo existente (transformar o vídeo em estilo de 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": "Transforme <<<video_1>>> em um estilo de anime de nível cinematográfico, mantendo o movimento e a composição originais",
  "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 passar imagens de referência (elementos / cenas / 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; menor lado ≥300px; proporção largura-altura de 1:2.5 ~ 2.5:1.
type: opcional. Se não for passado, será considerado como imagem de referência pura; se passar first_frame / end_frame, será considerado como primeiro quadro / último quadro (equivalente a start_image_url / end_image_url).

Ao usar, deve-se referenciar no prompt como <<<image_1>>>, <<<image_2>>>. Limite de quantidade: se não houver vídeo de referência, imagens de referência ≤ 7; se houver vídeo de referência, imagens de referência ≤ 4. Ao passar apenas o primeiro / último quadro, também pode-se usar diretamente start_image_url / end_image_url, mas o último quadro deve ser usado junto com o primeiro quadro.

Nota: Se start_image_url / end_image_url e image_list forem passados ao mesmo tempo, o primeiro / último quadro será priorizado em relação ao image_list, o que pode afetar a correspondência dos índices de <<<image_N>>>. Recomenda-se escolher um: se precisar do primeiro / último quadro, especifique diretamente no image_list usando type, 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": "Faça com que os personagens de <<<image_1>>> estejam na cena de <<<image_2>>>, com iluminação cinematográfica",
  "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 pode levar um tempo relativamente longo, cerca de 1-2 minutos, se a API não responder por um longo período, a solicitação HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente inicia a solicitação, deve especificar um campo callback_url adicional. Após o cliente fazer a solicitação à API, a API retornará 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 para o callback_url especificado pelo cliente em formato JSON POST, incluindo também o campo task_id, permitindo que o resultado da tarefa seja associado pelo ID. Abaixo, vamos entender como operar isso com um exemplo. 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 ele configurou. Para facilitar a demonstração, usamos um site de exemplo de Webhook público https://webhook.site/, ao abrir este site, você obterá uma URL de Webhook, como mostrado na imagem:

Copie esta URL, que pode ser usada como Webhook, o exemplo aqui é https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Em seguida, podemos definir o campo callback_url para a URL do Webhook acima, ao mesmo tempo preenchendo os parâmetros correspondentes, conforme mostrado na imagem:

Ao clicar em executar, você verá que receberá imediatamente um resultado, como abaixo:

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

Após alguns instantes, podemos observar o resultado do vídeo gerado em https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, como mostrado na imagem:

O conteúdo é o seguinte:

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Pode-se ver que o resultado contém um campo task_id, e os outros campos são semelhantes aos mencionados anteriormente, permitindo que a tarefa seja associada pelo ID.

Tratamento de Erros

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

400 token_mismatched: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented: Solicitação inválida, 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": "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

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 (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

​Processo de Solicitação

​Uso Básico

​Matriz de Capacidades do Modelo

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

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

​Vídeo 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

Processo de Solicitação

Uso Básico

Matriz de Capacidades do Modelo

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

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

Vídeo 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