Kling 3.0 Omni API 徹底解説:マルチショット動画生成と物理的な連続性
対象モデル:
kling-v3-omni
推論エンドポイント:https://api.toapis.com/v1/videos/generations
関連: Kling 3.0 Turbo 自動化ガイド · Kling V4 Flash API ガイド · kling-v3-omni リファレンス · kling-v3-omni モデルガイド
1. クイックスタートと性能概要 (TL;DR)
- まずカタログを見る: 企画ドラフトはときどき
kling-3-omniと書きます。その文字列は文書化された公開 ID ではありません。2026-11-18 に公式生成リファレンスと モデルガイドページ(HTTP 200)を確認した結果、固定のmodel値はkling-v3-omniです。この正確な文字列を送ってください。 - 契約:
POST /v1/videos/generationsに非同期で投入し、GET /v1/videos/generations/{id}をcompletedまたはfailedまでポーリングします。通常タスクはGET /v1/tasks/{id}でも照会できます。公式例はhttps://toapis.com(中国本土はhttps://toapis.cn)です。本シリーズの他ガイドはhttps://api.toapis.comを使います。オリジンは 1 つにそろえてください。 shots[]フィールドはない: マルチショットの連続性と物理的な一貫性は、プロンプトと参照素材の問題です。公式プレースホルダ<<<image_N>>>、<<<video_N>>>、<<<element_N>>>を、metadata.image_list、video_list、metadata.element_listと組み合わせて使います。リスト順はプレースホルダ順と一致させる必要があります。システムはプレースホルダを自動挿入せず、先頭フレームも自動追加しません。- メディア: 公開の
http://またはhttps://URL だけを送ってください。ローカルファイルはPOST /v1/uploads/imagesでアップロードし、返却 URL を使います。base64 は送らないでください。audioとvideo_listは互排他です。 - 捨てるべき未検証の主張:
$0.022/sのようなドラフト単価、99.95% の SLA、カスタムshotsスキーマは、現行の ToAPIs ドキュメントではありません。ライブ料金とチャネル可否はアカウントで確認してください。
2. 公式 Omni ID、プレースホルダ、連続性ワークフロー
model フィールドには公開モデル名を使います。ドラフトの別名、URL スラッグ、関連するが別のカタログ ID に置き換えないでください。
| カタログ ID | 本ガイドでの役割 | 文書化されているジョブ |
|---|---|---|
kling-v3-omni | 本記事のヒーロー ID | テキストから動画、および公式 Omni 参照:image_list、video_list、element_list |
kling-3.0-turbo | 姉妹のショートフォーム ID。Turbo ガイド を参照 | テキストから動画と先頭フレームの画像から動画のみ。Omni 参照契約ではない |
kling-v3 | 関連する非 Omni の v3 ID | 別の生成リファレンスです。その文書がそう書いていない限り、Omni リストやプレースホルダをこの ID に送らないでください |
kling-v3-omni の主なリクエストフィールド:
| フィールド | 文書化されている値 | 注記 |
|---|---|---|
prompt | 必須の文字列 | 1 始まりのプレースホルダで素材を参照する |
mode | std(デフォルト)または pro | std は 720P、pro は 1080P。同じフラグが課金解像度も決める |
duration | 整数 3–15(デフォルト 5) | 5 秒または 10 秒に限定されない |
aspect_ratio | 一般値 16:9(デフォルト)、9:16、1:1 | マーケ用のパラメータ表が短い場合は生成リファレンスを優先 |
audio | ブール、デフォルト false | true は Sound 課金。video_list と併用不可 |
video_list | 最大 1 本 | Video として課金。refer_type: base または feature。keep_original_sound: yes または no |
metadata.image_list | 公開の image_url | 任意の type は first_frame または end_frame。end_frame には first_frame が必須 |
metadata.element_list | 被写体または役割の素材 | url に加え、任意の type(例: image または video)と role |
watermark | ブール | オン / オフのみ |
client_business_id | 任意の文字列 | 中国語 Omni リファレンスではトップレベル(metadata でも可、トップレベル推奨)。後で GET /v1/videos/generations/{client_business_id} で照会できる |
プレースホルダは 1 始まりで、リスト順と一致させてください。
| 構文 | 参照先 |
|---|---|
<<<image_1>>> | metadata.image_list の先頭 |
<<<video_1>>> | video_list の先頭(中国語リファレンスでは唯一の項目) |
<<<element_1>>> | metadata.element_list の先頭 |
英語の生成ページはリスト構文として <<<video_2>>> を例示します。中国語リファレンスは video_list を 1 本に制限しています。アカウントリファレンスが後から別途述べない限り、2 本目の参照動画は送らないでください。
文書化されたフィールドだけで、マルチショットで物理的に一貫したクリップを組み立てる方法は残っています。
- 先頭と末尾フレームで弧を固定する。 開始静止画を
image_listにtype: "first_frame"で入れ、終了静止画をtype: "end_frame"にします。プロンプトで両方に言及し(<<<image_1>>>から<<<image_2>>>へ遷移)、その間の動き、重力、カメラ経路を記述します。 element_listで同一性を固定する。 関連ジョブで同じ被写体 URL と安定したrole(例:"subject")を再利用し、カメラ記述だけを変えたときに衣服・顔・比率が流れないようにします。refer_type: "feature"で動きを借りる。<<<video_1>>>を公開のモーション参照に向け、<<<element_1>>>にその動きを追わせます。ソースクリップ自体を編集する場合(背景置換など)はrefer_type: "base"を使います。- ジョブを明示的につなぐ。 ステータス文書は Omni 専用のラストフレーム API ではありません。後続ショットを前のテイクから始めたい場合は、そのテイクの公開スチルまたはダウンロードをホストし、次の
first_frameとして送ってください。各タスク id は永続化します。

