---
title: "Comfy Router 실시간 음성 세션"
sidebarTitle: "실시간 음성"
description: "Comfy Router를 통해 Grok Voice 실시간 WebSocket 세션을 엽니다. 엔드포인트, 인증, 초당 요금, 세션 제한, 종료 코드를 다룹니다."
translationSourceHash: 2555a808
translationFrom: development/comfy-router/realtime.mdx
translationBlockHashes:
"_intro": c24aeb22
"Authentication": 588d5135
"WebSocket sessions": 9f0733ee
"WebRTC world models": e3d1be35
"Errors": 507d94b1
"Next": aedde44a
---
Most Router 모델은 요청 하나를 받고 완료된 결과를 반환합니다. 반면 실시간 모델은 라이브 세션을 유지합니다. 모델이 실행되는 동안 입력을 보내고, 생성되는 대로 출력을 받습니다. Router는 이들을 두 가지 방식으로 제공합니다:
| 모델 | 기능 | 제공 방식 |
| --- | --- | --- |
| `google/genie-4` | 키와 텍스트로 조작하는 Genie 4 인터랙티브 월드 모델 | WebSocket 세션, `GET /v2/realtime/google/google/genie-4` |
| `xai/grok-voice/realtime` | Grok Voice 음성 대 음성 대화 | WebSocket 세션, `GET /v2/realtime/fal/xai/grok-voice/realtime` |
| `fal-ai/abot-world-0` | 인터랙티브 월드 모델, WebRTC를 통한 비디오 | WebRTC 시그널링, `POST /v2/realtime/wma/fal` |
| `fal-ai/lingbot-world-2` | 인터랙티브 월드 모델, WebRTC를 통한 비디오 | WebRTC 시그널링, `POST /v2/realtime/wma/fal` |
네 모델 모두 **세션 시간 1초 단위**로 과금되며, 다른 Router 호출과 동일한 워크스페이스 크레딧 잔액에서 차감됩니다. 요금은 [Router 가격](/ko/development/comfy-router/pricing)을 참고하세요. 세션을 열려면 크레딧이 충전된 워크스페이스가 필요합니다. 크레딧이 없으면 세션 개설은 `402`로 거부됩니다.
WebSocket 경로는 `/v2/realtime/{provider}/{model}`이며, 여기서 `{provider}`는 해당 모델을 제공하는 브로커이고 `{model}`은 전체 모델 id입니다. Genie 4 경로에 `google`이 두 번 나오는 이유가 여기에 있습니다.
## 인증
실시간 라우트는 다른 Router 호출과 동일한 자격 증명을 사용합니다.
- **서버에서** 전송하는 경우, WebSocket 업그레이드 요청 또는 시그널링 요청에 `X-API-Key: comfyui-...` 또는 `Authorization: Bearer comfyui-...` 형식으로 API 키를 보내세요. API 키는 서버에 보관하고 절대 브라우저로 전달하지 마세요.
- **브라우저에서** 전송하는 경우, WebSocket은 요청 헤더를 설정할 수 없습니다. Comfy 계정에 로그인 완료한 브라우저는 대신 서브프로토콜 제안에서 `comfy-realtime.v1`과 함께 Firebase ID 토큰을 전달합니다:
```js
const ws = new WebSocket(url, ["comfy-realtime.v1", "comfy-bearer." + idToken]);
```
토큰은 만료되지 않은 Firebase ID 토큰이어야 합니다. API 키는 이 방식으로 절대 허용되지 않으며, 자격 증명은 URL 쿼리 문자열로도 절대 허용되지 않습니다. `comfy-realtime.v1` 없이 `comfy-bearer.`를 포함한 제안은 세션이 열리기 이전에 `400`으로 거부됩니다. `comfy-realtime.v1`을 제안하면 서버가 `101` 응답에서 이를 선택합니다.
서브프로토콜 제안은 WebSocket 세션에만 적용됩니다. WebRTC 시그널링은 일반 HTTP이므로, 브라우저는 해당 요청에서 `Authorization: Bearer `을 헤더로 전송합니다.
## WebSocket 세션
`wss://api.comfy.org/v2/realtime/{provider}/{model}`로 WebSocket 업그레이드를 수행하여 세션을 엽니다. Router는 업그레이드를 인증하고, 잔액을 확인하며, 세션이 유지되는 동안 클라이언트와 모델 사이에서 프레임을 중계합니다.
### 세션 규칙
- **워크스페이스당 하나의 활성 WebSocket 세션.** 하나가 활성 상태일 때 두 번째 업그레이드는 `429`와 `code: router.realtime.session_already_live`로 거부됩니다. 다른 세션을 열기 전에 첫 세션을 닫으세요.
- **계량은 첫 프레임과 함께 시작됩니다.** 청구는 최소 1초를 기준으로 초 단위로 이루어집니다. `google/genie-4`의 경우 모델이 첫 프레임을 보낼 때 청구가 시작되며, 첫 20초 이내에 세션이 종료되면 청구되지 않습니다. 20초가 지나도 프레임이 도착하지 않으면 업그레이드가 성공한 시점부터 청구가 계산됩니다. 다른 모델은 `101`부터 청구됩니다.
- **세션이 실행되는 동안 잔액이 다시 확인됩니다.** Router는 세션을 계량하고 15초마다 잔액을 다시 확인합니다. 잔액이 아직 얼마간의 시간을 감당할 수 있다면 세션의 상한이 그에 맞게 단축됩니다(이 경우 Genie 4 세션은 그 상한에서 `1000`으로 종료됩니다). 잔액이 1초도 더 감당할 수 없거나 계정이 차단되면 Router는 close frame 없이 연결을 끊습니다(대부분의 클라이언트는 close code `1006`을 보고합니다). 크레딧이 소진되었다면 재연결 이전에 충전하세요. 세션의 최대 길이도 잔액이 감당할 수 있는 범위로 사전에 단축됩니다.
### Genie 4
`google/genie-4`는 텍스트 프롬프트로부터 상호작용 가능한 월드를 생성하며, 이후 키 입력으로 그 월드를 이동합니다. 이 모델은 **텍스트 프레임만** 받으며, 각 프레임은 `event_type`을 가진 JSON 객체입니다. 바이너리 프레임이나 64 KiB를 넘는 메시지는 세션을 종료합니다.
| `event_type` | 필드 | 비고 |
| --- | --- | --- |
| `world_setup` | `world_prompt: { "text": "..." }` | 첫 번째 이벤트여야 합니다. 프롬프트는 필수이고 비어 있을 수 없으며 최대 8 KiB입니다. 텍스트 전용이므로 `reference_image` 또는 이미지나 비디오 필드는 거부됩니다. 동일한 `world_setup`을 반복하면 무시되며, 다른 프롬프트로 보내면 세션이 종료됩니다. |
| `user_action` | `action`, `input` | `action`은 `key_down`, `key_up`, `key_click` 중 하나입니다. `input`은 아래 열 개 키 중 하나입니다. |
| `input` | `content: [{ "type": "text", "text": "..." }]` | 텍스트로 월드를 조작합니다. 텍스트 파트만 허용되며 각 파트는 최대 8 KiB입니다. |
| `interaction.complete` | 없음 | 세션을 정상적으로 종료합니다. 다른 필드 없이 보내세요. |
`user_action`이 지정할 수 있는 열 개의 키:
| 용도 | 키 |
| --- | --- |
| 이동 | `key_w`, `key_s`, `key_a`, `key_d` |
| 카메라 | `arrow_up`, `arrow_down`, `arrow_left`, `arrow_right` |
| 작업 | `space`, `key_e` |
그 밖의 이벤트 유형, 필드 또는 키, `world_setup` 이전에 보낸 `user_action`이나 `input`, 또는 지속적인 이벤트 폭주(약 120개의 버스트를 넘고 이후 초당 약 60개)는 종료 코드 `1008`(정책 위반)과 함께 세션을 종료합니다. 거부된 메시지의 내용은 모델에 전달되지 않습니다.
모델 자체의 이벤트는 같은 소켓으로 돌아옵니다. 세션은 다음과 같이 종료됩니다.
- 모델의 `interaction.completed` 이벤트 이후, 종료 코드 `1000`으로 종료됩니다.
- 모델의 `error` 이벤트 이후, 공급자의 종료 코드 또는 `1011`로 종료됩니다.
- **120초** 세션 상한에 도달하면(또는 잔액이 그보다 적게 커버한다면 그보다 이르게) 종료 코드 `1000`으로 종료됩니다.
모델 이벤트의 오류 텍스트는 사용자에게 도달하기 전에 일반 메시지로 교체될 수 있습니다.
```python Python
# Python 3.10+
# 설치: python -m pip install "websockets>=13"
# 실행: COMFY_API_KEY=comfyui-... python genie.py
import asyncio
import json
import os
from websockets.asyncio.client import connect
from websockets.exceptions import InvalidStatus
URL = "wss://api.comfy.org/v2/realtime/google/google/genie-4"
async def receive(ws):
async for message in ws:
if isinstance(message, bytes):
print(f"<- {len(message)} bytes")
continue
event = json.loads(message)
print("<-", event.get("event_type"))
async def main():
try:
ws = await connect(
URL,
additional_headers={"X-API-Key": os.environ["COMFY_API_KEY"]},
max_size=None,
)
except InvalidStatus as err:
# 거부된 업그레이드: 본문은 detail, error_type, code가 담긴 JSON입니다.
print(err.response.status_code, err.response.body.decode(errors="replace"))
return
async with ws:
reader = asyncio.create_task(receive(ws))
async def send(event):
await ws.send(json.dumps(event))
await send({
"event_type": "world_setup",
"world_prompt": {"text": "A quiet harbor town at sunset, seen from the docks"},
})
await send({"event_type": "user_action", "action": "key_down", "input": "key_w"})
await asyncio.sleep(2)
await send({"event_type": "user_action", "action": "key_up", "input": "key_w"})
await send({"event_type": "user_action", "action": "key_click", "input": "arrow_left"})
await send({"event_type": "input", "content": [{"type": "text", "text": "Make it start to rain"}]})
await asyncio.sleep(5)
await send({"event_type": "interaction.complete"})
await reader
print("closed:", ws.close_code)
asyncio.run(main())
```
```js Browser
// Comfy 계정으로 로그인 완료한 페이지입니다. getIdToken()은 Firebase 인증
// 호출이며, 토큰은 URL이 아니라 서브프로토콜 제안으로 전달됩니다.
const idToken = await auth.currentUser.getIdToken();
const ws = new WebSocket(
"wss://api.comfy.org/v2/realtime/google/google/genie-4",
["comfy-realtime.v1", "comfy-bearer." + idToken],
);
ws.addEventListener("open", () => {
ws.send(JSON.stringify({
event_type: "world_setup",
world_prompt: { text: "A quiet harbor town at sunset, seen from the docks" },
}));
});
// 지원되는 열 개의 키를 Genie 4 키 이름에 매핑합니다.
const keys = {
KeyW: "key_w", KeyS: "key_s", KeyA: "key_a", KeyD: "key_d",
ArrowUp: "arrow_up", ArrowDown: "arrow_down",
ArrowLeft: "arrow_left", ArrowRight: "arrow_right",
Space: "space", KeyE: "key_e",
};
for (const [type, action] of [["keydown", "key_down"], ["keyup", "key_up"]]) {
window.addEventListener(type, (e) => {
const input = keys[e.code];
if (!input || e.repeat || ws.readyState !== WebSocket.OPEN) return;
ws.send(JSON.stringify({ event_type: "user_action", action, input }));
});
}
ws.addEventListener("message", (e) => {
if (typeof e.data === "string") console.log("<-", JSON.parse(e.data).event_type);
});
ws.addEventListener("close", (e) => console.log("closed", e.code));
```
브라우저 예제는 실제 키를 한 번 누를 때마다 `key_down` 하나와 `key_up` 하나를 보내고 자동 반복은 건너뛰므로, 이벤트 속도 한도 안에 충분히 여유 있게 머뭅니다.
### Grok Voice
`xai/grok-voice/realtime`은 음성 대 음성 대화입니다. 이 세션은 fal의 실시간 wire format을 사용합니다. 각 이벤트를 [MessagePack](https://msgpack.org)으로 인코딩한 바이너리 프레임으로 전송하면, 응답은 MessagePack 바이너리 프레임 또는 JSON 텍스트 프레임으로 도착합니다. 그 안의 이벤트는 xAI의 실시간 음성 이벤트입니다.
다음 클라이언트 이벤트를 보낼 수 있습니다: `session.update`, `x-fal-session.configure`, `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`. 각 이벤트는 문서에 명시된 필드만 담을 수 있습니다.
- 도구는 클라이언트가 실행하는 `function` 도구로 제한됩니다. MCP 서버나 웹 또는 X 검색 같은 서버 측 도구는 거부됩니다.
- 이벤트 내 어디에든 이미지 및 비디오 콘텐츠가 포함되면 거부됩니다.
- `session.model`을 설정하는 경우 `grok-voice-latest`, `grok-voice-3.0` 또는 `grok-voice-2.0` 중 하나여야 합니다.
이러한 규칙을 위반한 메시지는 전달되지 않으며 close code `1008`로 세션을 종료합니다. 세션 최대 시간은 **30분**이며, 잔액이 감당할 수 있는 만큼 미리 단축됩니다. 최대 시간에 도달하면 close frame 없이 연결이 닫힙니다.
Grok Voice 세션 요금은 **초당 $0.0011869**입니다(분당 약 $0.0712, 211 크레딧 = $1 기준으로 초당 약 0.25 크레딧 또는 분당 15 크레딧). 오디오가 흐르는지 여부와 관계없이 소켓이 열려 있는 전체 시간에 대해 과금됩니다.
```js Node
// Node 20+
// 설치: npm install ws @msgpack/msgpack
// 실행: COMFY_API_KEY=comfyui-... node grok-voice.mjs
import { decode, encode } from "@msgpack/msgpack";
import WebSocket from "ws";
const ws = new WebSocket("wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime", {
headers: { "X-API-Key": process.env.COMFY_API_KEY },
});
const send = (event) => ws.send(Buffer.from(encode(event)));
ws.on("unexpected-response", (_req, res) => {
let body = "";
res.on("data", (chunk) => (body += chunk));
res.on("end", () => console.error("refused:", res.statusCode, body));
});
ws.on("open", () => {
send({
type: "session.update",
session: {
voice: "Ara",
instructions: "Answer in one short sentence.",
turn_detection: { type: null },
},
});
send({
type: "conversation.item.create",
item: { type: "message", role: "user", content: [{ type: "input_text", text: "Say hello." }] },
});
send({ type: "response.create" });
});
ws.on("message", (data, isBinary) => {
const event = isBinary ? decode(data) : JSON.parse(data.toString());
console.log("<-", event.type);
if (event.type === "response.done" || event.type === "error") ws.close(1000);
});
ws.on("close", (code) => console.log("closed", code));
```
텍스트 대신 음성을 보내려면 `input_audio_buffer.append`(base64 `audio`)로 오디오를 스트리밍한 다음 `input_audio_buffer.commit`과 `response.create`를 보내세요.
## WebRTC 월드 모델
`fal-ai/abot-world-0`와 `fal-ai/lingbot-world-2`는 WebRTC를 통해 비디오를 스트리밍합니다. 미디어는 **브라우저와 fal 사이를 직접**, 피어 투 피어로 이동합니다. Router는 연결을 설정하는 HTTP 시그널링만 처리하며, fal의 자격 증명을 추가하므로 클라이언트는 자격 증명을 보관하지 않습니다.
모든 시그널링 호출은 Comfy 자격 증명, JSON 본문, 그리고 `x-fal-target-url` 헤더에 실제 목적지를 담아 `https://api.comfy.org/v2/realtime/wma/fal`로 보내는 `POST`입니다. 이는 fal의 JavaScript 클라이언트가 사용하는 프록시 계약이므로, 해당 클라이언트의 프록시 설정을 이 라우트로 지정할 수 있습니다. 다음 목적지만 허용되며, 그 외에는 `400`과 `code: router.realtime.wma_target_rejected`로 거부됩니다:
| `x-fal-target-url` | 본문 | 목적 |
| --- | --- | --- |
| `https://wma.fal.run/ice` | `{"app_id": ""}` | ICE 서버를 가져옵니다. 세션을 열지 않으며 과금되지 않습니다. |
| `https://wma.fal.run/session` | `"app_id": ""` 포함 | 세션을 엽니다. 응답에는 `session_id`가 포함됩니다. |
| `https://wma.fal.run/session/heartbeat` | `{"session_id": ""}` | 세션을 활성 상태로 유지합니다. |
| `https://wma.fal.run/session/close` | `{"session_id": ""}` | 세션을 종료합니다. 동일한 본문으로 `DELETE /v2/realtime/wma/fal`을 호출해도 같은 작업이 수행됩니다. |
본문은 키가 중복되지 않은 최대 64 KiB의 JSON 객체여야 합니다. `app_id`와 `session_id`는 정확히 이 표기로 작성해야 하며, 대소문자가 다르면 `400`과 함께 거부됩니다.
```bash
# 월드 모델용 ICE 서버를 가져옵니다(세션 없음, 과금 없음).
curl -X POST https://api.comfy.org/v2/realtime/wma/fal \
-H "X-API-Key: $COMFY_API_KEY" \
-H "Content-Type: application/json" \
-H "x-fal-target-url: https://wma.fal.run/ice" \
-d '{"app_id": "fal-ai/lingbot-world-2"}'
```
```js
// Comfy 계정으로 로그인한 브라우저에서 하트비트와 종료를 보냅니다.
const signal = (target, body) =>
fetch("https://api.comfy.org/v2/realtime/wma/fal", {
method: "POST",
headers: {
Authorization: `Bearer ${idToken}`,
"Content-Type": "application/json",
"x-fal-target-url": target,
},
body: JSON.stringify(body),
});
const beat = setInterval(
() => signal("https://wma.fal.run/session/heartbeat", { session_id: sessionId }),
5000,
);
// 사용자가 중지하면 피어 연결을 정리한 뒤 세션을 닫습니다.
clearInterval(beat);
peerConnection.close();
const res = await signal("https://wma.fal.run/session/close", { session_id: sessionId });
console.log(await res.json()); // { session_id, closed: true, settled: true | false }
```
### 세션 수명 주기와 과금
- **최대 길이.** 각 세션은 최대 **480초** 동안 실행됩니다.
- **하트비트.** fal 클라이언트가 그러하듯 5초마다 하나씩 보냅니다. Router는 세션당 최대 1초에 하나만 전달합니다. 더 빠른 하트비트는 `429`와 `Retry-After: 1`과 함께 거부됩니다. 하트비트와 종료 요청은 계정이 열었고 아직 닫지 않은 `session_id`에 대해서만 허용되며, 그렇지 않으면 `404`와 `code: router.realtime.wma_session_not_found`로 응답합니다.
- **과금.** 세션은 열린 시점부터 마지막 하트비트 후 5초까지 초 단위로 과금되며, 최대 480초까지입니다. 세션을 닫으면 청구가 즉시 정산됩니다. 하트비트가 15초 넘게 중단된 세션은 자동으로 정산됩니다. 종료 응답의 `settled: false`는 청구가 아직 마무리 중이며 곧 반영된다는 뜻입니다.
- **개설 시 잔액 확인.** Router는 피어 투 피어 세션이 시작된 후에는 중지할 수 없으므로, 세션을 열려면 이 세션의 전체 480초와 워크스페이스에 이미 열려 있는 모든 WebRTC 세션의 전체 길이를 충당할 수 있는 잔액이 필요합니다. 그렇지 않으면 `/session`은 `402`와 `code: router.realtime.insufficient_credits`와 함께 거부됩니다. 이는 예약이 아니라 확인입니다. 세션이 실행되는 동안 다른 지출이 동일한 잔액을 사용할 수 있습니다.
- **동시 세션.** 워크스페이스는 한 번에 **2**개의 WebRTC 월드 모델 세션을 보유할 수 있습니다. 닫힌 세션은 열린 후 약 480초(짧은 정산 기간 포함)까지 슬롯을 유지하므로, 빠르게 닫고 다시 열면 `429`와 `code: router.realtime.concurrency_limit`과 함께 거부될 수 있습니다. 응답에 명시된 `Retry-After`를 기다리세요.
fal 자체가 시그널링 호출에 오류로 응답하면, Router는 fal의 상태 코드와 본문을 변경 없이 그대로 전달합니다.
## 오류
거부된 업그레이드 또는 시그널링 호출은 HTTP 상태와 `detail`, `error_type` 및 이유를 나타내는 `code`를 담은 JSON 본문으로 응답합니다. `detail`이 아니라 `code` 또는 `error_type`을 기준으로 분기하세요. WebSocket 세션이 열린 뒤에는 문제가 종료 코드로 보고됩니다.
| 상태 | `code` | 의미 |
| --- | --- | --- |
| `400` | `router.realtime.subprotocol_required` | `comfy-bearer.` 제안이 `comfy-realtime.v1` 없이 도착했습니다. |
| `401` | | 유효한 자격 증명이 없습니다. |
| `402` | `router.realtime.insufficient_credits` | 워크스페이스 잔액이 세션을 열기에는 너무 부족합니다. |
| `403` | `router.realtime.model_unavailable` | 해당 모델은 계정에서 사용할 수 없습니다. |
| `403` | `router.realtime.account_blocked` | 계정이 차단되었습니다. |
| `404` | `router.realtime.model_not_allowed` | 이 라우트에서는 해당 모델을 제공하지 않습니다. 경로와 모델 id를 확인하세요. |
| `426` | `router.realtime.upgrade_required` | WebSocket 라우트가 일반 HTTP 요청을 받았습니다. 프록시가 `Upgrade` 및 `Connection` 헤더를 제거하지 않는지 확인하세요. |
| `429` | `router.realtime.rate_limited` | 요청이 너무 많거나 공급자가 처리 용량에 도달했습니다. `Retry-After`를 기다리세요. |
| `429` | `router.realtime.session_already_live` | 워크스페이스에 이미 활성 WebSocket 세션이 있습니다. |
| `429` | `router.realtime.concurrency_limit` | 동시 세션이 너무 많습니다. 나중에 다시 시도하세요. |
| `503` | `router.realtime.shutting_down` | 요청을 처리하는 서버가 재시작 중입니다. 다시 시도하세요. |
업그레이드와 `/ice`, `/session` 시그널링 호출은 다른 Router 호출과 동일한 호출자별 [요청 허용량](/ko/development/comfy-router/limitations#요청은-호출자별로-속도-제한됩니다)을 사용합니다.
| 종료 코드 | 의미 |
| --- | --- |
| `1000` | 정상 종료: 모델이 완료되었거나 Genie 4 세션이 한도에 도달했습니다. |
| `1006` | 종료 프레임이 도착하지 않았습니다. Router 측 원인으로는 Grok Voice 세션이 시간 한도에 도달하거나, 크레딧이 소진되거나, 계정이 차단된 경우가 있습니다. 네트워크 끊김이나 프록시 타임아웃도 동일하게 보입니다. Router가 보내는 코드가 아닙니다. 연결이 끊어지면 클라이언트가 이 코드를 보고합니다. |
| `1008` | 클라이언트 메시지가 모델의 규칙을 위반했습니다(위의 각 모델 참조). |
| `1011` | 모델이 오류를 보고했습니다. |
| `1012` | 서버가 재시작 중입니다. 새 세션을 여세요. |
## 다음
Router가 지원하는 기능과 기한 및 요청 속도 제한.
요금과 결제 옵션.