> ## Documentation Index > Fetch the complete documentation index at: https://docs.jiekou.ai/llms.txt > Use this file to discover all available pages before exploring further. # Kling 3.0 & 3.0 Omni Os parâmetros e o modo de uso estão alinhados com a versão oficial. Para parâmetros detalhados, consulte diretamente a documentação oficial. ## 1. Visão geral Este documento explica como usar os recursos de vídeo a partir de texto, vídeo a partir de imagem, vídeo Omni e controle de movimento por meio do protocolo nativo Kling 3.0. Os quatro recursos utilizam o modo de tarefa assíncrona: 1. Chame a API de criação correspondente. 2. Salve o `data.id` da resposta de criação. 3. Use a mesma API Key usada na criação da tarefa para consultar o status. 4. Após o sucesso da tarefa, obtenha e salve o vídeo gerado a partir de `outputs`. ### 1.1 Endereços da API | Recurso | Criar tarefa | Consultar tarefa | | - | - | - | | Vídeo a partir de texto | `POST /v3/kling/text-to-video/kling-3.0` | `GET /v3/kling/tasks` | | Vídeo a partir de imagem | `POST /v3/kling/image-to-video/kling-3.0` | `GET /v3/kling/tasks` | | Vídeo Omni | `POST /v3/kling/omni-video/kling-3.0-omni` | `GET /v3/kling/tasks` | | Controle de movimento | `POST /v3/kling/motion-control/kling-3.0` | `GET /v3/kling/tasks` | Nos exemplos deste documento, o endereço completo é `https://{api_domain}` mais o caminho da API indicado na tabela, em que `{api_domain}` é o domínio da API que você utiliza. ### 1.2 Autenticação Todas as requisições exigem uma API Key. Requisições POST também devem especificar o tipo de conteúdo JSON: ``` Authorization: Bearer Content-Type: application/json ``` ### 1.3 Estrutura da resposta Na resposta de criação, `data` é um objeto com os seguintes campos comuns: | Campo | Tipo | Descrição | | - | - | - | | `id` | string | ID da tarefa gerado pelo sistema Kling, usado para consultas posteriores | | `external_id` | string | Retorno de `options.external_task_id`; pode não ser retornado quando não for definido | | `status` | string | Status da tarefa após a criação, geralmente `submitted` | Na resposta de consulta, `data` é uma matriz e cada tarefa contém os seguintes campos: | Campo | Tipo | Descrição | | - | - | - | | `id` | string | ID da tarefa gerado pelo sistema | | `external_id` | string | ID personalizado da tarefa do chamador, se houver | | `status` | string | `submitted`, `processing`, `succeeded` ou `failed` | | `message` | string | Informação de status da tarefa; em caso de falha, contém o motivo da falha, se houver | | `create_time` | integer | Hora de criação, timestamp Unix em milissegundos, se houver | | `update_time` | integer | Hora de atualização, timestamp Unix em milissegundos, se houver | | `outputs` | array | Resultados gerados; tarefas bem-sucedidas geralmente contêm um resultado com `type=video` | Os campos comuns do resultado de vídeo em `outputs` são `type`, `id`, `url`, `watermark_url` e `duration`. `url` é o endereço do resultado sem marca d'água, `watermark_url` é o endereço com marca d'água e `duration` é a duração do vídeo em segundos. ## 2. Vídeo a partir de texto Descrição oficial dos parâmetros: Text to Video ### 2.1 Criar tarefa ``` POST https://{api_domain}/v3/kling/text-to-video/kling-3.0 ``` Campos comuns da requisição: | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `prompt` | string | Sim | Prompt de geração do vídeo, não pode ser vazio, máximo de 3072 caracteres | | `settings.multi_shot` | boolean | Não | Se gera vídeo com múltiplos planos, padrão `true` | | `settings.resolution` | string | Não | `720p`, `1080p` ou `4k`, padrão `720p` | | `settings.aspect_ratio` | string | Não | `16:9`, `9:16` ou `1:1`, padrão `16:9` | | `settings.audio` | string | Não | `off` ou `native`, padrão `off` | | `settings.duration` | integer | Não | 3–15 segundos, padrão 5 segundos | | `options.callback_url` | string | Não | Endereço que recebe notificações de callback quando o status da tarefa muda | | `options.external_task_id` | string | Não | ID personalizado da tarefa | | `options.watermark_info.enabled` | boolean | Não | Se gera resultado com marca d'água, padrão `false` | Com `multi_shot=true`, você pode descrever múltiplos planos no prompt de acordo com o formato oficial da Kling; a soma das durações de cada plano deve ser igual à duração total do vídeo. ### 2.2 Exemplo de criação ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A cinematic tracking shot of a red sports car driving along a coastal road at sunset", "settings": { "resolution": "1080p", "duration": 5, "audio": "native" }, "options": { "external_task_id": "text-video-20260826-0001" } }' ``` Após a criação bem-sucedida, retorna o ID da tarefa: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-text-task-id", "external_id": "text-video-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` ### 2.3 Consultar tarefa ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` Salve `data.id`. Se `options.external_task_id` não for enviado, `data.external_id` pode não ser retornado. Use a mesma API Key usada na criação da tarefa. Se o ID da tarefa não existir ou não estiver acessível, será retornado `task not found`. Também é possível consultar pelo ID personalizado usando `external_task_ids`: ``` GET https://{api_domain}/v3/kling/tasks?external_task_ids={external_task_id} ``` Use `task_ids` ou `external_task_ids` em cada chamada, apenas um deles. Ambos aceitam de 1 a 50 IDs separados por vírgula, e `data` na resposta é uma matriz que mantém a ordem dos IDs da requisição. ### 2.4 Exemplo de consulta ```bash theme={null} curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-text-task-id' \ -H 'Authorization: Bearer ' ``` Quando a tarefa é bem-sucedida, retorna: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": [ { "id": "kling-text-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/text-video.mp4", "duration": 5 } ] } ] } ``` `status=processing` indica que a tarefa ainda está em execução; recomenda-se consultar a cada 10–30 segundos. `status=failed` indica que a tarefa falhou e não se deve continuar a pesquisa. Após o sucesso da tarefa, salve imediatamente o arquivo correspondente a `outputs[type=video].url`; o endereço de download pode ter validade. ### 2.5 Instruções de cobrança ``` Custo da tarefa = preço unitário por segundo do nível de resolução e áudio correspondente × settings.duration ``` O nível de preço é definido por `settings.resolution` e `settings.audio`. Por exemplo, o custo de `1080p`, `audio=native`, `duration=5` é "preço unitário por segundo do nível de áudio nativo 1080p × 5 segundos". Quando `duration` não é enviado, a cobrança considera 5 segundos padrão. Ao criar a tarefa, o valor é cobrado pela duração solicitada; se a criação da tarefa falhar ou a geração final falhar, o valor é reembolsado automaticamente. O preço unitário específico segue a página de preços do serviço que você utiliza. ## 3. Vídeo a partir de imagem Descrição oficial dos parâmetros: Image to Video ### 3.1 Criar tarefa ``` POST https://{api_domain}/v3/kling/image-to-video/kling-3.0 ``` Campos comuns da requisição: | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `contents` | array | Sim | Lista de conteúdos multimodais, contendo pelo menos um item | | `contents[].type` | string | Sim | `prompt`, `first_frame`, `last_frame` ou `element` | | `settings.resolution` | string | Não | `720p`, `1080p` ou `4k`, padrão `720p` | | `settings.multi_shot` | boolean | Não | Se gera vídeo com múltiplos planos, padrão `true` | | `settings.audio` | string | Não | `off` ou `native`, padrão `off` | | `settings.duration` | integer | Não | 3–15 segundos, padrão 5 segundos | | `options.callback_url` | string | Não | Endereço que recebe notificações de callback quando o status da tarefa muda | | `options.external_task_id` | string | Não | ID personalizado da tarefa | | `options.watermark_info.enabled` | boolean | Não | Se gera resultado com marca d'água, padrão `false` | Campos dos subitens de `contents`: | type | Campos obrigatórios | Descrição | | - | - | - | | `prompt` | `text` | Prompt de texto, máximo de 3072 caracteres | | `first_frame` | `url` | Imagem do primeiro quadro, suporta URL ou Base64; obrigatória | | `last_frame` | `url` | Imagem do último quadro, suporta URL ou Base64; não suporta apenas o último quadro, é necessário também o primeiro quadro | | `element` | `element_id`, `id` | ID do sujeito e o ID de índice usado para referenciar o sujeito no prompt; `id` não pode se repetir na mesma tarefa; suporta especificar no máximo 3 sujeitos | As imagens suportam `.jpg`, `.jpeg` e `.png`, com arquivo de no máximo 50 MB, dimensões mínimas de 300 pixels em largura e altura, e proporção entre 1:2,5 e 2,5:1. ### 3.2 Exemplo de criação ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "contents": [ { "type": "prompt", "text": "The subject turns toward the camera while the wind moves naturally through the scene" }, { "type": "first_frame", "url": "https://your-cdn.example.com/first-frame.png" } ], "settings": { "resolution": "1080p", "duration": 5, "audio": "off" }, "options": { "external_task_id": "image-video-20260826-0001" } }' ``` Quando a criação é bem-sucedida, `data.id` é o ID da tarefa usado nas consultas posteriores: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-image-task-id", "external_id": "image-video-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` ### 3.3 Consultar tarefa Consulte a tarefa usando `data.id` da resposta de criação: ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` Ao consultar por `task_ids`, use a mesma API Key usada na criação da tarefa. Você também pode consultar pelo `options.external_task_id` enviado na criação usando `external_task_ids`. O parâmetro de consulta aceita de 1 a 50 IDs separados por vírgula. ### 3.4 Exemplo de consulta ```bash theme={null} curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-image-task-id' \ -H 'Authorization: Bearer ' ``` Quando a tarefa é bem-sucedida, o endereço do vídeo está em `outputs[type=video].url`: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": [ { "id": "kling-image-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/image-video.mp4", "duration": 5 } ] } ] } ``` Quando `status=processing`, recomenda-se continuar consultando a cada 10–30 segundos; quando `status=failed`, pare a pesquisa e corrija a entrada com base na mensagem de erro. ### 3.5 Instruções de cobrança ``` Custo da tarefa = preço unitário por segundo do nível de resolução e áudio correspondente × settings.duration ``` O nível de preço é definido por `settings.resolution` e `settings.audio`. Quando `duration` não é enviado, a cobrança considera 5 segundos padrão. Ao criar a tarefa, o valor é cobrado pela duração solicitada; se a criação da tarefa falhar ou a geração final falhar, o valor é reembolsado automaticamente. O preço unitário específico segue a página de preços do serviço que você utiliza. ## 4. Vídeo Omni Descrição oficial dos parâmetros: Omni Video ### 4.1 Criar tarefa ``` POST https://{api_domain}/v3/kling/omni-video/kling-3.0-omni ``` Campos comuns da requisição: | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `contents` | array | Sim | Lista de conteúdos multimodais, contendo pelo menos um item | | `contents[].type` | string | Sim | `prompt`, `first_frame`, `last_frame`, `refer_image`, `feature_video`, `base_video` ou `element` | | `settings.resolution` | string | Não | `720p`, `1080p` ou `4k`, padrão `720p` | | `settings.multi_shot` | boolean | Não | Se gera vídeo com múltiplos planos, padrão `true` | | `settings.aspect_ratio` | string | Não | `16:9`, `9:16` ou `1:1`, padrão `16:9`; obrigatório quando não há imagem do primeiro quadro ou vídeo de referência | | `settings.audio` | string | Não | `off`, `native` ou `original`, padrão `off` | | `settings.duration` | integer | Não | 3–15 segundos, padrão 5 segundos | | `options.callback_url` | string | Não | Endereço que recebe notificações de callback quando o status da tarefa muda | | `options.external_task_id` | string | Não | ID personalizado da tarefa | | `options.watermark_info.enabled` | boolean | Não | Se gera resultado com marca d'água, padrão `false` | Campos dos subitens de `contents`: \| type This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.