Processo de Solicitação
Para usar a API Kling Motion Generation, primeiro acesse o Console Ace Data Cloud para obter seu API Token e mantê-lo em reserva.
Se você ainda não tiver feito login ou se registrado, será automaticamente redirecionado para a página de login para convidá-lo a se registrar e fazer login, e retornará automaticamente à página atual após a conclusão.
Um único API Token pode chamar todos os serviços da plataforma, sem necessidade de solicitar separadamente para cada serviço. Na primeira solicitação, créditos gratuitos serão oferecidos para uma experiência gratuita; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no console.
📘 Documentação completa: Kling Motion Generation API →
Uso Básico
Primeiro, vamos entender o método básico de uso: basta inserir o promptprompt, 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, também precisamos inserir o modelo mode; atualmente, existem principalmente os modelos std e pro, e os detalhes são os seguintes:
accept: qual formato de resultado de resposta deseja receber; aqui, preencha comapplication/json, ou seja, o formato JSON.authorization: a chave para chamar a API, que pode ser selecionada diretamente no menu suspenso após a solicitação.
image_url: URL da imagem de referência da aparência do personagem. Suporta JPG/JPEG/PNG, arquivo ≤50MB, largura e altura ambas ≥300px, proporção entre largura e altura de 1:2.5～2.5:1; o personagem deve exibir claramente a parte superior do corpo ou o corpo inteiro e a cabeça.video_url: URL do vídeo de referência de movimento. Suporta MP4/MOV, arquivo ≤100MB, largura e altura de 340–3850px cada, pelo menos 3 segundos; quandocharacter_orientation=image, no máximo 10 segundos; quandocharacter_orientation=video, no máximo 30 segundos. Recomenda-se usar um vídeo contínuo de plano único em que o personagem permaneça sempre no quadro.mode: o modo para gerar o vídeo, principalmente o modo padrãostde o modo rápidopro.keep_original_sound: é possível escolher se deseja manter o áudio original do vídeo, valores de enumeração: yes, no.character_orientation: a orientação do personagem no vídeo gerado; é possível escolher consistente com a imagem ou consistente com o vídeo, valores de enumeração: image, video.prompt: prompt.callback_url: a URL que precisa receber o resultado de callback.async: opcional; quando definido comotrue, a interface retorna imediatamentetask_id, sem necessidade de fornecercallback_url; em seguida, obtenha o resultado por polling através da interface de consulta de tarefas correspondente.
success, o status da tarefa de geração de vídeo neste momento.task_id, o ID da tarefa de geração de vídeo neste momento.video_id, o ID do vídeo da tarefa de geração de vídeo neste momento.video_url, o link do vídeo da tarefa de geração de vídeo neste momento.duration, a duração do link de vídeo da tarefa de geração de vídeo neste momento.state, o status da tarefa de geração de vídeo neste momento.
data no resultado.
Além disso, se quiser gerar o código de integração correspondente, você pode copiá-lo diretamente; por exemplo, o código CURL é o seguinte:
Callback Assíncrono
Como o tempo de geração da API Kling Motion Generation é relativamente longo, levando aproximadamente 1-2 minutos, se a API não responder por muito tempo, a solicitação HTTP manterá a conexão continuamente, resultando em consumo adicional de recursos do sistema; por isso, esta API também fornece suporte para callback assíncrono. O processo geral é: quando o cliente inicia uma solicitação, ele especifica adicionalmente um campocallback_url; após o cliente iniciar a solicitação da API, a API retornará imediatamente um resultado contendo informações do campo task_id, que representa o ID da tarefa atual. Após a tarefa ser concluída, o resultado do vídeo gerado será enviado na forma de POST JSON para o callback_url especificado pelo cliente, também incluindo o campo task_id, para que o resultado da tarefa possa ser associado por meio do ID.
A seguir, vamos entender como operar especificamente por meio de 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 próprio criou. Aqui, para facilitar a demonstração, é usado um site público de exemplo de Webhook, https://webhook.site/; ao abrir esse site, é possível obter uma URL de Webhook, como mostrado na imagem:
Copie esta URL para usá-la como Webhook; o exemplo aqui é https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3.
Em seguida, podemos definir o campo callback_url como a URL de Webhook acima e, ao mesmo tempo, preencher os parâmetros correspondentes; o conteúdo específico é mostrado na imagem:
https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, como mostrado na imagem:
O conteúdo é o seguinte:
task_id no resultado, os outros campos são semelhantes aos descritos acima, e a associação da tarefa pode ser realizada por meio desse campo.
Tratamento de erros
Ao chamar a API, se ocorrer um erro, a API retornará o código e as informações 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.