API de imagem para vídeo Kling 3.0 Turbo em Python: schema, script completo e tratamento de erros

O schema de kling-3.0-turbo/image-to-video é enxuto e rígido: uma URL de imagem pública, um prompt de movimento obrigatório, uma duração inteira de 3 a 15 segundos e saída em 720p ou 1080p. Esta página é a referência específica dessa versão, usada para validar esse corpo de requisição e distinguir erros HTTP 400 de resultados assíncronos TASK_FAILED.

Para o fluxo geral de criação, polling, callback e download, consulte o guia do executor de tarefas Kling em Python e de escolha entre Omni/Turbo.

Schema de entrada do Turbo

Campo	Tipo	Obrigatório	Valores aceitos
prompt	string	Sim	Descreve o movimento e o comportamento da câmera
image_urls	array de strings	Sim	Exatamente uma URL de imagem acessível publicamente
duration	integer	Não	3 a 15 segundos
resolution	string	Não	720p ou 1080p

O Turbo não aceita sound, aspect_ratio, negative_prompt, seed, mode, nem uma segunda URL de imagem. O schema rígido rejeita propriedades extras em vez de ignorá-las silenciosamente.

A imagem de entrada determina o formato do quadro. Antes de criar a tarefa, faça upload dela para um bucket ou CDN público; o renderizador não consegue buscar localhost, painéis privados ou URLs assinadas expiradas.

Requisição mínima funcional

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-turbo/image-to-video",
    "input": {
      "prompt": "The runner accelerates as the camera tracks from the side",
      "image_urls": ["https://cdn.example.com/first-frame.jpg"],
      "duration": 6,
      "resolution": "1080p"
    }
  }'

A resposta bem-sucedida contém data.taskId. O HTTP 200 indica apenas criação bem-sucedida, não conclusão; a renderização do vídeo continua de forma assíncrona.

Pré-validação em Python

Valide as restrições antes da chamada de rede, para que erros evidentes nunca criem uma tarefa:

from urllib.parse import urlparse

import requests


def turbo_input(prompt: str, image_url: str, duration: int, resolution: str) -> dict:
    if not prompt.strip():
        raise ValueError("prompt is required")
    if type(duration) is not int or not 3 <= duration <= 15:
        raise ValueError("duration must be an integer from 3 to 15")
    if resolution not in {"720p", "1080p"}:
        raise ValueError("resolution must be 720p or 1080p")
    parsed = urlparse(image_url)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        raise ValueError("image_url must be a public HTTP(S) URL")

    return {
        "prompt": prompt,
        "image_urls": [image_url],
        "duration": duration,
        "resolution": resolution,
    }


payload = {
    "model": "kling-3.0-turbo/image-to-video",
    "input": turbo_input(
        prompt="The runner accelerates as the camera tracks from the side",
        image_url="https://cdn.example.com/first-frame.jpg",
        duration=6,
        resolution="1080p",
    ),
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer sk-your-key"},
    json=payload,
    timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
print(task_id)

Essa verificação local detecta problemas de formato nos valores, mas não comprova que a imagem remota pode ser baixada publicamente. O renderizador executa essa busca após a criação da tarefa.

Script Python completo: enviar, consultar, baixar

O trecho acima termina no ID da tarefa. Esta versão executa o trabalho completo e salva o MP4. Ela envia o cabeçalho Idempotency-Key, de modo que repetir o mesmo envio após um timeout retorna a tarefa original, sem criar e cobrar uma segunda tarefa:

import os
import time
import uuid

import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}


