Comfy Router で Kling V3 を使用する

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

kling/kling-v3 の API リファレンス。Kling から提供され、Comfy Router 経由で配信されます。

​

クイックスタート

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

モデル ID: kling/kling-v3

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

結果を待つ

Python

from comfy_sdk import Comfy

# 環境変数から COMFY_API_KEY を読み取ります。
# SDK は自動的に冪等キーを作成し、自動リトライ時に再利用します。
with Comfy() as client:
    result = client.models.run(
        "kling/kling-v3",
        {
            "aspect_ratio": "16:9",
            "duration": "5",
            "mode": "std",
            "prompt": "A red fox trotting through falling snow, cinematic lighting.",
        },
    )

print(result)

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

同じボディを POST https://api.comfy.org/v2/models/kling/kling-v3/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-v3",
        {
            "aspect_ratio": "16:9",
            "duration": "5",
            "mode": "std",
            "prompt": "A red fox trotting through falling snow, cinematic lighting.",
        },
    )
    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-v3
• Higgsfield、higgsfield/higgsfield-kling-3-std として: POST https://api.comfy.org/v2/models/kling/kling-v3?model_provider=higgsfield

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

​

スキーマ

​

入力

aspect_ratio · string · デフォルト: "\"16:9\""

ビデオのアスペクト比

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

callback_url · string (uri)

コールバック通知先アドレス

形式: uri

camera_control · object

camera_control.config · object

camera_control.config.horizontal · number

水平軸（x軸）に沿ったカメラの移動を制御します。負の値は左、正の値は右を示します。

範囲: -10 から 10

camera_control.config.pan · number

垂直面内でのカメラの回転（x軸）を制御します。負の値は下向きの回転、正の値は上向きの回転を示します。

範囲: -10 から 10

camera_control.config.roll · number

カメラのロール量（z軸）を制御します。負の値は反時計回り、正の値は時計回りを示します。

範囲: -10 から 10

camera_control.config.tilt · number

水平面内でのカメラの回転（y軸）を制御します。負の値は左回転、正の値は右回転を示します。

範囲: -10 から 10

camera_control.config.vertical · number

垂直軸（y軸）に沿ったカメラの移動を制御します。負の値は下、正の値は上を示します。

範囲: -10 から 10

camera_control.config.zoom · number

カメラの焦点距離の変化を制御します。負の値は画角が狭くなり、正の値は画角が広がることを示します。

範囲: -10 から 10

camera_control.type · string

定義済みのカメラ動作タイプ。simple: カスタマイズ可能なカメラ動作。down_back: カメラが下降しながら後退します。forward_up: カメラが前進しながら上方向に傾きます。right_turn_forward: 右に回転して前進します。left_turn_forward: 左に回転して前進します。

指定可能な値: simple, down_back, forward_up, right_turn_forward, left_turn_forward

cfg_scale · number · デフォルト: "0.5"

ビデオ生成における柔軟性。値が高いほどモデルの柔軟性が低くなり、ユーザーのプロンプトとの関連性が強くなります。

範囲: 0 から 1

形式: float

duration · string · デフォルト: "\"5\""

ビデオの長さ（秒）

指定可能な値: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

external_task_id · string

カスタムタスクID

mode · string · デフォルト: "\"std\""

ビデオ生成モード。std: スタンダードモード。コスト効率に優れています。pro: プロフェッショナルモード。より長い再生時間のビデオを生成しますが、出力品質は高くなります。

指定可能な値: std, pro

model_name · string

モデル名。Comfy Router を使用する場合は省略するか null を送信してください。モデルはリクエストパスによって選択されます。名前を指定する場合は、そのパスと一致している必要があります。

multi_prompt · object[]

各ストーリーボードの情報（プロンプトや再生時間など）。最大 6 つのストーリーボードをサポートし、最小は 1 です。multi_shot が true かつ shot_type が customize の場合に必須です。

multi_prompt[].duration · string

このストーリーボードの再生時間（秒）。タスク全体の再生時間を超えてはならず、1 未満にもできません。すべてのストーリーボードの再生時間の合計は、タスク全体の再生時間と等しくなります。

multi_prompt[].index · integer

ショットの連番

multi_prompt[].prompt · string

このストーリーボードのプロンプトワード。最大長 512 文字。

multi_shot · boolean · デフォルト: "false"

マルチショットビデオを生成するかどうか。true の場合、prompt パラメータは無効です。false の場合、shot_type と multi_prompt パラメータは無効です。

negative_prompt · string

ネガティブテキストプロンプト。ネガティブプロンプトの情報は、ポジティブプロンプト内に直接ネガティブな文を加えて補足することを推奨します。

prompt · string

ポジティブテキストプロンプト。voice_list パラメータの順序に対応する音声を指定するには、<<<voice_1>>> を使用します。1 つのタスクで参照できるトーンは最大 2 つです。トーンを指定する場合、sound パラメータの値は on である必要があります。

shot_type · string

ストーリーボード方法。multi_shot パラメータが true に設定されている場合に必須です。

指定可能な値: customize, intelligence

sound · string · デフォルト: "\"off\""

ビデオ生成時に同時にサウンドを生成するかどうか。このパラメータをサポートするのは V2.6 以降のモデルのみです。

指定可能な値: on, off

watermark_info · object

ウォーターマーク付きの結果を同時に生成するかどうか。現時点ではカスタムウォーターマークはサポートされていません。

watermark_info.enabled · boolean

true はウォーターマークを生成することを意味し、false は生成しないことを意味します。

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

​

出力

code · integer

エラーコード

data · object

data.created_at · integer

タスク作成時間、Unix タイムスタンプ（ミリ秒）

data.final_unit_deduction · string

タスクの消費ユニット数

data.task_id · string

タスク ID

data.task_info · object

data.task_info.external_task_id · string

data.task_result · object

data.task_result.videos · object[]

data.task_result.videos[].duration · string

ビデオの合計再生時間（秒）

data.task_result.videos[].id · string

生成済みビデオ ID

data.task_result.videos[].url · string (uri)

生成済みビデオの URL

フォーマット: uri

data.task_result.videos[].watermark_url · string (uri)

ウォーターマーク付き生成済みビデオの URL、直リンク防止フォーマット

フォーマット: uri

data.task_status · string

タスクステータス

取り得る値: submitted、processing、succeed、failed

data.task_status_msg · string

タスクステータス情報。タスク失敗時に失敗理由を表示します

data.updated_at · integer

タスク更新時間、Unix タイムスタンプ（ミリ秒）

data.watermark_info · object

data.watermark_info.enabled · boolean

message · string

エラーメッセージ

request_id · string

リクエスト ID

​

例

​

入力

{
  "aspect_ratio": "16:9",
  "duration": "5",
  "mode": "std",
  "prompt": "A red fox trotting through falling snow, cinematic lighting."
}

​

出力

{
  "code": 0,
  "data": {
    "created_at": 1798761600000,
    "task_id": "kling-task-1a2b3c4d5e6f",
    "task_result": {
      "videos": [
        {
          "duration": "5",
          "id": "kling-video-6f5e4d3c2b1a",
          "url": "https://example.invalid/kling/kling-v2-5-turbo/generated.mp4"
        }
      ]
    },
    "task_status": "succeed",
    "task_status_msg": "",
    "updated_at": 1798761840000
  },
  "message": "SUCCEED",
  "request_id": "9f2c1a04-7b6e-4d38-8a51-3c0e7d9b2f46"
}

​

出荷前の確認

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 が現在対応していないことと、代替手段。