API do Kling 3.0: guia de migração, Motion Control e código

Não basta trocar uma string de modelo para atualizar com segurança uma requisição do Kling 2.6. O Kling 3.0 já está disponível oficialmente, mas as rotas V3, Turbo, Omni e Motion Control têm recursos e esquemas próprios. O caminho mais seguro é definir primeiro a rota e acrescentar áudio, múltiplas cenas e controles de referência aos poucos.

Escolha a rota antes de começar a programar

O guia oficial do VIDEO 3.0 da Kling apresenta o 3.0 como sucessor do VIDEO 2.6 e do VIDEO O1: o VIDEO 2.6 evolui para VIDEO 3.0, enquanto o VIDEO O1 evolui para VIDEO 3.0 Omni. A API para desenvolvedores expõe operações separadas por modelo; portanto, “API do Kling 3.0” representa uma família de acessos, não um único corpo de requisição universal.

O erro de integração mais comum é misturar o esquema simplificado de um provedor com o esquema direto da Kling: a requisição hospedada da Krea é um exemplo funcional, mas não comprova que a mesma URL ou os mesmos campos se aplicam à documentação oficial para desenvolvedores da Kling.

Para uma visão mais ampla das rotas, consulte o guia de integração da API do Kling. Este artigo se concentra na migração para o Kling 3.0 e no comportamento dos endpoints.

O que muda do Kling 2.6 para o 3.0

O guia de modelos da própria Kling indica que o avanço relevante está no controle, na continuidade e na direção audiovisual — não apenas em um preset de resolução superior. A tabela abaixo se baseia nos recursos que a Kling atribui à família de modelos.

Na prática, uma integração 2.6 baseada em um único prompt curto pode virar uma sequência dirigida no 3.0. O guia da Kling também afirma preservar melhor personagens, objetos e detalhes da cena durante movimentos de câmera, mas não publica um benchmark independente de consistência. Mantenha essa alegação separada daquilo que sua aplicação consegue testar de fato.

Monte a menor integração assíncrona funcional hospedada na Krea

A geração de vídeo é assíncrona. Sua aplicação deve enviar um job, guardar o identificador da tarefa, consultar seu status ou receber um callback e persistir a saída concluída. Não mantenha a requisição HTTP original aberta enquanto o modelo renderiza.

O exemplo abaixo usa o endpoint público do Kling 3.0 documentado pela Krea porque os campos de requisição e job estão visíveis no guia da API do Kling 3.0 publicado por ela. Substitua a URL e os nomes de campos específicos do provedor somente depois de verificar o esquema oficial da Kling que pretende usar.

Envie o job de geração

import os
import time
import requests

API_KEY = os.environ["KREA_API_KEY"]
BASE_URL = "https://api.krea.ai"

payload = {
    "prompt": (
        "A paper boat crosses a rain-filled city gutter at night, "
        "macro camera, practical street lights, realistic water movement"
    ),
    "duration": 5,
    "mode": "std",
    "aspect_ratio": "16:9",
}

