Comfy Router で Kling 3.0 Turbo を使用する

Comfy Router 経由で kling/kling-3.0-turbo を呼び出します: エンドポイント、リクエスト形状、Router が返すレスポンスについて説明します。

kling/kling-3.0-turbo の API リファレンス。Kling から Comfy Router が提供します。

​

クイックスタート

Comfy ワークスペースでキーを作成し、COMFY_API_KEY としてエクスポートします。Python、TypeScript、Swift のスニペットは Comfy SDK（pip install comfy-sdk、npm install @comfyorg/sdk、および ComfySwiftSDK Swift パッケージ）を使用しています。cURL のスニペットは、同じ呼び出しを生の HTTP で行うものです。

モデル ID: kling/kling-3.0-turbo

エンドポイント: POST https://api.comfy.org/v2/models/kling/kling-3.0-turbo

結果を待つ

Python

from comfy_sdk import Comfy

# 環境変数から COMFY_API_KEY を読み取ります。
# SDK は自動的に冪等性キーを作成し、自動リトライ時に再利用します。
with Comfy() as client:
    result = client.models.run(
        "kling/kling-3.0-turbo",
        {
            "prompt": "A neon-lit alley in the rain, slow dolly forward.",
            "settings": {
                "aspect_ratio": "16:9",
                "duration": 5,
                "resolution": "1080p",
            },
        },
    )

print(result)

キューに送信して後で取得

同じボディを POST https://api.comfy.org/v2/models/kling/kling-3.0-turbo/requests に送信します。Router は実行が受け付けられ次第 201 と request_id を返し、結果は準備が整った時点で、このプロセスからでも別のプロセスからでも取得できます。ステータス、キャンセル、結果の取得の詳細は キュー配信 を参照してください。

Python

from comfy_sdk import Comfy

# 環境変数から COMFY_API_KEY を読み取ります。
# submit() を呼び出すたびに独自の Idempotency-Key が発行され、自動リトライで再利用されます。
with Comfy() as client:
    handle = client.models.submit(
        "kling/kling-3.0-turbo",
        {
            "prompt": "A neon-lit alley in the rain, slow dolly forward.",
            "settings": {
                "aspect_ratio": "16:9",
                "duration": 5,
                "resolution": "1080p",
            },
        },
    )
    print("request_id:", handle.request_id)  # モデル ID と合わせて、別のプロセスに必要な情報はこれだけです

    # リクエストが完了するまでポーリングし、サーバーが指定する Retry-After の秒数だけ待機します。
    for update in handle.iter_events():
        print(update.status, update.queue_position)

    # プロバイダー自身のペイロードで、models.run() が返すのと同じ値です。
    # 失敗またはキャンセル済みのリクエストは、ここで型付きの Router エラーを発生させます。
    result = handle.get()

print(result)

​

サービス提供プロバイダー

このモデルは、リクエストで別のプロバイダーを指定しない限り、Comfy Router が直接サービスを提供します。以下のプロバイダーも、同じエンドポイント・同じモデル ID でこのモデルを提供しており、model_provider クエリパラメータで選択します。

• Comfy（デフォルト）: POST https://api.comfy.org/v2/models/kling/kling-3.0-turbo
• Higgsfield、higgsfield/higgsfield-kling-3-turbo として: POST https://api.comfy.org/v2/models/kling/kling-3.0-turbo?model_provider=higgsfield

strict_mode のデフォルトは false なので、Router はこのページで説明しているネイティブのリクエストボディをプロバイダー独自のスキーマに変換し、レスポンスを元の形式に戻します。API リファレンスの model_provider、strict_mode、fallback_provider と、この方法でルーティングされるすべてのモデルについてはサービス提供プロバイダーを参照してください。

​

スキーマ

​

入力

options · object

コールバックアドレスやウォーターマークオプションなどの一般設定。

options.callback_url · string

タスク結果のコールバック通知 URL。タスクのステータスが変化したときにサーバーが通知します。

options.external_task_id · string

カスタムタスク ID。システムが生成したタスク ID を上書きすることはありませんが、クエリに使用できます。1 つのユーザーアカウント内で一意である必要があります。

options.watermark_info · object

ウォーターマーク付きの結果を同時に生成するかどうか。カスタムウォーターマークには対応していません。

options.watermark_info.enabled · boolean

true の場合はウォーターマーク付きの結果を生成し、false の場合は生成しません。デフォルトは false。

prompt · string · 必須

ポジティブとネガティブの両方の記述を含めることができるプロンプト。推奨の長さは 2500 文字以下です。マルチショットビデオでは “shot n, m, words; shot n, m, words;” の形式を使用します。

settings · object

解像度、アスペクト比、再生時間などの出力設定。

settings.aspect_ratio · string

生成されるフレームのアスペクト比（幅:高さ）。“16:9”、“9:16”、“1:1” のいずれか。デフォルトは “16:9”。

指定可能な値: 16:9, 9:16, 1:1

settings.duration · integer

ビデオの長さ（秒）。対応する値は 3 から 15 です。デフォルトは 5。

範囲: 3 から 15

settings.resolution · string

生成されるビデオの鮮明さ。“720p” または “1080p” のいずれか。デフォルトは “720p”。

指定可能な値: 720p, 1080p

