Blog

Tutorial

How to Call kling-3.0-omni/transformation via the HiAPI API: curl and Python Guide

A working request walkthrough for video style transformation on HiAPI

Nov 12, 2026 11 min read
HiAPI blog cover image: nested broad arrows stepping forward on a deep indigo background, with apricot leading edges outlining a signal-flow diagram.
On this page

What the transformation endpoint does and when to use it

kling-3.0-omni/transformation is a video style transformation endpoint on HiAPI. You hand it two things: a source video and a style instruction in natural language. It returns a new video where the content of the source is preserved but rendered in the requested visual style.

Think of it as a post-production step that lives behind an HTTP call. You do not need to train a model, maintain a GPU fleet, or manage checkpoint files. You describe the look you want, point at a clip, and the endpoint produces a rendered result.

When this endpoint is the right tool

  • Stylizing existing footage. You already have a shot and want it to read as animation, watercolor, film grain, claymation, or some other look. The content and motion come from your clip; the endpoint changes the surface.
  • Consistent look across a batch. Because the style is expressed as an instruction, you can reuse the same prompt across many source clips and get a coherent set.
  • Prototyping look development. Creative teams can iterate on style direction cheaply before committing to a heavier production pipeline.

When it is not

  • You need to generate video from nothing (text-to-video is a different job).
  • You need frame-accurate editing, cutting, or compositing. Transformation restyles; it does not edit.
  • Your source is audio-only or a still image.

The rest of this guide walks through the request shape, a runnable curl call, a Python port, and the operational details around 4K output and long jobs.

Request anatomy: source video, style instruction, and output options

A transformation request is small. Before you write code, separate it into three groups of fields: the source, the instruction, and the output settings.

The source video

The endpoint needs to reach your input. In practice you pass a URL that the platform can fetch, or an identifier returned by HiAPI's file upload step. The practical rule: the source must be accessible from the service, not from your laptop. A localhost path or a file behind your VPN will not work.

Keep the source format conservative — a widely supported container and codec. If your clip was produced by an unusual pipeline and fails validation, re-encode it to a standard H.264 MP4 first. That single step resolves a large share of input errors.

The style instruction

This is a natural-language description of the target look. It is the highest-leverage field in the request and the one most worth iterating on.

  • Describe the visual treatment, not the content. The content comes from the video; telling the model what is already on screen wastes prompt budget.
  • Be concrete about medium and texture: "stop-motion clay animation with visible fingerprints" carries more signal than "animated."
  • State what to preserve when it matters: "keep faces recognizable and camera motion unchanged."
  • Keep it to a focused paragraph. Long, contradictory prompts tend to average out into something bland.

Output options

Output settings control resolution and other delivery details. The main decision is whether you ask for 4K or a standard resolution. Higher resolution costs more compute and takes longer, so treat it as a deliberate choice rather than a default. The endpoint also runs as an asynchronous job in the general case, so your request will typically return a job reference you poll or await rather than a finished file.

Map your inputs to these three groups first, and the actual JSON body becomes obvious.

A working curl request from scratch

The fastest way to confirm your understanding is a minimal call. The shape below sends a source video URL and a style instruction and asks for a standard-resolution result. Replace the placeholder values with your own.

curl -X POST "https://api.hiapi.ai/v1/kling-3.0-omni/transformation" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": "Transform into hand-painted watercolor animation with soft bleeding edges, visible paper texture, and a warm limited palette. Preserve faces and camera movement.",
    "resolution": "1080p"
  }'

What each part does

  • The URL path names the endpoint. Keep it exact; a typo here returns a routing error, not a validation error.
  • The Authorization header carries your HiAPI key. Export it into an environment variable rather than pasting it into shell history.
  • video_url is the source. It must be fetchable by the service.
  • prompt is the style instruction. This is the field you will revise most.
  • resolution is the output setting. Start low while iterating; raise it only when the look is settled.

Reading the response

A successful response gives you a job object. Capture the job identifier and any status field:

{
  "id": "job_abc123",
  "status": "queued"
}

The exact field names are what you should read from the live response rather than assume. The important habit is the same in every language: parse the JSON, pull out the job id, and treat the finished video as something that arrives later. Do not write code that assumes the first response contains a playable file.

The same request in Python

The Python version is the curl call with the JSON body expressed as a dictionary. Using requests keeps it readable and dependency-light.

import os
import time
import requests

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

payload = {
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": (
        "Transform into hand-painted watercolor animation with soft "
        "bleeding edges, visible paper texture, and a warm limited "
        "palette. Preserve faces and camera movement."
    ),
    "resolution": "1080p",
}

resp = requests.post(
    f"{BASE}/kling-3.0-omni/transformation",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
print("submitted", job_id, job.get("status"))

Polling until the job finishes

Because the render is asynchronous, wrap the wait in a loop with a bounded number of attempts and a sleep between checks. Keep the sleep generous enough not to hammer the API, and cap total wait time so a stuck job does not hang your worker.

def wait_for_job(job_id, max_attempts=60, interval=10):
    for _ in range(max_attempts):
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "succeeded":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error") or "job failed")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish in time")

result = wait_for_job(job_id)
print(result.get("output") or result)

