Kling 3.0 Turbo API:大量ショート動画オートメーションの設計
対象モデル:
kling-3.0-turbo
推論エンドポイント:https://api.toapis.com/v1/videos/generations
関連: Kling 3.0 Omni 徹底解説 · Kling V4 Flash API ガイド · kling-3.0-turbo リファレンス · kling-3.0-turbo モデルガイド
1. クイックスタートと性能概要 (TL;DR)
- まずカタログを見る: 企画ドラフトはときどき
kling-3-turboと書きます。その文字列は文書化された公開 ID ではありません。2026-11-18 に公式生成リファレンスと モデルガイドページ(HTTP 200)を確認した結果、固定のmodel値はkling-3.0-turboです。この正確な文字列を送ってください。 - 契約:
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 つにそろえてください。 - 文書化されている範囲:
durationは 3〜15 秒の任意の整数(デフォルト5)で、5 秒と 10 秒だけではありません。resolutionは720pまたは1080p(デフォルト720p)です。aspect_ratio(16:9、9:16、1:1)はテキストから動画のリクエストにだけ適用されます。 - 画像入力は先頭フレームのみです。
reference_imagesを送る場合、最初の公開 URL だけがfirst_frameとして使われます。この統合では末尾フレームはサポートされず、追加画像は無視されます。base64 は送らないでください。 - 捨てるべき未検証の主張: 5 秒クリップあたり
$0.11、「20 秒未満」のレイテンシ、「30+ 同時実行」、99.95% の SLA、「60% 安い」といったドラフト数字は、現行の API ドキュメントではありません。ライブのカタログまたはモデルガイドの数字だけを引用し、それらは変わり得る表示料金として扱ってください。
2. 公式 Turbo ID と大量処理の制約
model フィールドには公開モデル名を使います。ドラフトの別名、マーケ用の表示名、関連する Omni ID に置き換えないでください。
| カタログ ID | 本ガイドでの役割 | 文書化されているジョブ |
|---|---|---|
kling-3.0-turbo | 本記事のヒーロー ID | テキストから動画、および先頭フレーム入力のみの画像から動画 |
kling-v3-omni | 姉妹の Omni ID。Omni ガイド を参照 | 公式の image_list / video_list / element_list 参照(先頭・末尾フレームを含む) |
kling-v3 | 関連する非 Omni の v3 ID | 別の生成リファレンスです。Turbo のフィールドがそのまま使えると思わないでください |
公式の Turbo 生成ページは、一部のマーケ文言より狭いです。モデルガイドの一般的な説明は追加の動画ワークフローに触れることがありますが、この ID の API リファレンスが文書化しているのはテキストから動画と先頭フレームの画像から動画だけです。自動化はパンフレットではなくリファレンスに合わせてください。
| フィールド | 文書化されている値 | 注記 |
|---|---|---|
prompt | 必須の文字列 | 画像から動画では Turbo の prompt 内容として送られる |
reference_images | 任意の文字列配列 | 先頭の画像だけが first_frame として使われ、以降は無視される |
resolution | 720p(デフォルト)、1080p | Omni の mode=std/pro フラグではない |
duration | 整数 3–15(デフォルト 5) | 5 秒と 10 秒だけを列挙するドラフトは不完全 |
aspect_ratio | 16:9(デフォルト)、9:16、1:1 | テキストから動画にのみ適用 |
watermark | ブール、デフォルト false | 公式 Kling 透かしのオン / オフのみ。カスタム透かしオブジェクトは不可 |
高頻度ショートフォームの自動化は、この契約の上に載るオーケストレーションの問題です。
- 1 クリップ、1 タスク。 各バリアントを個別の非同期ジョブとして投入します。ポーリングを始める前に、タスク id(と自分側のリクエスト id)を永続化します。
- 待機には必ず上限を付ける。 期限、5〜10 秒以上のジッタ付き間隔、
429時のRetry-Afterを使います。ステータスリファレンスは長い動画に数分かかることがあると注記しています。同じ id を再照会するまで、クライアントのタイムアウトを失敗と見なさないでください。 - 同時実行 SLA を自作しない。 公式ドキュメントは、このモデルに予約された「30+ 同時実行」枠を公開していません。
429と 非同期タスクのレート制限 を見てください。バッチ状態照会は最大 100 件のタスク ID までです。 - 画像ジョブを正直に保つ。 カットに末尾フレーム、Omni リスト、またはモーション参照動画が必要なら、
reference_imagesに意味を背負わせずkling-v3-omniに切り替えてください。