response = requests.post(
    f"{BASE_URL}/generate/video/kling/kling-3.0",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
job_id = job["job_id"]
print(f"submitted {job_id}")

A resposta documentada pela Krea inclui um job_id e um status inicial como scheduled. O exemplo do provedor usa um endpoint separado de consulta do job para verificar o status. Seu banco de dados deve salvar o ID do job junto com seu próprio ID de pedido antes de iniciar o polling.

Faça polling com limite de tempo e salve a saída

TERMINAL = {"completed", "failed", "cancelled"}

for attempt in range(60):
    status_response = requests.get(
        f"{BASE_URL}/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    status_response.raise_for_status()
    job = status_response.json()
    status = job.get("status")

    if status in TERMINAL:
        break

    time.sleep(5)
else:
    raise TimeoutError(f"Kling job did not finish: {job_id}")

if job["status"] != "completed":
    raise RuntimeError(f"Kling job ended as {job['status']}: {job_id}")

video_url = job["result"]["urls"][0]
print(video_url)

Os exemplos da Krea levaram 51 segundos e 2 minutos e 3 segundos; por isso, use timeouts que considerem a fila em vez de prometer um tempo fixo de geração do Kling.

Em produção, um webhook pode eliminar o polling repetido. Verifique o ID do job em relação a um job criado pelo seu sistema, torne o handler idempotente e não considere um callback sem assinatura como prova de identidade por si só.

Inclua os controles do 3.0 aos poucos

Os nomes dos parâmetros variam entre a API direta da Kling e os provedores hospedados. Crie uma pequena camada de compatibilidade, em vez de espalhar JSON específico de cada provedor pela aplicação.

O guia oficial oferece suporte a áudio nativo, referências de elementos, narrativas de múltiplas cenas e cinco idiomas de diálogo nomeados. O endpoint de API escolhido pode expor apenas uma parte desse conjunto de recursos da família.

Um payload personalizado para múltiplas cenas

O esquema documentado pela Krea usa trechos temporizados em multi_prompt. É um padrão útil para uma integração hospedada:

{
  "multi_prompt": [
    {
      "prompt": "Wide shot: a lighthouse stands on a calm rocky coast at dusk.",
      "duration": 4
    },
    {
      "prompt": "Storm clouds arrive; waves rise and spray crosses the rocks.",
      "duration": 4
    },
    {
      "prompt": "Night rain begins as the lighthouse beam sweeps toward camera.",
      "duration": 4
    }
  ],
  "duration": 12,
  "generate_audio": true,
  "mode": "std",
  "aspect_ratio": "16:9"
}

Valide se a duração no nível superior é igual à soma das durações de cada trecho. A Krea informa um resultado de 12,04 segundos em um teste de 12 segundos com três trechos; portanto, não suponha que a duração do arquivo será matematicamente exata ao milissegundo.

Cada trecho da Krea é limitado a 512 caracteres, e toda a sequência dirigida tem teto de 15 segundos. Escreva cada trecho como uma direção de cena — sujeito, mudança e câmera — em vez de um longo texto descritivo. Se sua rota direta da Kling usar a gramática oficial de cenas, mantenha o mesmo modelo de timeline, mas traduza o payload na fronteira do adaptador.

Limites de áudio e idiomas

O guia oficial lista chinês, inglês, japonês, coreano e espanhol como idiomas de diálogo compatíveis, além de descrever dialetos, sotaques, diálogos específicos por personagem e cenas multilíngues. Segundo ele, entradas de diálogo não compatíveis são traduzidas para o inglês; aplicações multilíngues não devem presumir que todos os idiomas de origem serão preservados.

O áudio também é uma decisão de custo. As tarifas publicadas pela Krea listam std a $0.1764 por segundo sem áudio e $0.2646 com áudio; pro custa $0.2352 sem áudio e $0.3528 com áudio. A tarifa 4K listada é de $0.441 por segundo, com ou sem áudio. São preços da Krea, não uma tabela universal da API do Kling.

Um ciclo de iteração sensato é renderizar primeiro rascunhos sem som e ativar o áudio apenas no candidato final em std ou pro.

Limites de produção: custo, velocidade e tratamento de falhas

O guia oficial voltado ao consumidor da Kling lista o VIDEO 3.0 a 6 créditos por segundo para 720p sem áudio nativo, 8 créditos por segundo para 1080p sem áudio nativo, 9 créditos por segundo para 720p com áudio e 12 créditos por segundo para 1080p com áudio. O Voice Control acrescenta 2 créditos por segundo. Esses valores ajudam a entender o custo relativo dentro daquele guia; não devem ser convertidos em preço em dólar da API para desenvolvedores sem consultar a página de preços ativa para desenvolvedores.

A escolha direta não é apenas “qual modelo é o mais barato?”. É uma decisão de cobrança e operação:

Trate as falhas por categoria:

1. Repita erros transitórios do provedor com backoff exponencial limitado.
2. Não repita parâmetros inválidos até que seu adaptador corrija o payload.
3. Mantenha uma chave de idempotência ou ID de pedido no cliente para que um timeout de rede não crie um job duplicado sem ser percebido.
4. Defina um teto rígido em dólares ou créditos para geração em lote.
5. Baixe ou copie o resultado para armazenamento durável antes que a URL temporária do provedor expire.
6. Registre juntos a variante do modelo, duração, configuração de áudio, faixa de resolução e provedor; apenas “Kling 3.0” não basta para contabilizar custos.

Checklist de migração do Kling 2.6 para o 3.0

1. Mapeie as chamadas atuais do 2.6. Registre IDs de modelo, entradas de imagem, quadros inicial/final, duração, áudio e comportamento de callback.
2. Escolha a rota da família 3.0. Use V3 para geração cinematográfica guiada por prompt, Turbo para a rota mais rápida, Omni para o caminho multimodal no estilo O1 e Motion Control para trabalhos com referência de movimento.
3. Crie um adaptador de provedor. Mantenha os esquemas diretos da Kling, da Krea e de outros serviços hospedados atrás de tradutores separados.
4. Migre primeiro a menor requisição. Teste uma geração silenciosa de cinco segundos em 16:9 antes de incluir áudio ou controles de múltiplas cenas.
5. Adicione um controle por teste. Valide a duração, depois o áudio, em seguida a direção de cena e, por fim, as referências. Isso facilita isolar um campo com problema.
6. Teste estados terminais. Cubra cenários de sucesso, falha, cancelamento, timeout, callback duplicado e URL de saída expirada.
7. Faça um lançamento paralelo com custo medido. Compare um conjunto fixo de prompts entre o 2.6 e o 3.0, usando a mesma duração e faixa de saída; então decida se o ganho de qualidade ou controle justifica a nova rota.

A migração estará concluída quando sua aplicação conseguir reverter o ID do modelo sem alterar a lógica de negócio, os controles de cobrança ou o tratamento dos resultados.

Perguntas frequentes sobre a API do Kling 3.0

Existe uma API oficial do Kling 3.0?

Sim. A documentação oficial para desenvolvedores da Kling expõe páginas de API específicas para os modelos 3.0, e o guia oficial apresenta o VIDEO 3.0 como sucessor do VIDEO 2.6. O esquema exato do endpoint deve ser consultado no console de desenvolvedores ativo, pois algumas páginas são renderizadas no cliente.

Motion Control é um parâmetro do Kling 3.0?

Não presuma isso. O Motion Control é um recurso especializado com sua própria página de modelo no ecossistema Kling. Use a operação e o esquema de entrada documentados pelo provedor escolhido, em vez de adicionar um campo motion_control não verificado a uma requisição padrão de texto para vídeo.

Qual é a duração máxima gerada pelo Kling VIDEO 3.0?

O guia oficial de modelos da Kling informa que o VIDEO 3.0 aceita saídas flexíveis de 3 a 15 segundos. Uma rota hospedada ou Turbo específica pode impor limites menores; portanto, valide o endpoint selecionado.

O Kling 3.0 oferece suporte a áudio nativo?

Sim, segundo o guia oficial do VIDEO 3.0, que descreve diálogos específicos por personagem, vários idiomas, dialetos e sotaques. Se o áudio é opcional e como ele é cobrado depende do endpoint ou do esquema do provedor.

Kling 3.0 Omni é igual ao Kling 3.0 padrão?

Não. A Kling posiciona o VIDEO 3.0 como sucessor do 2.6 e o VIDEO 3.0 Omni como sucessor do O1. As páginas dos provedores podem expô-los com IDs de modelo diferentes e controles distintos de referência ou voz.

Uma assinatura web do Kling pode pagar chamadas de API?

Trate assinaturas de consumidor e cobrança da API para desenvolvedores como coisas separadas até que a documentação ativa da conta diga o contrário. Normalmente, a rota de API exige sua própria conta de desenvolvedor, chave e configuração de cobrança.

O limite útil da migração é simples: preserve o ciclo de vida dos jobs da integração 2.6, substitua o adaptador específico do modelo e valide cada novo controle do 3.0 na rota que de fato o atende. Isso evita o tipo mais caro de falha: uma integração que envia a requisição com sucesso, mas usa silenciosamente a variante, o modo de áudio ou a faixa de cobrança errados.