Como usar a API da Kling sem onboarding direto da Kling: Guia de 2026

TL;DR Você pode acessar os modelos de vídeo Kling compatíveis por meio da CometAPI com uma conta CometAPI e uma chave de API, em vez de concluir um fluxo separado de onboarding de desenvolvedor da Kling. A rota atual de texto para vídeo é POST /kling/v1/videos/text2video. Ela retorna um ID de tarefa, que seu backend consulta até a tarefa chegar a succeed ou failed. A disponibilidade de modelos, parâmetros, preços e elegibilidade da conta podem mudar, portanto verifique o catálogo de modelos ao vivo e a documentação da API antes da implantação em produção.

Resposta direta

O caminho prático é o catálogo de modelos Kling da CometAPI. Se o modelo Kling de que você precisa estiver disponível para a sua conta CometAPI, seu servidor pode autenticar com uma chave de API da CometAPI e chamar o endpoint compatível com Kling correspondente. Por esse caminho, uma aplicação de API da Kling separada não faz parte das etapas de integração.

Essa distinção importa para equipes que já usam a CometAPI para outros modelos. O aplicativo mantém uma única superfície de gerenciamento de credenciais e um relacionamento com o provedor, enquanto adiciona um fluxo de vídeo Kling. Seu código ainda precisa usar o esquema de requisição específico de vídeo da Kling e o ciclo de vida de tarefa assíncrona; “uma chave de API” não significa que todos os provedores compartilham um corpo de requisição idêntico.

Este artigo foca em texto para vídeo porque é a menor integração útil. A CometAPI também documenta imagem para vídeo e outros fluxos da Kling, mas cada um tem seu próprio endpoint e restrições de parâmetros. Comece com um caminho verificado e só depois adicione recursos após conferir a documentação atual.

Por que esse caminho pode ser útil para uma equipe de desenvolvimento

O benefício imediato é operacional, não mágico. Uma equipe que já usa a CometAPI pode adicionar um fluxo Kling disponível sem criar outra integração direta com provedor, distribuir outra credencial ou construir um caminho separado de gerenciamento de contas. Isso pode reduzir o número de segredos, relacionamentos de faturamento e configurações de clientes específicas de provedor que sua plataforma precisa manter.

O segundo benefício é arquitetural. Seu aplicativo pode expor um pequeno contrato interno de geração de vídeo — prompt, fluxo, modelo, opções e status do job — enquanto um adaptador de provedor traduz esse contrato na requisição documentada da Kling. Se a equipe avaliar outro modelo de vídeo mais tarde, o modelo de job voltado ao produto pode permanecer estável mesmo que caminhos de endpoint, parâmetros e metadados de saída mudem.

A limitação é igualmente importante: uma camada de acesso consolidada não torna os modelos subjacentes intercambiáveis. Comportamento do prompt, mídias aceitas, latência, preços, políticas de segurança e esquemas de resultado podem variar. Mantenha essas diferenças visíveis na configuração e nos testes, em vez de escondê-las atrás de suposições sem suporte.

O que esse caminho de acesso muda — e o que não muda

O que muda. Você cria e gerencia uma chave da CometAPI, envia requisições para a API compatível com Kling da CometAPI e acompanha o uso pelo lado da CometAPI. Isso remove uma etapa separada de onboarding direto da Kling deste caminho específico de acesso.

O que não muda. Kling continua sendo a família de modelos subjacente. Parâmetros específicos do provedor, comportamento de geração, regras de uso aceitável, disponibilidade de modelos e características de saída continuam importando. A documentação da CometAPI também observa que campos de requisição e resposta do provedor podem diferir, então trate a referência do endpoint ao vivo como o contrato para sua implementação.

O que você deve verificar antes de se comprometer. Confirme que sua conta pode acessar o ID de modelo necessário, revise o preço e os limites de taxa atuais e execute um pequeno teste autenticado. Não projete um fluxo de produção em torno de um nome de modelo encontrado em um post antigo de blog ou um exemplo em cache.

Antes de começar

Você precisa de uma conta CometAPI, uma chave de API armazenada no seu servidor e um backend capaz de executar um job assíncrono. Mantenha a chave em uma variável de ambiente como COMETAPI_KEY; não a exponha em código de navegador ou cliente móvel.

