API do Kling: guia de integração oficial e por agregadores (2026)

Uma solicitação de vídeo do Kling não se resume a uma chamada universal de API. O Kling, modelo de geração de vídeo da Kuaishou, está disponível pela Open Platform oficial e por agregadores como WaveSpeedAI, KIE e fal. Cada rota tem credenciais, IDs de modelo, estruturas de requisição e cobrança próprios. O fluxo que permanece consistente é o assíncrono: envie o job, salve seu ID, aguarde um status final e obtenha a saída sem fazer novas tentativas sem controle.

Escolha a rota antes de pensar no SDK

O Kling mantém uma Open Platform oficial, mas uma busca por “Kling API” também retorna gateways independentes. A decisão deve considerar o acesso ao fornecedor, a velocidade de integração e o controle de cobrança — não apenas o nome do modelo.

Para consultar preços por resolução, use o guia de preços da API do Kling 3. Neste artigo, trate preço, multiplicadores de áudio, concorrência e cobrança de tarefas com falha como configurações específicas de cada fornecedor.

Fluxo pela plataforma oficial do Kling

Use a Open Platform oficial quando a contratação exigir uma relação direta com a Kuaishou ou quando você precisar da disponibilidade de modelos de primeira parte. A documentação oficial atual separa configuração de credenciais, criação de tarefas, callbacks, regras de concorrência e códigos de erro. Portanto, siga essa rota em vez de adaptar o payload de um agregador:

1. Crie ou recupere a credencial oficial no guia de autenticação e mantenha o token no servidor.
2. Envie a tarefa assíncrona de vídeo documentada, usando o endpoint específico do modelo e os campos de requisição mostrados na referência oficial.
3. Adicione callback_url quando quiser receber atualizações de status. Os estados de callback documentados incluem submitted, processing, succeed e failed; em falhas, salve task_status_msg.
4. Aplique localmente a alocação de concorrência atual da conta. O guia oficial de concorrência descreve sobrecarga como HTTP 429 com código de negócio 1303, e não como trabalho que o Kling necessariamente colocará em fila por você.
5. Use a referência oficial de códigos de erro para diferenciar credenciais inválidas, parâmetros incorretos, recursos esgotados, bloqueios de política e falhas de servidor que permitem nova tentativa.

A página oficial de autenticação é renderizada no cliente na versão acessível da documentação. Por isso, este guia não reproduz um trecho de geração de token que não tenha sido verificado. Copie o formato atual da credencial nessa página, em vez de supor que um header da WaveSpeed, KIE ou fal funcionará.

Ainda assim, é possível normalizar o ciclo de vida oficial sem presumir detalhes do payload:

official_credential = get_from_kling_console()
task = POST official_model_endpoint(official_credential, documented_input)
store(task.task_id)
wait_for_callback_or_query_status(task.task_id)
if status == "succeed": save_output(task_result.videos)
else: classify(http_status, business_code, task_status_msg)

Isso é um esboço do ciclo de vida, não um endpoint pronto para copiar e colar. Consulte a referência oficial vinculada para conferir token, caminho, campos de requisição e envelope de resposta.

Quando um agregador faz mais sentido

Agregadores aceleram protótipos que precisam de acesso pay-as-you-go, uma conta para vários modelos ou um SDK do fornecedor. Em compensação, eles controlam a chave, o esquema, a fila, a URL de saída e, em alguns casos, a retenção. Antes de tentar novamente, identifique qual camada falhou.

O contrato da API do Kling que vale padronizar

Um cliente de produção deve esconder os detalhes de cada fornecedor atrás de uma única função interna. Independentemente da rota, sua aplicação precisa seguir estas etapas:

1. Valide o prompt e as URLs de mídia antes de gastar créditos.
2. Envie uma tarefa de geração de vídeo com um ID de modelo específico do fornecedor.
3. Persista imediatamente o ID retornado da tarefa ou previsão.
4. Receba um callback ou consulte um endpoint de resultado até que o job alcance um estado final.
5. Salve a URL de saída, o fornecedor, o modelo, os parâmetros e os metadados de custo.
6. Pare de tentar novamente quando o fornecedor informar falha, cancelamento, timeout ou exclusão.

A abstração deve retornar um objeto normalizado por você, por exemplo:

{
  "provider": "wavespeed",
  "job_id": "provider-job-id",
  "status": "queued",
  "output_url": null,
  "error": null
}

Parâmetros que se adaptam bem entre provedores

Os conceitos se transferem bem; os nomes dos campos, não. generate_audio, sound e generate_audio: true podem descrever comportamentos relacionados em serviços distintos. Trate o esquema de cada fornecedor como um adaptador separado.

Parâmetros que não são intercambiáveis

