How to Use the kling-3.0-turbo Text-to-Video API: curl, Python, and a Working Request

Kuaishou's Kling 3.0 Turbo generates short video clips from a plain-text prompt, and on hiapi you call it through the same unified async endpoint as every other generation model: POST /v1/tasks. This guide gives you a live-verified parameter table, a copy-paste curl request, a complete Python client with polling and download, and the production patterns (callbacks, idempotency, error handling) you'll want before wiring it into a real app.

Everything below — field names, enum values, duration limits, and error messages — was verified against the live API, not copied from a spec.

What you're building, and what you need

Goal: send a text prompt to kling-3.0-turbo/text-to-video, wait for the render, and download the resulting .mp4.

Prerequisites:

• A hiapi API key — create one in the dashboard. Keys look like sk-... and go in the Authorization: Bearer header.
• Enough account balance for video generation. Video is billed per second of generated output, so it draws more per call than image models — current rates are on the pricing page.
• curl or Python 3.8+ with requests. No SDK required.

The input schema (live-verified)

kling-3.0-turbo/text-to-video accepts exactly four input fields. The schema is strict: any field not in this table is rejected with a 400, so don't pass negative_prompt, cfg_scale, mode, or seed — they are not part of this model's contract.

Flexible Duration, and why it matters for cost

Unlike models that lock you into fixed 5s/10s tiers, Kling 3.0 Turbo's duration is a plain integer from 3 to 15. Because billing is per second of generated video, this means you tune spend at one-second granularity: a 6-second product teaser costs literally half of a 12-second one. Ask for the shortest clip that serves the shot — you can always chain another generation.

Minimal working example: curl

Create the task:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-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": 6,
      "aspect_ratio": "16:9",
      "resolution": "1080p"
    }
  }'

The response returns immediately with a task id:

{
  "code": 200,
  "data": {
    "taskId": "task_..."
  }
}

Poll for the result (every ~5 seconds is fine):

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-<your-key>"

While rendering, data.status stays in a non-terminal state. When it flips to "success", the video URL is at data.output[0].url:

# one-liner: grab the finished mp4 URL with jq
curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-<your-key>" | jq -r '.data.output[0].url'

Download it immediately. Output URLs are temporary (they carry an expireAt) — persist the bytes to your own storage as soon as the task succeeds. Never hot-link the task output URL from a web page.

Complete Python client

A full create → poll → download loop with timeout and failure handling:

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Create the task
create = requests.post(
    API_BASE,
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "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": 6,
            "aspect_ratio": "16:9",
            "resolution": "1080p",
        },
    },
    timeout=60,
)
body = create.json()
task_id = (body.get("data") or {}).get("taskId")
if not task_id:
    raise RuntimeError(f"create failed: {body}")
print(f"task created: {task_id}")

# 2. Poll until terminal state (video takes minutes, not seconds)
deadline = time.time() + 600
video_url = None
while time.time() < deadline:
    task = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    data = task.get("data") or {}
    status = data.get("status")
    if status == "success":
        video_url = data["output"][0]["url"]
        break
    if status == "fail":
        err = data.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

if not video_url:
    raise TimeoutError(f"task {task_id} not finished after 600s")

# 3. Download immediately — the output URL expires
clip = requests.get(video_url, timeout=120)
clip.raise_for_status()
with open("kling-clip.mp4", "wb") as f:
    f.write(clip.content)
print(f"saved kling-clip.mp4 ({len(clip.content)} bytes)")

Notes on the defaults chosen here:

• 600-second polling budget. Video rendering time scales with duration and resolution; a 10-minute ceiling with 5-second intervals is a sane starting point.
• The poll reads data.status, and treats "success" / "fail" as the only terminal states — anything else means keep waiting.
• Failures surface in data.error with a code and message; log both.

Production patterns

Callbacks instead of polling

For server-side workloads, skip the poll loop entirely: pass a callback object at the top level of the create request (next to model, not inside input), and hiapi will POST the terminal task state to your endpoint when the render finishes:

{
  "model": "kling-3.0-turbo/text-to-video",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your.app/hiapi-callback", "when": "final" }
}

when: "final" means you get exactly one call, on the terminal state. Rule of thumb: polling is fine for CLIs, scripts, and dev loops; callbacks are better once you're generating from a queue or handling user traffic, because you hold no open loops and pay no polling latency.

Idempotency: log the taskId before you retry

Task creation is not idempotent — if your process crashes after the POST but before persisting the taskId, retrying blindly creates (and bills) a second render. Write the taskId to your own storage the moment create returns, and on ambiguous failures check your task history before re-submitting.

Error handling: the 400s you'll actually hit

These are real responses from the live API, so you can match on them:

Two operational gotchas worth coding for:

• A 402 means balance, not a bug. Because video bills per second, a low balance can reject a video task even while cheaper image calls on the same key still succeed. If you see 402s only on video, top up before debugging anything else.
• Distinguish create-time 400s from run-time fails. Schema errors come back synchronously on the POST; generation failures arrive later as status: "fail" with data.error populated. Handle both paths.

Related reading

• kling-3.0-turbo/text-to-video model page — playground, pricing, and capabilities
• hiapi pricing — current per-second video rates
• hiapi docs — full API reference
• How to use grok-imagine text-to-video — same task workflow, different model and schema
• Free text-to-video API options compared — if you're still evaluating

FAQ

How long does a kling-3.0-turbo generation take?

Expect minutes rather than seconds — render time grows with duration and resolution. Poll every ~5 seconds with a generous ceiling (the example above uses 10 minutes), or use a callback and don't wait at all.

Can I generate videos longer than 15 seconds?

Not in a single task — duration is capped at 15. For longer sequences, generate multiple clips and stitch them, or use kling-3.0-turbo/image-to-video to continue from the last frame of a previous clip for better continuity.

Does the model support negative prompts or a cfg scale?

No. The input schema is strict and accepts only prompt, duration, aspect_ratio, and resolution. Sending anything else returns a 400 (additional properties ... not allowed). Put avoidance instructions ("no text overlays, no watermarks") directly into the prompt instead.

What does kling-3.0-turbo text-to-video cost?

Billing is per second of generated video, so a 6-second clip costs half of a 12-second one at the same settings. See the pricing page for current rates.

Is there a free way to try it without an API key?

Production API access requires a key. If you're exploring free options first, this comparison of free text-to-video APIs covers what's realistically available and the trade-offs.

Is my aspect ratio wrong, or my resolution?

Both are closed enums, and the errors tell you exactly which one you tripped: aspect_ratio must be 16:9, 9:16, or 1:1; resolution must be 720p or 1080p. There is no custom width/height for this model.