スキーマから生成されており、Router が GET /v2/models/kling/kling-3.0-turbo/openapi.json で提供するドキュメント、つまりリクエストがプロバイダーに到達する前に呼び出しを検証するのと同じドキュメントです。

​

出力

code · integer

エラーコード。0 は成功を示します。

data · object[]

クエリに一致するタスク。

data[].billing · object[]

タスクの課金詳細。

data[].billing[].amount · string

消費量。小数点以下 2 桁まで正確です。

data[].billing[].charge_type · string

消費アカウントの種類。残高の場合は “cash”、リソースパッケージの場合は “unit”。

data[].billing[].package_type · string

消費可能なリソースバンドルの種類（charge_type が “unit” の場合のみ存在）。“video”、“image”、“audio” のいずれか。

data[].create_time · integer

タスクの作成時刻。ミリ秒単位の Unix タイムスタンプ。

フォーマット: int64

data[].external_id · string

このタスクのカスタムタスク ID（存在する場合）。

data[].id · string

タスク ID。

data[].message · string

タスクのステータス情報。タスクが失敗した場合は失敗理由を表示します。

data[].outputs · object[]

タスクの生成済み出力。

data[].outputs[].duration · string

生成されるビデオの再生時間（秒）。

data[].outputs[].group_id · string

グループ化マーカー。グループ化された画像の場合のみ存在します。

data[].outputs[].id · string

システムが生成した出力 ID。

data[].outputs[].mp3_duration · string

生成される MP3 オーディオの再生時間（秒）。

data[].outputs[].mp3_url · string

生成されるオーディオの MP3 URL（直リンク防止あり）。

data[].outputs[].name · string

生成されるマテリアルの名前。

data[].outputs[].owned_by · string

マテリアルのソース。“kling” は公式ライブラリを示し、数値はクリエイター ID です。

data[].outputs[].status · string

マテリアルのステータス。“succeeded” または “deleted” のいずれか。

data[].outputs[].type · string

出力コンテンツの種類。“video”、“image”、“audio”、“voice”、“element” のいずれか。

data[].outputs[].url · string

生成された結果の URL（直リンク防止あり）。30 日後にクリアされます。

data[].outputs[].watermark_url · string

ウォーターマーク付きの結果の URL（直リンク防止あり）。

data[].outputs[].wav_duration · string

生成される WAV オーディオの再生時間（秒）。

data[].outputs[].wav_url · string

生成されるオーディオの WAV URL（直リンク防止あり）。

data[].status · string

タスクのステータス。“submitted”、“processing”、“succeeded”、“failed” のいずれか。

data[].update_time · integer

タスクの更新時刻。ミリ秒単位の Unix タイムスタンプ。

フォーマット: int64

message · string

エラーメッセージ。

request_id · string

システムが生成したリクエスト ID。

​

例

​

入力

{
  "prompt": "A neon-lit alley in the rain, slow dolly forward.",
  "settings": {
    "aspect_ratio": "16:9",
    "duration": 5,
    "resolution": "1080p"
  }
}

​

出力

{
  "code": 0,
  "data": [
    {
      "create_time": 1798761600000,
      "id": "kling-v2-task-7c8d9e0f1a2b",
      "message": "",
      "outputs": [
        {
          "duration": "5",
          "id": "kling-v2-output-2b1a0f9e8d7c",
          "type": "video",
          "url": "https://example.invalid/kling/kling-3.0-turbo/generated.mp4"
        }
      ],
      "status": "succeeded",
      "update_time": 1798761820000
    }
  ],
  "message": "SUCCEED",
  "request_id": "3d7e5c91-0b42-4f68-9a13-8e2c6d4b0a75"
}

​

出荷前の確認

SDK は Idempotency-Key を生成し、自動リトライで再利用します。手動リトライでは元のキーを再利用してください。Router は最大 10 分間接続を保持できます。

リクエストが失敗すると、Router は理由を説明する X-Comfy-Error-Type レスポンスヘッダーを送信します。422 は、プロバイダーを呼び出す前に Router が入力を拒否したことを意味し、413 はリクエスト本文が Router の受け入れ可能なサイズを超えていたことを意味します。生成されたアセットは 結果 URL の有効期限 があるため、早めにダウンロードしてください。

上記のフィールド説明に記載されているサイズ制限は、プロバイダーの仕様から引用した、そのフィールドに対するプロバイダー自身の上限です。Router はリクエスト本文全体に対して別の上限を適用し、base64 エンコードされたメディアもこれにカウントされます。リクエスト本文のサイズ を参照してください。

このページは、Comfy Router 経由で呼び出す 1 つのパートナーモデルについて説明しています。同じ comfy-sdk / @comfyorg/sdk パッケージには、Comfy Cloud 上で ComfyUI のワークフローグラフ全体を実行するための 2 つ目のクライアントも含まれています: Comfy(api_key=...) / new Comfy({ apiKey })、および client.workflows、client.assets、client.jobs。Comfy SDKs を参照してください。

ヘッダー

認証、冪等性、リクエスト ID、エラー分類、リトライ間隔、支出上限。

Router API の利用

モデルの検出、バリデーションエラー、リトライ、課金。

制限事項

Router が現在対応していないことと、代替手段。