Os IDs de modelo são a primeira armadilha. kling-3.0, kling-3.0/video, fal-ai/kling-video/v3/standard/text-to-video e kwaivgi/kling-v3.0-std/text-to-video identificam rotas de API diferentes, não valores que podem ser trocados entre si.

O mesmo vale para headers de autenticação, nomes de callback, URLs de resultado, valores de status da tarefa e regras de upload de arquivos. Um cliente que fixa uma string de status de um fornecedor — como completed — pode classificar incorretamente uma resposta succeeded ou failed de outro.

Três formatos reais de requisição

Estes exemplos específicos de cada fornecedor mostram por que não existe um endpoint universal para o Kling.

WaveSpeedAI: ID de previsão e consulta do resultado

A WaveSpeedAI documenta o Kling 3.0 Standard de texto para vídeo neste endpoint:

POST https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video

A requisição usa um token Bearer. O endpoint retorna um ID de previsão, e o resultado é obtido em:

GET https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

Um fluxo cURL mínimo é:

export WAVESPEED_API_KEY="replace_me"

submit=$(curl --fail-with-body -s \
  -X POST \
  "https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic sunrise over a futuristic cityscape",
    "duration": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5,
    "shot_type": "customize"
  }')

prediction_id=$(printf '%s' "$submit" | jq -r '.data.id // .id')

curl -s \
  "https://api.wavespeed.ai/api/v3/predictions/$prediction_id/result" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY"

A documentação do modelo da WaveSpeedAI informa duração de 3–15 segundos, proporções 16:9, 9:16 e 1:1, além de cfg_scale padrão de 0.5. A tabela de preços do Standard mostra US$ 0,42 para um clipe de 5 segundos sem som e US$ 0,63 com som. Considere esses valores um retrato desse fornecedor, não um preço universal do Kling.

Em produção, consulte o endpoint de resultado com backoff, em vez de disparar requisições em loop apertado. Pare em completed, failed, cancelled, timeout ou deleted, que são os status finais documentados para esse endpoint.

KIE: createTask com callback ou consulta da tarefa

A KIE utiliza um endpoint compartilhado de criação de tarefas:

POST https://api.kie.ai/api/v1/jobs/createTask

O identificador do modelo Kling 3.0 é kling-3.0/video, e a autenticação usa token Bearer. Um payload compacto para um único plano é assim:

{
  "model": "kling-3.0/video",
  "callBackUrl": "https://example.com/webhooks/kie",
  "input": {
    "prompt": "A paper boat moving across a sunlit stream, gentle camera push-in",
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "sound": false,
    "multi_shots": false
  }
}

A KIE documenta vídeos de 3–15 segundos, proporções de saída 16:9, 9:16 e 1:1, e até cinco planos no modo multi-shot. As entradas multi-shot podem especificar de 1–12 segundos cada. Elementos de imagem usam de 2–4 URLs JPG ou PNG, com máximo documentado de 10 MB por imagem; elementos de vídeo usam uma URL MP4 ou MOV de até 50 MB.

O callback é opcional, mas a KIE o recomenda em produção. Seu webhook deve verificar a assinatura quando disponível, responder rapidamente e colocar o resultado da tarefa em uma fila. Mantenha a consulta da tarefa como rota de recuperação para callbacks perdidos.

A KIE documenta códigos de resposta distintos para falhas comuns, incluindo 401 para autenticação inválida, 402 para créditos insuficientes, 422 para erros de validação e 429 para limites de taxa. Registre código e mensagem juntos: uma mensagem genérica de “falha no Kling” não basta para decidir se uma nova tentativa é segura.

fal: endpoint do modelo com cliente de fila

A fal disponibiliza o Kling 3.0 por IDs de endpoint específicos de cada modelo. Para Standard de texto para vídeo, o ID documentado é:

fal-ai/kling-video/v3/standard/text-to-video

A API bruta usa o header Authorization: Key $FAL_KEY. Os exemplos em Python e JavaScript usam o cliente da fal com suporte à fila, normalmente mais simples do que escrever seu próprio loop de consulta.

import { fal } from "@fal-ai/client";

fal.config({ credentials: process.env.FAL_KEY });

const result = await fal.subscribe(
  "fal-ai/kling-video/v3/standard/text-to-video",
  {
    input: {
      prompt: "A paper boat moving across a sunlit stream, gentle camera push-in",
      duration: 5,
      aspect_ratio: "16:9",
      generate_audio: false,
      negative_prompt: "blur, distort, low quality",
      cfg_scale: 0.5
    },
    logs: true
  }
);

console.log(result.data.video.url);

A fal documenta duração de 3–15 segundos, três proporções para texto para vídeo e intervalo de cfg_scale de 0–1, com padrão de 0.5. O esquema Standard informa que prompt e multi_prompt são alternativas: envie um deles, não ambos. O padrão documentado para generate_audio é true; portanto, defina-o explicitamente se seu orçamento ou pipeline de pós-produção pressupõe saída sem som.

