API de imagem para vídeo do Kling AI em Python

Use a API de imagem para vídeo do Kling AI em Python através do endpoint de tarefas assíncronas da HiAPI. O início rápido abaixo usa o ID de modelo kling-3.0-omni/image-to-video disponível no momento, consulta a tarefa até que ela atinja um estado terminal e baixa o MP4 gerado.

Para consultar os campos exatos, abra a documentação da API de imagem para vídeo do Kling 3.0 Omni. Use a página atual do modelo Omni para ver o modelo e o Playground, e verifique o preço em tempo real da API do Kling antes de executar em produção.

Início rápido: executar o Kling de imagem para vídeo em Python

Instale o requests com python -m pip install requests, defina HIAPI_API_KEY no ambiente e substitua IMAGE_URL por uma URL pública de JPEG, PNG ou WebP. O script completo é o primeiro bloco de código copiável:

import os
import time
from pathlib import Path

import requests

API_BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
IMAGE_URL = "https://cdn.example.com/first-frame.jpg"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "kling-3.0-omni/image-to-video",
    "input": {
        "image_urls": [IMAGE_URL],
        "prompt": "The camera slowly pushes in as leaves move in a light breeze",
        "duration": 5,
        "resolution": "1080p",
        "sound": False,
    },
}

created = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["taskId"]

deadline = time.time() + 900
while time.time() < deadline:
    response = requests.get(
        f"{API_BASE}/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"]

    if task["status"] == "success":
        output_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(task.get("error") or f"Task {task_id} failed")

    time.sleep(8)
else:
    raise TimeoutError(f"Task {task_id} did not finish within 15 minutes")

with requests.get(output_url, stream=True, timeout=180) as download:
    download.raise_for_status()
    with Path("kling-output.mp4").open("wb") as video:
        for chunk in download.iter_content(1024 * 1024):
            if chunk:
                video.write(chunk)

print("Saved kling-output.mp4")

A requisição de criação retorna um taskId e não espera a geração do vídeo ser concluída. O script consulta GET /v1/tasks/{taskId}, para em success ou fail e baixa a primeira saída o quanto antes, pois a URL do resultado expira.

Abra o modelo Kling Omni e experimente este payload.

Escolha o modelo de imagem para vídeo do Kling atualmente disponível

ID do modelo	Cenário de uso	Convenções de entrada e saída
kling-3.0-omni/image-to-video	Necessidade de controle de primeiro/último quadro, áudio nativo opcional ou 4K	Uma ou duas URLs públicas de imagem; 3-15 segundos; 720p, 1080p ou 4K
kling-3.0-turbo/image-to-video	Apenas um quadro inicial, e um schema mais simples em 720p/1080p atende à necessidade	Exatamente uma URL pública de imagem; prompt obrigatório; 3-15 segundos; 720p ou 1080p

A referência completa de campos do Omni está na documentação do Omni I2V. O Turbo tem uma referência de schema própria do Turbo I2V. Ambos usam o mesmo fluxo de criação e consulta em /v1/tasks, portanto você pode manter um único executor e substituir apenas model e input.

Corpo da requisição compatível com os requisitos do modelo

Omni com primeiro e último quadro

Envie uma URL para representar o primeiro quadro, ou envie duas URLs na ordem [first, last]:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": {
    "image_urls": [
      "https://cdn.example.com/first-frame.jpg",
      "https://cdn.example.com/last-frame.jpg"
    ],
    "prompt": "The camera arcs around the subject as the light changes from dawn to noon",
    "duration": 8,
    "resolution": "1080p",
    "sound": true
  }
}

O Omni aceita um ou dois image_urls. Seu prompt é opcional, duration é um inteiro de 3 a 15 e resolution é 720p, 1080p ou 4K; sound é opcional.

Turbo com um quadro inicial

{
  "model": "kling-3.0-turbo/image-to-video",
  "input": {
    "prompt": "The subject turns toward the camera while leaves move in a light breeze",
    "image_urls": ["https://cdn.example.com/first-frame.jpg"],
    "duration": 8,
    "resolution": "1080p"
  }
}

O Turbo exige o prompt e exatamente um item em image_urls. Não envie campos suportados apenas pelo Omni (por exemplo, sound), nem adicione campos de texto para vídeo (por exemplo, aspect_ratio); a imagem determina o enquadramento.

Preços do Kling AI: use as faixas em tempo real, não copie preços