図 1: 各ショートフォームのバリアントを POST /v1/videos/generations に投入し、上限付きループで同じタスク id をポーリングし、status が completed になってから result.data[0].url を読む。
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-3.0-turbo",
"prompt": "A 5-second product teaser for a lightweight running shoe, street-level camera, clean daylight",
"resolution": "720p",
"duration": 5,
"aspect_ratio": "16:9",
"watermark": false
}'
画像から動画のジョブでは "reference_images": ["https://example.com/first-frame.png"] を追加し、aspect_ratio や 2 枚目の画像を末尾フレームとして頼らないでください。
ステップ 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-3.0-turbo"
DURATION_RANGE = range(3, 16)
def dispatch_turbo(
prompt: str,
*,
model: str = DOCUMENTED_ID,
resolution: str = "720p",
duration: int = 5,
aspect_ratio: str = "16:9",
reference_images: list[str] | None = None,
watermark: bool = False,
) -> str:
if model != DOCUMENTED_ID:
raise ValueError("Send kling-3.0-turbo; kling-3-turbo is not a documented public ID")
if resolution not in {"720p", "1080p"}:
raise ValueError("resolution must be 720p or 1080p")
if duration not in DURATION_RANGE:
raise ValueError("duration must be an integer from 3 to 15")
payload = {
"model": model,
"prompt": prompt,
"resolution": resolution,
"duration": duration,
"watermark": watermark,
}
if reference_images:
payload["reference_images"] = reference_images[:1]
else:
payload["aspect_ratio"] = aspect_ratio
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")
def dispatch_batch(prompts: list[str], **kwargs) -> list[str]:
"""Submit every prompt first, then poll. A failed submit must not hide already-issued ids."""
task_ids = []
for prompt in prompts:
task_ids.append(dispatch_turbo(prompt, **kwargs))
return task_ids
if __name__ == "__main__":
variants = [
"A 5-second product teaser for a lightweight running shoe, street-level camera, clean daylight",
"The same shoe on a wet evening street, slower tracking shot, warm storefront light",
]
ids = dispatch_batch(variants, resolution="720p", duration=5)
for task_id in ids:
print("Task:", task_id)
print("Video:", poll_task(task_id))
プロンプトテンプレートの版を各タスク記録の横に保存し、解像度や duration の変更と文言変更を区別できるようにします。各ファイルは expires_at の前にダウンロードしてください。ステータスリファレンスは 30 日の保持期間を文書化しています。
4. エラー処理とステータスマトリクス
下表は診断の出発点であり、ToAPIs の正確なエラーコードを保証するものではありません。HTTP 照会が成功しても、タスクの status を読む必要があります。リクエストエラーと status: failed の理由(content_policy_rejected、insufficient_user_balance、generation_timeout など)は エラーリファレンス を見てください。
| HTTP またはタスク状態 | よくある分類 | 推奨アクション |
|---|---|---|
400 | 無効なフィールド、未対応の duration や resolution、この統合が受け付けないメディア種別 | kling-3.0-turbo であること、duration が 3–15、resolution が 720p または 1080p、画像があれば公開 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
2026-11-18 に取得した kling-3.0-turbo モデルガイド は、次の表示比較料金を示し、料金は変わる可能性があり、最終請求は現行のアカウント料金、duration、resolution、アスペクト比、送信パラメータに従うと注記していました。
| 仕様 | ToAPIs 表示料金(2026-11-18) | 同じページの公式表示料金 |
|---|---|---|
720p | $0.08 / 秒 | $0.1143 / 秒 |
1080p | $0.1 / 秒 | $0.1429 / 秒 |
リポジトリ内のモデルガイド設定も同じ ToAPIs 表示額と、720p で 16 クレジット/秒、1080p で 20 クレジット/秒の行を載せています。これらはスナップショットであり、契約ではありません。「1000 本で $380」といったドラフト計算は再利用しないでください。
- まず
720pで下書きする。 duration は控えめに保ち(文書上のデフォルトは 5 秒)、プロンプトテンプレートを版管理し、一度に 1 変数だけ変えます。 - 表示価格はチャネル保証ではない。 バッチを見積もる前に、
GET /v1/models?type=videoとアカウントのライブ見積もりで ID と可用性を確認してください。 - オーケストレーション層で支出を抑える: すべてのタスク id を永続化し、クライアントがタイムアウトしても状態確認まで再投入せず、
expires_atの前に結果をダウンロードします。公式ベンダー契約はコミットや前払い下限を付けることが多く、ToAPIs の課金は通常従量制です。有効な条件はアカウントで確認してください。
6. よくある質問
frontmatter の FAQ を参照してください。要約: kling-3.0-turbo を送り、kling-3-turbo は送らない。duration は 3–15 秒。画像入力は先頭フレームのみ。文書化された Turbo 音声や Omni リスト契約はない。generations のステータスパスをポーリングし、すべてのタスク id を永続化し、SLA を自作しない。
7. アクションチェックリスト
- ToAPIs Developer Portal でキーを作成する。
-
GET /v1/models?type=videoでキーにkling-3.0-turboが見えることを確認する。kling-3-turboは送らない。 -
resolution: "720p"、duration: 5、aspect_ratio: "16:9"で上記 cURL をスモークテストする。 - 上限付きの期限で
GET /v1/videos/generations/{id}をポーリングし、expires_atの前に結果をダウンロードする。 - 次のステップ: 公式 Omni 参照や末尾フレームが必要なら Kling 3.0 Omni 徹底解説、ライブカタログは kling-3.0-turbo モデルガイド、別の Kling 契約は Kling V4 Flash ガイド。







