Kling Image-to-Video API in Python: Omni vs Turbo Working Examples

This is the generic Kling AI image-to-video API Python guide for hiapi. Choose Omni or Turbo from the job requirements, keep the model-specific payload separate, and run either payload through the same create, poll, and download code.

Both are asynchronous task models: create a task with POST /v1/tasks, poll GET /v1/tasks/{taskId}, and download data.output[0].url before it expires.

Two model-accurate payloads

The outer task envelope is shared. The model and input fields are where the variants differ.

Omni: first and last frames with sound

{
  "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
  }
}

With two images, entry 0 is the first frame and entry 1 is the last frame. Use one image when you only need a starting frame.

Turbo: one starting frame

{
  "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"
  }
}

Turbo requires a prompt and exactly one image. Its accepted duration is 3-15 seconds and its resolution is 720p or 1080p. For its strict fields and failure cases, see the Turbo schema, limits, and Python errors guide.

One Python task runner for both models

Install requests, set HIAPI_API_KEY, then keep payload selection outside the network functions:

import os
import time
from pathlib import Path

import requests

API_BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def create_task(model: str, model_input: dict) -> str:
    response = requests.post(
        f"{API_BASE}/tasks",
        headers=HEADERS,
        json={"model": model, "input": model_input},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_seconds: int = 900) -> dict:
    deadline = time.time() + timeout_seconds
    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":
            return task
        if task["status"] == "fail":
            raise RuntimeError(task.get("error", "task failed"))
        time.sleep(8)
    raise TimeoutError(f"task {task_id} did not finish in time")


def download_output(task: dict, destination: str) -> None:
    output_url = task["output"][0]["url"]
    with requests.get(output_url, stream=True, timeout=180) as response:
        response.raise_for_status()
        with Path(destination).open("wb") as file:
            for chunk in response.iter_content(1024 * 1024):
                file.write(chunk)

Choose a payload and call the shared functions:

MODEL = "kling-3.0-omni/image-to-video"
MODEL_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 daylight grows warmer",
    "duration": 8,
    "resolution": "1080p",
    "sound": True,
}

task_id = create_task(MODEL, MODEL_INPUT)
task = wait_for_task(task_id)
download_output(task, "kling-output.mp4")

To run Turbo, replace MODEL and MODEL_INPUT with the Turbo payload above. Do not send Omni-only fields to Turbo.

Schema differences that affect code

Input images must be publicly reachable by the API. A localhost URL, an authenticated page, or an expired signed URL can pass basic JSON validation and still make the asynchronous task fail when the renderer fetches it.

The source image defines framing, so do not add text-to-video fields such as aspect_ratio. Unknown fields are rejected by strict schemas.

Current image-to-video prices

Prices below are the production rates verified for these image-to-video tiers. Check the live pricing page before budgeting a large run.

The word “Turbo” does not mean every tier is cheaper. Select by capabilities and the price of the exact resolution and audio mode you intend to send.

Polling, callbacks, and output storage

Polling is appropriate for a script or notebook. A production service can send a top-level callback configuration when it creates the task, then update its job record when the terminal event arrives.

Whichever completion method you use:

1. Store the task id before retrying a worker, or a retry may create and bill a duplicate task.
2. Treat success and fail as terminal outcomes.
3. Download output[0].url promptly; the result includes expireAt because the pickup URL is temporary.
4. Re-host the MP4 in storage you control instead of serving the temporary output URL to users.

Error boundaries

• HTTP 400 means the task was not created because the JSON failed schema validation. Inspect the field named in the response.
• HTTP 401 means the key is missing, invalid, or not permitted for the selected model.
• A task that is created and later reaches fail passed request validation but failed during input fetching or generation. Log the task id and structured error separately from the original HTTP response.
• An expired output URL does not mean the task failed. It means the result was not downloaded during its pickup window.

FAQ

Which Kling image-to-video model should I use in Python?

Use Omni when you need two-frame control, sound, or 4K. Use Turbo when its exact one-image, 720p/1080p schema fits the job. The create and polling code can remain shared.

Can Omni use a first and last frame?

Yes. Send two public URLs in image_urls; the first is the starting frame and the second is the ending frame.

Can Turbo generate sound or 4K output?

No. Turbo's image-to-video schema accepts 720p or 1080p and does not accept the Omni sound field.

How long can a Kling image-to-video task be?

For these endpoints, duration is an integer from 3 through 15 seconds.

Why did my task fail after POST returned 200?

The create request passed schema validation, but the renderer may have been unable to fetch the image or complete the generation. Inspect the terminal task error and confirm the image URL is public and unexpired.