> ## 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 Turbo Os parâmetros e o modo de uso estão alinhados ao oficial; para parâmetros detalhados, consulte diretamente a documentação oficial. ## 1. Visão geral Este documento explica como usar as capacidades de geração de vídeo a partir de texto e a partir de imagem por meio do protocolo nativo do Kling 3.0 Turbo. O Turbo usa o mesmo protocolo nativo do Kling 3.0 padrão, com estruturas de requisição e resposta idênticas, diferindo apenas no escopo de recursos, nos níveis de resolução e na cobrança. Ambas as capacidades usam o modo de tarefa assíncrona: 1. Chame o endpoint de criação correspondente. 2. Salve o `data.id` presente na resposta da criação. 3. Use a mesma API Key usada ao criar a tarefa para consultar o status. 4. Após o sucesso da tarefa, obtenha e salve o vídeo gerado em `outputs`. ### 1.1 Endereços dos endpoints | Capacidade | Criar tarefa | Consultar tarefa | | - | - | - | | Texto para vídeo | `POST /v3/kling/text-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` | | Imagem para vídeo | `POST /v3/kling/image-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` | O endereço completo nos exemplos deste documento é `https://{api_domain}` somado ao caminho do endpoint na tabela, em que `{api_domain}` é o domínio da API que você usa. O Turbo oferece apenas geração de vídeo a partir de texto e a partir de imagem; não suporta vídeo Omni nem controle de movimento. ### 1.2 Autenticação Todas as requisições precisam incluir a 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. Os campos comuns são `id` (ID da tarefa gerado pelo sistema Kling, usado para consultas posteriores), `external_id` (refere-se ao `options.external_task_id`; pode não ser retornado quando não configurado) e `status` (status da tarefa após a criação, normalmente `submitted`). Na resposta da consulta, `data` é um array. Cada tarefa contém `id`, `external_id`, `status` (`submitted`, `processing`, `succeeded` ou `failed`), `message`, `create_time`, `update_time` e `outputs`. Os campos comuns dos resultados 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 do resultado com marca d'água; `duration` é a duração do vídeo em segundos. ## 2. Texto para vídeo ### 2.1 Criar tarefa ``` POST https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo ``` Campos da requisição: | Campo | Tipo | Obrigatório | Valor padrão / Faixa de valores | Descrição | | - | - | - | - | - | | `prompt` | string | Sim | | Texto do prompt, pode incluir descrições positivas e negativas; limite de 3072 caracteres, recomendado não exceder 2500 caracteres | | `settings.resolution` | string | Não | Padrão `720p`; `720p`, `1080p` | Resolução do vídeo gerado | | `settings.aspect_ratio` | string | Não | Padrão `16:9`; `16:9`, `9:16`, `1:1` | Proporção de aspecto (largura:altura) do vídeo gerado | | `settings.duration` | int | Não | Padrão 5; inteiro de 3–15 | Duração do vídeo gerado, em segundos | | `options.callback_url` | string | Não | | Endereço para receber notificações de callback quando o status da tarefa mudar | | `options.external_task_id` | string | Não | | ID de tarefa personalizado; não substitui o ID de tarefa do sistema, pode ser usado em consultas e deve ser único por usuário | | `options.watermark_info.enabled` | boolean | Não | Padrão `false` | Se deve gerar resultado com marca d'água | Vídeos com múltiplas cenas são implementados pelo formato fixo do `prompt`: “镜头 n, m, words; 镜头 n, m, words;” (separados por ponto e vírgula ASCII). Onde `n` é o número da cena (mínimo 1, máximo 6), `m` é a duração da cena (cada uma não inferior a 1, e a soma das durações de todas as cenas é igual à duração total do vídeo), e `words` é o prompt da cena (máximo de 512 caracteres). ### 2.2 Exemplo de criação ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo' \ -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", "aspect_ratio": "16:9", "duration": 5 }, "options": { "external_task_id": "turbo-text-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-turbo-text-task-id", "external_id": "turbo-text-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` Salve `data.id`. Quando `options.external_task_id` não for enviado, `data.external_id` pode não ser retornado. ### 2.3 Consultar tarefa ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` Use a mesma API Key usada ao criar a tarefa. Também é possível consultar pelo ID de tarefa personalizado usando `external_task_ids`. Em cada chamada, informe exatamente um dos parâmetros `task_ids` ou `external_task_ids`; ambos aceitam de 1 a 50 IDs separados por vírgula em inglês. Na resposta, `data` é um array e mantém a ordem dos IDs informados. ### 2.4 Exemplo de consulta ```bash theme={null} curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-turbo-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-turbo-text-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/turbo-text.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; não continue fazendo polling. Após o sucesso, salve imediatamente o arquivo correspondente a `outputs[type=video].url`; o endereço de download pode ter prazo de validade. ### 2.5 Descrição de cobrança ``` Custo da tarefa = preço por segundo da resolução correspondente × settings.duration ``` O nível de preço é determinado apenas por `settings.resolution` (`720p` ou `1080p`). Se `duration` não for informado, a cobrança é feita pelos 5 segundos padrão. Ao criar a tarefa, o valor é cobrado com base na duração solicitada; se a criação da tarefa falhar ou a geração final falhar, o valor é estornado automaticamente. O preço unitário específico deve ser consultado na página de preços do serviço que você utiliza. ## 3. Imagem para vídeo ### 3.1 Criar tarefa ``` POST https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo ``` Campos da requisição: | Campo | Tipo | Obrigatório | Valor padrão / Faixa de valores | Descrição | | - | - | - | - | - | | `contents` | array | Sim | | Conjunto de materiais de referência, com pelo menos um item | | `contents[].type` | string | Sim | `prompt`, `first_frame` | Tipo de material: prompt, imagem do primeiro quadro | | `contents[].text` | string | Não | | Texto do prompt quando `type=prompt`, máximo de 2500 caracteres | | `contents[].url` | string | Não | | Imagem do primeiro quadro quando `type=first_frame`, aceita URL ou Base64 | | `settings.resolution` | string | Não | Padrão `720p`; `720p`, `1080p` | Resolução do vídeo gerado | | `settings.duration` | int | Não | Padrão 5; inteiro de 3–15 | Duração do vídeo gerado, em segundos | | `options.external_task_id` | string | Não | | ID de tarefa personalizado; não substitui o ID de tarefa do sistema, pode ser usado em consultas e deve ser único por usuário | | `options.watermark_info.enabled` | boolean | Não | Padrão `false` | Se deve gerar resultado com marca d'água | As imagens aceitas são `.jpg`, `.jpeg` e `.png`; o arquivo não pode exceder 50 MB, a largura e a altura não podem ser inferiores a 300 pixels, e a proporção de aspecto deve estar entre 1:2.5 e 2.5:1. A geração de vídeo a partir de imagem suporta apenas imagem do primeiro quadro; por enquanto, não suporta “primeiro quadro + último quadro” nem “somente último quadro”. `options.callback_url` também pode ser enviado, com o mesmo uso do texto para vídeo. Vídeos com múltiplas cenas também são implementados pelo formato fixo do `prompt`. ### 3.2 Exemplo de criação ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo' \ -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 }, "options": { "external_task_id": "turbo-image-20260826-0001" } }' ``` Quando a criação é bem-sucedida, retorna: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-turbo-image-task-id", "external_id": "turbo-image-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` ### 3.3 Consultar tarefa Use o `data.id` da resposta de criação para consultar a tarefa: ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` Ao consultar usando `task_ids`, use a mesma API Key usada na criação da tarefa. Também é possível consultar pelo `options.external_task_id` informado na criação usando `external_task_ids`. O parâmetro de consulta aceita de 1 a 50 IDs separados por vírgula em inglês. ### 3.4 Exemplo de consulta ```bash theme={null} curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-turbo-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-turbo-image-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/turbo-image.mp4", "duration": 5 } ] } ] } ``` Quando `status=processing`, recomenda-se continuar consultando a cada 10–30 segundos. Quando `status=failed`, pare o polling e ajuste a entrada com base na mensagem de erro. ### 3.5 Descrição de cobrança ``` Custo da tarefa = preço por segundo da resolução correspondente × settings.duration ``` O nível de preço é determinado apenas por `settings.resolution` (`720p` ou `1080p`). Se `duration` não for informado, a cobrança é feita pelos 5 segundos padrão. Ao criar a tarefa, o valor é cobrado com base na duração solicitada; se a criação da tarefa falhar ou a geração final falhar, o valor é estornado automaticamente. O preço unitário específico deve ser consultado na página de preços do serviço que você utiliza. ## 4. Erros comuns e observações Erros da API seguem a seguinte estrutura: ```json theme={null} { "code": 1203, "message": "task not found (trace_id: platform-trace-id)", "request_id": "", "data": null } ``` Códigos de status comuns: 400/1200 (parâmetros ou tipo de conteúdo inválidos; ajuste conforme `message`), 401/1000 (API Key ausente ou inválida), 403/1103 (sem permissão para executar), 404/1203 (tarefa inexistente ou sem permissão para consultar), 429/1302 (requisições frequentes demais; reduza a frequência e use backoff exponencial), 500/5000, 503/5001, 504/5002 (serviço anormal ou timeout; tente novamente mais tarde e evite reenvios descontrolados). Se `message` contiver `trace_id`, forneça-o ao contatar o suporte técnico. Outras observações: * O corpo da requisição não precisa incluir `model` ou `model_name`; a versão do modelo já está contida na URL. * Após criar a tarefa, persista `data.id`; não use `request_id` como ID da tarefa. * O corpo de uma única requisição tem o limite de 64 MB; para imagens grandes, recomenda-se usar uma URL pública acessível pela Kling. * As URLs dos materiais de entrada precisam ser publicamente acessíveis pela Kling; não podem depender de rede interna, cookies ou estado de login temporário. * No endpoint de consulta, use intervalo de polling de 10–30 segundos e configure um timeout global e backoff exponencial. * O timeout de um POST não significa necessariamente que a tarefa não foi criada; primeiro consulte usando `external_task_id` e então decida se deve tentar novamente. * Assim que receber o status de sucesso, salve imediatamente o arquivo correspondente a `outputs[type=video].url`; a URL do resultado pode expirar. ## 5. Exemplo de chamada em Python O exemplo a seguir usa a biblioteca padrão `requests` e demonstra a criação e o polling de uma tarefa de texto para vídeo. Para imagem para vídeo, basta substituir o endpoint de criação e o corpo da requisição. ```python theme={null} import os import time import requests api_domain = os.environ["API_DOMAIN"] api_key = os.environ["PLATFORM_API_KEY"] headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.