Saltar para o conteúdo principal
Este documento apresentará as instruções de integração da API de Geração de Movimento 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, você precisa primeiro solicitar o serviço correspondente na página da API de Geração de Movimento Kling. Após acessar a página, clique no botão “Adquirir”, conforme mostrado na imagem: Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o registro e login, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito da API.

​
Uso Básico

Primeiro, entenda a forma básica de uso, que consiste em inserir a palavra-chave prompt, a imagem de referência image_url e o link do vídeo de referência video_url, para obter o resultado processado. Em seguida, precisamos inserir o modelo mode, que atualmente possui os modelos std e pro, com os detalhes a seguir:

Podemos ver que aqui configuramos os Headers da Solicitação, incluindo:
  • accept: o formato de resposta desejado, que deve ser preenchido como application/json, ou seja, formato JSON.
  • authorization: a chave de acesso à API, que pode ser selecionada diretamente após a solicitação.
Além disso, configuramos o Corpo da Solicitação, incluindo:
  • image_url: a imagem de referência, a qual os elementos como personagens e fundo do vídeo gerado serão baseados.
  • video_url: o link de obtenção do vídeo de referência. Os movimentos dos personagens no vídeo gerado serão consistentes com o vídeo de referência.
  • mode: o modo de geração do vídeo, que possui os modos padrão std e o modo rápido pro.
  • keep_original_sound: opção para manter o som original do vídeo, valores enumerados: yes, no.
  • character_orientation: a orientação dos personagens no vídeo gerado, podendo ser escolhida para ser consistente com a imagem ou com o vídeo, valores enumerados: image, video.
  • prompt: a palavra-chave.
  • callback_url: a URL para onde os resultados devem ser retornados.
Após a seleção, você pode notar que o código correspondente também foi gerado à direita, conforme mostrado na imagem:

Clique no botão “Tentar” para realizar o teste, como mostrado na imagem acima, e assim obtemos o seguinte resultado: 
{
  "success": true,
  "video_id": "842578800134742051",
  "video_url": "https://v4-fdl.kechuangai.com/ksc2/yGPGHvUVDQEzDCs6tC0rYIbd_JwWNFaF8BEYAlw_xVcWX72xFuIUVqB_Hp5Sa7YEijI-yXqfKI92WW7bmyeCtpMjSOImlOFpQCmMUa-9iojt_ifXJnex_tvNkA0ZlJmuJLpeOfvX3j8d9oeeWgLeU3ftzBjQq1g9OC9FU92OfjRQLUTSzfWRzkhzirV32BT-BwfxgqJKsUD-WHxjqCJmOw.mp4?cacheKey=ChtzZWN1cml0eS5rbGluZy5tZXRhX2VuY3J5cHQSsAHtyCrKxB23NXn5ddMedV5Mw4pp_kOk_TRbCVA-wO9LJZuga8_KxXCzhw6bU3hS1V5PpNoSTxSkm_E80i5U1PkJ5d444cjPvoIq2VboPqCip2QbsoiVMu6CuGP7tB7fStLbezBNA4lQtHeSVPxWTE7Hy0wbJ33tKlf-X_-1ad3u0cyHfT_8EroD4iYZ1ZVasuYxAKjcdmbbVZ7NlDK9rqyI5euyz-70-M-QM5Lk6l88SRoSS2Y9drB8Z4ednHxTIh7XZcnaIiB5Xf4Mv8Rc51nUyIC5lKp02LP7oViCg6OaAhR4ynNJkCgFMAE&x-kcdn-pid=112757&pkey=AAX8ukavvkZsIz-IUg2pTvMOAV7LVItIdg_5TUYhGA1YINT8x-SR7rXY7BWLKqspLTYIjK7C0SjbXtX25Lm4_sx2V229AIyfVzjrlQQ7IjPsxvAv9cTG72YN0TPSjVowBZQ",
  "duration": "5.066",
  "state": "succeed",
  "task_id": "363c7a84-e880-472e-a4d4-098e50cfc292"
}
O resultado retornado possui vários campos, descritos a seguir:
  • success: o estado atual da tarefa de geração do vídeo.
  • task_id: o ID da tarefa de geração do 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 atual da tarefa de geração do vídeo.
Podemos ver que obtivemos 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/motion' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://sourceyoya.wenge.com/2025/06/03/683e9f76e4b0684509ab1aca.jpg",
  "video_url": "https://cdn.acedata.cloud/odwfm5.mp4",
  "prompt": "Deixe a cena mais vívida",
  "mode": "std",
  "character_orientation": "image"
}'

​
Callback Assíncrono

Como o tempo de geração da API de Geração de Movimento Kling é relativamente longo, levando 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 a solicitação da 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. A seguir, vamos entender como operar isso através de um exemplo. Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP, e os desenvolvedores devem substituí-lo pela URL do servidor HTTP que construíram. Para facilitar a demonstração, usaremos um site de exemplo de Webhook público https://webhook.site/, onde você pode abrir o site e obter uma URL de Webhook, conforme mostrado na imagem: Copie esta URL e você poderá usá-la 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, enquanto preenchemos os parâmetros correspondentes, o conteúdo específico é mostrado na imagem abaixo:

Clique em executar e você verá que imediatamente receberá 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 abaixo: 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"
}
Podemos ver que o resultado contém um campo task_id, e os outros campos são semelhantes aos mencionados acima, através deste campo é possível realizar a associação da tarefa.

​
Tratamento de Erros

Ao chamar a API, se encontrar um erro, a API retornará o código de erro e a mensagem correspondente. 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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusão

Através deste documento, você já entendeu como usar a API de Geração de Movimento Kling para implementar a funcionalidade de controle de movimento oficial da Kling. 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.