A fal também documenta IDs separados para imagem para vídeo e controle de movimento. Não deduza esses IDs apenas trocando text-to-video em uma string sem consultar a referência atual do modelo.

Cotas, tempo de fila e proteção de créditos

Não existe uma cota pública única do Kling que se aplique à plataforma oficial, WaveSpeedAI, KIE e fal. Concorrência, limites de taxa, saldo de créditos, cobrança de tarefas com falha e retenção da saída pertencem à rota escolhida. Armazene esses valores como configuração do fornecedor, e não como constantes chamadas KLING_LIMIT.

Um usuário resumiu o risco operacional com mais precisão do que uma recomendação genérica de novas tentativas:

“O Kling cobra por geração e tem latência real de fila. A primeira coisa que eu implementaria é um limite de custo/concorrência; caso contrário, um agente que tenta novamente ao receber um frame ruim pode consumir seus créditos silenciosamente durante a noite.” — @ukrroot no X

Proteções para orçamento e concorrência

Implemente estes controles antes de permitir que um agente ou worker em lote chame o Kling:

1. Máximo de jobs em andamento: Defina um teto específico por fornecedor, em vez de iniciar um job para cada prompt.
2. Orçamento por job: Estime duração, nível, áudio e quantidade de saídas antes do envio.
3. Orçamento de tentativas: Tente novamente falhas de transporte de forma seletiva; não repita erros de validação, autenticação ou créditos insuficientes.
4. Livro-razão de jobs: Registre o ID do job do fornecedor antes de qualquer requisição de acompanhamento, para que uma reinicialização do worker não envie uma geração duplicada.
5. Política de estados finais: Marque jobs com falha, cancelados, expirados ou excluídos como concluídos, exceto quando o fornecedor disser explicitamente que é seguro reenviá-los.
6. Alerta de crédito: Interrompa a fila quando o saldo ou o gasto projetado ultrapassar um limite.
7. Segurança de chaves e saídas: Mantenha as chaves no servidor, revogue chaves expostas imediatamente e copie vídeos concluídos para armazenamento durável.

Um teste Standard de cinco segundos pode ser barato diante de um job Pro de 15 segundos ou com áudio ativado, mas o que é “barato” depende do fornecedor. Consulte a página atual do modelo antes de definir o nível padrão.

O que medir antes de ir para produção

Acompanhe estes campos em toda requisição:

Trate latência e cotas como aspectos específicos de cada endpoint: as fontes públicas não fornecem um único SLA entre fornecedores.

Perguntas frequentes sobre a API do Kling

O Kling tem API oficial?

Sim. O Kling mantém uma área de documentação para desenvolvedores da Open Platform oficial. A rota oficial e os gateways de terceiros são serviços separados; portanto, confirme credenciais, cotas e preços atuais na documentação da Kling Open Platform.

Existe um endpoint universal para a API do Kling?

Não. A plataforma oficial, WaveSpeedAI, KIE e fal usam caminhos de endpoint, IDs de modelo, headers de autenticação e envelopes de resposta diferentes. Crie um adaptador por fornecedor, em vez de supor que kling-3.0 é válido em qualquer lugar.

Devo usar polling ou webhooks?

Use callback ou webhook em produção quando o fornecedor oferecer suporte, mas mantenha o polling para testes locais e recuperação de callbacks perdidos. Adicione backoff exponencial, um limite total de espera e idempotência para que um callback atrasado não crie um registro duplicado.

Quais durações e proporções são aceitas?

Várias documentações atuais de agregadores para o Kling 3.0 listam clipes de 3–15 segundos e proporções 16:9, 9:16 e 1:1. Endpoints individuais podem variar, então valide na página do modelo selecionado em vez de tratar esses valores como um contrato universal de primeira parte.

Ativar áudio altera o custo?

Em geral, pode alterar. A WaveSpeedAI documenta multiplicador de som de 1.5× para seu endpoint Kling 3.0 Standard, enquanto fal e KIE expõem áudio ou som como parâmetros de requisição. Verifique a página de cobrança atual do endpoint selecionado e defina a flag explicitamente.

Por que uma nova tentativa gerou cobranças extras?

Uma nova tentativa pode criar uma segunda geração mesmo quando o primeiro job ainda está na fila. Persista o ID do job, use um limite de concorrência, repita apenas falhas transitórias e reconcilie a cobrança do fornecedor antes de reenviar uma solicitação ambígua.

No primeiro teste próximo de produção, execute um job Standard silencioso de 5 segundos, registre todo o ciclo de vida e só então adicione Pro, áudio, multi-shot ou concorrência, depois que o tratamento de workers duplicados estiver funcionando.