> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Documentação de Integração da API de Geração de Vídeos Kling > Kling video generation API guide - Ace Data Cloud 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](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado para uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Documentação Completa: [API de Geração de Vídeos Kling →](https://platform.acedata.cloud/documents/kling-videos) ## 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: ```json theme={null} { "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: ```shell theme={null} 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](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels), 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: ```python theme={null} 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: ```json theme={null} { "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 `<<>>`, `<<>>` (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`. ### Vídeo de referência e edição de vídeo (`video_list`) `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): ```shell theme={null} 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 <<>> 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 `<<>>`, `<<>>`. 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 `<<>>`. 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: ```shell theme={null} 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 <<>> estejam na cena de <<>>, 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/](https://webhook.site/), ao abrir este site, você obterá uma URL de Webhook, como mostrado na imagem: ![](https://cdn.acedata.cloud/tbcnai.png) 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: ![](https://cdn.acedata.cloud/zv5u2q.png) O conteúdo é o seguinte: ```json theme={null} { "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 ```json theme={null} { "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.