> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Instruções de Integração da API de Geração de Movimento Kling
> Kling video generation 集成指南 - XHuoAPI
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](https://api.xhuoapi.ai/documents/d3f2c369-102d-4856-9565-702ac5f2df63). 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:
```json theme={null}
{
"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:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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/](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:
```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"
}
```
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
```json theme={null}
{
"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.