Kling 4.0 API入門：PythonとcURLで最初の動画を生成する方法

PoYoのKling 4.0 APIは、テキストから動画生成、先頭／末尾フレーム生成、ビジュアル参照、動画編集のすべてを1つのモデルID kling-4.0 で扱います。リクエストを送信してタスクIDを保存し、タスクが完了するまでポーリングするのが基本の流れです。本ガイドは2026年10月24日時点で確認したPoYoの現行スキーマに基づいています。他のプロバイダーのフィールド名とは互換性がありません。

入力を画面上で試すにはKling 4.0 プレイグラウンドを開くか、APIドキュメントを参照してください。

cURLで最初の動画を生成する

シェルの環境変数に POYO_API_KEY を設定し、次の5秒のリクエストを送信します。認証情報はブラウザのコードに含めず、サーバー側で管理してください。

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-4.0",
    "input": {
      "prompt": "A paper boat floats beneath a stone bridge. One continuous low tracking shot, soft morning light, gentle water sounds, no speech or on-screen text.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

JSONレスポンスから data.task_id を読み取ります。送信が成功しても、動画が完成したわけではありません。下記の YOUR_TASK_ID をその値に置き換えてください。

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

ドキュメントに記載されているステータスは not_started、running、finished、failed です。完了したら、data.files 内の動画の file_url を確認します。失敗した場合は error_message を確認し、調査用にタスクIDを保管してください。既存タスクのポーリングに、再送信は必要ありません。

待機時間に上限を設けたPythonのポーリングループ

requests をインストールし、バックエンドで実行します。このコードはHTTPエラーとアプリケーションエラーの両方をチェックし、タスクが失敗したら停止し、待機時間を30分に制限します。タイムアウトした場合は、後で同じタスクを確認してください。自動で再送信すると、課金対象のジョブが2件作成される可能性があります。

import os
import time
import requests

base = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") not in (0, 200):
        raise RuntimeError(body.get("message") or "PoYo API error")
    return body["data"]

task = checked(session.post(base + "/api/generate/submit", json={
    "model": "kling-4.0",
    "input": {
        "prompt": "A paper boat floats beneath a stone bridge. Slow tracking shot.",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Task:", task_id, flush=True)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    task = checked(session.get(
        base + "/api/generate/status/" + task_id, timeout=60))
    if task["status"] == "failed":
        raise RuntimeError(task.get("error_message") or "Generation failed")
    if task["status"] == "finished":
        videos = [f["file_url"] for f in task.get("files", [])
                  if f.get("file_type") == "video"]
        if not videos:
            raise RuntimeError("Finished task returned no video")
        print(videos[0])
        break
    time.sleep(10)
else:
    raise TimeoutError("Check the saved task ID again: " + task_id)

目的に合った入力モードを選ぶ

参照画像が同時に指定されていても、ソース動画のフィールドがあれば編集モードが選択されます。画像から動画生成では、1枚目の画像が開始フレームとなり、2枚目の画像が終了フレームを定義します。参照画像は人物やスタイルを誘導するもので、境界フレームとは意味が異なります。

送信前に確認しておきたい上限

生成は 3〜30秒 の整数の長さと、720pまたは1080p に対応しています。このPoYoスキーマでは、通常のプロンプトは26,000文字までです。multi_prompt の各ショットは最大512文字で、ショットの長さを省略した場合は5秒になります。ショットの長さの合計は3〜30秒でなければならず、トップレベルの長さを明示する場合はその合計と一致させる必要があります。

参照には画像を最大10枚、動画を最大5本、被写体を最大7件まで指定でき、合計の上限は15アセットです。先頭フレームは画像数と合計数の両方にカウントされます。参照動画や被写体動画はそれぞれ3〜30秒である必要があり、実際の長さの合計は30秒を超えられません。上限を超える入力を通すために、長さを切り捨てて申告しないでください。

最初の請求額を把握する

動画入力なしの5秒・720pのリクエストは 142.5クレジット、現在の換算レートで $0.7125 です。動画入力を加えると、単価と課金対象の長さの両方が変わります。参照動画や編集のワークフローを見積もる前に、料金の計算例を確認してください。

公式のクリエイター向けプロダクトでは、複数のキーフレームなど追加のコントロールが紹介されています。ここでのPoYoスキーマで利用できるのは、最大2枚の境界フレームとショットごとのプロンプトです。存在しない keyframes、seed、negative_prompt、generate_audio フィールドをこのエンドポイントに送信しないでください。実例については、プロンプトガイドとOmni Referenceチュートリアルに進んでください。

よくある質問

APIのモデルIDは kling-4-0 ですか？ いいえ。それはページのスラッグです。リクエストのモデルIDは kling-4.0 です。

ここで4Kをリクエストできますか？ このPoYoエンドポイントは現在 720p と 1080p のみを受け付けます。クリエイターアプリのマーケティング上の仕様をそのまま使わず、プロバイダーのスキーマを確認してください。

コールバックは使えますか？ 送信リクエストはトップレベルの callback_url に対応しています。コールバックの扱いについては最新のドキュメントを参照してください。上記のポーリング例はコールバックに依存していません。

どこから始めればよいですか？ まずテキストのみの短いリクエストを送り、タスクIDと結果を保存してから、プレイグラウンドで入力モダリティを1つずつ追加していきましょう。