# 에이전트 생성 (/docs/api/agents/createAgent) **POST /v1/accounts/{accountId}/agents** ```json { "operationId": "createAgent", "summary": "에이전트 생성", "description": "`name`만으로 바로 통화 가능한 한국어 실시간 음성 에이전트를 생성합니다. instructions, greeting, model, voice를 생략하면 한국AI통신 기본값이 적용됩니다. API 기본 출력은 GPT Realtime 2.1 mini + Cartesia sonic-3.5 + Minji 음성입니다.", "tags": [ "Agents" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "계정 ID", "example": "AC1a2b3c4d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "example": "고객 지원 에이전트" }, "instructions": { "type": "string", "maxLength": 16000, "example": "예약 요청을 확인하고 필요한 정보를 안내하세요.", "description": "생략하면 한국AI통신의 범용 한국어 음성 에이전트 프롬프트가 적용됩니다." }, "greeting": { "type": "boolean", "default": true, "description": "통화 연결 직후 에이전트가 먼저 인사할지 여부" }, "maxDurationSeconds": { "type": "integer", "nullable": true, "minimum": 10, "maximum": 7200, "example": 600, "description": "최대 통화 시간(초). 통화가 연결된 뒤 이 시간이 지나면 대화 중이어도 통화를 끊습니다. 수신은 받은 순간, 발신은 상대가 받은 순간부터 잽니다. 끊기 전 안내 멘트는 나가지 않습니다. 생략하거나 null 이면 제한 없음입니다." }, "beginMessageDelayMs": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 5000, "example": 800, "description": "첫 인사 전 대기 시간(밀리초). 발신 통화에서 상대가 받은 뒤 이 시간만큼 기다렸다가 첫 인사를 시작합니다. greeting 이 true 일 때만 적용되며, 수신 통화에는 적용되지 않습니다. 생략하면 0(바로 인사)입니다." }, "liveEvents": { "type": "object", "description": "통화 중 이벤트(실시간 전사·키패드) 설정. 받을 이벤트를 `events` 에 고르면 이 에이전트의 통화 이벤트를\n`GET /v1/accounts/{accountId}/calls/{callId}/live-events`(·`/stream`) 로 받습니다. 추가 요금은 없습니다.\n", "required": [ "events" ], "properties": { "events": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "transcript.final", "transcript.partial", "dtmf.received", "dtmf.sent" ] }, "description": "받을 이벤트. 비우면 꺼집니다(새 에이전트 기본값). 수정할 때는 보낸 목록으로 통째로 바뀝니다.\n하나라도 고르면 `stream.started`·`stream.ended` 가 함께 옵니다.\n- `transcript.final`: 한 발화의 확정 텍스트\n- `transcript.partial`: 말하는 도중의 텍스트\n- `dtmf.sent`: AI가 통화 미디어 연결로 보낸 키 하나. 상대 시스템의 수신 완료를 보장하지 않습니다.\n- `dtmf.received`: 상대가 누른 키 하나\n", "example": [ "transcript.final", "dtmf.received" ] } } }, "model": { "type": "string", "enum": [ "gpt-realtime-2.1", "gpt-realtime-2.1-mini" ], "description": "생략하면 gpt-realtime-2.1-mini가 적용됩니다." }, "voice": { "type": "string", "format": "uuid", "description": "Cartesia voice ID. 생략하면 Minji - Modern Communicator (7706804e-ea85-443a-968a-b9bf363bdde8)가 적용됩니다." }, "configuration": { "description": "모델 내장 음성, Realtime + 외부 TTS, STT·LLM·TTS 파이프라인 또는 GPT-Live(전이중)의 전체 실행 설정입니다. 지정하면 model과 voice 단축 필드는 함께 사용할 수 없습니다.", "discriminator": { "propertyName": "outputMode" }, "oneOf": [ { "title": "모델 내장 음성", "type": "object", "additionalProperties": false, "required": [ "outputMode", "llm" ], "properties": { "outputMode": { "type": "string", "enum": [ "realtime_voice" ] }, "language": { "type": "string", "default": "ko" }, "knowledge": { "type": "object", "additionalProperties": false, "required": [ "enabled", "topK" ], "properties": { "enabled": { "type": "boolean" }, "topK": { "type": "integer", "minimum": 1, "maximum": 10 } } }, "llm": { "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "openai-realtime" ] }, "model": { "type": "string", "enum": [ "gpt-realtime-2.1", "gpt-realtime-2.1-mini" ] }, "voice": { "type": "string", "enum": [ "marin", "cedar", "alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse" ] }, "input_audio_noise_reduction": { "type": "string", "description": "실시간 모델이 듣는 입력 오디오의 노이즈 감소. 전화 회선은 `far_field` 를 권합니다.\n생략하면 사용하지 않습니다.\n", "enum": [ "near_field", "far_field" ] }, "input_transcription_model": { "type": "string", "description": "상대방 말을 받아쓰는 모델(입력 전사). 실시간 전사(`liveEvents`)의 상대방 말과 대화 기록에 쓰입니다.\n모델이 대화를 알아듣는 방식에는 영향이 없습니다. 언어는 `language` 를 따릅니다.\n생략하면 `gpt-4o-mini-transcribe` 입니다.\n\n- `gpt-live-transcribe`·`gpt-realtime-whisper`: 상대가 말하는 도중에 글자가 나옵니다.\n- `gpt-transcribe`·`gpt-live-transcribe`: `input_transcription_keywords` 를 받습니다.\n- `whisper-1`·`gpt-4o-mini-transcribe`·`gpt-4o-transcribe`: `input_transcription_prompt` 를 받습니다.\n- `gpt-realtime-whisper`: `input_transcription_delay` 를 받습니다.\n\n고른 모델이 받지 않는 값을 함께 보내면 400 입니다.\n", "enum": [ "gpt-4o-mini-transcribe", "gpt-4o-transcribe", "gpt-transcribe", "gpt-live-transcribe", "gpt-realtime-whisper", "whisper-1" ] }, "input_transcription_prompt": { "type": "string", "description": "받아쓰기 힌트 문장. 통화 상황을 알려 주면 받아쓰기가 정확해집니다(예: `고객센터 자동 안내 멘트입니다.`).\n`whisper-1`·`gpt-4o-mini-transcribe`·`gpt-4o-transcribe` 만 받습니다.\n", "minLength": 1, "maxLength": 1024 }, "input_transcription_keywords": { "type": "string", "description": "받아쓰기 단어 힌트. 쉼표나 줄바꿈으로 구분합니다(예: `상담원 연결, 샵 버튼`). 최대 100개, 각 50자.\n`gpt-transcribe`·`gpt-live-transcribe` 만 받습니다.\n", "minLength": 1 }, "input_transcription_delay": { "type": "string", "description": "받아쓰기 지연. 높일수록 글자가 조금 늦게 나오는 대신 정확해집니다. 생략하면 모델 기본값입니다.\n`gpt-realtime-whisper` 만 받습니다.\n", "enum": [ "minimal", "low", "medium", "high", "xhigh" ] } } }, "vad": { "type": "object", "additionalProperties": false, "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "silero" ] }, "min_silence_duration": { "type": "number", "minimum": 0, "maximum": 3 }, "min_speech_duration": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_duration": { "type": "number", "minimum": 0, "maximum": 2 }, "max_buffered_speech": { "type": "number", "minimum": 1, "maximum": 120 }, "activation_threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "sample_rate": { "type": "integer", "enum": [ 16000, 8000 ] }, "force_cpu": { "type": "boolean" } } }, "session": { "type": "object", "additionalProperties": false, "properties": { "turn_detection": { "type": "string", "enum": [ "vad", "stt" ] }, "allow_interruptions": { "type": "boolean" }, "min_endpointing_delay": { "type": "number", "minimum": 0, "maximum": 5 }, "max_endpointing_delay": { "type": "number", "minimum": 0, "maximum": 15 }, "min_interruption_duration": { "type": "number", "minimum": 0, "maximum": 2 } } } } }, { "title": "Realtime과 외부 TTS", "type": "object", "additionalProperties": false, "required": [ "outputMode", "llm", "tts" ], "properties": { "outputMode": { "type": "string", "enum": [ "external_tts" ] }, "language": { "type": "string", "default": "ko" }, "knowledge": { "type": "object", "additionalProperties": false, "required": [ "enabled", "topK" ], "properties": { "enabled": { "type": "boolean" }, "topK": { "type": "integer", "minimum": 1, "maximum": 10 } } }, "llm": { "type": "object", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "enum": [ "openai-realtime" ] }, "model": { "type": "string", "enum": [ "gpt-realtime-2.1", "gpt-realtime-2.1-mini" ] }, "input_audio_noise_reduction": { "type": "string", "description": "실시간 모델이 듣는 입력 오디오의 노이즈 감소. 전화 회선은 `far_field` 를 권합니다.\n생략하면 사용하지 않습니다.\n", "enum": [ "near_field", "far_field" ] }, "input_transcription_model": { "type": "string", "description": "상대방 말을 받아쓰는 모델(입력 전사). 실시간 전사(`liveEvents`)의 상대방 말과 대화 기록에 쓰입니다.\n모델이 대화를 알아듣는 방식에는 영향이 없습니다. 언어는 `language` 를 따릅니다.\n생략하면 `gpt-4o-mini-transcribe` 입니다.\n\n- `gpt-live-transcribe`·`gpt-realtime-whisper`: 상대가 말하는 도중에 글자가 나옵니다.\n- `gpt-transcribe`·`gpt-live-transcribe`: `input_transcription_keywords` 를 받습니다.\n- `whisper-1`·`gpt-4o-mini-transcribe`·`gpt-4o-transcribe`: `input_transcription_prompt` 를 받습니다.\n- `gpt-realtime-whisper`: `input_transcription_delay` 를 받습니다.\n\n고른 모델이 받지 않는 값을 함께 보내면 400 입니다.\n", "enum": [ "gpt-4o-mini-transcribe", "gpt-4o-transcribe", "gpt-transcribe", "gpt-live-transcribe", "gpt-realtime-whisper", "whisper-1" ] }, "input_transcription_prompt": { "type": "string", "description": "받아쓰기 힌트 문장. 통화 상황을 알려 주면 받아쓰기가 정확해집니다(예: `고객센터 자동 안내 멘트입니다.`).\n`whisper-1`·`gpt-4o-mini-transcribe`·`gpt-4o-transcribe` 만 받습니다.\n", "minLength": 1, "maxLength": 1024 }, "input_transcription_keywords": { "type": "string", "description": "받아쓰기 단어 힌트. 쉼표나 줄바꿈으로 구분합니다(예: `상담원 연결, 샵 버튼`). 최대 100개, 각 50자.\n`gpt-transcribe`·`gpt-live-transcribe` 만 받습니다.\n", "minLength": 1 }, "input_transcription_delay": { "type": "string", "description": "받아쓰기 지연. 높일수록 글자가 조금 늦게 나오는 대신 정확해집니다. 생략하면 모델 기본값입니다.\n`gpt-realtime-whisper` 만 받습니다.\n", "enum": [ "minimal", "low", "medium", "high", "xhigh" ] } } }, "tts": { "discriminator": { "propertyName": "provider" }, "oneOf": [ { "title": "Cartesia", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "cartesia" ] }, "model": { "type": "string", "enum": [ "sonic-3.5", "sonic-3.6" ] }, "voice": { "type": "string", "format": "uuid" }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "speed": { "type": "number", "minimum": 0.6, "maximum": 1.5 }, "volume": { "type": "number", "minimum": 0.5, "maximum": 1.5 } } }, { "title": "xAI", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "xai" ] }, "model": { "type": "string", "enum": [ "tts-1" ] }, "voice": { "type": "string", "minLength": 1 }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." } } }, { "title": "Google", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "google" ] }, "model": { "type": "string", "enum": [ "chirp_3" ] }, "voice": { "type": "string", "description": "Chirp 3 HD 음성명입니다(예 `ko-KR-Chirp3-HD-Aoede`).", "pattern": "^[a-z]{2,3}-[A-Z]{2}-Chirp3-HD-[A-Za-z]+$" }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "speed": { "type": "number", "minimum": 0.6, "maximum": 1.5 } } }, { "title": "ElevenLabs", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "elevenlabs" ] }, "model": { "type": "string", "description": "eleven_flash_v2_5(빠름) 또는 eleven_multilingual_v2(고품질, 글자당 요금 2배)", "enum": [ "eleven_flash_v2_5", "eleven_multilingual_v2" ] }, "voice": { "type": "string", "description": "ElevenLabs 음성 id(20자 영숫자). provider가 elevenlabs인 내 복제 음성도 쓸 수 있습니다.", "pattern": "^[A-Za-z0-9]{20}$" }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2 } } } ] }, "vad": { "type": "object", "additionalProperties": false, "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "silero" ] }, "min_silence_duration": { "type": "number", "minimum": 0, "maximum": 3 }, "min_speech_duration": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_duration": { "type": "number", "minimum": 0, "maximum": 2 }, "max_buffered_speech": { "type": "number", "minimum": 1, "maximum": 120 }, "activation_threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "sample_rate": { "type": "integer", "enum": [ 16000, 8000 ] }, "force_cpu": { "type": "boolean" } } }, "session": { "type": "object", "additionalProperties": false, "properties": { "turn_detection": { "type": "string", "enum": [ "vad", "stt" ] }, "allow_interruptions": { "type": "boolean" }, "min_endpointing_delay": { "type": "number", "minimum": 0, "maximum": 5 }, "max_endpointing_delay": { "type": "number", "minimum": 0, "maximum": 15 }, "min_interruption_duration": { "type": "number", "minimum": 0, "maximum": 2 } } } } }, { "title": "STT·LLM·TTS 파이프라인", "type": "object", "additionalProperties": false, "required": [ "outputMode", "stt", "llm", "tts" ], "properties": { "outputMode": { "type": "string", "enum": [ "pipeline" ] }, "language": { "type": "string", "default": "ko" }, "knowledge": { "type": "object", "additionalProperties": false, "required": [ "enabled", "topK" ], "properties": { "enabled": { "type": "boolean" }, "topK": { "type": "integer", "minimum": 1, "maximum": 10 } } }, "stt": { "type": "object", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "enum": [ "openai" ] }, "model": { "type": "string", "enum": [ "gpt-4o-transcribe", "gpt-4o-mini-transcribe", "whisper-1" ] }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "prompt": { "type": "string" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "detect_language": { "type": "boolean" }, "noise_reduction_type": { "type": "string", "enum": [ "near_field", "far_field" ] }, "use_realtime": { "type": "boolean" } } }, "llm": { "type": "object", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "enum": [ "openai" ] }, "model": { "type": "string", "enum": [ "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.2", "gpt-5.1", "gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "gpt-5 · gpt-5-mini · gpt-5-nano 에서는 지원하지 않습니다(400)." }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "description": "gpt-5 · gpt-5-mini · gpt-5-nano 에서는 지원하지 않습니다(400)." }, "verbosity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "GPT-5 계열 전용입니다. gpt-4.1 · gpt-4o 계열에서는 지원하지 않습니다(400)." }, "max_completion_tokens": { "type": "integer", "minimum": 1 }, "frequency_penalty": { "type": "number", "minimum": -2, "maximum": 2, "description": "gpt-5 · gpt-5-mini · gpt-5-nano · gpt-5.6-luna 에서는 지원하지 않습니다(400)." }, "presence_penalty": { "type": "number", "minimum": -2, "maximum": 2, "description": "gpt-5 · gpt-5-mini · gpt-5-nano · gpt-5.6-luna 에서는 지원하지 않습니다(400)." }, "service_tier": { "type": "string", "enum": [ "auto", "default", "flex", "priority" ], "description": "처리 티어. `flex` 는 gpt-4.1·gpt-4o 계열에서 지원하지 않습니다(400)." }, "parallel_tool_calls": { "type": "boolean" }, "seed": { "type": "integer" } } }, "tts": { "discriminator": { "propertyName": "provider" }, "oneOf": [ { "title": "Cartesia", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "cartesia" ] }, "model": { "type": "string", "enum": [ "sonic-3.5", "sonic-3.6" ] }, "voice": { "type": "string", "format": "uuid" }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "speed": { "type": "number", "minimum": 0.6, "maximum": 1.5 }, "volume": { "type": "number", "minimum": 0.5, "maximum": 1.5 } } }, { "title": "xAI", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "xai" ] }, "model": { "type": "string", "enum": [ "tts-1" ] }, "voice": { "type": "string", "minLength": 1 }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." } } }, { "title": "Google", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "google" ] }, "model": { "type": "string", "enum": [ "chirp_3" ] }, "voice": { "type": "string", "description": "Chirp 3 HD 음성명입니다(예 `ko-KR-Chirp3-HD-Aoede`).", "pattern": "^[a-z]{2,3}-[A-Z]{2}-Chirp3-HD-[A-Za-z]+$" }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "speed": { "type": "number", "minimum": 0.6, "maximum": 1.5 } } }, { "title": "ElevenLabs", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "elevenlabs" ] }, "model": { "type": "string", "description": "eleven_flash_v2_5(빠름) 또는 eleven_multilingual_v2(고품질, 글자당 요금 2배)", "enum": [ "eleven_flash_v2_5", "eleven_multilingual_v2" ] }, "voice": { "type": "string", "description": "ElevenLabs 음성 id(20자 영숫자). provider가 elevenlabs인 내 복제 음성도 쓸 수 있습니다.", "pattern": "^[A-Za-z0-9]{20}$" }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2 } } } ] }, "vad": { "type": "object", "additionalProperties": false, "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "silero" ] }, "min_silence_duration": { "type": "number", "minimum": 0, "maximum": 3 }, "min_speech_duration": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_duration": { "type": "number", "minimum": 0, "maximum": 2 }, "max_buffered_speech": { "type": "number", "minimum": 1, "maximum": 120 }, "activation_threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "sample_rate": { "type": "integer", "enum": [ 16000, 8000 ] }, "force_cpu": { "type": "boolean" } } }, "session": { "type": "object", "additionalProperties": false, "properties": { "turn_detection": { "type": "string", "enum": [ "vad", "stt" ] }, "allow_interruptions": { "type": "boolean" }, "min_endpointing_delay": { "type": "number", "minimum": 0, "maximum": 5 }, "max_endpointing_delay": { "type": "number", "minimum": 0, "maximum": 15 }, "min_interruption_duration": { "type": "number", "minimum": 0, "maximum": 2 } } } } }, { "title": "GPT-Live (전이중)", "description": "듣는 동시에 말하는 전이중(full duplex) 음성 모델입니다. 음성 모델은 대화를 맡고, 조회·도구 실행·통화 종료는 업무 처리 모델이 맡습니다. 음성은 모델이 직접 내므로 외부 TTS·STT를 쓰지 않으며, 끼어들기도 모델이 스스로 판단해 vad·session 설정을 받지 않습니다.", "type": "object", "additionalProperties": false, "required": [ "outputMode", "llm" ], "properties": { "outputMode": { "type": "string", "enum": [ "live" ] }, "language": { "type": "string", "default": "ko" }, "knowledge": { "type": "object", "additionalProperties": false, "required": [ "enabled", "topK" ], "properties": { "enabled": { "type": "boolean" }, "topK": { "type": "integer", "minimum": 1, "maximum": 10 } } }, "llm": { "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "openai-live" ] }, "model": { "type": "string", "enum": [ "gpt-live-1" ] }, "voice": { "type": "string", "description": "GPT-Live 전용 음성 13종과 Realtime 음성 10종을 쓸 수 있습니다.", "enum": [ "quartz", "ripple", "vesper", "willow", "stone", "gleam", "meridian", "bossa", "tempo", "beacon", "delta", "cinder", "noeul", "marin", "cedar", "alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse" ] }, "backend_model": { "type": "string", "enum": [ "gpt-5.6-luna", "gpt-5.6-terra" ], "default": "gpt-5.6-luna", "description": "업무 처리 모델. 조회·도구 실행·복잡한 판단을 맡습니다. 기본은 gpt-5.6-luna이고, 판단이 복잡한 업무라면 gpt-5.6-terra를 쓰십시오." }, "backend_reasoning_effort": { "type": "string", "enum": [ "none", "low", "medium", "high" ], "default": "low", "description": "업무 처리 모델의 추론 강도. 높을수록 정확하지만 답이 늦어집니다." } } } } }, { "title": "Grok Voice (xAI)", "description": "xAI Grok Voice 실시간 음성 모델입니다. 음성은 모델이 직접 내므로 외부 TTS·STT를 쓰지 않으며, 발화 끝 감지와 끼어들기는 xAI 서버가 판단해 vad·session 설정을 받지 않습니다. 요금은 통화가 연결된 시간(초 단위, 말이 없는 시간 포함)과 모델에 넣는 텍스트 입력 건수로 계산됩니다.", "type": "object", "additionalProperties": false, "required": [ "outputMode", "llm" ], "properties": { "outputMode": { "type": "string", "enum": [ "grok" ] }, "language": { "type": "string", "default": "ko" }, "knowledge": { "type": "object", "additionalProperties": false, "required": [ "enabled", "topK" ], "properties": { "enabled": { "type": "boolean" }, "topK": { "type": "integer", "minimum": 1, "maximum": 10 } } }, "llm": { "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "xai-realtime" ] }, "model": { "type": "string", "enum": [ "grok-voice-3.0" ] }, "voice": { "type": "string", "description": "Grok Voice 음성 26종을 쓸 수 있습니다.", "enum": [ "carina", "zagan", "helix", "orion", "luna", "iris", "altair", "zenith", "perseus", "helios", "lux", "kepler", "rigel", "cosmo", "celeste", "ursa", "sirius", "lumen", "castor", "naksh", "atlas", "ara", "eve", "leo", "rex", "sal" ] }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.5, "description": "모델 음성의 재생 속도. 비우면 1.0입니다." }, "reasoning_effort": { "type": "string", "enum": [ "high", "none" ], "description": "none 이면 생각하지 않고 바로 답해 응답이 빨라집니다. 비우면 high입니다. 요금은 같습니다." } } } } }, { "title": "ElevenLabs Realtime", "description": "ElevenLabs 실시간 음성 모델입니다. 음성은 모델이 직접 내므로 외부 TTS·STT를 쓰지 않으며, 발화 끝 감지와 끼어들기는 ElevenLabs 서버가 판단해 vad·session 설정을 받지 않습니다. 요금은 통화가 연결된 시간(초 단위, 말이 없는 시간 포함)과 모델이 처리한 토큰으로 계산됩니다.", "type": "object", "additionalProperties": false, "required": [ "outputMode", "llm" ], "properties": { "outputMode": { "type": "string", "enum": [ "elevenlabs" ] }, "language": { "type": "string", "default": "ko" }, "knowledge": { "type": "object", "additionalProperties": false, "required": [ "enabled", "topK" ], "properties": { "enabled": { "type": "boolean" }, "topK": { "type": "integer", "minimum": 1, "maximum": 10 } } }, "llm": { "type": "object", "additionalProperties": false, "required": [ "provider", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "elevenlabs-realtime" ] }, "model": { "type": "string", "enum": [ "eleven_realtime_v1_max", "eleven_realtime_v1_mini" ], "default": "eleven_realtime_v1_max", "description": "eleven_realtime_v1_max 는 답하기 전에 추론합니다. eleven_realtime_v1_mini 는 토큰 요금이 더 낮습니다." }, "voice": { "type": "string", "pattern": "^[A-Za-z0-9]{20}$", "description": "ElevenLabs 음성 id 입니다. 음성 라이브러리 음성과 내가 복제한 음성을 쓸 수 있습니다." } } } } } ] } } } } } }, "responses": { "201": { "description": "생성 성공", "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "name", "instructions", "greeting", "language", "maxDurationSeconds", "beginMessageDelayMs", "liveEvents", "model", "voice", "voiceProvider", "voiceModel", "configuration", "phoneNumbers", "dateCreated", "dateUpdated" ], "properties": { "agentId": { "type": "string", "example": "cmagent123", "description": "에이전트 ID" }, "name": { "type": "string", "example": "고객 지원 에이전트" }, "instructions": { "type": "string", "example": "당신은 친절하고 유능한 한국어 음성 에이전트입니다. 사용자의 요청을 주의 깊게 듣고 정확하고 간결하게 답하세요.", "description": "에이전트 시스템 프롬프트" }, "greeting": { "type": "boolean", "example": true, "description": "통화 연결 직후 에이전트가 먼저 인사할지 여부" }, "language": { "type": "string", "example": "ko", "description": "에이전트 기본 언어" }, "maxDurationSeconds": { "type": "integer", "nullable": true, "minimum": 10, "maximum": 7200, "example": null, "description": "통화가 연결된 뒤 이 시간(초)이 지나면 통화를 끊습니다. 수신은 받은 순간, 발신은 상대가 받은 순간부터 잽니다. null 이면 제한 없음입니다. 시간이 되면 대화 중이어도 끊으며, 끊기 전 안내 멘트는 나가지 않습니다." }, "beginMessageDelayMs": { "type": "integer", "minimum": 0, "maximum": 5000, "example": 0, "description": "발신 통화에서 상대가 받은 뒤 첫 인사를 시작하기 전에 기다리는 시간(밀리초)입니다. 0 이면 바로 인사합니다. greeting 이 true 일 때만 적용되며, 수신 통화에는 적용되지 않습니다." }, "liveEvents": { "type": "object", "description": "통화 중 이벤트(실시간 전사·키패드) 설정. 받을 이벤트를 `events` 에 고르면 이 에이전트의 통화 이벤트를\n`GET /v1/accounts/{accountId}/calls/{callId}/live-events`(·`/stream`) 로 받습니다. 추가 요금은 없습니다.\n", "required": [ "events" ], "properties": { "events": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "transcript.final", "transcript.partial", "dtmf.received", "dtmf.sent" ] }, "description": "받을 이벤트. 비우면 꺼집니다(새 에이전트 기본값). 수정할 때는 보낸 목록으로 통째로 바뀝니다.\n하나라도 고르면 `stream.started`·`stream.ended` 가 함께 옵니다.\n- `transcript.final`: 한 발화의 확정 텍스트\n- `transcript.partial`: 말하는 도중의 텍스트\n- `dtmf.sent`: AI가 통화 미디어 연결로 보낸 키 하나. 상대 시스템의 수신 완료를 보장하지 않습니다.\n- `dtmf.received`: 상대가 누른 키 하나\n", "example": [ "transcript.final", "dtmf.received" ] } } }, "model": { "type": "string", "example": "gpt-realtime-2.1-mini", "description": "현재 에이전트가 사용하는 LLM 모델" }, "voice": { "type": "string", "nullable": true, "example": "7706804e-ea85-443a-968a-b9bf363bdde8", "description": "현재 음성 ID" }, "voiceProvider": { "type": "string", "nullable": true, "example": "cartesia", "description": "음성 출력 제공자" }, "voiceModel": { "type": "string", "nullable": true, "example": "sonic-3.5", "description": "외부 TTS 모델. 모델 내장 음성에서는 null입니다." }, "configuration": { "type": "object", "required": [ "outputMode", "language", "knowledge", "stt", "llm", "tts", "vad", "session" ], "properties": { "outputMode": { "type": "string", "enum": [ "realtime_voice", "external_tts", "pipeline", "live", "grok", "elevenlabs" ] }, "language": { "type": "string" }, "knowledge": { "type": "object", "additionalProperties": false, "required": [ "enabled", "topK" ], "properties": { "enabled": { "type": "boolean" }, "topK": { "type": "integer", "minimum": 1, "maximum": 10 } } }, "stt": { "type": "object", "allOf": [ { "type": "object", "additionalProperties": false, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string", "enum": [ "openai" ] }, "model": { "type": "string", "enum": [ "gpt-4o-transcribe", "gpt-4o-mini-transcribe", "whisper-1" ] }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "prompt": { "type": "string" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "detect_language": { "type": "boolean" }, "noise_reduction_type": { "type": "string", "enum": [ "near_field", "far_field" ] }, "use_realtime": { "type": "boolean" } } } ], "nullable": true }, "llm": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "required": [ "provider", "model" ], "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voice": { "type": "string" } } }, "tts": { "type": "object", "allOf": [ { "discriminator": { "propertyName": "provider" }, "oneOf": [ { "title": "Cartesia", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "cartesia" ] }, "model": { "type": "string", "enum": [ "sonic-3.5", "sonic-3.6" ] }, "voice": { "type": "string", "format": "uuid" }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "speed": { "type": "number", "minimum": 0.6, "maximum": 1.5 }, "volume": { "type": "number", "minimum": 0.5, "maximum": 1.5 } } }, { "title": "xAI", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "xai" ] }, "model": { "type": "string", "enum": [ "tts-1" ] }, "voice": { "type": "string", "minLength": 1 }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." } } }, { "title": "Google", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "google" ] }, "model": { "type": "string", "enum": [ "chirp_3" ] }, "voice": { "type": "string", "description": "Chirp 3 HD 음성명입니다(예 `ko-KR-Chirp3-HD-Aoede`).", "pattern": "^[a-z]{2,3}-[A-Z]{2}-Chirp3-HD-[A-Za-z]+$" }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "speed": { "type": "number", "minimum": 0.6, "maximum": 1.5 } } }, { "title": "ElevenLabs", "type": "object", "additionalProperties": false, "required": [ "provider", "model", "voice" ], "properties": { "provider": { "type": "string", "enum": [ "elevenlabs" ] }, "model": { "type": "string", "description": "eleven_flash_v2_5(빠름) 또는 eleven_multilingual_v2(고품질, 글자당 요금 2배)", "enum": [ "eleven_flash_v2_5", "eleven_multilingual_v2" ] }, "voice": { "type": "string", "description": "ElevenLabs 음성 id(20자 영숫자). provider가 elevenlabs인 내 복제 음성도 쓸 수 있습니다.", "pattern": "^[A-Za-z0-9]{20}$" }, "language": { "type": "string", "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다." }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2 } } } ] } ], "nullable": true }, "vad": { "type": "object", "allOf": [ { "type": "object", "additionalProperties": false, "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "silero" ] }, "min_silence_duration": { "type": "number", "minimum": 0, "maximum": 3 }, "min_speech_duration": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_duration": { "type": "number", "minimum": 0, "maximum": 2 }, "max_buffered_speech": { "type": "number", "minimum": 1, "maximum": 120 }, "activation_threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "sample_rate": { "type": "integer", "enum": [ 16000, 8000 ] }, "force_cpu": { "type": "boolean" } } } ], "nullable": true }, "session": { "type": "object", "allOf": [ { "type": "object", "additionalProperties": false, "properties": { "turn_detection": { "type": "string", "enum": [ "vad", "stt" ] }, "allow_interruptions": { "type": "boolean" }, "min_endpointing_delay": { "type": "number", "minimum": 0, "maximum": 5 }, "max_endpointing_delay": { "type": "number", "minimum": 0, "maximum": 15 }, "min_interruption_duration": { "type": "number", "minimum": 0, "maximum": 2 } } } ], "nullable": true } } }, "phoneNumbers": { "type": "array", "items": { "type": "string" }, "example": [ "07012340001" ], "description": "이 에이전트에 착신 연결된 전화번호" }, "dateCreated": { "type": "string", "format": "date-time" }, "dateUpdated": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "입력값 검증 실패", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "사람이 읽을 수 있는 에러 메시지" }, "code": { "type": "string", "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n 해제해야 발신됩니다.\n - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)", "example": "recipient_blocked" }, "ip": { "type": "string", "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.", "example": "52.79.213.41" }, "processedAt": { "type": "string", "format": "date-time", "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.", "example": "2026-10-21T04:10:34.303Z" }, "blockers": { "type": "array", "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.", "items": { "type": "object", "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |", "properties": { "number": { "type": "string", "description": "422 응답의 blockers 에만 있다", "example": "07012340002" }, "code": { "type": "string", "enum": [ "number_not_owned", "number_not_carrier_issued", "business_info_incomplete", "identity_unverified", "account_restricted", "business_recheck_pending", "holder_is_personal" ], "example": "number_not_carrier_issued" }, "message": { "type": "string", "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다." } }, "required": [ "code", "message" ] } } } } } } }, "401": { "description": "인증 실패", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "사람이 읽을 수 있는 에러 메시지" }, "code": { "type": "string", "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n 해제해야 발신됩니다.\n - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)", "example": "recipient_blocked" }, "ip": { "type": "string", "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.", "example": "52.79.213.41" }, "processedAt": { "type": "string", "format": "date-time", "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.", "example": "2026-10-21T04:10:34.303Z" }, "blockers": { "type": "array", "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.", "items": { "type": "object", "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |", "properties": { "number": { "type": "string", "description": "422 응답의 blockers 에만 있다", "example": "07012340002" }, "code": { "type": "string", "enum": [ "number_not_owned", "number_not_carrier_issued", "business_info_incomplete", "identity_unverified", "account_restricted", "business_recheck_pending", "holder_is_personal" ], "example": "number_not_carrier_issued" }, "message": { "type": "string", "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다." } }, "required": [ "code", "message" ] } } } } } } }, "403": { "description": "다른 계정이 등록한 Cartesia 음성 사용 시도", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "사람이 읽을 수 있는 에러 메시지" }, "code": { "type": "string", "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n 해제해야 발신됩니다.\n - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)", "example": "recipient_blocked" }, "ip": { "type": "string", "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.", "example": "52.79.213.41" }, "processedAt": { "type": "string", "format": "date-time", "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.", "example": "2026-10-21T04:10:34.303Z" }, "blockers": { "type": "array", "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.", "items": { "type": "object", "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |", "properties": { "number": { "type": "string", "description": "422 응답의 blockers 에만 있다", "example": "07012340002" }, "code": { "type": "string", "enum": [ "number_not_owned", "number_not_carrier_issued", "business_info_incomplete", "identity_unverified", "account_restricted", "business_recheck_pending", "holder_is_personal" ], "example": "number_not_carrier_issued" }, "message": { "type": "string", "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다." } }, "required": [ "code", "message" ] } } } } } } } } } ```