図 1: 公開 URL のみの image_list、video_list、element_list を POST /v1/videos/generations に送り、同じタスク id をポーリングし、status が completed になってから result.data[0].url を読む。
Omni リストが不要な高頻度ショートフォームの下書きには、kling-3.0-turbo を使います。別の Kling 生成契約については Kling V4 Flash ガイド を参照してください。
3. 本番実装: cURL と Python
本シリーズの国際例は https://api.toapis.com を使います。公式ドキュメントは中国本土の利用者に https://toapis.cn を案内しています。環境ごとにオリジンは 1 つに固定してください。パス、モデル ID、Bearer ヘッダは同じです。
ステップ 1: 先頭・末尾フレームジョブの cURL 投入
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"}
]
}
}'
テキストのみのジョブでは metadata とプレースホルダを省略します。被写体とモーション参照のジョブでは refer_type: "feature" の video_list と metadata.element_list を使い、audio: true は設定しません。
ステップ 2: Python ヘルパーとポーラー
このスニペットは文書化されたタスク状態パスと、queued / in_progress / completed / failed に従います。出荷前に、アカウント向け API リファレンスで id、result.data[0].url、エンベロープを確認してください。
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))
プロンプトテンプレートの版をタスク記録の横に保存し、プレースホルダやリスト順の変更と文言変更を区別できるようにします。expires_at の前にファイルをダウンロードしてください。ステータスリファレンスは 30 日の保持期間を文書化しています。
4. エラー処理とステータスマトリクス
下表は診断の出発点であり、ToAPIs の正確なエラーコードを保証するものではありません。HTTP 照会が成功しても、タスクの status を読む必要があります。リクエストエラーと status: failed の理由(content_policy_rejected、insufficient_user_balance、generation_timeout など)は エラーリファレンス を見てください。
| HTTP またはタスク状態 | よくある分類 | 推奨アクション |
|---|---|---|
400 | 無効なフィールド、プレースホルダとリストの不一致、audio と video_list の併用、first_frame なしの end_frame | kling-v3-omni であること、プレースホルダ順が各リストと一致すること、メディアが公開 URL であること、互排他フィールドを併用していないことを確認する |
401 | API キー不足または無効 | ToAPIs ダッシュボードでキーをローテーションし、Authorization: Bearer ヘッダを確認する |
429 | レートまたは同時実行の制限 | Retry-After があれば従い、ジッタ付きでバックオフし、安全なときだけ再試行する |
5xx またはクライアントタイムアウト | ゲートウェイまたは上流の一時的な問題 | 再投入する前に既存のタスク id を照会する |
status: queued または in_progress | エラーではない | 待って再ポーリングする。2 つ目のジョブを作らない |
status: failed | 生成が成功しなかった | error.code と error.message(あれば error.reason)を読む。未変更のポリシー拒否ペイロードを再試行しない |
5. 料金と FinOps ROI
公式の中国語 Omni リファレンスは課金マップを公開しています。まず SKU 系統を選び、アカウントが実際に提示する金額を読んでください。
| リクエストの形 | 課金仕様 |
|---|---|
mode=std、audio=false、video_list なし | 720P |
mode=pro、audio=false、video_list なし | 1080P |
mode=std、audio=true | 720P+Sound |
mode=pro、audio=true | 1080P+Sound |
mode=std、video_list あり | 720P+Video |
mode=pro、video_list あり | 1080P+Video |
2026-11-18 に取得した kling-v3-omni モデルガイド は、料金参考値として 12 クレジット / 秒 を示し、最終請求は現行のアカウント見積もりに従うと述べていました。このページは Omni のドル毎秒料金を掲載しておらず、Sound や Video を別のドル金額にも分けていません。クレジットを独自に通貨換算せず、企画ドラフトの $0.022/s のような単価も再利用しないでください。
- まず文書化された安いモードで下書きする。
std(720P)と 5 秒程度の中間 duration で反復し、版管理したプロンプトテンプレートを保ち、参照リストは一度に 1 つだけ変えます。 - 表示価格はチャネル保証ではない。 ショットリストを見積もる前に、
GET /v1/models?type=videoとアカウントのライブ見積もりで ID、SKU、可用性を確認してください。 - プロンプト層で支出を抑える: クライアントがタイムアウトしても、状態を確認するまで再投入しないでください。公式ベンダー契約はコミットや前払い下限を付けることが多く、ToAPIs の課金は通常従量制です。有効な条件はアカウントで確認してください。
6. よくある質問
frontmatter の FAQ を参照してください。要約: kling-v3-omni を送り、kling-3-omni は送らない。文書化された shots[] はない。duration は 3–15 秒で、mode が 720P または 1080P を選ぶ。audio と video_list は併用できない。generations のステータスパスをポーリングし、タスク id を永続化する。
7. アクションチェックリスト
- ToAPIs Developer Portal でキーを作成する。
-
GET /v1/models?type=videoでキーにkling-v3-omniが見えることを確認する。kling-3-omniは送らない。 - 先頭・末尾フレームの
image_list、mode: "std"、duration: 5で上記 cURL をスモークテストする。 - 上限付きの期限で
GET /v1/videos/generations/{id}をポーリングし、expires_atの前に結果をダウンロードする。 - 次のステップ: 高頻度ショートフォームの下書きは Kling 3.0 Turbo 自動化ガイド、ライブカタログは kling-v3-omni モデルガイド、別の Kling 契約は Kling V4 Flash ガイド。







