diff --git a/docs.json b/docs.json index adeab7e429..ba584cd2a3 100644 --- a/docs.json +++ b/docs.json @@ -7487,6 +7487,7 @@ "zh/development/comfy-router/queue", "zh/development/comfy-router/errors", "zh/development/comfy-router/billing", + "zh/development/comfy-router/realtime", "zh/development/comfy-router/headers", "zh/development/comfy-router/reference", "zh/development/comfy-router/limitations", @@ -11556,6 +11557,7 @@ "ja/development/comfy-router/queue", "ja/development/comfy-router/errors", "ja/development/comfy-router/billing", + "ja/development/comfy-router/realtime", "ja/development/comfy-router/headers", "ja/development/comfy-router/reference", "ja/development/comfy-router/limitations", @@ -15555,6 +15557,7 @@ "ko/development/comfy-router/queue", "ko/development/comfy-router/errors", "ko/development/comfy-router/billing", + "ko/development/comfy-router/realtime", "ko/development/comfy-router/headers", "ko/development/comfy-router/reference", "ko/development/comfy-router/limitations", diff --git a/ja/development/comfy-router/api.mdx b/ja/development/comfy-router/api.mdx index c6f3fadec0..98ff194042 100644 --- a/ja/development/comfy-router/api.mdx +++ b/ja/development/comfy-router/api.mdx @@ -2,7 +2,7 @@ title: "Comfy Router API の概要" sidebarTitle: "概要" description: "Comfy Router API の仕組み: モデル ID ごとに 1 つのルート。検出、スキーマ、キュー中のリクエスト、エラー、課金に関するガイドを用意しています。" -translationSourceHash: dac7e853 +translationSourceHash: cb493feb translationFrom: development/comfy-router/api.mdx --- @@ -45,4 +45,5 @@ translationFrom: development/comfy-router/api.mdx - [クイックスタート](/ja/development/comfy-router/quickstart): インストール、呼び出し、画像の保存。 - [モデル](/ja/development/comfy-router/models): カタログをブラウズし、モデル固有のリクエスト例を確認します。 - [ヘッダー](/ja/development/comfy-router/headers): 認証、冪等性、リクエスト ID、リトライのペース配分。 -- [API リファレンス](/ja/development/comfy-router/reference): エンドポイントのパラメータ、スキーマ、レスポンスコード。 \ No newline at end of file +- [API リファレンス](/ja/development/comfy-router/reference): エンドポイントのパラメータ、スキーマ、レスポンスコード。 +- [リアルタイム音声](/ja/development/comfy-router/realtime): Grok Voice WebSocket セッションを開き、秒単位で課金されます。 diff --git a/ja/development/comfy-router/limitations.mdx b/ja/development/comfy-router/limitations.mdx index e251530d59..81ad9ee96c 100644 --- a/ja/development/comfy-router/limitations.mdx +++ b/ja/development/comfy-router/limitations.mdx @@ -2,7 +2,7 @@ title: "Comfy Router の機能と制限" sidebarTitle: "機能と制限" description: "Comfy Router とパートナープロキシのどちらを選ぶか、長時間実行される呼び出しへの備え、リカバリ・レート制限・アセット保存について説明します。" -translationSourceHash: 235802c5 +translationSourceHash: 91b99a79 translationFrom: development/comfy-router/limitations.mdx translationBlockHashes: "_intro": 6b871cf3 @@ -14,7 +14,7 @@ translationBlockHashes: "Requests are rate limited per caller": 249d4d51 "No progress while a call runs": 75d42d8d "Comfy charges and usage": cf6e2050 - "Models without a pre-flight estimate": 495bdb2b + "Models without a pre-flight estimate": dcd4dce1 "Router does not cover every partner operation": 786c0fb2 "Model outputs and stored assets": 06c737c1 "Next": be85b789 @@ -122,7 +122,6 @@ Router は、以下のモデルへの呼び出しを実行前に確実に価格 - **heygen**: `heygen/starfish` - **ideogram**: `ideogram/ideogram-v3`, `ideogram/ideogram-v4`, `ideogram/p-image-ideogram` - **kling**: `kling/kling-3.0-turbo`, `kling/kling-image-o1`, `kling/kling-v2-5-turbo`, `kling/kling-v2-6`, `kling/kling-v3`, `kling/kling-v3-omni`, `kling/kling-video-o1`, `kling/videos-avatar-image2video`, `kling/videos-lip-sync`, `kling/videos-video-extend` -- **luma**: `luma/photon-1`, `luma/photon-flash-1` - **meshy**: `meshy/animations`, `meshy/meshy-6`, `meshy/meshy-7`, `meshy/meshy-7.1`, `meshy/remesh`, `meshy/rigging` - **moonvalley**: `moonvalley/image-to-video`, `moonvalley/text-to-video`, `moonvalley/video-to-video` - **openai**: `openai/gpt-image-1.5` diff --git a/ja/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx b/ja/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx index e387986e28..8cbd43340f 100644 --- a/ja/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx +++ b/ja/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx @@ -2,13 +2,13 @@ title: "Comfy Router で Kling 3.0 Turbo を使用する" description: "Comfy Router 経由で kling/kling-3.0-turbo を呼び出します: エンドポイント、リクエスト形状、Router が返すレスポンスについて説明します。" sidebarTitle: "Kling 3.0 Turbo" -translationSourceHash: 301a1ee1 +translationSourceHash: d03a4ba5 translationFrom: development/comfy-router/models/kling/kling-3-0-turbo/code.mdx translationBlockHashes: "_intro": 5a8c5f4b "Quick start": a2145573 "Serving providers": 7ec93d4f - "Schema": 1f5f61c1 + "Schema": 4ec53894 "Examples": 0a9a8bbe --- @@ -195,11 +195,11 @@ curl https://api.comfy.org/v2/models/kling/kling-3.0-turbo/requests/$REQUEST_ID - タスク結果のコールバック通知 URL。タスクのステータスが変化したときにサーバーが通知します。 + タスク結果のコールバック通知 URL。タスクのステータスが変化したときにサーバーが通知します。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 - カスタムタスク ID。システムが生成したタスク ID を上書きすることはありませんが、クエリに使用できます。1 つのユーザーアカウント内で一意である必要があります。 + カスタムタスク ID。システムが生成したタスク ID を上書きすることはありませんが、クエリに使用できます。1 つのユーザーアカウント内で一意である必要があります。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 diff --git a/ja/development/comfy-router/models/kling/kling-image-o1/code.mdx b/ja/development/comfy-router/models/kling/kling-image-o1/code.mdx index 1dfb6f8731..7ae7773069 100644 --- a/ja/development/comfy-router/models/kling/kling-image-o1/code.mdx +++ b/ja/development/comfy-router/models/kling/kling-image-o1/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router で Kling Image O1 を使用する" description: "Comfy Router を通じて kling/kling-image-o1 を呼び出します: エンドポイント、リクエスト形状、Router が返すレスポンスについて説明します。" sidebarTitle: "Kling Image O1" -translationSourceHash: cf053382 +translationSourceHash: 0d76917c translationFrom: development/comfy-router/models/kling/kling-image-o1/code.mdx translationBlockHashes: "_intro": 513c65df "Quick start": 6256a30d - "Schema": d18a5393 + "Schema": 61821697 "Examples": 826db173 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-image-o1/requests/$REQUEST_ID \ - このタスクの結果を受け取るコールバック通知先アドレス。設定すると、タスクステータスが変化したときにサーバーから能動的に通知されます。 + このタスクの結果を受け取るコールバック通知先アドレス。設定すると、タスクステータスが変化したときにサーバーから能動的に通知されます。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 形式: `uri` @@ -182,7 +182,7 @@ curl https://api.comfy.org/v2/models/kling/kling-image-o1/requests/$REQUEST_ID \ - カスタムタスク ID。単一のユーザーアカウント内で一意である必要があります。 + カスタムタスク ID。単一のユーザーアカウント内で一意である必要があります。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 diff --git a/ja/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx b/ja/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx index a69f9bf8a4..e5139674ea 100644 --- a/ja/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx +++ b/ja/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx @@ -2,12 +2,12 @@ title: "Kling V2.5 Turbo を Comfy Router で使用する" description: "Comfy Router 経由で kling/kling-v2-5-turbo を呼び出します: エンドポイント、リクエストの形状、Router が返すレスポンスについて説明します。" sidebarTitle: "Kling V2.5 Turbo" -translationSourceHash: 1a5ec6e5 +translationSourceHash: 1671e7b6 translationFrom: development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx translationBlockHashes: "_intro": 2495a4d3 "Quick start": dc63b3ac - "Schema": 68d50e72 + "Schema": 3bcb036e "Examples": 8623c725 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-5-turbo/requests/$REQUEST_ID - コールバック通知先アドレス + コールバック通知先アドレス. このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 形式: `uri` @@ -236,7 +236,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-5-turbo/requests/$REQUEST_ID - カスタムタスクID + カスタムタスクID. このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 diff --git a/ja/development/comfy-router/models/kling/kling-v2-6/code.mdx b/ja/development/comfy-router/models/kling/kling-v2-6/code.mdx index 86f2e928dc..a34c0094ab 100644 --- a/ja/development/comfy-router/models/kling/kling-v2-6/code.mdx +++ b/ja/development/comfy-router/models/kling/kling-v2-6/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router で Kling V2.6 を使用する" description: "Comfy Router 経由で kling/kling-v2-6 を呼び出します。endpoint、リクエストの形状、Router が返すレスポンスについて説明します。" sidebarTitle: "Kling V2.6" -translationSourceHash: 1e64e957 +translationSourceHash: c445a7bd translationFrom: development/comfy-router/models/kling/kling-v2-6/code.mdx translationBlockHashes: "_intro": 04868509 "Quick start": 48a3d970 - "Schema": 9d23ff94 + "Schema": a61a551f "Examples": 8623c725 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-6/requests/$REQUEST_ID \ - コールバック通知先アドレス + コールバック通知先アドレス. このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 形式: `uri` @@ -236,7 +236,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-6/requests/$REQUEST_ID \ - カスタムタスク ID + カスタムタスク ID. このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 diff --git a/ja/development/comfy-router/models/kling/kling-v3-omni/code.mdx b/ja/development/comfy-router/models/kling/kling-v3-omni/code.mdx index d6e09f2638..af91731aa1 100644 --- a/ja/development/comfy-router/models/kling/kling-v3-omni/code.mdx +++ b/ja/development/comfy-router/models/kling/kling-v3-omni/code.mdx @@ -2,12 +2,12 @@ title: "Kling V3 Omni を Comfy Router で使用する" description: "Comfy Router 経由で kling/kling-v3-omni を呼び出します: エンドポイント、リクエストの形状、Router が返すレスポンスについて説明します。" sidebarTitle: "Kling V3 Omni" -translationSourceHash: 226ee8a6 +translationSourceHash: 29d1799c translationFrom: development/comfy-router/models/kling/kling-v3-omni/code.mdx translationBlockHashes: "_intro": 98827333 "Quick start": 3a226de2 - "Schema": f9b37353 + "Schema": 68bd0500 "Examples": 6c2642d6 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3-omni/requests/$REQUEST_ID \ - このタスクの結果を受け取るコールバック通知先アドレス。設定すると、タスクのステータスが変化した際にサーバーが能動的に通知します。 + このタスクの結果を受け取るコールバック通知先アドレス。設定すると、タスクのステータスが変化した際にサーバーが能動的に通知します。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 フォーマット: `uri` @@ -188,7 +188,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3-omni/requests/$REQUEST_ID \ - カスタムタスクID。単一のユーザーアカウント内で一意である必要があります。 + カスタムタスクID。単一のユーザーアカウント内で一意である必要があります。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 diff --git a/ja/development/comfy-router/models/kling/kling-v3/code.mdx b/ja/development/comfy-router/models/kling/kling-v3/code.mdx index bd8c4f29cf..dddc96e01c 100644 --- a/ja/development/comfy-router/models/kling/kling-v3/code.mdx +++ b/ja/development/comfy-router/models/kling/kling-v3/code.mdx @@ -2,13 +2,13 @@ title: "Comfy Router で Kling V3 を使用する" description: "Comfy Router 経由で kling/kling-v3 を呼び出します。エンドポイント、リクエスト形状、Router が返すレスポンスについて説明します。" sidebarTitle: "Kling V3" -translationSourceHash: ecfa3f9b +translationSourceHash: e07d4035 translationFrom: development/comfy-router/models/kling/kling-v3/code.mdx translationBlockHashes: "_intro": 74a12e0f "Quick start": 09c0a41a "Serving providers": a8b20c72 - "Schema": 77550c0a + "Schema": 8e8b04e6 "Examples": 8623c725 --- @@ -177,7 +177,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3/requests/$REQUEST_ID \ - コールバック通知先アドレス + コールバック通知先アドレス. このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 形式: `uri` @@ -247,7 +247,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3/requests/$REQUEST_ID \ - カスタムタスクID + カスタムタスクID. このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 diff --git a/ja/development/comfy-router/models/kling/kling-video-o1/code.mdx b/ja/development/comfy-router/models/kling/kling-video-o1/code.mdx index 1bc4fa1c1c..4b2967fcb2 100644 --- a/ja/development/comfy-router/models/kling/kling-video-o1/code.mdx +++ b/ja/development/comfy-router/models/kling/kling-video-o1/code.mdx @@ -2,12 +2,12 @@ title: "Kling Video O1 を Comfy Router で使用する" description: "Comfy Router 経由で kling/kling-video-o1 を呼び出します。エンドポイント、リクエストの形状、Router が返すレスポンスについて説明します。" sidebarTitle: "Kling Video O1" -translationSourceHash: 3c228231 +translationSourceHash: 892ccf77 translationFrom: development/comfy-router/models/kling/kling-video-o1/code.mdx translationBlockHashes: "_intro": a36df86f "Quick start": 2dd48300 - "Schema": 6f4cf55b + "Schema": f693e2ef "Examples": 6c2642d6 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-video-o1/requests/$REQUEST_ID \ - このタスクの結果を受け取るコールバック通知先アドレス。設定すると、タスクのステータスが変化した際にサーバーから能動的に通知されます。 + このタスクの結果を受け取るコールバック通知先アドレス。設定すると、タスクのステータスが変化した際にサーバーから能動的に通知されます。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 形式: `uri` @@ -188,7 +188,7 @@ curl https://api.comfy.org/v2/models/kling/kling-video-o1/requests/$REQUEST_ID \ - カスタムタスクID。1 つのユーザーアカウント内で一意である必要があります。 + カスタムタスクID。1 つのユーザーアカウント内で一意である必要があります。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 diff --git a/ja/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx b/ja/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx index 46daa06fdf..5b92859b1a 100644 --- a/ja/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx +++ b/ja/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router で Videos Avatar Image 2video を使用する" description: "Comfy Router 経由で kling/videos-avatar-image2video を呼び出します: エンドポイント、リクエスト形状、Router が返すレスポンスについて説明します。" sidebarTitle: "Videos Avatar Image 2video" -translationSourceHash: 444b1395 +translationSourceHash: 5181e917 translationFrom: development/comfy-router/models/kling/videos-avatar-image2video/code.mdx translationBlockHashes: "_intro": baca1542 "Quick start": 5605d33f - "Schema": eeb06fe1 + "Schema": 073bf8b2 "Examples": ce6803dd --- @@ -164,13 +164,13 @@ curl https://api.comfy.org/v2/models/kling/videos-avatar-image2video/requests/$R - このタスクの結果を受け取るコールバック通知アドレス。 + このタスクの結果を受け取るコールバック通知アドレス。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 形式: `uri` - カスタムタスク ID。単一のユーザーアカウント内で一意である必要があります。 + カスタムタスク ID。単一のユーザーアカウント内で一意である必要があります。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 diff --git a/ja/development/comfy-router/models/kling/videos-lip-sync/code.mdx b/ja/development/comfy-router/models/kling/videos-lip-sync/code.mdx index 80a7965e28..60019faeb6 100644 --- a/ja/development/comfy-router/models/kling/videos-lip-sync/code.mdx +++ b/ja/development/comfy-router/models/kling/videos-lip-sync/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router で Videos Lip Sync を使う" description: "Comfy Router 経由で kling/videos-lip-sync を呼び出します: エンドポイント、リクエスト形状、Router が返すレスポンスについて。" sidebarTitle: "Videos Lip Sync" -translationSourceHash: ddd2a405 +translationSourceHash: 6103bea9 translationFrom: development/comfy-router/models/kling/videos-lip-sync/code.mdx translationBlockHashes: "_intro": 0477697a "Quick start": e13a4628 - "Schema": 90571e9f + "Schema": 4fb7c777 "Examples": d1dd6ed8 --- @@ -176,7 +176,7 @@ curl https://api.comfy.org/v2/models/kling/videos-lip-sync/requests/$REQUEST_ID ### 入力 - コールバック通知アドレス。タスクのステータスが変更されるとサーバーから通知されます。 + コールバック通知アドレス。タスクのステータスが変更されるとサーバーから通知されます。このフィールドは無視されます。comfy-api が転送前に破棄し、Comfy Router が代わりにポーリングします。 形式: `uri` diff --git a/ja/development/comfy-router/realtime.mdx b/ja/development/comfy-router/realtime.mdx new file mode 100644 index 0000000000..738a85300c --- /dev/null +++ b/ja/development/comfy-router/realtime.mdx @@ -0,0 +1,223 @@ +--- +title: "Comfy Router リアルタイム音声セッション" +sidebarTitle: "リアルタイム音声" +description: "Comfy Router 経由で Grok Voice リアルタイム WebSocket セッションを開きます。エンドポイント、認証、秒単位の料金、セッション制限、発生しうるエラーとクローズコードについて説明します。" +translationSourceHash: e4024a38 +translationFrom: development/comfy-router/realtime.mdx +translationBlockHashes: + "_intro": a85f88e5 + "Endpoint": 2ae36abf + "Authentication": 582120fe + "Connect": b61ae8c6 + "Events": a3ac8c47 + "Pricing": 25d35f6c + "Limits": 85e21dff + "Errors": 3085ba65 + "Next": 3e8c1bd8 +--- +Comfy Routerは、falが提供するxAIのGrok Voiceとのリアルタイムなspeech-to-speechセッションを中継します。Comfy APIキーを使ってRouterへのWebSocketを1本開きます。Routerはアカウントとクレジットを確認し、上流でセッションを開いてから、イベントを双方向に中継します。セッションの秒数に応じて、Comfyのクレジットから支払います。 + +## エンドポイント + +```text +wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime +``` + +リクエストは WebSocket のアップグレードです(`Connection: Upgrade` と `Upgrade: websocket` を伴う `GET`)。それ以外は `426` で拒否されます。 + +## 認証 + +アップグレードリクエストのヘッダーで Comfy APIキーを送信します。`X-API-Key: comfyui-...` または `Authorization: Bearer comfyui-...` のいずれかを使用します。Router はクエリ文字列や WebSocket サブプロトコルからキーを読み取りません。 + + +ブラウザは WebSocket でヘッダーを設定できず、Comfy APIキーがブラウザに到達してはなりません。サーバーからセッションを開き、オーディオを自分でブラウザに中継してください。 + + +## 接続 + +アップグレードが成功したら、xAI が Grok Voice 向けにドキュメント化しているリアルタイムイベントを送受信します。この例では、セッションを設定し、1回のテキストターンを送信して、受信した各イベントタイプを出力します。 + + + +```python Python +# pip install websockets msgpack +import asyncio +import os + +import msgpack +import websockets + +URL = "wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime" + + +async def send(ws, event): + await ws.send(msgpack.packb(event)) + + +async def main(): + async with websockets.connect( + URL, + additional_headers={"X-API-Key": os.environ["COMFY_API_KEY"]}, + ) as ws: + await send(ws, { + "type": "session.update", + "session": { + "voice": "eve", + "instructions": "You are a helpful assistant.", + "turn_detection": {"type": "server_vad"}, + }, + }) + await send(ws, { + "type": "conversation.item.create", + "item": { + "type": "message", + "role": "user", + "content": [{"type": "input_text", "text": "Hello!"}], + }, + }) + await send(ws, {"type": "response.create"}) + + async for message in ws: + if isinstance(message, str): + continue # fal 独自の x-fal-message フレーム + event = msgpack.unpackb(message) + print(event["type"]) + if event["type"] == "response.done": + break + + +asyncio.run(main()) +``` + +```javascript Node.js +// npm install ws @msgpack/msgpack +import WebSocket from "ws"; +import { encode, decode } from "@msgpack/msgpack"; + +const ws = new WebSocket( + "wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime", + { headers: { "X-API-Key": process.env.COMFY_API_KEY } }, +); + +ws.on("unexpected-response", (req, res) => { + // アップグレードが拒否されました。JSON ボディに理由が示されます。 + let body = ""; + res.on("data", (chunk) => (body += chunk)); + res.on("end", () => console.error(res.statusCode, body)); +}); + +const send = (event) => ws.send(encode(event)); + +ws.on("open", () => { + send({ + type: "session.update", + session: { + voice: "eve", + instructions: "You are a helpful assistant.", + turn_detection: { type: "server_vad" }, + }, + }); + send({ + type: "conversation.item.create", + item: { + type: "message", + role: "user", + content: [{ type: "input_text", text: "Hello!" }], + }, + }); + send({ type: "response.create" }); +}); + +ws.on("message", (data, isBinary) => { + if (!isBinary) return; // fal 独自の x-fal-message フレーム + const event = decode(data); + console.log(event.type); + if (event.type === "response.done") ws.close(); +}); + +ws.on("close", (code) => console.log("closed", code)); +``` + + + +終わったらすぐにソケットを閉じてください。課金は最後の応答までではなく、セッションが閉じるまで発生します。 + +## イベント + +Router は独自のイベントプロトコルを定義していません。サーバーイベントは fal が送信したそのままの形で届き、Router が受け付けるクライアントイベントは変更されずに転送されます。イベント一覧、セッションフィールド、音声、オーディオ形式については、以下を参照してください。 + +- [xAI Speech to Speech](https://docs.x.ai/developers/model-capabilities/audio/speech-to-speech) と xAI の [realtime event schema](https://docs.x.ai/voice-realtime.ws.json) +- fal の [Grok Voice realtime モデルページ](https://fal.ai/models/xai/grok-voice/realtime) とその [API ページ](https://fal.ai/models/xai/grok-voice/realtime/api) + +例のように、各クライアントイベントを 1 つの msgpack バイナリメッセージとして送信してください。これは fal の realtime クライアントが使用するフレーミングであり、モデルのイベントも同じ方法で、`session.created` で始まる msgpack バイナリメッセージとして返されます。fal はさらに、タイプ `x-fal-message` の独自の JSON テキストメッセージ(タイミング情報)も送信しますが、これらはスキップしてかまいません。Router のチェックはクライアントイベントを 1 つの JSON テキストメッセージとしても受け付けますが、クライアントで JSON をテスト済みでない限り msgpack を使用してください。 + +Router は転送する前に各クライアントイベントをチェックします。 + +- **イベントタイプ:** `session.update`、`input_audio_buffer.append`、`input_audio_buffer.commit`、`input_audio_buffer.clear`、`conversation.item.create`、`conversation.item.delete`、`conversation.item.truncate`、`response.create`、`response.cancel`、および fal の `x-fal-session.configure`。 +- **モデル:** `session.update` 内の `model` は `grok-voice-latest`、`grok-voice-3.0`、または `grok-voice-2.0` である必要があります。 +- **ツール:** クライアントが実行する関数ツールは許可されます。サーバー側ツール(Web検索、X検索、ファイル検索、MCP)は拒否されます。 +- **メディア:** 画像およびビデオ入力は拒否されます。セッションは音声とテキストのみです。 +- **サイズ:** 1 つのクライアントメッセージは最大 1 MiB です。 + +拒否されたイベントは転送されず、Router はクローズコード `1008` でセッションをクローズします。 + +## 料金 + +セッションの料金は**1秒あたり$0.0011869**です(1分あたり約$0.0712、または1秒あたり0.2504クレジット、1分あたり約15.0クレジット。211クレジット = $1 USDとして)。セッションが開いている間は15秒単位で課金され、最後の端数分は1秒単位で切り上げて課金されます。課金はアップグレードからソケットが閉じるまで、オーディオが流れているかどうかに関係なく行われます。 + +## 制限 + +| 制限 | 値 | +| --- | --- | +| アカウントあたりのセッション数 | 同時に開けるセッションは 1 つです。2 つ目を開こうとすると `429` と `router.realtime.session_already_live` が返されます。 | +| セッションの長さ | 最大 30 分で、接続時点のあなたのクレジット残高で賄える時間を超えることはありません。 | +| セッション中のクレジット | Router は 15 秒ごとに残高を再確認し、次の 1 秒を賄えなくなった時点でセッションを終了します。 | +| 接続レート | 各アップグレードの試行は[呼び出し元ごとのリクエストレート](/ja/development/comfy-router/limitations#リクエストは呼び出し元ごとにレート制限される)にカウントされ、他の Router 呼び出しと共有されます。 | + +セッションが時間制限に達した場合、またはクレジットが不足した場合、接続は close フレームなしで閉じられることがあります(多くの場合、クローズコード `1006` として現れます)。再接続はチャージした後に行うか、より長い時間が必要な場合は新しいセッションを開始してください。 + +## エラー + +### アップグレード前 + +Routerが接続を拒否した場合、プロトコルを切り替える代わりにHTTPステータスとJSONボディで応答します: + +```json +{ + "detail": "Insufficient credits to open a realtime session.", + "error_type": "insufficient_credits", + "code": "router.realtime.insufficient_credits" +} +``` + +`code` で分岐します。`detail` は人向けの情報です。 + +| ステータス | `code` | 原因 | 対処方法 | +| --- | --- | --- | --- | +| `426` | `router.realtime.upgrade_required` | リクエストがWebSocketアップグレードではありませんでした。 | WebSocketクライアントで接続してください。 | +| `401` | `router.realtime.unauthorized` | APIキーが不足しているか無効です。 | `X-API-Key` または `Authorization: Bearer` で有効なキーを送信してください。 | +| `402` | `router.realtime.insufficient_credits` | 残高が少なくとも1秒分のセッションをカバーできません。 | クレジットを追加してから再接続してください。 | +| `402` | `router.realtime.spend_denied` | セッションの請求先となるウォレットに、そのための資金がありません。ボディ内の `denied_reason` と `billed_workspace` がどのウォレットかを示します。 | そのワークスペースにクレジットを追加してから再接続してください。 | +| `403` | `router.realtime.provider_disabled` | ワークスペースのパートナープロバイダーポリシーでは、このプロバイダーは許可されていません。 | ワークスペース管理者に許可を依頼してください。 | +| `404` | `router.realtime.model_not_allowed` | URL内のモデルはリアルタイムでは利用できません。 | URLを確認してください。 | +| `429` | `router.realtime.rate_limited` | リクエストレートを超えました。 | `Retry-After` を待ってから再試行してください。 | +| `429` | `router.realtime.session_already_live` | アカウントでは別のセッションがすでに開いています。 | 先にそれを閉じてください。 | +| `429` | `router.realtime.concurrency_limit` | パートナーモデルの同時呼び出しが多すぎます。 | 同時実行を減らして再試行してください。 | +| `502` | `router.realtime.upstream_refused`, `router.realtime.token_mint_failed` | 上流プロバイダーがセッションを開きませんでした。 | バックオフしながら再試行してください。 | +| `503` | その他の `router.realtime.*` コード | リアルタイムセッションは一時的に利用できません。 | バックオフしながら再試行してください。 | + +### アップグレード後 + +| クローズコード | 意味 | 対処方法 | +| --- | --- | --- | +| `1008` | クライアントイベントが拒否されました([イベント](#イベント) を参照)。 | イベントを修正してください。セッションは終了です。 | +| `1012` | Routerが再起動しています。 | 再接続してください。新しいセッションが開始され、新しいアップグレードから課金されます。 | +| `1006`(クローズフレームなし) | セッションが時間制限に達したか、クレジットが不足したときにクライアントが報告する内容であることがよくあります。ネットワーク切断も同じように見えます。 | クレジットを追加するか、新しいセッションを開始してください。 | + +その他のクローズは fal または xAI からのものです。詳細は [イベント](#イベント) でリンクされているドキュメントを参照してください。 + +## 次のステップ + +- [課金](/ja/development/comfy-router/billing): Router の課金方法と使用量の照合方法。 +- [エラーとリトライ](/ja/development/comfy-router/errors): 他の Router 呼び出しが返すエラーバケット。 +- [機能と制限](/ja/development/comfy-router/limitations): リクエストレートやその他の制限。 diff --git a/ko/development/comfy-router/api.mdx b/ko/development/comfy-router/api.mdx index dfff2eac06..f205d1bf4d 100644 --- a/ko/development/comfy-router/api.mdx +++ b/ko/development/comfy-router/api.mdx @@ -2,7 +2,7 @@ title: "Comfy Router API 개요" sidebarTitle: "개요" description: "Comfy Router API의 작동 방식: 모델 ID당 하나의 라우트이며, 검색, 스키마, 대기 중인 요청, 오류, 결제에 대한 가이드를 제공합니다." -translationSourceHash: dac7e853 +translationSourceHash: cb493feb translationFrom: development/comfy-router/api.mdx --- @@ -45,4 +45,5 @@ translationFrom: development/comfy-router/api.mdx - [빠른 시작](/ko/development/comfy-router/quickstart): 설치, 호출, 이미지 저장. - [모델](/ko/development/comfy-router/models): 카탈로그를 찾아보고 모델별 요청 예시를 확인합니다. - [헤더](/ko/development/comfy-router/headers): 인증, 멱등성, 요청 ID, 재시도 간격 조정. -- [API 레퍼런스](/ko/development/comfy-router/reference): 엔드포인트 파라미터, 스키마, 응답 코드. \ No newline at end of file +- [API 레퍼런스](/ko/development/comfy-router/reference): 엔드포인트 파라미터, 스키마, 응답 코드. +- [실시간 음성](/ko/development/comfy-router/realtime): Grok Voice WebSocket 세션을 열고 초 단위로 과금됩니다. diff --git a/ko/development/comfy-router/limitations.mdx b/ko/development/comfy-router/limitations.mdx index 5fd22da5b6..c5500205f3 100644 --- a/ko/development/comfy-router/limitations.mdx +++ b/ko/development/comfy-router/limitations.mdx @@ -2,7 +2,7 @@ title: "Comfy Router 기능과 한계" sidebarTitle: "기능과 한계" description: "Comfy Router 또는 파트너 프록시 선택, 장시간 실행되는 호출 대비, 복구, 속도 제한 및 자산 저장에 대해 설명합니다." -translationSourceHash: 235802c5 +translationSourceHash: 91b99a79 translationFrom: development/comfy-router/limitations.mdx translationBlockHashes: "_intro": 6b871cf3 @@ -14,7 +14,7 @@ translationBlockHashes: "Requests are rate limited per caller": 249d4d51 "No progress while a call runs": 75d42d8d "Comfy charges and usage": cf6e2050 - "Models without a pre-flight estimate": 495bdb2b + "Models without a pre-flight estimate": dcd4dce1 "Router does not cover every partner operation": 786c0fb2 "Model outputs and stored assets": 06c737c1 "Next": be85b789 @@ -122,7 +122,6 @@ Router는 아직 아래 모델에 대한 호출 비용을 실행 전에 안정 - **heygen**: `heygen/starfish` - **ideogram**: `ideogram/ideogram-v3`, `ideogram/ideogram-v4`, `ideogram/p-image-ideogram` - **kling**: `kling/kling-3.0-turbo`, `kling/kling-image-o1`, `kling/kling-v2-5-turbo`, `kling/kling-v2-6`, `kling/kling-v3`, `kling/kling-v3-omni`, `kling/kling-video-o1`, `kling/videos-avatar-image2video`, `kling/videos-lip-sync`, `kling/videos-video-extend` -- **luma**: `luma/photon-1`, `luma/photon-flash-1` - **meshy**: `meshy/animations`, `meshy/meshy-6`, `meshy/meshy-7`, `meshy/meshy-7.1`, `meshy/remesh`, `meshy/rigging` - **moonvalley**: `moonvalley/image-to-video`, `moonvalley/text-to-video`, `moonvalley/video-to-video` - **openai**: `openai/gpt-image-1.5` diff --git a/ko/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx b/ko/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx index fb407ea5de..b4f253ad71 100644 --- a/ko/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx +++ b/ko/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx @@ -2,13 +2,13 @@ title: "Comfy Router로 Kling 3.0 Turbo 사용하기" description: "Comfy Router를 통해 kling/kling-3.0-turbo를 호출합니다. 엔드포인트, 요청 형태, Router가 반환하는 응답을 설명합니다." sidebarTitle: "Kling 3.0 Turbo" -translationSourceHash: 301a1ee1 +translationSourceHash: d03a4ba5 translationFrom: development/comfy-router/models/kling/kling-3-0-turbo/code.mdx translationBlockHashes: "_intro": 5a8c5f4b "Quick start": a2145573 "Serving providers": 7ec93d4f - "Schema": 1f5f61c1 + "Schema": 4ec53894 "Examples": 0a9a8bbe --- @@ -195,11 +195,11 @@ curl https://api.comfy.org/v2/models/kling/kling-3.0-turbo/requests/$REQUEST_ID - 작업 결과에 대한 콜백 알림 URL입니다. 작업 상태가 변경되면 서버가 알림을 보냅니다. + 작업 결과에 대한 콜백 알림 URL입니다. 작업 상태가 변경되면 서버가 알림을 보냅니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. - 사용자 지정 작업 ID입니다. 시스템이 생성한 작업 ID를 덮어쓰지는 않지만 조회에 사용할 수 있습니다. 단일 사용자 계정 내에서 고유해야 합니다. + 사용자 지정 작업 ID입니다. 시스템이 생성한 작업 ID를 덮어쓰지는 않지만 조회에 사용할 수 있습니다. 단일 사용자 계정 내에서 고유해야 합니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. diff --git a/ko/development/comfy-router/models/kling/kling-image-o1/code.mdx b/ko/development/comfy-router/models/kling/kling-image-o1/code.mdx index 85e9483b17..a5d2c965e0 100644 --- a/ko/development/comfy-router/models/kling/kling-image-o1/code.mdx +++ b/ko/development/comfy-router/models/kling/kling-image-o1/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router와 함께 Kling Image O1 사용하기" description: "Comfy Router를 통해 kling/kling-image-o1 호출하기: 엔드포인트, 요청 형태, 그리고 Router가 반환하는 응답." sidebarTitle: "Kling Image O1" -translationSourceHash: cf053382 +translationSourceHash: 0d76917c translationFrom: development/comfy-router/models/kling/kling-image-o1/code.mdx translationBlockHashes: "_intro": 513c65df "Quick start": 6256a30d - "Schema": d18a5393 + "Schema": 61821697 "Examples": 826db173 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-image-o1/requests/$REQUEST_ID \ - 이 작업 결과에 대한 콜백 알림 주소입니다. 설정하면 작업 상태가 변경될 때 서버가 능동적으로 알림을 보냅니다. + 이 작업 결과에 대한 콜백 알림 주소입니다. 설정하면 작업 상태가 변경될 때 서버가 능동적으로 알림을 보냅니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. 형식: `uri` @@ -182,7 +182,7 @@ curl https://api.comfy.org/v2/models/kling/kling-image-o1/requests/$REQUEST_ID \ - 사용자 지정 작업 ID입니다. 단일 사용자 계정 내에서 고유해야 합니다. + 사용자 지정 작업 ID입니다. 단일 사용자 계정 내에서 고유해야 합니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. diff --git a/ko/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx b/ko/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx index ac88236104..f3e0deaa44 100644 --- a/ko/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx +++ b/ko/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router로 Kling V2.5 Turbo 사용하기" description: "Comfy Router를 통해 kling/kling-v2-5-turbo를 호출합니다: 엔드포인트, 요청 형태, 그리고 Router가 반환하는 응답." sidebarTitle: "Kling V2.5 Turbo" -translationSourceHash: 1a5ec6e5 +translationSourceHash: 1671e7b6 translationFrom: development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx translationBlockHashes: "_intro": 2495a4d3 "Quick start": dc63b3ac - "Schema": 68d50e72 + "Schema": 3bcb036e "Examples": 8623c725 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-5-turbo/requests/$REQUEST_ID - 콜백 알림 주소 + 콜백 알림 주소. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. 형식: `uri` @@ -236,7 +236,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-5-turbo/requests/$REQUEST_ID - 사용자 정의 Task ID + 사용자 정의 Task ID. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. diff --git a/ko/development/comfy-router/models/kling/kling-v2-6/code.mdx b/ko/development/comfy-router/models/kling/kling-v2-6/code.mdx index 893e68985e..7454cada1d 100644 --- a/ko/development/comfy-router/models/kling/kling-v2-6/code.mdx +++ b/ko/development/comfy-router/models/kling/kling-v2-6/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router로 Kling V2.6 사용하기" description: "Comfy Router를 통해 kling/kling-v2-6을 호출합니다: 엔드포인트, 요청 형태, Router가 반환하는 응답." sidebarTitle: "Kling V2.6" -translationSourceHash: 1e64e957 +translationSourceHash: c445a7bd translationFrom: development/comfy-router/models/kling/kling-v2-6/code.mdx translationBlockHashes: "_intro": 04868509 "Quick start": 48a3d970 - "Schema": 9d23ff94 + "Schema": a61a551f "Examples": 8623c725 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-6/requests/$REQUEST_ID \ - 콜백 알림 주소 + 콜백 알림 주소. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. 형식: `uri` @@ -236,7 +236,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-6/requests/$REQUEST_ID \ - 사용자 정의 작업 ID + 사용자 정의 작업 ID. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. diff --git a/ko/development/comfy-router/models/kling/kling-v3-omni/code.mdx b/ko/development/comfy-router/models/kling/kling-v3-omni/code.mdx index deae7364d7..27f78ccb45 100644 --- a/ko/development/comfy-router/models/kling/kling-v3-omni/code.mdx +++ b/ko/development/comfy-router/models/kling/kling-v3-omni/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router로 Kling V3 Omni 사용하기" description: "Comfy Router를 통해 kling/kling-v3-omni를 호출합니다: endpoint, 요청 형태, 그리고 Router가 반환하는 응답입니다." sidebarTitle: "Kling V3 Omni" -translationSourceHash: 226ee8a6 +translationSourceHash: 29d1799c translationFrom: development/comfy-router/models/kling/kling-v3-omni/code.mdx translationBlockHashes: "_intro": 98827333 "Quick start": 3a226de2 - "Schema": f9b37353 + "Schema": 68bd0500 "Examples": 6c2642d6 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3-omni/requests/$REQUEST_ID \ - 이 작업의 결과에 대한 콜백 알림 주소입니다. 설정하면 작업 상태가 변경될 때 서버가 능동적으로 알림을 보냅니다. + 이 작업의 결과에 대한 콜백 알림 주소입니다. 설정하면 작업 상태가 변경될 때 서버가 능동적으로 알림을 보냅니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. 형식: `uri` @@ -188,7 +188,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3-omni/requests/$REQUEST_ID \ - 사용자 정의 작업 ID입니다. 단일 사용자 계정 내에서 고유해야 합니다. + 사용자 정의 작업 ID입니다. 단일 사용자 계정 내에서 고유해야 합니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. diff --git a/ko/development/comfy-router/models/kling/kling-v3/code.mdx b/ko/development/comfy-router/models/kling/kling-v3/code.mdx index 27d8caab71..ec48fa6aee 100644 --- a/ko/development/comfy-router/models/kling/kling-v3/code.mdx +++ b/ko/development/comfy-router/models/kling/kling-v3/code.mdx @@ -2,13 +2,13 @@ title: "Comfy Router로 Kling V3 사용하기" description: "Comfy Router를 통해 kling/kling-v3 호출하기: endpoint, 요청 형태, 그리고 Router가 반환하는 응답." sidebarTitle: "Kling V3" -translationSourceHash: ecfa3f9b +translationSourceHash: e07d4035 translationFrom: development/comfy-router/models/kling/kling-v3/code.mdx translationBlockHashes: "_intro": 74a12e0f "Quick start": 09c0a41a "Serving providers": a8b20c72 - "Schema": 77550c0a + "Schema": 8e8b04e6 "Examples": 8623c725 --- @@ -177,7 +177,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3/requests/$REQUEST_ID \ - 콜백 알림 주소 + 콜백 알림 주소. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. 형식: `uri` @@ -247,7 +247,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3/requests/$REQUEST_ID \ - 사용자 정의 작업 ID + 사용자 정의 작업 ID. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. diff --git a/ko/development/comfy-router/models/kling/kling-video-o1/code.mdx b/ko/development/comfy-router/models/kling/kling-video-o1/code.mdx index f80a82c880..2e338a51ec 100644 --- a/ko/development/comfy-router/models/kling/kling-video-o1/code.mdx +++ b/ko/development/comfy-router/models/kling/kling-video-o1/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router로 Kling Video O1 사용하기" description: "Comfy Router를 통해 kling/kling-video-o1 호출: endpoint, 요청 형태, 그리고 Router가 반환하는 응답." sidebarTitle: "Kling Video O1" -translationSourceHash: 3c228231 +translationSourceHash: 892ccf77 translationFrom: development/comfy-router/models/kling/kling-video-o1/code.mdx translationBlockHashes: "_intro": a36df86f "Quick start": 2dd48300 - "Schema": 6f4cf55b + "Schema": f693e2ef "Examples": 6c2642d6 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-video-o1/requests/$REQUEST_ID \ - 이 작업 결과에 대한 콜백 알림 주소입니다. 설정하면 작업 상태가 변경될 때 서버가 능동적으로 알림을 보냅니다. + 이 작업 결과에 대한 콜백 알림 주소입니다. 설정하면 작업 상태가 변경될 때 서버가 능동적으로 알림을 보냅니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. 형식: `uri` @@ -188,7 +188,7 @@ curl https://api.comfy.org/v2/models/kling/kling-video-o1/requests/$REQUEST_ID \ - 사용자 정의 작업 ID입니다. 단일 사용자 계정 내에서 고유해야 합니다. + 사용자 정의 작업 ID입니다. 단일 사용자 계정 내에서 고유해야 합니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. diff --git a/ko/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx b/ko/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx index 5e9cf499b4..0d9eca308a 100644 --- a/ko/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx +++ b/ko/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router로 Videos Avatar Image 2video 사용하기" description: "Comfy Router를 통해 kling/videos-avatar-image2video를 호출합니다: 엔드포인트, 요청 형태, Router가 반환하는 응답입니다." sidebarTitle: "Videos Avatar Image 2video" -translationSourceHash: 444b1395 +translationSourceHash: 5181e917 translationFrom: development/comfy-router/models/kling/videos-avatar-image2video/code.mdx translationBlockHashes: "_intro": baca1542 "Quick start": 5605d33f - "Schema": eeb06fe1 + "Schema": 073bf8b2 "Examples": ce6803dd --- @@ -164,13 +164,13 @@ curl https://api.comfy.org/v2/models/kling/videos-avatar-image2video/requests/$R - 이 작업의 결과에 대한 콜백 알림 주소입니다. + 이 작업의 결과에 대한 콜백 알림 주소입니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. 형식: `uri` - 사용자 지정 작업 ID입니다. 단일 사용자 계정 내에서 고유해야 합니다. + 사용자 지정 작업 ID입니다. 단일 사용자 계정 내에서 고유해야 합니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. diff --git a/ko/development/comfy-router/models/kling/videos-lip-sync/code.mdx b/ko/development/comfy-router/models/kling/videos-lip-sync/code.mdx index 8ea8d2d235..0dbe76c2b1 100644 --- a/ko/development/comfy-router/models/kling/videos-lip-sync/code.mdx +++ b/ko/development/comfy-router/models/kling/videos-lip-sync/code.mdx @@ -2,12 +2,12 @@ title: "Comfy Router로 Videos Lip Sync 사용하기" description: "Comfy Router를 통해 kling/videos-lip-sync를 호출합니다. endpoint, 요청 형태, 그리고 Router가 반환하는 응답을 설명합니다." sidebarTitle: "Videos Lip Sync" -translationSourceHash: ddd2a405 +translationSourceHash: 6103bea9 translationFrom: development/comfy-router/models/kling/videos-lip-sync/code.mdx translationBlockHashes: "_intro": 0477697a "Quick start": e13a4628 - "Schema": 90571e9f + "Schema": 4fb7c777 "Examples": d1dd6ed8 --- @@ -176,7 +176,7 @@ curl https://api.comfy.org/v2/models/kling/videos-lip-sync/requests/$REQUEST_ID ### 입력 - 콜백 알림 주소입니다. 작업 상태가 변경되면 서버가 알림을 보냅니다. + 콜백 알림 주소입니다. 작업 상태가 변경되면 서버가 알림을 보냅니다. 이 필드는 무시됩니다. comfy-api가 전달 전에 제거하고 Comfy Router가 대신 폴링합니다. 형식: `uri` diff --git a/ko/development/comfy-router/realtime.mdx b/ko/development/comfy-router/realtime.mdx new file mode 100644 index 0000000000..3619e9e2a0 --- /dev/null +++ b/ko/development/comfy-router/realtime.mdx @@ -0,0 +1,223 @@ +--- +title: "Comfy Router 실시간 음성 세션" +sidebarTitle: "실시간 음성" +description: "Comfy Router를 통해 Grok Voice 실시간 WebSocket 세션을 여는 방법을 설명합니다. 엔드포인트, 인증, 초당 과금, 세션 제한, 그리고 발생할 수 있는 오류와 종료 코드를 다룹니다." +translationSourceHash: e4024a38 +translationFrom: development/comfy-router/realtime.mdx +translationBlockHashes: + "_intro": a85f88e5 + "Endpoint": 2ae36abf + "Authentication": 582120fe + "Connect": b61ae8c6 + "Events": a3ac8c47 + "Pricing": 25d35f6c + "Limits": 85e21dff + "Errors": 3085ba65 + "Next": 3e8c1bd8 +--- +Comfy Router는 fal에서 제공하는 xAI의 Grok Voice와 실시간 음성 대 음성 세션을 중계합니다. Comfy API 키를 사용하여 Router에 WebSocket 하나를 엽니다. Router는 계정과 크레딧을 확인하고 업스트림에서 세션을 연 뒤 이벤트를 양방향으로 중계합니다. 세션 시간 1초당 Comfy 크레딧에서 비용이 차감됩니다. + +## 엔드포인트 + +```text +wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime +``` + +요청은 WebSocket 업그레이드입니다(`Connection: Upgrade` 및 `Upgrade: websocket`을 사용하는 `GET`). 그 밖의 요청은 `426`으로 거부됩니다. + +## 인증 + +업그레이드 요청의 헤더에 `X-API-Key: comfyui-...` 또는 `Authorization: Bearer comfyui-...` 형식으로 Comfy API 키를 보내세요. Router는 쿼리 문자열이나 WebSocket 하위 프로토콜에서 키를 읽지 않습니다. + + +브라우저는 WebSocket에 헤더를 설정할 수 없으며, Comfy API 키는 절대 브라우저에 도달해서는 안 됩니다. 서버에서 세션을 열고 오디오를 브라우저로 직접 중계하세요. + + +## 연결 + +업그레이드가 성공하면 xAI가 Grok Voice용으로 문서화한 실시간 이벤트를 보내고 받으세요. 이 예제는 세션을 구성하고, 텍스트 턴 하나를 보내며, 수신하는 각 이벤트 유형을 출력합니다. + + + +```python Python +# pip install websockets msgpack +import asyncio +import os + +import msgpack +import websockets + +URL = "wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime" + + +async def send(ws, event): + await ws.send(msgpack.packb(event)) + + +async def main(): + async with websockets.connect( + URL, + additional_headers={"X-API-Key": os.environ["COMFY_API_KEY"]}, + ) as ws: + await send(ws, { + "type": "session.update", + "session": { + "voice": "eve", + "instructions": "You are a helpful assistant.", + "turn_detection": {"type": "server_vad"}, + }, + }) + await send(ws, { + "type": "conversation.item.create", + "item": { + "type": "message", + "role": "user", + "content": [{"type": "input_text", "text": "Hello!"}], + }, + }) + await send(ws, {"type": "response.create"}) + + async for message in ws: + if isinstance(message, str): + continue # fal 자체의 x-fal-message 프레임 + event = msgpack.unpackb(message) + print(event["type"]) + if event["type"] == "response.done": + break + + +asyncio.run(main()) +``` + +```javascript Node.js +// npm install ws @msgpack/msgpack +import WebSocket from "ws"; +import { encode, decode } from "@msgpack/msgpack"; + +const ws = new WebSocket( + "wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime", + { headers: { "X-API-Key": process.env.COMFY_API_KEY } }, +); + +ws.on("unexpected-response", (req, res) => { + // 업그레이드가 거부되었습니다. JSON 본문이 이유를 알려줍니다. + let body = ""; + res.on("data", (chunk) => (body += chunk)); + res.on("end", () => console.error(res.statusCode, body)); +}); + +const send = (event) => ws.send(encode(event)); + +ws.on("open", () => { + send({ + type: "session.update", + session: { + voice: "eve", + instructions: "You are a helpful assistant.", + turn_detection: { type: "server_vad" }, + }, + }); + send({ + type: "conversation.item.create", + item: { + type: "message", + role: "user", + content: [{ type: "input_text", text: "Hello!" }], + }, + }); + send({ type: "response.create" }); +}); + +ws.on("message", (data, isBinary) => { + if (!isBinary) return; // fal 자체의 x-fal-message 프레임 + const event = decode(data); + console.log(event.type); + if (event.type === "response.done") ws.close(); +}); + +ws.on("close", (code) => console.log("closed", code)); +``` + + + +작업이 끝나면 즉시 소켓을 닫으세요. 마지막 응답이 아니라 세션이 닫힐 때까지 과금됩니다. + +## 이벤트 + +Router는 자체 이벤트 프로토콜을 정의하지 않습니다. 서버 이벤트는 fal이 보내는 그대로 도달하며, Router가 허용하는 클라이언트 이벤트는 변경 없이 전달됩니다. 이벤트 목록, 세션 필드, 음성, 오디오 형식은 다음을 참조하세요. + +- [xAI Speech to Speech](https://docs.x.ai/developers/model-capabilities/audio/speech-to-speech) 및 xAI의 [실시간 이벤트 스키마](https://docs.x.ai/voice-realtime.ws.json) +- fal의 [Grok Voice 실시간 모델 페이지](https://fal.ai/models/xai/grok-voice/realtime) 및 [API 페이지](https://fal.ai/models/xai/grok-voice/realtime/api) + +예제에서처럼 각 클라이언트 이벤트를 하나의 msgpack 바이너리 메시지로 보내세요. 이는 fal의 실시간 클라이언트가 사용하는 프레이밍 방식이며, 모델의 이벤트도 `session.created`로 시작하는 msgpack 바이너리 메시지로 같은 방식으로 돌아옵니다. fal은 유형이 `x-fal-message`인 자체 JSON 텍스트 메시지(타이밍 정보)도 보내는데, 이는 건너뛰어도 됩니다. Router의 검사에서는 클라이언트 이벤트를 하나의 JSON 텍스트 메시지로도 허용하지만, 클라이언트에서 JSON을 테스트해 보지 않았다면 msgpack을 사용하세요. + +Router는 전달하기 전에 각 클라이언트 이벤트를 검사합니다. + +- **이벤트 유형:** `session.update`, `input_audio_buffer.append`, `input_audio_buffer.commit`, `input_audio_buffer.clear`, `conversation.item.create`, `conversation.item.delete`, `conversation.item.truncate`, `response.create`, `response.cancel`, 및 fal의 `x-fal-session.configure`. +- **모델:** `session.update`의 `model`은 `grok-voice-latest`, `grok-voice-3.0`, `grok-voice-2.0` 중 하나여야 합니다. +- **도구:** 클라이언트가 실행하는 함수 도구는 허용됩니다. 서버 측 도구(웹 검색, X 검색, 파일 검색, MCP)는 거부됩니다. +- **미디어:** 이미지 및 비디오 입력은 거부됩니다. 세션은 음성과 텍스트만 지원합니다. +- **크기:** 클라이언트 메시지 하나는 최대 1 MiB까지 허용됩니다. + +거부된 이벤트는 전달되지 않으며, Router는 종료 코드 `1008`로 세션을 닫습니다. + +## 요금 + +세션 요금은 **초당 $0.0011869**입니다(분당 약 $0.0712, 초당 0.2504 크레딧, 분당 약 15.0 크레딧, 211 크레딧 = 1 USD 기준). 세션이 열려 있는 동안 15초 증가 단위로 청구되며, 마지막 부분 증가분은 초 단위로 올림하여 청구됩니다. 청구는 업그레이드 시점부터 소켓이 닫힐 때까지 진행되며, 오디오가 흐르는지 여부와 관계없습니다. + +## 제한 사항 + +| 제한 | 값 | +| --- | --- | +| 계정당 세션 | 한 번에 하나의 세션만 열 수 있습니다. 두 번째 세션을 열면 `429`와 함께 `router.realtime.session_already_live`가 반환됩니다. | +| 세션 길이 | 최대 30분이며, 연결 시점의 보유 크레딧 잔액이 감당할 수 있는 시간을 초과할 수 없습니다. | +| 세션 중 크레딧 | Router는 15초마다 잔액을 다시 확인하고, 잔액이 다음 1초를 감당할 수 없게 되면 세션을 종료합니다. | +| 연결 속도 | 각 업그레이드 시도는 다른 Router 호출과 공유되는 [호출자별 요청 속도](/ko/development/comfy-router/limitations#요청은-호출자별로-속도-제한됩니다)에 포함됩니다. | + +세션이 시간 제한에 도달하거나 크레딧이 소진되면, close frame 없이 연결이 종료될 수 있습니다(흔히 close code `1006`으로 표시됩니다). 잔액을 충전한 이후에만 다시 연결하고, 더 많은 시간이 필요하면 새 세션을 시작하세요. + +## 오류 + +### 업그레이드 이전 + +Router가 연결을 거부하면 프로토콜을 전환하는 대신 HTTP 상태와 JSON 본문으로 응답합니다: + +```json +{ + "detail": "Insufficient credits to open a realtime session.", + "error_type": "insufficient_credits", + "code": "router.realtime.insufficient_credits" +} +``` + +분기는 `code`를 기준으로 하세요. `detail`은 사람이 읽기 위한 것입니다. + +| 상태 | `code` | 원인 | 해결 방법 | +| --- | --- | --- | --- | +| `426` | `router.realtime.upgrade_required` | 요청이 WebSocket 업그레이드가 아니었습니다. | WebSocket 클라이언트로 연결하세요. | +| `401` | `router.realtime.unauthorized` | API 키가 누락되었거나 유효하지 않습니다. | `X-API-Key` 또는 `Authorization: Bearer`에 유효한 키를 보내세요. | +| `402` | `router.realtime.insufficient_credits` | 잔액으로 최소 1초의 세션도 감당할 수 없습니다. | 크레딧을 추가한 뒤 다시 연결하세요. | +| `402` | `router.realtime.spend_denied` | 세션 요금이 청구될 지갑에 자금이 없습니다. 본문의 `denied_reason`과 `billed_workspace`가 어느 지갑인지 알려줍니다. | 해당 워크스페이스에 크레딧을 추가한 뒤 다시 연결하세요. | +| `403` | `router.realtime.provider_disabled` | 워크스페이스의 파트너 공급자 정책이 이 공급자를 허용하지 않습니다. | 워크스페이스 관리자에게 허용을 요청하세요. | +| `404` | `router.realtime.model_not_allowed` | URL의 모델은 realtime에 사용할 수 없습니다. | URL을 확인하세요. | +| `429` | `router.realtime.rate_limited` | 요청 속도 한도를 초과했습니다. | `Retry-After`만큼 기다린 뒤 다시 시도하세요. | +| `429` | `router.realtime.session_already_live` | 계정에 이미 다른 세션이 열려 있습니다. | 먼저 해당 세션을 닫으세요. | +| `429` | `router.realtime.concurrency_limit` | 동시 파트너 모델 호출이 너무 많습니다. | 동시 작업을 줄이고 다시 시도하세요. | +| `502` | `router.realtime.upstream_refused`, `router.realtime.token_mint_failed` | 업스트림 공급자가 세션을 열지 못했습니다. | 백오프를 두고 다시 시도하세요. | +| `503` | 그 외 다른 `router.realtime.*` 코드 | Realtime 세션을 일시적으로 사용할 수 없습니다. | 백오프를 두고 다시 시도하세요. | + +### 업그레이드 이후 + +| 종료 코드 | 의미 | 해결 방법 | +| --- | --- | --- | +| `1008` | 클라이언트 이벤트가 거부되었습니다([이벤트](#이벤트) 참조). | 이벤트를 수정하세요. 세션은 종료됩니다. | +| `1012` | Router가 재시작 중입니다. | 다시 연결하세요. 새 세션이 시작되며 새 업그레이드 시점부터 과금됩니다. | +| `1006` (종료 프레임 없음) | 세션이 시간 제한에 도달했거나 크레딧이 소진되었을 때 클라이언트가 흔히 보고하는 값입니다. 네트워크 끊김도 동일하게 보입니다. | 크레딧을 추가하거나 새 세션을 시작하세요. | + +그 외의 종료는 fal 또는 xAI에서 발생합니다. [이벤트](#이벤트) 아래에 링크된 해당 문서를 참조하세요. + +## 다음 + +- [청구](/ko/development/comfy-router/billing): Router가 요금을 청구하는 방식과 사용량을 확인하는 방법입니다. +- [오류 및 재시도](/ko/development/comfy-router/errors): 다른 Router 호출이 반환하는 오류 유형입니다. +- [기능과 한계](/ko/development/comfy-router/limitations): 요청 속도 및 기타 제한 사항입니다. diff --git a/zh/development/comfy-router/api.mdx b/zh/development/comfy-router/api.mdx index 63a66aff1a..32a3545b2e 100644 --- a/zh/development/comfy-router/api.mdx +++ b/zh/development/comfy-router/api.mdx @@ -2,7 +2,7 @@ title: "Comfy Router API 概览" sidebarTitle: "概览" description: "Comfy Router API 的工作方式:每个模型 ID 对应一个路由,并提供关于发现模型、schema、排队请求、错误和计费的指南。" -translationSourceHash: dac7e853 +translationSourceHash: cb493feb translationFrom: development/comfy-router/api.mdx --- @@ -45,4 +45,5 @@ translationFrom: development/comfy-router/api.mdx - [快速开始](/zh/development/comfy-router/quickstart):安装、调用以及保存图像。 - [模型](/zh/development/comfy-router/models):浏览目录并查看各模型专属的请求示例。 - [请求头](/zh/development/comfy-router/headers):身份验证、幂等性、请求 ID 以及重试节奏。 -- [API 参考](/zh/development/comfy-router/reference):端点参数、schema 以及响应码。 \ No newline at end of file +- [API 参考](/zh/development/comfy-router/reference):端点参数、schema 以及响应码。 +- [实时语音](/zh/development/comfy-router/realtime):打开 Grok Voice WebSocket 会话,按秒计费。 diff --git a/zh/development/comfy-router/limitations.mdx b/zh/development/comfy-router/limitations.mdx index f580a19c68..c46e2beedb 100644 --- a/zh/development/comfy-router/limitations.mdx +++ b/zh/development/comfy-router/limitations.mdx @@ -2,7 +2,7 @@ title: "Comfy Router 的能力与限制" sidebarTitle: "能力与限制" description: "选择 Comfy Router 还是合作伙伴代理,为长时间运行的调用做好规划,并了解恢复、速率限制与资产存储。" -translationSourceHash: 235802c5 +translationSourceHash: 91b99a79 translationFrom: development/comfy-router/limitations.mdx translationBlockHashes: "_intro": 6b871cf3 @@ -14,7 +14,7 @@ translationBlockHashes: "Requests are rate limited per caller": 249d4d51 "No progress while a call runs": 75d42d8d "Comfy charges and usage": cf6e2050 - "Models without a pre-flight estimate": 495bdb2b + "Models without a pre-flight estimate": dcd4dce1 "Router does not cover every partner operation": 786c0fb2 "Model outputs and stored assets": 06c737c1 "Next": be85b789 @@ -122,7 +122,6 @@ Router 目前还无法在运行前可靠地为对以下模型的调用定价, - **heygen**: `heygen/starfish` - **ideogram**: `ideogram/ideogram-v3`, `ideogram/ideogram-v4`, `ideogram/p-image-ideogram` - **kling**: `kling/kling-3.0-turbo`, `kling/kling-image-o1`, `kling/kling-v2-5-turbo`, `kling/kling-v2-6`, `kling/kling-v3`, `kling/kling-v3-omni`, `kling/kling-video-o1`, `kling/videos-avatar-image2video`, `kling/videos-lip-sync`, `kling/videos-video-extend` -- **luma**: `luma/photon-1`, `luma/photon-flash-1` - **meshy**: `meshy/animations`, `meshy/meshy-6`, `meshy/meshy-7`, `meshy/meshy-7.1`, `meshy/remesh`, `meshy/rigging` - **moonvalley**: `moonvalley/image-to-video`, `moonvalley/text-to-video`, `moonvalley/video-to-video` - **openai**: `openai/gpt-image-1.5` diff --git a/zh/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx b/zh/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx index 05ce84cd96..50cec705c9 100644 --- a/zh/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx +++ b/zh/development/comfy-router/models/kling/kling-3-0-turbo/code.mdx @@ -2,13 +2,13 @@ title: "通过 Comfy Router 使用 Kling 3.0 Turbo" description: "通过 Comfy Router 调用 kling/kling-3.0-turbo:endpoint、请求结构以及 Router 返回的响应。" sidebarTitle: "Kling 3.0 Turbo" -translationSourceHash: 301a1ee1 +translationSourceHash: d03a4ba5 translationFrom: development/comfy-router/models/kling/kling-3-0-turbo/code.mdx translationBlockHashes: "_intro": 5a8c5f4b "Quick start": a2145573 "Serving providers": 7ec93d4f - "Schema": 1f5f61c1 + "Schema": 4ec53894 "Examples": 0a9a8bbe --- @@ -195,11 +195,11 @@ curl https://api.comfy.org/v2/models/kling/kling-3.0-turbo/requests/$REQUEST_ID - 任务结果回调通知 URL。当任务状态发生变化时,服务器会发送通知。 + 任务结果回调通知 URL。当任务状态发生变化时,服务器会发送通知。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 - 自定义任务 ID。不会覆盖系统生成的任务 ID,但可用于查询。在单个用户账号内必须唯一。 + 自定义任务 ID。不会覆盖系统生成的任务 ID,但可用于查询。在单个用户账号内必须唯一。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 diff --git a/zh/development/comfy-router/models/kling/kling-image-o1/code.mdx b/zh/development/comfy-router/models/kling/kling-image-o1/code.mdx index e3731aac5b..b44c2ee9f0 100644 --- a/zh/development/comfy-router/models/kling/kling-image-o1/code.mdx +++ b/zh/development/comfy-router/models/kling/kling-image-o1/code.mdx @@ -2,12 +2,12 @@ title: "使用 Comfy Router 调用 Kling Image O1" description: "通过 Comfy Router 调用 kling/kling-image-o1:端点、请求结构以及 Router 返回的响应。" sidebarTitle: "Kling Image O1" -translationSourceHash: cf053382 +translationSourceHash: 0d76917c translationFrom: development/comfy-router/models/kling/kling-image-o1/code.mdx translationBlockHashes: "_intro": 513c65df "Quick start": 6256a30d - "Schema": d18a5393 + "Schema": 61821697 "Examples": 826db173 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-image-o1/requests/$REQUEST_ID \ - 此任务结果的回调通知地址。若已配置,任务状态发生变化时服务器会主动通知。 + 此任务结果的回调通知地址。若已配置,任务状态发生变化时服务器会主动通知。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 格式:`uri` @@ -182,7 +182,7 @@ curl https://api.comfy.org/v2/models/kling/kling-image-o1/requests/$REQUEST_ID \ - 自定义任务 ID。在单个用户账户内必须唯一。 + 自定义任务 ID。在单个用户账户内必须唯一。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 diff --git a/zh/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx b/zh/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx index 711df496fd..acef580a58 100644 --- a/zh/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx +++ b/zh/development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx @@ -2,12 +2,12 @@ title: "将 Kling V2.5 Turbo 与 Comfy Router 搭配使用" description: "通过 Comfy Router 调用 kling/kling-v2-5-turbo:端点、请求结构以及 Router 返回的响应。" sidebarTitle: "Kling V2.5 Turbo" -translationSourceHash: 1a5ec6e5 +translationSourceHash: 1671e7b6 translationFrom: development/comfy-router/models/kling/kling-v2-5-turbo/code.mdx translationBlockHashes: "_intro": 2495a4d3 "Quick start": dc63b3ac - "Schema": 68d50e72 + "Schema": 3bcb036e "Examples": 8623c725 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-5-turbo/requests/$REQUEST_ID - 回调通知地址 + 回调通知地址。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 格式:`uri` @@ -236,7 +236,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-5-turbo/requests/$REQUEST_ID - 自定义任务 ID + 自定义任务 ID。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 diff --git a/zh/development/comfy-router/models/kling/kling-v2-6/code.mdx b/zh/development/comfy-router/models/kling/kling-v2-6/code.mdx index ccfd89e64f..3432320c0c 100644 --- a/zh/development/comfy-router/models/kling/kling-v2-6/code.mdx +++ b/zh/development/comfy-router/models/kling/kling-v2-6/code.mdx @@ -2,12 +2,12 @@ title: "通过 Comfy Router 使用 Kling V2.6" description: "通过 Comfy Router 调用 kling/kling-v2-6:端点、请求形状以及 Router 返回的响应。" sidebarTitle: "Kling V2.6" -translationSourceHash: 1e64e957 +translationSourceHash: c445a7bd translationFrom: development/comfy-router/models/kling/kling-v2-6/code.mdx translationBlockHashes: "_intro": 04868509 "Quick start": 48a3d970 - "Schema": 9d23ff94 + "Schema": a61a551f "Examples": 8623c725 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-6/requests/$REQUEST_ID \ - 回调通知地址 + 回调通知地址。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 格式:`uri` @@ -236,7 +236,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v2-6/requests/$REQUEST_ID \ - 自定义任务 ID + 自定义任务 ID。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 diff --git a/zh/development/comfy-router/models/kling/kling-v3-omni/code.mdx b/zh/development/comfy-router/models/kling/kling-v3-omni/code.mdx index 9bbff5063b..5b1c80edff 100644 --- a/zh/development/comfy-router/models/kling/kling-v3-omni/code.mdx +++ b/zh/development/comfy-router/models/kling/kling-v3-omni/code.mdx @@ -2,12 +2,12 @@ title: "通过 Comfy Router 使用 Kling V3 Omni" description: "通过 Comfy Router 调用 kling/kling-v3-omni:端点、请求结构以及 Router 返回的响应。" sidebarTitle: "Kling V3 Omni" -translationSourceHash: 226ee8a6 +translationSourceHash: 29d1799c translationFrom: development/comfy-router/models/kling/kling-v3-omni/code.mdx translationBlockHashes: "_intro": 98827333 "Quick start": 3a226de2 - "Schema": f9b37353 + "Schema": 68bd0500 "Examples": 6c2642d6 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3-omni/requests/$REQUEST_ID \ - 本任务结果的回调通知地址。若配置此项,任务状态发生变化时服务器将主动通知。 + 本任务结果的回调通知地址。若配置此项,任务状态发生变化时服务器将主动通知。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 格式:`uri` @@ -188,7 +188,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3-omni/requests/$REQUEST_ID \ - 自定义任务 ID。在单个用户账号内必须唯一。 + 自定义任务 ID。在单个用户账号内必须唯一。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 diff --git a/zh/development/comfy-router/models/kling/kling-v3/code.mdx b/zh/development/comfy-router/models/kling/kling-v3/code.mdx index 614cc72b20..5149adbaf2 100644 --- a/zh/development/comfy-router/models/kling/kling-v3/code.mdx +++ b/zh/development/comfy-router/models/kling/kling-v3/code.mdx @@ -2,13 +2,13 @@ title: "通过 Comfy Router 使用 Kling V3" description: "通过 Comfy Router 调用 kling/kling-v3:端点、请求形状以及 Router 返回的响应。" sidebarTitle: "Kling V3" -translationSourceHash: ecfa3f9b +translationSourceHash: e07d4035 translationFrom: development/comfy-router/models/kling/kling-v3/code.mdx translationBlockHashes: "_intro": 74a12e0f "Quick start": 09c0a41a "Serving providers": a8b20c72 - "Schema": 77550c0a + "Schema": 8e8b04e6 "Examples": 8623c725 --- @@ -177,7 +177,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3/requests/$REQUEST_ID \ - 回调通知地址 + 回调通知地址。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 格式:`uri` @@ -247,7 +247,7 @@ curl https://api.comfy.org/v2/models/kling/kling-v3/requests/$REQUEST_ID \ - 自定义任务 ID + 自定义任务 ID。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 diff --git a/zh/development/comfy-router/models/kling/kling-video-o1/code.mdx b/zh/development/comfy-router/models/kling/kling-video-o1/code.mdx index 1fd6d2c0a4..7101575072 100644 --- a/zh/development/comfy-router/models/kling/kling-video-o1/code.mdx +++ b/zh/development/comfy-router/models/kling/kling-video-o1/code.mdx @@ -2,12 +2,12 @@ title: "将 Kling Video O1 与 Comfy Router 配合使用" description: "通过 Comfy Router 调用 kling/kling-video-o1:endpoint、请求结构以及 Router 返回的响应。" sidebarTitle: "Kling Video O1" -translationSourceHash: 3c228231 +translationSourceHash: 892ccf77 translationFrom: development/comfy-router/models/kling/kling-video-o1/code.mdx translationBlockHashes: "_intro": a36df86f "Quick start": 2dd48300 - "Schema": 6f4cf55b + "Schema": f693e2ef "Examples": 6c2642d6 --- @@ -166,7 +166,7 @@ curl https://api.comfy.org/v2/models/kling/kling-video-o1/requests/$REQUEST_ID \ - 本任务结果的回调通知地址。若已配置,任务状态发生变化时服务器会主动通知。 + 本任务结果的回调通知地址。若已配置,任务状态发生变化时服务器会主动通知。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 格式:`uri` @@ -188,7 +188,7 @@ curl https://api.comfy.org/v2/models/kling/kling-video-o1/requests/$REQUEST_ID \ - 自定义任务 ID。在单个用户账号内必须唯一。 + 自定义任务 ID。在单个用户账号内必须唯一。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 diff --git a/zh/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx b/zh/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx index f59763d31c..2148abb492 100644 --- a/zh/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx +++ b/zh/development/comfy-router/models/kling/videos-avatar-image2video/code.mdx @@ -2,12 +2,12 @@ title: "配合 Comfy Router 使用 Videos Avatar Image 2video" description: "通过 Comfy Router 调用 kling/videos-avatar-image2video:端点、请求结构以及 Router 返回的响应。" sidebarTitle: "Videos Avatar Image 2video" -translationSourceHash: 444b1395 +translationSourceHash: 5181e917 translationFrom: development/comfy-router/models/kling/videos-avatar-image2video/code.mdx translationBlockHashes: "_intro": baca1542 "Quick start": 5605d33f - "Schema": eeb06fe1 + "Schema": 073bf8b2 "Examples": ce6803dd --- @@ -164,13 +164,13 @@ curl https://api.comfy.org/v2/models/kling/videos-avatar-image2video/requests/$R - 本任务结果的回调通知地址。 + 本任务结果的回调通知地址。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 格式:`uri` - 自定义任务 ID。在单个用户账户内必须唯一。 + 自定义任务 ID。在单个用户账户内必须唯一。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 diff --git a/zh/development/comfy-router/models/kling/videos-lip-sync/code.mdx b/zh/development/comfy-router/models/kling/videos-lip-sync/code.mdx index de571505d6..7a64d5cb02 100644 --- a/zh/development/comfy-router/models/kling/videos-lip-sync/code.mdx +++ b/zh/development/comfy-router/models/kling/videos-lip-sync/code.mdx @@ -2,12 +2,12 @@ title: "通过 Comfy Router 使用视频唇形同步" description: "通过 Comfy Router 调用 kling/videos-lip-sync:端点、请求结构以及 Router 返回的响应。" sidebarTitle: "视频唇形同步" -translationSourceHash: ddd2a405 +translationSourceHash: 6103bea9 translationFrom: development/comfy-router/models/kling/videos-lip-sync/code.mdx translationBlockHashes: "_intro": 0477697a "Quick start": e13a4628 - "Schema": 90571e9f + "Schema": 4fb7c777 "Examples": d1dd6ed8 --- @@ -176,7 +176,7 @@ curl https://api.comfy.org/v2/models/kling/videos-lip-sync/requests/$REQUEST_ID ### 输入 - 回调通知地址。任务状态发生变化时,服务器会发出通知。 + 回调通知地址。任务状态发生变化时,服务器会发出通知。该字段会被忽略:comfy-api 在转发前会将其丢弃,由 Comfy Router 代为轮询。 格式:`uri` diff --git a/zh/development/comfy-router/realtime.mdx b/zh/development/comfy-router/realtime.mdx new file mode 100644 index 0000000000..22b3285c77 --- /dev/null +++ b/zh/development/comfy-router/realtime.mdx @@ -0,0 +1,223 @@ +--- +title: "Comfy Router 实时语音会话" +sidebarTitle: "实时语音" +description: "通过 Comfy Router 开启 Grok Voice 实时 WebSocket 会话:端点、身份验证、按秒计费、会话限制,以及可能遇到的错误和关闭码。" +translationSourceHash: e4024a38 +translationFrom: development/comfy-router/realtime.mdx +translationBlockHashes: + "_intro": a85f88e5 + "Endpoint": 2ae36abf + "Authentication": 582120fe + "Connect": b61ae8c6 + "Events": a3ac8c47 + "Pricing": 25d35f6c + "Limits": 85e21dff + "Errors": 3085ba65 + "Next": 3e8c1bd8 +--- +Comfy Router 通过 fal 提供的 xAI Grok Voice 中继实时语音到语音会话。你使用自己的 Comfy API 密钥与 Router 建立一个 WebSocket 连接。Router 会校验你的账户与积分,在上游开启会话,随后双向中继事件。会话按秒从你的 Comfy 积分中计费。 + +## 端点 + +```text +wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime +``` + +该请求是一次 WebSocket 升级(使用 `GET`,并带有 `Connection: Upgrade` 和 `Upgrade: websocket`)。其他任何请求都会被拒绝,并返回 `426`。 + +## 身份验证 + +在升级请求的标头中发送你的 Comfy API 密钥,形式为 `X-API-Key: comfyui-...` 或 `Authorization: Bearer comfyui-...`。Router 不会从查询字符串或 WebSocket 子协议中读取密钥。 + + +浏览器无法在 WebSocket 上设置标头,而 Comfy API 密钥绝不应出现在浏览器中。请从你的服务器打开会话,并自行将音频中继到浏览器。 + + +## 连接 + +升级成功后,即可发送和接收 xAI 为 Grok Voice 记录的实时事件。本示例会配置会话、发送一轮文本内容,并打印收到的每个事件类型。 + + + +```python Python +# pip install websockets msgpack +import asyncio +import os + +import msgpack +import websockets + +URL = "wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime" + + +async def send(ws, event): + await ws.send(msgpack.packb(event)) + + +async def main(): + async with websockets.connect( + URL, + additional_headers={"X-API-Key": os.environ["COMFY_API_KEY"]}, + ) as ws: + await send(ws, { + "type": "session.update", + "session": { + "voice": "eve", + "instructions": "You are a helpful assistant.", + "turn_detection": {"type": "server_vad"}, + }, + }) + await send(ws, { + "type": "conversation.item.create", + "item": { + "type": "message", + "role": "user", + "content": [{"type": "input_text", "text": "Hello!"}], + }, + }) + await send(ws, {"type": "response.create"}) + + async for message in ws: + if isinstance(message, str): + continue # fal 自己的 x-fal-message 帧 + event = msgpack.unpackb(message) + print(event["type"]) + if event["type"] == "response.done": + break + + +asyncio.run(main()) +``` + +```javascript Node.js +// npm install ws @msgpack/msgpack +import WebSocket from "ws"; +import { encode, decode } from "@msgpack/msgpack"; + +const ws = new WebSocket( + "wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime", + { headers: { "X-API-Key": process.env.COMFY_API_KEY } }, +); + +ws.on("unexpected-response", (req, res) => { + // 升级被拒绝了。JSON 正文会说明原因。 + let body = ""; + res.on("data", (chunk) => (body += chunk)); + res.on("end", () => console.error(res.statusCode, body)); +}); + +const send = (event) => ws.send(encode(event)); + +ws.on("open", () => { + send({ + type: "session.update", + session: { + voice: "eve", + instructions: "You are a helpful assistant.", + turn_detection: { type: "server_vad" }, + }, + }); + send({ + type: "conversation.item.create", + item: { + type: "message", + role: "user", + content: [{ type: "input_text", text: "Hello!" }], + }, + }); + send({ type: "response.create" }); +}); + +ws.on("message", (data, isBinary) => { + if (!isBinary) return; // fal 自己的 x-fal-message 帧 + const event = decode(data); + console.log(event.type); + if (event.type === "response.done") ws.close(); +}); + +ws.on("close", (code) => console.log("closed", code)); +``` + + + +完成后请立即关闭该套接字。计费会持续到会话关闭,而不是到最后一次响应结束。 + +## 事件 + +Router 并不定义自己的事件协议。服务器事件会完全按照 fal 发送它们的方式到达你这里,而 Router 接受的客户端事件也会原样转发。关于事件列表、会话字段、语音和音频格式,请参阅: + +- [xAI Speech to Speech](https://docs.x.ai/developers/model-capabilities/audio/speech-to-speech) 以及 xAI 的 [realtime 事件 schema](https://docs.x.ai/voice-realtime.ws.json) +- fal 的 [Grok Voice realtime 模型页面](https://fal.ai/models/xai/grok-voice/realtime)及其 [API 页面](https://fal.ai/models/xai/grok-voice/realtime/api) + +请将每个客户端事件作为一条 msgpack 二进制消息发送,如示例所示。这是 fal 的 realtime 客户端所使用的封帧方式,模型的事件也会以同样的方式返回,即以 `session.created` 开头的 msgpack 二进制消息。fal 还会发送自己类型为 `x-fal-message` 的 JSON 文本消息(计时信息);你可以跳过它们。Router 的检查也接受将客户端事件作为一条 JSON 文本消息发送,但除非你已用你的客户端测试过 JSON,否则请使用 msgpack。 + +Router 在转发每个客户端事件之前都会对其进行检查: + +- **事件类型:** `session.update`、`input_audio_buffer.append`、`input_audio_buffer.commit`、`input_audio_buffer.clear`、`conversation.item.create`、`conversation.item.delete`、`conversation.item.truncate`、`response.create`、`response.cancel` 以及 fal 的 `x-fal-session.configure`。 +- **模型:** `session.update` 中的 `model` 必须是 `grok-voice-latest`、`grok-voice-3.0` 或 `grok-voice-2.0`。 +- **工具:** 允许由你的客户端执行的函数工具。服务器端工具(网页搜索、X 搜索、文件搜索和 MCP)会被拒绝。 +- **媒体:** 图像和视频输入会被拒绝。会话仅支持语音和文本。 +- **大小:** 单条客户端消息最大为 1 MiB。 + +被拒绝的事件不会被转发,并且 Router 会以关闭码 `1008` 关闭会话。 + +## 价格 + +一次会话的费用为**每秒 $0.0011869**(约每分钟 $0.0712,或每秒 0.2504 积分、约每分钟 15.0 积分,按 211 积分 = $1 USD 计算)。会话开启期间按 15 秒为单位计费,最后不足一个计费单位的时长按秒计费并向上取整。计费从升级开始,直到 socket 关闭为止,无论音频是否正在传输。 + +## 限制 + +| 限制 | 值 | +| --- | --- | +| 每个账户的会话数 | 同一时间只能有一个打开的会话。打开第二个会话会返回 `429`,并带有 `router.realtime.session_already_live`。 | +| 会话时长 | 最多 30 分钟,且绝不会超过连接时您的积分余额所能覆盖的时长。 | +| 会话期间的积分 | Router 每 15 秒重新检查一次您的余额,当余额不足以覆盖下一秒时就会结束该会话。 | +| 连接速率 | 每次升级尝试都会计入您的[按调用方的请求速率](/zh/development/comfy-router/limitations#请求按调用方进行速率限制),并与您的其他 Router 调用共享该速率。 | + +当会话达到时间上限或积分已用完时,连接可能会在没有关闭帧的情况下关闭(通常表现为关闭代码 `1006`)。请仅在充值之后重新连接,或者如果需要更多时间,请启动一个新的会话。 + +## 错误 + +### 升级之前 + +如果 Router 拒绝连接,它会返回 HTTP 状态码和 JSON 响应体,而不是切换协议: + +```json +{ + "detail": "Insufficient credits to open a realtime session.", + "error_type": "insufficient_credits", + "code": "router.realtime.insufficient_credits" +} +``` + +根据 `code` 判断;`detail` 供人阅读。 + +| 状态码 | `code` | 原因 | 处理方式 | +| --- | --- | --- | --- | +| `426` | `router.realtime.upgrade_required` | 该请求不是 WebSocket 升级请求。 | 使用 WebSocket 客户端连接。 | +| `401` | `router.realtime.unauthorized` | API 密钥缺失或无效。 | 在 `X-API-Key` 或 `Authorization: Bearer` 中发送有效密钥。 | +| `402` | `router.realtime.insufficient_credits` | 你的余额不足以支付至少一秒的会话费用。 | 添加积分,然后重新连接。 | +| `402` | `router.realtime.spend_denied` | 该会话将要扣费的钱包没有足够资金。响应体中的 `denied_reason` 和 `billed_workspace` 会说明是哪个钱包。 | 为该工作区添加积分,然后重新连接。 | +| `403` | `router.realtime.provider_disabled` | 你的工作区的合作伙伴提供商策略不允许使用此提供商。 | 请工作区管理员允许使用它。 | +| `404` | `router.realtime.model_not_allowed` | URL 中的模型不可用于实时会话。 | 检查 URL。 | +| `429` | `router.realtime.rate_limited` | 你超出了请求速率限制。 | 等待 `Retry-After` 指定的时间,然后重试。 | +| `429` | `router.realtime.session_already_live` | 你的账户已打开另一个会话。 | 请先关闭它。 | +| `429` | `router.realtime.concurrency_limit` | 并发合作伙伴模型调用过多。 | 减少并发任务并重试。 | +| `502` | `router.realtime.upstream_refused`、`router.realtime.token_mint_failed` | 上游提供商未能打开会话。 | 使用退避策略重试。 | +| `503` | 其他任意 `router.realtime.*` 代码 | 实时会话暂时不可用。 | 使用退避策略重试。 | + +### 升级之后 + +| 关闭代码 | 含义 | 处理方式 | +| --- | --- | --- | +| `1008` | 客户端事件被拒绝(参见 [Events](#事件))。 | 修正该事件。会话已结束。 | +| `1012` | Router 正在重启。 | 重新连接。将启动新会话,并从新的升级开始计费。 | +| `1006`(无关闭帧) | 通常是会话达到时间限制或积分已用完时客户端报告的状态。网络中断看起来也一样。 | 添加积分或启动新会话。 | + +其他任何关闭代码都来自 fal 或 xAI。请参阅 [Events](#事件) 下链接的文档。 + +## 下一步 + +- [计费](/zh/development/comfy-router/billing):Router 如何收费以及如何核对用量。 +- [错误与重试](/zh/development/comfy-router/errors):其他 Router 调用返回的错误分类。 +- [能力与限制](/zh/development/comfy-router/limitations):请求速率及其他限制。