Kling 3.0 API in Python: Text-to-Video and Image-to-Video Guide

TL;DR

• Kling 3.0 (by Kuaishou) is available through one API on HiAPI as kling-3.0/text-to-video and kling-3.0/image-to-video: 3–15 second clips, up to 4K, with optional native sound and first-and-last-frame control.
• Pricing is per second: $0.10 at 720p ($0.143 with sound), $0.129 at 1080p ($0.193 with sound), $0.479 at 4K. A 5-second 720p clip costs $0.50.
• Below is a complete Python script (submit, poll, download) for both text-to-video and image-to-video, plus the schema and the errors you will actually hit.

What it looks like

Text-to-video, the example from the model page:

VIDEO

A lone red fox sprints across a windswept snowy ridge at golden hour, powder snow kicking up behind each stride, then leaps over a frozen creek in a graceful arc. Cinematic, dramatic side lighting, ultra-detailed fur, shallow depth of field, smooth motion.

Generate with this prompt → (5 seconds, 16:9)

kling-3.0/text-to-video model page example, 5 seconds. At 720p without sound this costs $0.50; at 1080p with sound, $0.965.

Image-to-video, starting from this lighthouse image:

VIDEO

The waves surge and crash against the rocks, the lighthouse beam sweeps slowly across the stormy night sky, rain streaks through the wind. Smooth cinematic motion, synchronized ambient sound of waves and storm.

Generate with this prompt → (upload your own start frame, 5 seconds)

kling-3.0/image-to-video model page example, 5 seconds. At 720p with sound this costs $0.715.

Python: text-to-video and image-to-video in one script

Get an API key from the dashboard, pip install requests, and set HIAPI_KEY. Both endpoints share the same task flow: POST /v1/tasks returns a taskId, then you poll GET /v1/tasks/{taskId} until status is success and download output[0].url.

import os
import time
import uuid

import requests

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


def run_kling(model: str, out_path: str, timeout_s: int = 900, **params) -> str:
    # Reuse the same Idempotency-Key if you retry this submission, so it is billed once
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post(API, json={"model": model, "input": params}, headers=headers, 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() + timeout_s
    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 {task_id} failed: {data.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)


# Text-to-video: 5 s at 720p, no sound ($0.50)
run_kling(
    "kling-3.0/text-to-video", "fox.mp4",
    prompt="A red fox sprints across a snowy ridge at golden hour, smooth tracking shot",
    duration=5, resolution="720p", aspect_ratio="16:9", sound=False,
)

# Image-to-video: start and end frame, 5 s at 720p ($0.50)
run_kling(
    "kling-3.0/image-to-video", "transition.mp4",
    image_urls=["https://your-cdn.example.com/start.jpg", "https://your-cdn.example.com/end.jpg"],
    prompt="The camera slowly pushes in as the scene transitions smoothly",
    duration=5, resolution="720p", sound=False,
)

The same request in curl:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/text-to-video",
    "input": {
      "prompt": "A red fox sprints across a snowy ridge at golden hour, smooth tracking shot",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "sound": false
    }
  }'

Input schema

Pricing

Because resolution defaults to 1080p, setting 720p explicitly while you iterate saves about 22%. Failed tasks are not charged. For Omni and Turbo rates, see Kling 3.0 API pricing.

Kling 3.0 vs Omni vs Turbo

If you only need one start frame and no sound, the Kling 3.0 Turbo image-to-video guide covers that endpoint's stricter schema.

Errors you will see

• HTTP 400 INVALID_REQUEST: the payload failed validation and no task was created. The message names the field, for example duration: maximum: got 20, want 15. Fix the payload; don't retry it unchanged.
• HTTP 401 permission_denied: the key is wrong, revoked, or not allowed to use this model.
• status: "fail" after a successful create: usually an image URL the renderer couldn't fetch (cookies, an expired signature, or an HTML page instead of an image). Check that the URL downloads without a browser session, then submit again.

For production, add a top-level "callback": {"url": "https://your-app.example.com/hiapi/callback"} instead of polling and deduplicate notifications by taskId.

FAQ

Can I write prompts in languages other than English?

Yes. Chinese prompts work too, including dialogue lines when sound is on.

How long can a Kling 3.0 clip be?

3 to 15 seconds per task. For longer videos, generate several clips and edit them together.

Does sound cost extra?

Yes. With sound: true, 720p goes from $0.10 to $0.143 per second and 1080p from $0.129 to $0.193. 4K is $0.479 per second either way.

How do I get a vertical video?

Set aspect_ratio to 9:16 on text-to-video. On image-to-video, upload a vertical start frame.

For ready-to-use prompts, see Kling 3.0 prompt examples, or copy the fox prompt above and run it on the model page.