Kling AI - Texto para Vídeo
Visão Geral
Gere vídeos a partir de prompts textuais usando o endpoint /v1/videos/text2video. Suporta modelos v1 a v2.6, modos standard e professional, controle de câmera, prompts negativos e áudio nativo (v2.6+).
Endpoint: POST https://api.klingai.com/v1/videos/text2video
Parâmetros da Requisição
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model_name | string | Sim | Versão do modelo (veja catálogo de modelos) |
prompt | string | Sim | Descrição do vídeo, máximo de 2500 caracteres |
negative_prompt | string | Não | O que excluir da geração |
duration | string | Sim | "5" ou "10" segundos |
aspect_ratio | string | Não | "16:9" (padrão), "9:16", "1:1", etc. |
mode | string | Não | "standard" (padrão) ou "professional" |
cfg_scale | float | Não | Adesão ao prompt (0.0-1.0, padrão 0.5) |
camera_control | object | Não | Configuração de movimento de câmera |
callback_url | string | Não | URL do webhook para notificação de conclusão |
Exemplo Completo — Python
import jwt, time, os, requests
BASE = "https://api.klingai.com/v1"
def get_headers():
ak, sk = os.environ["KLING_ACCESS_KEY"], os.environ["KLING_SECRET_KEY"]
token = jwt.encode(
{"iss": ak, "exp": int(time.time()) + 1800, "nbf": int(time.time()) - 5},
sk, algorithm="HS256", headers={"alg": "HS256", "typ": "JWT"}
)
return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
# Criar tarefa de texto para vídeo
response = requests.post(f"{BASE}/videos/text2video", headers=get_headers(), json={
"model_name": "kling-v2-6",
"prompt": "Aerial drone shot of a coral reef at golden hour, "
"tropical fish swimming through crystal clear water, "
"sun rays penetrating the surface, cinematic 4K",
"negative_prompt": "blurry, low quality, distorted, watermark",
"duration": "5",
"aspect_ratio": "16:9",
"mode": "professional",
"cfg_scale": 0.5,
})
task = response.json()
task_id = task["data"]["task_id"]
# Polling até a conclusão
while True:
time.sleep(15)
result = requests.get(
f"{BASE}/videos/text2video/{task_id}", headers=get_headers()
).json()
status = result["data"]["task_status"]
if status == "succeed":
video = result["data"]["task_result"]["videos"][0]
print(f"URL do Vídeo: {video['url']}")
print(f"Duração: {video['duration']}s")
break
elif status == "failed":
raise RuntimeError(result["data"]["task_status_msg"])
# else: submitted/processing — continue polling
Com Controle de Câmera
# Tipos de movimento da câmera: pan, tilt, zoom, roll
response = requests.post(f"{BASE}/videos/text2video", headers=get_headers(), json={
"model_name": "kling-v2-6",
"prompt": "A medieval castle on a cliff at sunrise, fog in the valley",
"duration": "5",
"mode": "standard",
"camera_control": {
"type": "simple",
"config": {
"horizontal": 5, # mover para direita (negativo = esquerda), intervalo -10 a 10
"vertical": 0, # inclinar para cima/baixo (negativo = para baixo, positivo = para cima)
"zoom": 3, # zoom in (positivo) ou out (negativo)
"roll": 0, # rotação
"pan": 0, # dolly esquerda/direita
"tilt": -2, # dolly cima/baixo
}
},
})
Regra: Apenas um campo não nulo em config para type: "simple".
Com Áudio Nativo (apenas v2.6)
response = requests.post(f"{BASE}/videos/text2video", headers=get_headers(), json={
"model_name": "kling-v2-6",
"prompt": "A jazz band performing in a dimly lit club, saxophone solo, "
"audience clapping, warm amber lighting",
"duration": "10",
"mode": "professional",
"motion_has_audio": True, # gera áudio sincronizado
})
Dicas de Engenharia de Prompt
| Técnica | Exemplo |
|---|---|
| Cena + ação + estilo | "A samurai walking through cherry blossoms, cinematic slow motion" |
| Dicas de iluminação | "golden hour", "neon-lit", "overcast diffused light" |
| Linguagem de câmera | "close-up", "wide establishing shot", "tracking shot" |
| Prompt negativo | "blurry, watermark, text overlay, distorted faces" |
| Material/textura | "brushed steel", "hand-painted watercolor", "photorealistic" |
Referência de Custos
| Duração | Standard | Professional |
|---|---|---|
| 5 segundos | 10 créditos | 35 créditos |
| 10 segundos | 20 créditos | 70 créditos |
Tratamento de Erros
| Erro | Causa | Correção |
|---|---|---|
400 prompt inválido | Prompt vazio ou >2500 caracteres | Verifique o tamanho do prompt |
400 modelo inválido | model_name não suportado | Use um ID de modelo válido do catálogo |
402 créditos insuficientes | Créditos insuficientes | Recarregue sua conta |
task_status: failed | Violação de política de conteúdo ou complexidade | Simplifique o prompt, remova conteúdo restrito |
Pré-requisitos
- Um brief aprovado, material de referência com direitos liberados ou sintético, um workspace e orçamento autorizados, uma revisão de política de conteúdo e um proprietário nomeado para publicação e remoção.
Instruções
- Crie um rascunho sandbox a partir de um brief aprovado; não inclua pessoas privadas, material protegido ou alegações não verificadas em prompts ou uploads.
- Verifique a duração, estilo, destino, orçamento de crédito, status da política de conteúdo e configuração de apenas rascunho solicitados antes do envio.
- Revise uma renderização com marca d'água para política, direitos e qualidade; pare em caso de preocupação com política ou atribuição e exclua o rascunho em vez de publicá-lo.
- Promova somente após aprovação do proprietário e retenha um recibo de produção editado; remova ativos temporários no prazo de retenção aprovado.
Saída
Produza um recibo de renderização com ID do brief, classificação da fonte aprovada, modelo/modo, duração, estimativa de crédito, resultado da revisão de política e direitos, destino do rascunho, aprovador, referência de retenção/remoção e ID da tarefa. Exclua texto do prompt, identidades e credenciais.
Exemplos
brief=synthetic-product-demo; source=rights-cleared; mode=standard; duration=5s; policy=pass; destination=draft-only; approval=pending; cleanup=24h é uma solicitação de teste segura.