Making it production-safe

  • Read the endpoint path and polling route from the API response documentation rather than hardcoding assumptions that may drift.
  • Log the job id on submission. It is your only handle if something goes wrong downstream.
  • Treat failed and timeout as distinct outcomes. A failed job is usually a parameter problem; a timeout is usually a capacity or length problem.

Handling 4K output and long-running jobs

Two variables dominate the operational behavior of this endpoint: output resolution and input length. Plan for both explicitly.

4K output

4K is a delivery decision, not a default. Each output pixel costs compute, and the jump from standard resolution to 4K is large in relative terms. A sensible workflow:

  1. Iterate on the style instruction at a lower resolution. Prompt quality is resolution-independent, so you get the look right cheaply first.
  2. Lock the prompt and the source clip.
  3. Re-run at 4K once, for delivery.

Avoid generating 4K variants in a tight loop while tuning wording — that is the most common way to burn budget on renders you will throw away.

Long-running jobs

Longer source clips take longer to transform, and the endpoint returns a job reference rather than a finished file. Build your client around that reality:

  • Never block a web request on a render. Submit, store the job id, and return immediately to your caller.
  • Separate submission from retrieval. A queue plus a worker that polls is more robust than an inline wait, and it survives process restarts.
  • Persist job state. If your worker dies mid-poll, the job does not disappear; you can resume from the stored id.
  • Use webhooks if available in your account, and keep polling as the fallback path.
  • Set a total wait budget that reflects your longest expected clip, not an arbitrary number.

A practical pattern

Split source clips that exceed your typical length into segments, transform each, and stitch the results. This shortens individual waits, lets you retry one segment instead of a whole render, and makes failures cheap. Do confirm that segment boundaries do not cut through fast motion, or the seams will show.

Troubleshooting common failures

Most failures fall into three buckets: the source cannot be read, the parameters are rejected, or the job never completes. Isolate the bucket before changing anything.

Upload and source-access errors

Symptom: submission fails, or the job fails almost immediately with an input error.

  • The URL is not publicly reachable. Test it from a machine outside your network. A signed URL that expired between submission and fetch is a classic culprit.
  • The format is unsupported. Re-encode to a standard H.264 MP4 and retry.
  • The file is truncated or corrupt. Download it yourself and play it end to end.
  • The request is too large. If you are sending file bytes inline rather than a URL, switch to the upload flow and pass the returned identifier.

Parameter errors

Symptom: a 4xx response at submission time.

  • Malformed JSON. Run your body through a linter. Trailing commas and unescaped quotes are frequent offenders in hand-written curl calls.
  • Wrong field names or types. Compare against the current request schema; a resolution passed as a number where a string is expected will fail.
  • An empty or contradictory prompt. If the instruction describes nothing or asks for mutually exclusive styles, expect weak or rejected output. Rewrite it around one clear visual direction.
  • Missing or invalid API key. Check the header value and that the key is active for this endpoint.

Timeouts and stuck jobs

Symptom: the job stays queued or running past your wait budget, or your client gives up.

  • Distinguish client timeout from job failure. A short HTTP timeout on submission does not mean the job did not start; check for a job id before resubmitting, or you may duplicate renders.
  • Long inputs and 4K output extend run time. If you are timing out consistently, lower resolution or shorten the clip to confirm the pipeline works, then scale back up.
  • If a job reports failed, read the error message before retrying. Blind retries on a deterministic parameter error just multiply the cost.

A debug order that works

Start with the smallest possible request: a short, standard-resolution clip and a one-sentence prompt. If that succeeds, reintroduce your real prompt, then your real length, then 4K, one change at a time. The step where it breaks tells you which variable is responsible.

Cost and latency tradeoffs to plan for

Once the request works, the remaining decisions are operational. Three levers move both cost and latency, and they interact.

Resolution

Output resolution is the biggest single lever. Billing is tied to the work the render performs, and higher-resolution output means more of it. The rule of thumb: iterate low, deliver high. Never let a styling experiment run at 4K.

Input length

Longer sources mean more frames to transform, which means more compute and more wall-clock time. If your use case allows, transform a shorter hero clip rather than a full-length cut, or segment long footage and transform only what needs the treatment.

Retries

Every retry is a full render unless the failure happened before the job started. This is why the debugging order matters: validate parameters cheaply before spending on renders. Guard against duplicate submissions by recording job ids and checking before resubmitting after a client-side timeout.

Batching and parallelism

Parallel jobs reduce wall-clock time but not total cost — and they can hit concurrency limits. For batch work, a modest queue with controlled parallelism is usually better than fan-out. It keeps you under rate limits, makes failures easy to retry individually, and gives you a predictable spend curve.

A budgeting checklist

  • Fix the prompt at low resolution before any delivery renders.
  • Cache finished outputs; do not re-render identical inputs.
  • Set per-job and per-batch spend expectations, and alert when a batch exceeds them.
  • Track job duration alongside resolution and input length so you can predict new work from past runs.
  • Treat 4K as a final step in a pipeline, not an interactive mode.

Pricing for this endpoint is listed on the HiAPI site, so check the current rates there before you size a batch. Get the minimal request working first, then scale resolution and length deliberately — that ordering keeps both your latency and your bill predictable.

Related articles

View all articles →

Start building with persistent AI artifacts

Get your API key and call image, video and audio models through one task-based API.

Read the API docs