Como usar a API de texto para vídeo do Kling 3.0 Turbo? Parâmetros, código e erros

TL;DR

• O nome do modelo de texto para vídeo do Kling 3.0 Turbo é kling-3.0-turbo/text-to-video, a versão rápida do Kling 3.0. Abra a página do modelo para testar online.
• Cobrança por segundo: 720p a $0.13 por segundo, 1080p a $0.16 por segundo. Duração de 3 a 15 segundos, qualquer número inteiro; 5 segundos em 720p custa $0.65 por vídeo.
• São apenas 4 parâmetros: prompt, duration, aspect_ratio e resolution. Enviar qualquer campo extra (como seed ou negative_prompt) retorna 400.

Veja um exemplo primeiro

720p, 5 segundos, 16:9:

aerial drone shot sweeping over a norwegian fjord waterfall, mist drifting,
camera gliding forward, smooth natural motion, stable cinematic camera
movement, consistent lighting across frames, cinematic composition, dramatic
directional lighting, rich cohesive color grade, ultra-detailed, premium
commercial finish

Gerar com este prompt → (5 segundos, 720p, 16:9)

kling-3.0-turbo/text-to-video, 5 segundos.

Consulta rápida de parâmetros

Campo	Obrigatório	Valores	Descrição
prompt	Sim	Até 2500 caracteres	Cena, sujeito, ação, movimento de câmera; falas entre aspas podem ter sincronia labial
duration	Não	Inteiro de 3 a 15, padrão 5	Cobrança por segundo; cada segundo a mais custa mais
aspect_ratio	Não	16:9 (padrão) / 9:16 / 1:1	Horizontal, vertical, quadrado
resolution	Não	720p (padrão) / 1080p	Define o preço por segundo

Não há campo sound, mas o vídeo final já vem com áudio e não é possível desativá-lo. Também não há 4K, frame final nem imagem de referência; para isso, use o Kling 3.0 padrão ou o Omni.

curl: rode o primeiro

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-turbo/text-to-video",
    "input": {
      "prompt": "A golden retriever surfing a turquoise wave at sunset, cinematic slow motion, water droplets frozen mid-air",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'

A resposta contém apenas data.taskId. Faça polling em GET /v1/tasks/{taskId} a cada 5–10 segundos; quando status virar success, baixe o vídeo em output[0].url.

Python: enviar, fazer polling e baixar

# pip install requests; export HIAPI_KEY=你的 Key
import os, time, uuid, requests

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

def generate(timeout_s=900, **inp):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    r = requests.post(API, json={"model": "kling-3.0-turbo/text-to-video", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(8)
    raise TimeoutError(task_id)

# 竖屏 3 秒 720p 试方向，$0.39
url = generate(
    prompt="A barista pours latte art in slow motion, close-up, warm cafe light",
    duration=3, aspect_ratio="9:16", resolution="720p",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Quanto custa

Duração	720p ($0.13/segundo)	1080p ($0.16/segundo)
3 segundos (mínimo)	$0.39	$0.48
5 segundos	$0.65	$0.80
10 segundos	$1.30	$1.60
15 segundos (máximo)	$1.95	$2.40

Preço atual da HiAPI, verificado em 18 de outubro de 2026.

Falhas não são cobradas. Veja a comparação completa em Preço da API do Kling 3.0 Turbo.

Erros que você vai encontrar

O que você enviou	Resposta
Sem prompt	400, missing required field "prompt"
Campos extras (como seed, negative_prompt)	400, additional properties ... not allowed
duration: 2	400, duration: minimum: got 2, want 3
duration: 99	400, duration: maximum: got 99, want 15
aspect_ratio: "4:3"	400, só pode ser 16:9, 9:16, 1:1
resolution: "480p"	400, só pode ser 720p, 1080p
Key errada ou ausente	401, permission_denied
Saldo insuficiente	402, recarregue antes de investigar

Erros de parâmetro são retornados na hora do envio; falhas de geração aparecem depois no polling, com status igual a fail, e o erro fica em data.error. É preciso tratar os dois casos.

Atenção antes de ir para produção

• Use callback em vez de polling: adicione "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"} no mesmo nível de input; a tarefa notifica apenas uma vez ao terminar, e você deve deduplicar por taskId.
• Inclua o cabeçalho Idempotency-Key: em retentativas por timeout, use a mesma Key; assim apenas uma tarefa é criada e a cobrança ocorre uma única vez.
• Baixe o resultado imediatamente: output[0].url tem prazo de validade.
• Acima de 15 segundos, divida em partes: passe o último frame do trecho anterior como frame inicial para kling-3.0-turbo/image-to-video e continue a geração.

Perguntas frequentes

Quanto tempo leva cada vídeo?

Na casa dos minutos; quanto maior a duração e a resolução, mais demorado. Sugerimos limite de polling de 10–15 minutos, ou usar callback diretamente.

Há suporte a prompt negativo?

Não. O que você quer evitar deve ser escrito diretamente no prompt, por exemplo "no text overlays, no watermarks".

Como escolher entre Turbo e Kling 3.0 padrão?

O Turbo é a versão rápida e já vem com áudio; o padrão sem áudio em 720p custa $0.10 por segundo, é mais barato, permite ligar ou desligar o áudio e ainda gera em 4K. Veja a comparação com o mesmo prompt em Kling 3.0 Turbo vs Kling 3.0.

Copie o prompt do fiorde acima e gere um teste de 3 segundos por $0.39.