Kling 3.0 Omni API Deep Dive: Multi-Shot Video Generation and Physics Coherence
Target Model:
kling-v3-omni
Inference Endpoint:https://api.toapis.com/v1/videos/generations
Related: Kling 3.0 Turbo automation guide · Kling V4 Flash API guide · kling-v3-omni reference · kling-v3-omni model guide
1. TL;DR & Performance Overview
- Catalog first: Planning drafts sometimes write
kling-3-omni. That string is not the documented public ID. A 2026-11-18 check of the official generation reference and the model-guide page (HTTP 200) listskling-v3-omnias the fixedmodelvalue. Send that exact string. - Contract: Submit asynchronously to
POST /v1/videos/generations, then pollGET /v1/videos/generations/{id}untilcompletedorfailed. Ordinary tasks may also be queried withGET /v1/tasks/{id}. Official examples usehttps://toapis.com(andhttps://toapis.cnfor mainland China). Other guides in this series usehttps://api.toapis.com. Pick one origin and keep it consistent. - No
shots[]field: Multi-shot continuity and physics coherence are prompt-plus-reference problems. Use official placeholders<<<image_N>>>,<<<video_N>>>, and<<<element_N>>>withmetadata.image_list,video_list, andmetadata.element_list. List order must match placeholder order; the system will not auto-insert placeholders or auto-add a first frame. - Media: Send public
http://orhttps://URLs only. Upload local files withPOST /v1/uploads/imagesand use the returned URL. Do not send base64.audioandvideo_listare mutually exclusive. - Unverified claims to drop: Draft unit prices such as
$0.022/s, SLA figures such as 99.95%, or a customshotsschema are not current ToAPIs documentation. Confirm live rates and channel support in your account.
2. Official Omni ID, Placeholders, and Coherence Workflows
Use the public model name in the model field. Do not substitute a draft alias, a URL slug, or a related but different catalog ID.
| Catalog ID | Role in this guide | Documented jobs |
|---|---|---|
kling-v3-omni | Hero ID for this article | Text-to-video plus official Omni references: image_list, video_list, and element_list |
kling-3.0-turbo | Sister short-form ID; see the Turbo guide | Text-to-video and first-frame image-to-video only — not an Omni reference contract |
kling-v3 | Related non-Omni v3 ID | A separate generation reference — do not reuse Omni lists here unless its own docs say so |
Core request fields on kling-v3-omni:
| Field | Documented values | Notes |
|---|---|---|
prompt | Required string | Reference assets with 1-based placeholders |
mode | std (default) or pro | std maps to 720P; pro maps to 1080P, and the same flag drives billing resolution |
duration | Integers 3–15 (default 5) | Not limited to 5 or 10 seconds |
aspect_ratio | Common values 16:9 (default), 9:16, 1:1 | Prefer the generation reference if a marketing parameter table is shorter |
audio | Boolean, default false | true bills as Sound; incompatible with video_list |
video_list | At most one clip | Bills as Video. refer_type: base or feature. keep_original_sound: yes or no |
metadata.image_list | Public image_url values | Optional type of first_frame or end_frame; end_frame requires first_frame |
metadata.element_list | Subject or role assets | url plus optional type (for example image or video) and role |
watermark | Boolean | On/off only |
client_business_id | Optional string | Documented on the Chinese Omni reference as a top-level field (also accepted under metadata, top-level preferred). You can later query GET /v1/videos/generations/{client_business_id} |
Placeholder syntax is 1-based and must stay aligned with list order:
| Syntax | References |
|---|---|
<<<image_1>>> | First item in metadata.image_list |
<<<video_1>>> | First (and, per the Chinese reference, only) item in video_list |
<<<element_1>>> | First item in metadata.element_list |
The English generation page illustrates <<<video_2>>> as list syntax. The Chinese reference caps video_list at one clip. Do not send a second reference video unless your account reference later says otherwise.
There is still a practical way to build multi-shot and physically coherent clips:
- Lock the arc with first and end frames. Put the opening still in
image_listwithtype: "first_frame"and the closing still withtype: "end_frame". Mention both in the prompt (Transition from <<<image_1>>> to <<<image_2>>>) and describe the motion, gravity, and camera path between them. - Anchor identity with
element_list. Reuse the same subject URL and a stablerole(for example"subject") across related jobs so clothing, face, and proportions do not drift when you change the camera description. - Borrow motion with
refer_type: "feature". Point<<<video_1>>>at a public motion reference and ask<<<element_1>>>to follow that motion. Userefer_type: "base"when you are editing the source clip itself (for example a background replacement). - Chain jobs explicitly. The status document is not an Omni-specific last-frame API. If a later shot must start from a previous take, host a public still or download of that take and send it as the next
first_frame. Persist each task id.