1. Abra o catálogo de modelos Kling e confirme que o modelo que você pretende usar está atualmente listado para sua conta.
2. Revise a referência atual da API de texto para vídeo da Kling. No momento da verificação, o exemplo documentado usa kling-v3.
3. Crie uma chave de API no lado do servidor no console da CometAPI e defina-a no seu ambiente de execução.
4. Decida onde seu serviço irá armazenar o ID de tarefa e o vídeo final. A requisição de geração retorna uma tarefa, não o arquivo de vídeo finalizado.

Escolha o fluxo da Kling antes de projetar a requisição

Comece pelo ativo que seu produto já tem. Se o usuário possui apenas um conceito escrito, texto para vídeo é o caminho direto. Se o usuário tem uma imagem estática que deve permanecer como âncora visual, use o caminho de imagem para vídeo documentado separadamente. Não adicione um campo de imagem a uma requisição de texto para vídeo presumindo que a API irá inferir o fluxo.

A referência atual de imagem para vídeo aceita uma URL pública de imagem ou uma string de imagem em base64 e retorna uma tarefa assíncrona. Fluxos mais especializados da Kling têm suas próprias páginas e restrições de requisição. Adicione-os um de cada vez somente quando o requisito do produto e a documentação atual justificarem o adaptador extra.

Para uma primeira prova de produção, use um fluxo, um ID de modelo verificado, duração curta e um conjunto pequeno de prompts representativos. Isso isola acesso à conta e orquestração de tarefa de uma avaliação subjetiva de saída. Quando o pipeline estiver confiável, compare modos ou modelos com um conjunto de avaliação fixo em vez de mudar várias variáveis no mesmo teste.

Faça sua primeira requisição de texto para vídeo da Kling

O endpoint atual de texto para vídeo aceita JSON e autenticação Bearer. Comece com um prompt curto e a menor duração suportada. A requisição a seguir usa apenas campos mostrados na referência atual da CometAPI:

curl https://api.cometapi.com/kling/v1/videos/text2video \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Uma pequena xícara de cerâmica sobre uma mesa de madeira, vapor subindo sob a suave luz da manhã",
    "model_name": "kling-v3",
    "mode": "std",
    "duration": "5",
    "sound": "off"
  }'

Um envio bem-sucedido retorna um objeto contendo data.task_id e um status de tarefa. Salve esse ID de tarefa com o registro de job do seu aplicativo. Não mantenha a conexão HTTP aberta enquanto o vídeo é renderizado.

Trate a tarefa assíncrona com segurança

A geração Kling é assíncrona. Para texto para vídeo, faça polling em GET /kling/v1/videos/text2video/{task_id}. A referência de tarefas da CometAPI diz que uma resposta pode retornar a tarefa diretamente ou dentro de um envelope data, então o exemplo normaliza ambos os formatos. Ele também trata todo estado não terminal como “continuar aguardando”, em vez de assumir uma lista fixa de estados intermediários.

import os
import time
import requests