Os preços do Kling AI na HiAPI são cobrados por uso. Atualmente, os dois modelos de imagem para vídeo são cobrados pela quantidade de segundos gerados, com tarifas definidas pelo modelo e pela resolução; o Omni também tem uma faixa diferente com áudio ativado. Clipes mais longos, resoluções mais altas ou áudio nativo alteram o custo da tarefa.

As tarifas podem mudar, por isso este guia não fixa uma tabela de preços em dólares. Antes de orçar ou enviar tarefas em lote, consulte imediatamente a tabela de preços dos modelos em tempo real.

O Kling AI é gratuito?

Não: na HiAPI, a geração pela API de imagem para vídeo do Kling não é uma API gratuita e ilimitada. Tarefas bem-sucedidas consomem saldo conforme a tarifa em tempo real do modelo, duração, resolução e configuração de áudio escolhidos. Promoções de conta ou bônus para novos usuários podem mudar e estar sujeitos a condições, portanto não os trate como um nível gratuito garantido do Kling; verifique as ofertas vigentes e seu saldo na conta antes de enviar tarefas.

Verificações de produção que evitam falhas ou tarefas duplicadas

1. Use URLs de imagem HTTPS diretamente baixáveis. localhost, páginas que exigem login, páginas de compartilhamento HTML e URLs assinadas expiradas podem falhar após a criação da tarefa.
2. Salve o taskId antes de repetir o worker. Repetir a chamada de criação pode criar e cobrar uma segunda tarefa.
3. Trate success e fail como estados terminais. Em produção, use o callback.url de nível superior e mantenha a consulta periódica como contingência de reconciliação.
4. Baixe output[].url rapidamente e copie os resultados que precisam ser mantidos a longo prazo para um armazenamento sob seu controle.
5. Valide o schema do modelo escolhido antes de enviar. Contratos estritos de modelo rejeitam campos desconhecidos.

Erros comuns

• HTTP 400: a requisição não corresponde ao schema; verifique os campos indicados, valores de enumeração, comprimentos de array e tipos JSON.
• HTTP 401: a chave bearer está ausente, é inválida ou não pode usar o modelo escolhido.
• Tarefa entra em fail: a requisição de criação passou na validação, mas o renderizador não conseguiu obter a entrada ou concluir a geração. Registre o taskId e o erro retornado separadamente da resposta de criação.
• URL de saída expirada: a renderização pode ter sido concluída, mas a URL temporária de download não foi baixada a tempo.

Perguntas frequentes

Qual modelo de imagem para vídeo do Kling devo usar em Python?

Use kling-3.0-omni/image-to-video quando precisar de controle de um ou dois quadros, áudio nativo opcional ou 4K. Use kling-3.0-turbo/image-to-video quando um quadro inicial e saída em 720p/1080p forem suficientes. O código Python de criação, consulta e download permanece o mesmo.

Quais são os IDs atuais dos modelos de imagem para vídeo do Kling AI?

Os IDs disponíveis no momento abordados neste artigo são kling-3.0-omni/image-to-video e kling-3.0-turbo/image-to-video. Envie qualquer um deles no campo model de nível superior em POST /v1/tasks.

Quantas imagens o Kling de imagem para vídeo aceita?

O Omni aceita uma imagem como primeiro quadro, ou duas imagens na ordem [first, last]. O Turbo aceita exatamente uma imagem de quadro inicial.

Quanto custa a API do Kling AI?

A cobrança é por segundos gerados. A tarifa exata em tempo real depende do modelo e da resolução, e no Omni também da configuração de áudio. Use a página de preços em tempo real; não copie preços estáticos deste guia.

O uso do Kling AI via API é gratuito?

Não há garantia de um nível gratuito ilimitado da API do Kling. A geração consome o saldo da conta conforme a tarifa em tempo real da tarefa. Verifique se há alguma oferta inicial vigente e sujeita a condições na conta, em vez de presumir uma cota gratuita fixa.

Por que uma tarefa ainda falha após a requisição de criação ser bem-sucedida?

O JSON passou na validação inicial, mas o renderizador pode não conseguir obter a imagem ou concluir a geração. Confirme que a imagem é pública e não expirou, e depois verifique o erro de estado terminal usando o taskId salvo.

Como obter o vídeo gerado?

Leia data.taskId na resposta de criação. Scripts locais podem consultar GET /v1/tasks/{taskId}; em produção, use callback.url. Em success, baixe data.output[0].url antes que expire.

Em seguida, leia a referência completa da API do Kling Omni e, quando estiver pronto para testar a requisição, abra a página atual do modelo.