--- 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가 지원하는 기능과 기한 및 요청 속도 제한. 요금과 결제 옵션.