def run_turbo(prompt: str, image_url: str, duration: int = 5,
              resolution: str = "720p", out_path: str = "turbo.mp4") -> str:
    body = {
        "model": "kling-3.0-turbo/image-to-video",
        "input": turbo_input(prompt, image_url, duration, resolution),
    }
    key = str(uuid.uuid4())  # reuse this key if you retry the same submission
    r = requests.post(API, json=body, headers={**HEADERS, "Idempotency-Key": key}, timeout=30)
    if r.status_code == 400:
        raise ValueError(f"schema error, no task created: {r.text}")
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 900
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if data["status"] == "success":
            video = requests.get(data["output"][0]["url"], timeout=120)
            video.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(video.content)  # the output URL is temporary, so save it now
            return out_path
        if data["status"] == "fail":
            raise RuntimeError(f"TASK_FAILED {task_id}: {data.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)


print(run_turbo(
    "The runner accelerates as the camera tracks from the side",
    "https://cdn.example.com/first-frame.jpg",
))

Um clipe de 5 segundos em 720p custa $0.65. Em produção, substitua o laço de polling pelo "callback": {"url": "https://your-app.example.com/hiapi/callback"} no nível superior e deduplique as notificações pelo ID da tarefa.

HTTP 400: a tarefa nunca é criada

Uma resposta HTTP 400 é o resultado da validação síncrona do schema. Causas típicas incluem:

Entrada inválida	Por que falha	Como corrigir
"duration": "5"	Enviou uma string em vez de um inteiro	Envie 5
"duration": 20	O máximo é 15	Escolha 3–15
Duas image_urls	O Turbo só aceita uma	Mantenha apenas o quadro inicial
"resolution": "4K"	O Turbo suporta 720p e 1080p	Use 720p ou 1080p, ou escolha Omni
"sound": true	sound não está no schema do Turbo	Remova o campo ou escolha Omni
Falta de prompt	O Turbo exige um prompt	Adicione um prompt de movimento não vazio

Como a validação falha antes da criação, não há ID de tarefa para consultar. Registre o corpo da resposta e o ID da requisição, corrija o corpo e reenvie uma nova requisição.

TASK_FAILED: criação bem-sucedida, mas renderização com falha

Se POST /v1/tasks retorna HTTP 200 com um ID de tarefa, a falha posterior é um problema do ciclo de vida assíncrono da tarefa e deve ser tratada de forma diferente do 400.

As causas comuns incluem:

• a URL da imagem exige Cookie ou cabeçalho de autorização;
• a URL de imagem assinada expirou antes de o renderizador buscá-la;
• o host bloqueia a busca do lado do servidor ou redireciona para uma página HTML;
• o arquivo está corrompido, ou seu tipo de mídia não corresponde ao conteúdo;
• o provedor não conseguiu concluir essa renderização.

Registre o ID da tarefa, o código e a mensagem do erro final, a URL de entrada original e o horário da requisição. Antes de tentar novamente, confirme que um servidor não autenticado consegue buscar essa imagem com uma resposta 2xx e um tipo de conteúdo de imagem. Repetir cegamente a mesma URL inacessível só cria outra tarefa com falha.

O guia Python geral contém o laço compartilhado de polling de estado terminal e o código de download da saída; mantê-lo lá evita repetir a lógica de ciclo de vida nesta página de referência da versão.

Preços do Turbo e escolha do modelo

As tarifas de produção atuais são:

Opção do Turbo	Preço por segundo	Tarefa de 5 segundos
720p	$0.130	$0.65
1080p	$0.160	$0.80

Antes de usar em grande volume, consulte a página de preços em tempo real. O nome Turbo descreve uma variante do modelo e não promete ser mais barato em todas as resoluções, nem garante um SLA de tempo de renderização fixo para as tarefas.

Quando você precisar de quadro final, áudio ou 4K, escolha o Kling 3.0 padrão (kling-3.0/image-to-video): ele aceita uma ou duas imagens (quadro inicial e final), tem a opção sound, custa $0.10/s em 720p sem áudio e $0.129/s em 1080p sem áudio. Quando precisar de imagens de referência ou vídeos de referência, escolha Omni. Para um único quadro de entrada em 720p ou 1080p, faça benchmark dessas variantes com seus próprios prompts de movimento e avalie qualidade da saída, tempo na fila e custo total.

Perguntas frequentes

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

Exatamente uma URL de imagem pública. Uma segunda imagem dispara um erro de schema (image_urls: maxItems: got 2, want 1); para controle de quadro inicial e final, use o Kling 3.0 padrão de imagem para vídeo.

Quais valores de duração são válidos?

Envie um inteiro de 3 a 15. Números entre aspas como "5" são strings e falham na validação.

O Turbo suporta 4K ou áudio?

Não suporta 4K: este endpoint aceita 720p ou 1080p. Não há campo sound, mas os clipes do Turbo já vêm com áudio, que não pode ser desativado. Quando precisar de 4K ou saída sem áudio, use o Kling 3.0 padrão ou o Omni.

Qual é a diferença entre HTTP 400 e TASK_FAILED?

HTTP 400 significa que a requisição viola o schema e, portanto, a tarefa não foi criada. TASK_FAILED ocorre após uma resposta de criação válida, na fase de busca da entrada ou de geração.

Por que uma URL de imagem aparentemente pública causa TASK_FAILED?

A URL pode depender de Cookie, ter assinatura expirada, bloquear a busca do lado do servidor ou retornar HTML em vez de bytes de imagem. Antes de tentar novamente, teste-a sem autenticação de navegador.