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
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
Authorizationheader carries your HiAPI key. Export it into an environment variable rather than pasting it into shell history. video_urlis the source. It must be fetchable by the service.promptis the style instruction. This is the field you will revise most.resolutionis 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
failedand 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:
- Iterate on the style instruction at a lower resolution. Prompt quality is resolution-independent, so you get the look right cheaply first.
- Lock the prompt and the source clip.
- 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 →-
Tutorial
gpt-6.2-sol in Practice: 5 High-Value Uses of a Text Model in Business
-
Tutorial
gpt-6.2-astra Practical Guide: Integration and Implementation Key Points for 5 High-Value Text Scenarios
A Developer's Checklist from Scenario Selection to Engineering Implementation
-
Tutorial
Tripo H3.1 Practical Application Scenarios: 5 High-Value Use Cases and Implementation Essentials
From text-to-3D to multiview reconstruction: choosing the right mode and parameters by business scenario