Kling AI Image-to-Video
Visão Geral
Anime imagens estáticas usando o endpoint /v1/videos/image2video. Suporta prompts de movimento, controle de câmera, máscaras dinâmicas (pincel de movimento), máscaras estáticas e imagens de cauda para transições início-fim.
Endpoint: POST https://api.klingai.com/v1/videos/image2video
Parâmetros da Requisição
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model_name | string | Sim | kling-v1-5, kling-v2-1, kling-v2-master, etc. |
image | string | Sim | URL da imagem de origem (JPG, PNG, WebP) |
prompt | string | Não | Descrição do movimento para a animação |
negative_prompt | string | Não | O que excluir |
duration | string | Sim | "5" ou "10" segundos |
aspect_ratio | string | Não | "16:9" padrão |
mode | string | Não | "standard" ou "professional" |
cfg_scale | float | Não | Adesão ao prompt (0.0-1.0) |
image_tail | string | Não | URL da imagem do quadro final (mutuamente exclusivo com máscaras/câmera) |
camera_control | object | Não | Movimento da câmera (mutuamente exclusivo com máscaras/image_tail) |
static_mask | string | Não | URL da imagem da máscara para regiões fixas |
dynamic_masks | array | Não | Trajetórias do pincel de movimento |
callback_url | string | Não | Webhook para conclusão |
Conversão Básica de Imagem para Vídeo
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"}
# Anima uma foto de paisagem
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-1",
"image": "https://exemplo.com/paisagem.jpg",
"prompt": "Nuvens se movendo lentamente pelo céu, vento suave balançando as árvores",
"negative_prompt": "estático, congelado, borrado",
"duration": "5",
"mode": "standard",
})
task_id = response.json()["data"]["task_id"]
# Poll para resultado
while True:
time.sleep(15)
result = requests.get(
f"{BASE}/videos/image2video/{task_id}", headers=get_headers()
).json()
if result["data"]["task_status"] == "succeed":
print(f"Vídeo: {result['data']['task_result']['videos'][0]['url']}")
break
elif result["data"]["task_status"] == "failed":
raise RuntimeError(result["data"]["task_status_msg"])
Transição Início-Fim (image_tail)
Use image_tail para especificar tanto o primeiro quanto o último quadro. O Kling interpola o movimento entre eles.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://exemplo.com/nascer-do-sol.jpg", # primeiro quadro
"image_tail": "https://exemplo.com/por-do-sol.jpg", # último quadro
"prompt": "Timelapse do sol se movendo pelo céu",
"duration": "5",
"mode": "professional",
})
Pincel de Movimento (dynamic_masks)
Desenhe caminhos de movimento para elementos específicos na imagem. Até 6 caminhos de movimento por imagem na v2.6.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-6",
"image": "https://exemplo.com/pessoa-em-pe.jpg",
"prompt": "Pessoa andando para frente de forma natural",
"duration": "5",
"dynamic_masks": [
{
"mask": "https://exemplo.com/mascara-pessoa.png", # branco = região selecionada
"trajectories": [
{"x": 0.5, "y": 0.7, "t": 0.0}, # posição inicial (normalizado 0-1)
{"x": 0.5, "y": 0.5, "t": 0.5}, # ponto médio
{"x": 0.5, "y": 0.3, "t": 1.0}, # posição final
]
}
],
})
Máscara Estática (regiões congeladas)
Mantenha áreas específicas da imagem estáticas enquanto anima o restante.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://exemplo.com/cena.jpg",
"prompt": "Água fluindo no rio, pássaros voando",
"duration": "5",
"static_mask": "https://exemplo.com/mascara-predios.png", # branco = congelado
})
Regras de Exclusividade Mútua
Estes recursos não podem ser combinados em uma única requisição:
| Conjunto de Recursos A | Conjunto de Recursos B |
|---|---|
image_tail | dynamic_masks, static_mask, camera_control |
dynamic_masks / static_mask | image_tail, camera_control |
camera_control | image_tail, dynamic_masks, static_mask |
Requisitos de Imagem
| Restrição | Valor |
|---|---|
| Formatos | JPG, PNG, WebP |
| Tamanho máx. | 10 MB |
| Resolução mín. | 300x300 px |
| Resolução máx. | 4096x4096 px |
| Formato da máscara | PNG com branco (selecionado) / preto (excluído) |
Tratamento de Erros
| Erro | Causa | Correção |
|---|---|---|
400 imagem inválida | URL inacessível ou formato incorreto | Verifique se a URL da imagem está acessível publicamente |
400 exclusividade mútua | Recursos incompatíveis combinados | Use apenas um conjunto de recursos por requisição |
task_status: failed | Imagem muito complexa ou de baixa qualidade | Use resolução maior, fonte mais clara |
| Incompatibilidade de máscara | Dimensões da máscara diferentes da fonte | Garanta que a máscara corresponda às dimensões da imagem de origem |
Pré-requisitos
- Uma credencial de API Kling armazenada no gerenciador de segredos do runtime, uma lista de permissões aprovada de modelo e duração, e um orçamento de crédito por job.
- Uma imagem de origem sintética ou com direitos autorais liberados, bem como qualquer imagem de máscara ou cauda, com consentimento registrado para pessoas identificáveis e permissão para transformar o ativo.
- Um bucket de staging privado e um proprietário de revisão. Novas gerações devem permanecer apenas como rascunho e com marca d'água até que a política, qualidade e aprovação de publicação sejam registradas.
Instruções
- Resolva as referências de origem e máscara a partir de uma lista de permissões aprovada; rejeite dados de URLs não confiáveis, proveniência ausente ou ativos contendo uma pessoa identificável sem consentimento documentado.
- Valide formato, dimensões, exclusividade mútua de recursos, comprimento do prompt e a duração solicitada antes de gastar créditos. Use um fixture sintético para verificações automatizadas.
- Deduplica a requisição usando uma chave de job estável, submeta apenas após a verificação da política de conteúdo ser aprovada, e mantenha a tarefa e a fonte em armazenamento de staging privado.
- Execute um canário sandbox curto e com marca d'água. Verifique o movimento, o resultado da política, a fidelidade da fonte e o orçamento de crédito antes de solicitar aprovação do proprietário para um render maior ou público.
- Após aprovação, promova o resultado exato da tarefa pelo digest. Em caso de falha ou retirada, pare a publicação downstream, remova a mídia em staging e URLs temporárias, e restaure o ativo ou estado de job aprovado anterior.
- Registre um recibo editado contendo apenas digests opacos de tarefa e ativo, resultados de política e aprovação, resultado de orçamento, prazo de retenção e referência de rollback.
Saída
Retorne um resultado contendo o identificador opaco da tarefa, modelo e duração, status, digest de saída ou URL de staging privada, estado de canary/aprovação e referência de limpeza ou rollback. Não coloque imagens de origem, URLs de máscaras, prompts, dados faciais, credenciais ou respostas do provedor não editadas em logs ou recibos.
Exemplos
Para uma verificação automatizada segura, use um fixture sintético de paisagem e um canary privado:
source=fixture:synthetic-landscape-v3; rights=cleared; mode=standard;
duration=5; canary=watermarked-sandbox; policy=pass; approval=pending;
publish=false; contacts_exported=0; receipt=asset-sha256:opaque
Não substitua por uma foto de cliente ao vivo ou publique o canary até que consentimento, política, qualidade e aprovação do proprietário estejam todos registrados.