Figure 1: image_list, video_list, and element_list (public URLs only) are submitted to POST /v1/videos/generations; poll the same task id and read result.data[0].url only after status is completed.
For high-volume short-form drafts that do not need Omni lists, use kling-3.0-turbo. For a different Kling generation contract, see the Kling V4 Flash guide.
3. Production Implementation: cURL & Python
International examples in this series use https://api.toapis.com. Official docs tell mainland China users to use https://toapis.cn. Keep one origin per environment. Paths, model IDs, and the Bearer header stay the same.
Step 1: cURL dispatch for a first-and-end-frame job
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-omni",
"prompt": "Transition from <<<image_1>>> to <<<image_2>>>, keeping gravity, footsteps, and camera height consistent",
"mode": "std",
"duration": 5,
"aspect_ratio": "16:9",
"metadata": {
"image_list": [
{"image_url": "https://example.com/start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/end.jpg", "type": "end_frame"}
]
}
}'
A text-only job omits metadata and the placeholders. A subject-plus-motion job uses video_list with refer_type: "feature" and metadata.element_list, and must not set audio: true.
Step 2: Python helper and poller
The snippet follows the documented task-status path and the queued / in_progress / completed / failed statuses. Confirm id, result.data[0].url, and the envelope against the API reference for your account before you ship.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
DOCUMENTED_ID = "kling-v3-omni"
DURATION_RANGE = range(3, 16)
def dispatch_omni(
prompt: str,
*,
model: str = DOCUMENTED_ID,
mode: str = "std",
duration: int = 5,
aspect_ratio: str = "16:9",
audio: bool = False,
image_list: list[dict] | None = None,
element_list: list[dict] | None = None,
video_list: list[dict] | None = None,
client_business_id: str | None = None,
) -> str:
if model != DOCUMENTED_ID:
raise ValueError("Send kling-v3-omni; kling-3-omni is not a documented public ID")
if mode not in {"std", "pro"}:
raise ValueError("mode must be std or pro")
if duration not in DURATION_RANGE:
raise ValueError("duration must be an integer from 3 to 15")
if audio and video_list:
raise ValueError("audio and video_list are mutually exclusive")
if video_list and len(video_list) > 1:
raise ValueError("video_list is documented as at most one clip")
types = [item.get("type") for item in (image_list or [])]
if "end_frame" in types and "first_frame" not in types:
raise ValueError("end_frame requires first_frame")
payload = {
"model": model,
"prompt": prompt,
"mode": mode,
"duration": duration,
"aspect_ratio": aspect_ratio,
}
if audio:
payload["audio"] = True
if video_list:
payload["video_list"] = video_list
metadata = {}
if image_list:
metadata["image_list"] = image_list
if element_list:
metadata["element_list"] = element_list
if metadata:
payload["metadata"] = metadata
if client_business_id:
payload["client_business_id"] = client_business_id
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_omni(
"Transition from <<<image_1>>> to <<<image_2>>>, keeping gravity, footsteps, and camera height consistent",
image_list=[
{"image_url": "https://example.com/start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/end.jpg", "type": "end_frame"},
],
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Store the prompt template version next to the task record so you can tell a placeholder or list-order change from a wording change. Download the file before expires_at; the status reference documents a 30-day retention window.
4. Error Handling & Status Matrix
The categories below are diagnostic starting points, not a guarantee of exact ToAPIs error codes. A successful HTTP query still requires you to read task status. See the error reference for request errors versus status: failed reasons such as content_policy_rejected, insufficient_user_balance, or generation_timeout.
| HTTP or task state | Common category | Recommended action |
|---|---|---|
400 | Invalid field, placeholder/list mismatch, audio plus video_list, or end_frame without first_frame | Confirm kling-v3-omni, that placeholder order matches each list, that media values are public URLs, and that mutually exclusive fields are not combined |
401 | Missing or invalid API key | Rotate the key in the ToAPIs dashboard and confirm the Authorization: Bearer header |
429 | Rate or concurrency limit | Honor Retry-After when present; back off with jitter; retry only when safe |
5xx or client timeout | Temporary gateway or upstream issue | Query the existing task id before resubmitting |
status: queued or in_progress | Not an error | Wait and poll again; do not create a second job |
status: failed | Generation did not succeed | Read error.code and error.message (and error.reason when present). Do not retry an unchanged policy-rejected payload |
5. Pricing & FinOps ROI
The official Chinese Omni reference publishes a billing map. Use it to choose a SKU family, then read the amount your account actually quotes.
| Request shape | Billing specification |
|---|---|
mode=std, audio=false, no video_list | 720P |
mode=pro, audio=false, no video_list | 1080P |
mode=std, audio=true | 720P+Sound |
mode=pro, audio=true | 1080P+Sound |
mode=std, with video_list | 720P+Video |
mode=pro, with video_list | 1080P+Video |
A 2026-11-18 fetch of the kling-v3-omni model-guide page showed a pricing reference of 12 credits / second and stated that final billing follows the current account quote. That page did not publish a USD per-second rate for Omni, and it did not break Sound or Video out as separate dollar figures. Do not convert credits to currency yourself, and do not reuse planning-draft rates such as $0.022/s.
- Draft at the cheaper documented mode first. Iterate in
std(720P) and a mid-range duration such as 5 seconds, keep a versioned prompt template, and change one reference list at a time. - A display price is not a channel guarantee. Confirm the ID, SKU, and availability with
GET /v1/models?type=videoand the live quote in your account before you forecast a shot list. - Control spend in the prompt layer: do not resubmit after a client timeout until you have checked task status. Official vendor contracts often add commitments or prepayment floors; ToAPIs billing is typically pay-as-you-go — confirm the active terms on your account.
6. Frequently Asked Questions
See the FAQ block in frontmatter. Summary: send kling-v3-omni, not kling-3-omni; there is no documented shots[] field; duration is 3–15 seconds and mode selects 720P or 1080P; audio and video_list cannot be combined; always poll the generations status path and persist the task id.
7. Action Checklist
- Create a key on the ToAPIs Developer Portal.
- Confirm
kling-v3-omniappears for your key viaGET /v1/models?type=video— do not sendkling-3-omni. - Smoke-test the cURL snippet with a first-and-end-frame
image_list,mode: "std", andduration: 5. - Poll
GET /v1/videos/generations/{id}with a bounded deadline, and download the result beforeexpires_at. - Next: the Kling 3.0 Turbo automation guide for high-volume short-form drafts, the kling-v3-omni model guide for the live catalog status, and the Kling V4 Flash guide if you need a different Kling contract.