API_KEY = os.environ["COMETAPI_KEY"]
BASE_URL = "https://api.cometapi.com/kling/v1/videos/text2video"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def submit_video(prompt: str) -> str:
    response = requests.post(
        BASE_URL,
        headers=HEADERS,
        json={
            "prompt": prompt,
            "model_name": "kling-v3",
            "mode": "std",
            "duration": "5",
            "sound": "off",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    return payload["data"]["task_id"]


def wait_for_video(task_id: str, timeout_seconds: int = 600) -> str:
    deadline = time.monotonic() + timeout_seconds
    poll_url = f"{BASE_URL}/{task_id}"

    while time.monotonic() < deadline:
        response = requests.get(poll_url, headers=HEADERS, timeout=30)
        response.raise_for_status()
        payload = response.json()
        task = payload.get("data") or payload
        status = task.get("task_status")

        if status == "succeed":
            videos = task.get("task_result", {}).get("videos", [])
            if not videos or not videos[0].get("url"):
                raise RuntimeError("A tarefa foi concluída sem uma URL de vídeo")
            return videos[0]["url"]

        if status == "failed":
            detail = task.get("task_status_msg") or task.get("task_result")
            raise RuntimeError(f"Tarefa Kling falhou: {detail}")

        time.sleep(10)

    raise TimeoutError(f"A tarefa Kling {task_id} excedeu {timeout_seconds}s")


task_id = submit_video(
    "Uma pequena xícara de cerâmica sobre uma mesa de madeira, vapor subindo sob a suave luz da manhã"
)
video_url = wait_for_video(task_id)
print(video_url)

A string de sucesso terminal é succeed, não succeeded. Quando uma tarefa é concluída, copie o ativo gerado para um armazenamento sob seu controle se seu produto requer retenção. URLs de entrega do provedor não devem ser tratadas como armazenamento permanente do aplicativo.

Para cargas maiores, use uma fila ou worker em vez de fazer polling dentro de uma requisição web. A CometAPI também documenta URLs de callback para tarefas da Kling. Se você adotar webhooks, autentique e deduplique eventos de callback e mantenha uma alternativa de polling para entregas perdidas.

Projete o ciclo de vida do job do aplicativo antes de escalar

Trate a tarefa do provedor como uma parte do seu próprio registro de job. Armazene um ID de job do aplicativo, fluxo, modelo solicitado, ID da tarefa do provedor, URL de consulta, status atual, timestamp de envio, último horário de polling e localização da saída. Isso dá às suas equipes de suporte e operações contexto suficiente para investigar uma geração com falha ou lenta sem vasculhar logs brutos de requisições.

Não repita a requisição de criação apenas porque o cliente não recebeu uma resposta. O provedor pode já ter criado uma tarefa. Persista seu job local antes do envio, salve imediatamente o ID de tarefa retornado e separe as tentativas de criação das tentativas de consulta de status. A referência atual de texto para vídeo também documenta external_task_id para rastreamento; confirme seu comportamento ao vivo antes de depender dele como um mecanismo de deduplicação.

const TERMINAL = new Set(["succeed", "failed"]);

function normalizeKlingTask(payload) {
  const task = payload?.data ?? payload;
  if (!task?.task_id || !task?.task_status) {
    throw new Error("A resposta da Kling não contém identidade ou status da tarefa");
  }
  return task;
}

async function refreshVideoJob(job, apiKey) {
  const response = await fetch(job.queryUrl, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  if (!response.ok) {
    throw new Error(`Consulta da tarefa falhou com HTTP ${response.status}`);
  }

  const task = normalizeKlingTask(await response.json());
  const outputUrl = task.task_result?.videos?.[0]?.url ?? null;

  return {
    ...job,
    providerTaskId: task.task_id,
    providerStatus: task.task_status,
    terminal: TERMINAL.has(task.task_status),
    outputUrl,
    failureDetail: task.task_status_msg ?? null,
    checkedAt: new Date().toISOString(),
  };
}

Este exemplo deliberadamente não traduz cada possível status intermediário do provedor em uma promessa do produto. Seu worker mantém tarefas não terminais ativas, trata succeed e failed explicitamente e registra o status bruto do provedor para depuração. Adicione um tempo limite próprio do aplicativo para que uma tarefa estagnada não permaneça aberta para sempre.

Use polling como base porque o ID de tarefa permanece consultável. Quando o endpoint selecionado suportar callback_url, um webhook pode reduzir requisições repetidas de status, mas não deve se tornar seu único mecanismo de recuperação. O guia oficial de polling e webhooks observa que payloads de callback podem ser específicos do provedor. Armazene o evento bruto, torne o processamento idempotente por ID de tarefa, retorne uma resposta HTTP bem-sucedida rapidamente e reconcilie o estado terminal por meio de polling.

Lista de verificação para produção para equipes de desenvolvimento

• Validar o modelo em tempo de execução. Verifique o catálogo atual e falhe claramente quando um modelo solicitado não estiver disponível. Não substitua silenciosamente por outro modelo se o comportamento da saída for importante.
• Separar envio de recuperação. Armazene o ID de tarefa da CometAPI, seu próprio ID de job, o modelo selecionado e timestamps para que as tentativas não criem trabalho duplicado.
• Limitar o polling. Use um tempo limite, backoff exponencial ou um intervalo fixo razoável e um número máximo de tentativas. Revise a orientação de limites de taxa e concorrência da CometAPI antes de aumentar o paralelismo.
• Classificar erros. Não tente novamente parâmetros inválidos ou falhas de autenticação. Aplique backoff a erros de limite de taxa e de plataforma que sejam reaproveitáveis, seguindo o guia atual de códigos de erro e estratégia de retry.
• Proteger credenciais e entradas. Mantenha chaves de API no lado do servidor, evite registrar segredos e confirme que os usuários têm direitos sobre quaisquer prompts, imagens ou outros ativos de origem que enviarem.
• Medir o job completo. Acompanhe sucesso do envio, tempo de fila, tempo de geração, taxa de falha terminal, taxa de timeout, sucesso de recuperação de saída e custo por modelo e modo.
• Persistir saídas de forma deliberada. Baixe ativos concluídos para um armazenamento controlado por você quando seu produto precisar de acesso durável e aplique sua política de retenção e exclusão.

Perguntas frequentes práticas

Preciso de uma conta de desenvolvedor Kling separada para este caminho?

Nenhuma etapa separada de onboarding de desenvolvedor da Kling aparece no fluxo de integração da CometAPI. Você usa uma conta CometAPI e uma chave de API. O acesso ainda depende de o modelo estar disponível para sua conta CometAPI e região, então confirme isso antes de se comprometer com a produção.

A API da Kling é totalmente compatível com OpenAI?

Não para o fluxo de vídeo mostrado aqui. Ele usa rotas específicas da Kling como /kling/v1/videos/text2video e campos específicos da Kling. Você pode gerenciar a credencial por meio da CometAPI, mas seu adaptador deve preservar o esquema específico do provedor.

Qual ID de modelo da Kling devo usar?

A referência atual de texto para vídeo da CometAPI usa kling-v3 em seu primeiro exemplo funcional e lista várias trilhas anteriores de modelo. Use um ID de modelo do enum do endpoint ao vivo e verifique se ele está habilitado para sua conta. Não presuma que o modelo mais novo está disponível em todos os lugares.

Por que a primeira resposta não contém um vídeo?

A geração de vídeo é executada como uma tarefa assíncrona. A resposta inicial retorna um ID de tarefa. Faça polling na rota de consulta correspondente até task_status se tornar succeed ou failed, então leia os metadados do resultado.

Devo fazer polling ou usar uma URL de callback?

Polling é mais fácil para uma primeira integração. Callbacks reduzem requisições repetidas em escala, mas exigem um receptor autenticado, idempotente e lógica de recuperação. Muitos sistemas de produção usam callbacks como caminho principal e polling como fallback.

Posso usar imagem para vídeo pelo mesmo endpoint?

Não. A CometAPI documenta imagem para vídeo sob uma rota separada, /kling/v1/videos/image2video. Siga o esquema de requisição atual desse endpoint em vez de adicionar um campo de imagem ao exemplo de texto para vídeo.

Devo começar com o modo padrão ou profissional?

Use std para validar autenticação, formato da requisição, armazenamento da tarefa, polling e recuperação da saída. A referência atual descreve pro como um modo de maior qualidade e maior custo. Avalie-o com prompts representativos apenas depois que o fluxo básico funcionar e compare a qualidade da saída junto com o tempo de geração e o custo real.

Como posso evitar gerações duplicadas durante tentativas?

Crie um registro de job do aplicativo antes de chamar a API e salve imediatamente o ID de tarefa do provedor retornado. Repita as consultas de status de forma independente das requisições de criação. Não presuma que repetir o mesmo POST é idempotente. O endpoint atualmente documenta external_task_id para rastreamento, mas verifique sua semântica atual antes de tratá-lo como uma garantia de deduplicação.

Conclusão

Para uma equipe de desenvolvimento nos EUA que deseja testar a geração de vídeo da Kling sem concluir uma aplicação direta separada de desenvolvedor da Kling, a CometAPI oferece um caminho documentado: verifique se o modelo Kling necessário está disponível para a conta, autentique com uma chave da CometAPI, chame o endpoint específico do fluxo e acompanhe a tarefa assíncrona até um estado terminal.

O valor de engenharia prático é o acesso centralizado e um modelo de job de aplicativo reutilizável — não a suposição de que todo provedor de vídeo se comporta da mesma forma. Mantenha um adaptador enxuto para cada fluxo, persista a identidade da tarefa e a saída de forma deliberada e retenha o polling como caminho de recuperação mesmo quando callbacks estiverem habilitados.

Um rollout seguro é pequeno e mensurável: valide um modelo e um fluxo, envie jobs curtos de baixo custo, registre taxas de sucesso e falha terminais, verifique a recuperação de saída e compare custo e latência reais com os requisitos do seu produto. Expanda para imagem para vídeo ou outros fluxos da Kling somente depois que a documentação atual e sua conta de destino tiverem sido verificadas.