음성 실시간 2025-10-01 API 참고

음성 라이브 API는 WebSocket 연결을 사용하는 음성 지원 애플리케이션에 실시간 양방향 통신을 제공합니다. 이 API는 음성 인식, 텍스트 음성 합성, 아바타 스트리밍, 애니메이션 데이터, 포괄적인 오디오 처리 기능 등 고급 기능을 지원합니다.

API는 WebSocket 연결을 통해 전송되는 JSON 형식의 이벤트를 사용하여 대화, 오디오 스트림, 아바타 상호작용, 실시간 응답을 관리합니다. 이벤트는 클라이언트 이벤트(클라이언트에서 서버로 전송)와 서버 이벤트(서버에서 클라이언트로 전송)로 분류됩니다.

Key Features

• 실시간 오디오 처리: PCM16을 포함한 다양한 샘플링 속도와 G.711 코덱 지원
• 고급 음성 옵션: OpenAI 음성, Azure 맞춤 음성, Azure 표준 음성, Azure 개인 음성
• 아바타 통합: WebRTC 기반 아바타 스트리밍, 비디오, 애니메이션, 블렌드셰이프
• 지능형 턴 감지: Azure 의미 VAD와 서버 측 감지를 포함한 여러 VAD 옵션
• 오디오 향상: 내장된 노이즈 감소 및 에코 캔슬링
• 기능 호출: 향상된 대화 기능을 위한 도구 통합
• 유연한 세션 관리: 구성 가능한 출력 방식, 명령어, 응답 매개변수

Client Events

음성 라이브 API는 클라이언트에서 서버로 전송할 수 있는 다음과 같은 클라이언트 이벤트를 지원합니다:

session.update

세션 구성을 업데이트하세요. 이 이벤트는 언제든지 전송되어 음성, 출력 모달리티, 턴 감지, 도구 및 기타 세션 매개변수 등을 수정할 수 있습니다. 한 번 세션이 특정 모델로 초기화되면 다른 모델로 변경할 수 없다는 점에 유의하세요.

Event Structure

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Properties

Azure Custom Voice 예시

{
  "type": "session.update",
  "session": {
    "voice": {
      "type": "azure-custom",
      "name": "my-custom-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "temperature": 0.7,
      "style": "cheerful"
    },
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "avatar": {
      "character": "lisa",
      "customized": false,
      "video": {
        "resolution": {
          "width": 1920,
          "height": 1080
        },
        "bitrate": 2000000
      }
    }
  }
}

session.avatar.connect

클라이언트의 SDP(세션 설명 프로토콜) 제안을 제공하여 WebRTC 미디어 협상을 위해 아바타 연결을 구축하세요. 이 이벤트는 아바타 기능을 사용할 때 필요합니다.

Event Structure

{
  "type": "session.avatar.connect",
  "client_sdp": "<client_sdp>"
}

Properties

input_audio_buffer.append

입력 오디오 버퍼에 오디오 바이트를 추가하세요.

Event Structure

{
  "type": "input_audio_buffer.append",
  "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

Properties

input_audio_buffer.commit

입력 오디오 버퍼를 처리를 위해 커밋합니다.

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

입력 오디오 버퍼를 지우세요.

Event Structure

{
  "type": "input_audio_buffer.clear"
}

Properties

conversation.item.create

대화 맥락에 새로운 항목을 추가하세요. 여기에는 메시지, 함수 호출, 함수 호출 응답이 포함될 수 있습니다. 대화 기록의 특정 위치에 항목을 삽입할 수 있습니다.

Event Structure

{
  "type": "conversation.item.create",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Properties

오디오 콘텐츠가 포함된 예시

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello there"
      }
    ]
  }
}

함수 호출 출력 예시

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_123",
    "output": "{\"location\": \"San Francisco\", \"temperature\": \"70\"}"
  }
}

MCP 승인 응답 예시

{
  "type": "conversation.item.create",
  "item": {
    "type": "mcp_approval_response",
    "approval_request_id": "mcp_approval_req_456",
    "approve": true,
  }
}

conversation.item.retrieve

대화 기록에서 특정 항목을 불러오세요. 이는 노이즈 캔슬링 및 VAD 후 처리된 오디오를 검사하는 데 유용합니다.

Event Structure

{
  "type": "conversation.item.retrieve",
  "item_id": "item_ABC123"
}

Properties

conversation.item.truncate

보조 메시지의 오디오 내용을 잘라내세요. 이는 특정 시점에서 재생을 멈추고 서버의 이해를 클라이언트 상태와 동기화하는 데 유용합니다.

Event Structure

{
  "type": "conversation.item.truncate",
  "item_id": "item_ABC123",
  "content_index": 0,
  "audio_end_ms": 5000
}

Properties

conversation.item.delete

대화 기록에서 항목을 삭제하세요.

Event Structure

{
  "type": "conversation.item.delete",
  "item_id": "item_ABC123"
}

Properties

response.create

서버에 모델 추론을 통해 응답을 생성하도록 지시하세요. 이 이벤트는 세션 기본값을 덮어쓰는 응답별 구성을 지정할 수 있습니다.

Event Structure

{
  "type": "response.create",
  "response": {
    "modalities": ["text", "audio"],
    "instructions": "Be extra helpful and detailed.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "output_audio_format": "pcm16",
    "temperature": 0.7,
    "max_response_output_tokens": 1000
  }
}

Properties

도구 선택이 있는 예시

{
  "type": "response.create",
  "response": {
    "modalities": ["text"],
    "tools": [
      {
        "type": "function",
        "name": "get_current_time",
        "description": "Get the current time",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      }
    ],
    "tool_choice": "get_current_time",
    "temperature": 0.3
  }
}

애니메이션 예시

{
  "type": "response.create",
  "response": {
    "modalities": ["audio", "animation"],
    "animation": {
      "model_name": "default",
      "outputs": ["blendshapes", "viseme_id"]
    },
    "voice": {
      "type": "azure-custom",
      "name": "my-expressive-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "style": "excited"
    }
  }
}

response.cancel

진행 중인 응답을 취소하세요. 이로 인해 즉시 응답 생성과 관련 오디오 출력이 중단됩니다.

Event Structure

{
  "type": "response.cancel"
}

Properties

input_audio_buffer.append

클라이언트 input_audio_buffer.append 이벤트는 입력 오디오 버퍼에 오디오 바이트를 추가하는 데 사용됩니다. 오디오 버퍼는 임시 저장소로, 나중에 커밋할 수 있습니다.

서버 VAD(음성 활동 감지) 모드에서는 오디오 버퍼를 사용해 음성을 감지하고 서버가 언제 커밋할지 결정합니다. 서버 VAD가 비활성화되면 클라이언트는 각 이벤트에 최대 15 MiB까지 입력할 오디오 양을 선택할 수 있습니다. 예를 들어, 클라이언트에서 작은 청크를 스트리밍하면 VAD가 더 반응할 수 있습니다.

대부분의 다른 클라이언트 이벤트와 달리, 서버는 클라이언트 input_audio_buffer.append 이벤트에 대해 확인 응답을 보내지 않습니다.

Event structure

{
  "type": "input_audio_buffer.append",
  "audio": "<audio>"
}

Properties

input_audio_buffer.clear

클라이언트 input_audio_buffer.clear 이벤트는 버퍼의 오디오 바이트를 지우는 데 사용됩니다.

서버는 이벤트로 input_audio_buffer.cleared 응답합니다.

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

input_audio_buffer.commit

클라이언트 input_audio_buffer.commit 이벤트는 사용자 입력 오디오 버퍼를 커밋하는 데 사용되며, 이는 대화 내 새로운 사용자 메시지 항목을 생성합니다. 세션에 맞게 설정된 오디오는 input_audio_transcription 전사됩니다.

서버 VAD 모드에서는 클라이언트가 이 이벤트를 보낼 필요가 없고, 서버가 오디오 버퍼를 자동으로 커밋합니다. 서버 VAD가 없으면, 클라이언트는 사용자 메시지 항목을 생성하기 위해 오디오 버퍼를 커밋해야 합니다. 이 클라이언트 이벤트는 입력 오디오 버퍼가 비어 있으면 오류를 생성합니다.

입력 오디오 버퍼를 커밋한다고 해서 모델에서 응답이 생성되지 않습니다.

서버는 이벤트로 input_audio_buffer.committed 응답합니다.

Event structure

{
  "type": "input_audio_buffer.commit"
}

Properties

Server Events

음성 라이브 API는 클라이언트에 상태, 응답 및 데이터를 전달하기 위해 다음과 같은 서버 이벤트를 전송합니다:

session.created

새 세션이 성공적으로 설정되면 전송됩니다. 이 이벤트는 API에 연결된 후 처음 받는 이벤트입니다.

Event Structure

{
  "type": "session.created",
  "session": {
    "id": "sess_ABC123DEF456",
    "object": "realtime.session",
    "model": "gpt-realtime",
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful assistant.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Properties

session.updated

클라이언트 이벤트에 대응 session.update 하여 세션 구성이 성공적으로 업데이트될 때 전송됩니다.

Event Structure

{
  "type": "session.updated",
  "session": {
    "id": "sess_ABC123DEF456",
    "voice": {
      "type": "azure-custom",
      "name": "my-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012"
    },
    "temperature": 0.7,
    "avatar": {
      "character": "lisa",
      "customized": false
    }
  }
}

Properties

session.avatar.connecting

아바타 WebRTC 연결이 구축 중임을 나타냅니다. 이 이벤트는 클라이언트 이벤트에 session.avatar.connect 대한 응답으로 전송됩니다.

Event Structure

{
  "type": "session.avatar.connecting",
  "server_sdp": "<server_sdp>"
}

Properties

conversation.item.created

고객 이벤트를 통해 conversation.item.create 서든 응답 생성 중에 대화에 새로운 항목이 추가될 때 자동으로 전송됩니다.

Event Structure

{
  "type": "conversation.item.created",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Properties

오디오 아이템 예시

{
  "type": "conversation.item.created",
  "item": {
    "id": "item_GHI789",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": null,
        "transcript": "What's the weather like today?"
      }
    ]
  }
}

conversation.item.retrieved

클라이언트 이벤트에 conversation.item.retrieve 대한 답변으로 보내졌으며, 요청된 대화 항목을 제공했습니다.

Event Structure

{
  "type": "conversation.item.retrieved",
  "item": {
    "id": "item_ABC123",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
      }
    ]
  }
}

Properties

conversation.item.truncated

서버 conversation.item.truncated 이벤트는 클라이언트가 이전 보조 오디오 메시지 항목을 이벤트로 conversation.item.truncate 잘라버릴 때 반환됩니다. 이 이벤트는 서버가 오디오를 이해하고 클라이언트의 재생과 동기화하는 데 사용됩니다.

이 이벤트는 오디오를 잘라내고 서버 측 텍스트 전사본을 제거하여 사용자가 모르는 문맥 내 텍스트가 없도록 합니다.

Event structure

{
  "type": "conversation.item.truncated",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

Properties

conversation.item.deleted

클라이언트 이벤트에 conversation.item.delete 대한 답변으로 보내졌으며, 지정된 항목이 대화에서 삭제되었음을 확인합니다.

Event Structure

{
  "type": "conversation.item.deleted",
  "item_id": "item_ABC123"
}

Properties

response.created

새로운 응답 생성이 시작되면 전송됩니다. 이것은 반응 시퀀스의 첫 번째 사건입니다.

Event Structure

{
  "type": "response.created",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "in_progress",
    "status_details": null,
    "output": [],
    "usage": {
      "total_tokens": 0,
      "input_tokens": 0,
      "output_tokens": 0
    }
  }
}

Properties

response.done

응답 생성이 완료되면 전송됩니다. 이 이벤트는 모든 출력 항목과 사용 통계가 포함된 최종 응답을 포함합니다.

Event Structure

{
  "type": "response.done",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "completed",
    "status_details": null,
    "output": [
      {
        "id": "item_DEF456",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
          }
        ]
      }
    ],
    "usage": {
      "total_tokens": 87,
      "input_tokens": 52,
      "output_tokens": 35,
      "input_token_details": {
        "cached_tokens": 0,
        "text_tokens": 45,
        "audio_tokens": 7
      },
      "output_token_details": {
        "text_tokens": 15,
        "audio_tokens": 20
      }
    }
  }
}

Properties

response.output_item.added

생성 과정에서 응답에 새로운 출력 항목이 추가될 때 전송됩니다.

Event Structure

{
  "type": "response.output_item.added",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "assistant",
    "content": []
  }
}

Properties

response.output_item.done

출력 항목이 완료되면 전송됩니다.

Event Structure

{
  "type": "response.output_item.done",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm doing well, thank you for asking."
      }
    ]
  }
}

Properties

response.content_part.added

서버 response.content_part.added 이벤트는 응답 생성 중 보조 메시지 항목에 새로운 콘텐츠 부분이 추가될 때 반환됩니다.

Event Structure

{
  "type": "response.content_part.added",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": ""
  }
}

Properties

response.content_part.done

서버 response.content_part.done 이벤트는 콘텐츠 부분이 보조 메시지 항목에서 스트리밍이 완료되면 반환됩니다.

이 이벤트는 응답이 중단되거나 불완전하거나 취소될 때도 반환됩니다.

Event Structure

{
  "type": "response.content_part.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": "Hello! I'm doing well, thank you for asking."
  }
}

Properties

response.text.delta

모델에서 텍스트 콘텐츠를 스트리밍하는 것. 모델이 텍스트를 생성하는 동안 점진적으로 전송됩니다.

Event Structure

{
  "type": "response.text.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm"
}

Properties

response.text.done

텍스트 콘텐츠 생성이 완료되면 전송됩니다.

Event Structure

{
  "type": "response.text.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Properties

response.audio.delta

모델에서 오디오 콘텐츠를 스트리밍하는 중입니다. 오디오는 base64 인코딩 데이터로 제공됩니다.

Event Structure

{
  "type": "response.audio.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

Properties

response.audio.done

오디오 콘텐츠 생성이 완료되면 전송됩니다.

Event Structure

{
  "type": "response.audio.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Properties

response.audio_transcript.delta

생성된 오디오 콘텐츠의 스트리밍 전사본.

Event Structure

{
  "type": "response.audio_transcript.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm doing"
}

Properties

response.audio_transcript.done

오디오 대본이 생성되면 전송됩니다.

Event Structure

{
  "type": "response.audio_transcript.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Properties

conversation.item.input_audio_transcription.completed

서버 conversation.item.input_audio_transcription.completed 이벤트는 음성 버퍼에 기록된 음성 전사의 결과입니다.

전사는 클라이언트 또는 서버가 입력 오디오 버퍼를 커밋할 때 시작됩니다(모드 상태 server_vad ). 전사는 응답 생성과 비동기적으로 진행되므로, 이 이벤트는 응답 이벤트 전이나 후에 발생할 수 있습니다.

실시간 API 모델은 오디오를 네이티브로 받아들이므로, 입력 전사는 별도의 음성 인식 모델(예: whisper-1.)에서 실행되는 별도의 프로세스입니다. 따라서 전사본은 모델 해석과 다소 다를 수 있으며, 대략적인 가이드로 간주해야 합니다.

Event structure

{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "<item_id>",
  "content_index": 0,
  "transcript": "<transcript>"
}

Properties

conversation.item.input_audio_transcription.delta

서버 conversation.item.input_audio_transcription.delta 이벤트는 입력 오디오 전사가 설정되어 있고 사용자 메시지에 대한 전사 요청이 진행 중일 때 반환됩니다. 이 이벤트는 부분적인 전사 결과가 공개될 때마다 제공합니다.

Event structure

{
  "type": "conversation.item.input_audio_transcription.delta",
  "item_id": "<item_id>",
  "content_index": 0,
  "delta": "<delta>"
}

Properties

conversation.item.input_audio_transcription.failed

서버 conversation.item.input_audio_transcription.failed 이벤트는 입력 오디오 전사가 설정되었을 때 반환되며, 사용자 메시지에 대한 전사 요청이 실패할 때 반환됩니다. 이 이벤트는 다른 error 이벤트와 별도로 진행되어 클라이언트가 관련 항목을 식별할 수 있도록 합니다.

Event structure

{
  "type": "conversation.item.input_audio_transcription.failed",
  "item_id": "<item_id>",
  "content_index": 0,
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

Properties

Error properties

response.animation_blendshapes.delta

서버 response.animation_blendshapes.delta 이벤트는 모델이 반응의 일부로 애니메이션 블렌드쉐이프 데이터를 생성할 때 반환됩니다. 이 이벤트는 추가적인 블렌드셰이프 데이터를 제공한다.

Event structure

{
  "type": "response.animation_blendshapes.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "frame_index": 0,
  "frames": [
    [0.0, 0.1, 0.2, ..., 1.0]
    ...
  ]
}

Properties

response.animation_blendshapes.done

서버 response.animation_blendshapes.done 이벤트는 모델이 애니메이션 블렌드셰이프 데이터를 생성한 후 응답의 일부로 반환됩니다.

Event structure

{
  "type": "response.animation_blendshapes.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
}

Properties

response.audio_timestamp.delta

서버 response.audio_timestamp.delta 이벤트는 모델이 응답의 일부로 오디오 타임스탬프 데이터를 생성할 때 반환됩니다. 이 이벤트는 출력 오디오와 텍스트 정렬을 위한 점진적 타임스탬프 데이터를 제공합니다.

Event structure

{
  "type": "response.audio_timestamp.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "audio_duration_ms": 500,
  "text": "Hello",
  "timestamp_type": "word"
}

Properties

response.audio_timestamp.done

오디오 타임스탬프 생성이 완료되면 전송됩니다.

Event Structure

{
  "type": "response.audio_timestamp.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Properties

response.animation_viseme.delta

서버 response.animation_viseme.delta 는 모델이 응답의 일부로 애니메이션 비셈 데이터를 생성할 때 반환됩니다. 이 이벤트는 추가적인 비셈 데이터를 제공한다.

Event Structure

{
  "type": "response.animation_viseme.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "viseme_id": 1
}

Properties

response.animation_viseme.done

서버 response.animation_viseme.done 이벤트는 모델이 애니메이션 비셈 데이터를 생성한 후 응답의 일부로 반환됩니다.

Event Structure

{
  "type": "response.animation_viseme.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Properties

error

서버 error 이벤트는 클라이언트 문제나 서버 문제일 수 있는 오류가 발생하면 반환됩니다. 대부분의 오류는 복구 가능하며 세션은 계속 열려 있습니다.

Event structure

{
  "type": "error",
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>",
    "event_id": "<event_id>"
  }
}

Properties

Error properties

warning

서버 warning 이벤트는 대화 흐름을 방해하지 않는 경고가 발생하면 반환됩니다. 경고는 정보 제공이며, 세션은 정상적으로 계속됩니다.

Event structure

{
  "type": "warning",
  "warning": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

Properties

Warning properties

input_audio_buffer.cleared

서버 input_audio_buffer.cleared 이벤트는 클라이언트가 이벤트로 input_audio_buffer.clear 입력 오디오 버퍼를 지우면 반환됩니다.

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

input_audio_buffer.committed

서버 input_audio_buffer.committed 이벤트는 입력 오디오 버퍼가 커밋될 때 클라이언트에 의해 또는 서버 VAD 모드에서 자동으로 반환됩니다. 속성은 item_id 생성된 사용자 메시지 항목의 ID입니다. 따라서 conversation.item.created 이벤트도 클라이언트에게 전송됩니다.

Event structure

{
  "type": "input_audio_buffer.committed",
  "previous_item_id": "<previous_item_id>",
  "item_id": "<item_id>"
}

Properties

input_audio_buffer.speech_started

음성 제어가 오디오 버퍼에서 감지되면 서버 input_audio_buffer.speech_started 이벤트가 모드로 server_vad 반환됩니다. 이 현상은 오디오가 버퍼에 추가될 때마다 발생할 수 있습니다(이미 음성 신호가 감지되지 않은 경우).

내담자는 말이 중단되면 이벤트를 받을 input_audio_buffer.speech_stopped 것으로 예상해야 합니다. 속성은 item_id 말이 멈췄을 때 생성되는 사용자 메시지 항목의 ID입니다. item_id 클라이언트가 VAD 활성화 시 오디오 버퍼를 수동으로 커밋하지 않는 한 이벤트에 input_audio_buffer.speech_stopped 포함됩니다.

Event structure

{
  "type": "input_audio_buffer.speech_started",
  "audio_start_ms": 0,
  "item_id": "<item_id>"
}

Properties

input_audio_buffer.speech_stopped

서버 input_audio_buffer.speech_stopped 이벤트는 서버가 오디오 버퍼에서 음성 종료를 감지하면 모드로 server_vad 반환됩니다.

서버는 또한 오디오 버퍼에서 생성된 사용자 메시지 항목이 포함된 이벤트를 전송 conversation.item.created 합니다.

Event structure

{
  "type": "input_audio_buffer.speech_stopped",
  "audio_end_ms": 0,
  "item_id": "<item_id>"
}

Properties

rate_limits.updated

서버 rate_limits.updated 이벤트는 응답 시작 시 업데이트된 속도 제한을 알리기 위해 발송됩니다.

응답이 생성되면 일부 토큰이 출력 토큰에 예약됩니다. 여기에 표시된 요금 한도는 해당 예약을 반영하며, 응답이 완료된 후 이에 맞게 조정됩니다.

Event structure

{
  "type": "rate_limits.updated",
  "rate_limits": [
    {
      "name": "<name>",
      "limit": 0,
      "remaining": 0,
      "reset_seconds": 0
    }
  ]
}

Properties

response.audio.delta

서버 response.audio.delta 이벤트는 모델에서 생성된 오디오가 업데이트될 때 반환됩니다.

Event structure

{
  "type": "response.audio.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Properties

response.audio.done

모델 생성 오디오가 완료되면 서버 response.audio.done 이벤트가 반환됩니다.

이 이벤트는 응답이 중단되거나 불완전하거나 취소될 때도 반환됩니다.

Event structure

{
  "type": "response.audio.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

Properties

response.audio_transcript.delta

서버 response.audio_transcript.delta 이벤트는 모델 생성 오디오 출력의 전사가 업데이트될 때 반환됩니다.

Event structure

{
  "type": "response.audio_transcript.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Properties

response.audio_transcript.done

서버 response.audio_transcript.done 이벤트는 모델 생성 오디오 출력의 전사가 스트리밍으로 완료될 때 반환됩니다.

이 이벤트는 응답이 중단되거나 불완전하거나 취소될 때도 반환됩니다.

Event structure

{
  "type": "response.audio_transcript.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "transcript": "<transcript>"
}

Properties

response.function_call_arguments.delta

서버 response.function_call_arguments.delta 이벤트는 모델이 생성한 함수 호출 인자가 업데이트될 때 반환됩니다.

Event structure

{
  "type": "response.function_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "delta": "<delta>"
}

Properties

response.function_call_arguments.done

서버 response.function_call_arguments.done 이벤트는 모델이 생성한 함수 호출 인자가 스트리밍이 완료되면 반환됩니다.

이 이벤트는 응답이 중단되거나 불완전하거나 취소될 때도 반환됩니다.

Event structure

{
  "type": "response.function_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "arguments": "<arguments>"
}

Properties

mcp_list_tools.in_progress

서버 mcp_list_tools.in_progress 이벤트는 서비스가 MCP 서버에서 사용 가능한 도구를 나열하기 시작할 때 반환됩니다.

Event structure

{
  "type": "mcp_list_tools.in_progress",
  "item_id": "<mcp_list_tools_item_id>"
}

Properties

mcp_list_tools.completed

서버 mcp_list_tools.completed 이벤트는 서비스가 MCP 서버에서 사용 가능한 도구를 나열하는 것을 완료할 때 반환됩니다.

Event structure

{
  "type": "mcp_list_tools.completed",
  "item_id": "<mcp_list_tools_item_id>"
}

Properties

mcp_list_tools.failed

서버 mcp_list_tools.failed 이벤트는 서비스가 MCP 서버에서 사용 가능한 도구를 목록에 올리지 못할 때 반환됩니다.

Event structure

{
  "type": "mcp_list_tools.failed",
  "item_id": "<mcp_list_tools_item_id>"
}

Properties

response.mcp_call_arguments.delta

서버 response.mcp_call_arguments.delta 이벤트는 모델 생성 MCP 도구 호출 인자가 업데이트될 때 반환됩니다.

Event structure

{
  "type": "response.mcp_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "delta": "<delta>"
}

Properties

response.mcp_call_arguments.done

서버 response.mcp_call_arguments.done 이벤트는 모델 생성 MCP 도구 호출 인자가 스트리밍이 완료되면 반환됩니다.

Event structure

{
  "type": "response.mcp_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "arguments": "<arguments>"
}

Properties

response.mcp_call.in_progress

서버 response.mcp_call.in_progress 이벤트는 MCP 툴 호출이 처리를 시작할 때 반환됩니다.

Event structure

{
  "type": "response.mcp_call.in_progress",
  "item_id": "<item_id>",
  "output_index": 0
}

Properties

response.mcp_call.completed

MCP 툴 호출이 성공적으로 완료되면 서버 response.mcp_call.completed 이벤트가 반환됩니다.

Event structure

{
  "type": "response.mcp_call.completed",
  "item_id": "<item_id>",
  "output_index": 0
}

Properties

response.mcp_call.failed

서버 response.mcp_call.failed 이벤트는 MCP 툴 호출이 실패할 때 반환됩니다.

Event structure

{
  "type": "response.mcp_call.failed",
  "item_id": "<item_id>",
  "output_index": 0
}

Properties

response.output_item.added

서버 response.output_item.added 이벤트는 응답 생성 중 새 항목이 생성될 때 반환됩니다.

Event structure

{
  "type": "response.output_item.added",
  "response_id": "<response_id>",
  "output_index": 0
}

Properties

response.output_item.done

서버 response.output_item.done 이벤트는 아이템 스트리밍이 완료되면 반환됩니다.

이 이벤트는 응답이 중단되거나 불완전하거나 취소될 때도 반환됩니다.

Event structure

{
  "type": "response.output_item.done",
  "response_id": "<response_id>",
  "output_index": 0
}

Properties

response.text.delta

모델 생성 텍스트가 업데이트될 때 서버 response.text.delta 이벤트가 반환됩니다. 텍스트는 보조 메시지 항목의 내용 부분에 text 해당합니다.

Event structure

{
  "type": "response.text.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Properties

response.text.done

서버 response.text.done 이벤트는 모델 생성 텍스트가 스트리밍이 완료되면 반환됩니다. 텍스트는 보조 메시지 항목의 내용 부분에 text 해당합니다.

이 이벤트는 응답이 중단되거나 불완전하거나 취소될 때도 반환됩니다.

Event structure

{
  "type": "response.text.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "text": "<text>"
}

Properties

Components

Audio Formats

RealtimeAudioFormat

입력 오디오에 사용되는 기본 오디오 포맷.

Allowed Values:

• pcm16 - 16비트 PCM 오디오 포맷
• g711_ulaw - G.711 μ법 오디오 포맷
• g711_alaw - G.711 A-law(법률) 오디오 포맷

RealtimeOutputAudioFormat

특정 샘플링 속도를 가진 출력 오디오에 사용되는 오디오 포맷입니다.

Allowed Values:

• pcm16 - 기본 샘플링 속도(24kHz)에서의 16비트 PCM 오디오 포맷
• pcm16_8000hz - 8kHz 샘플링 속도의 16비트 PCM 오디오 포맷
• pcm16_16000hz - 16kHz 샘플링 속도의 16비트 PCM 오디오 포맷
• g711_ulaw - 8kHz 샘플링 속도의 G.711 μ-로(mu-law) 오디오 포맷
• g711_alaw - G.711 8kHz 샘플링 속도의 A-law 오디오 포맷

RealtimeAudioInputTranscriptionSettings

입력 오디오 전사를 위한 설정.

RealtimeInputAudioNoiseReductionSettings

이는 다음과 같습니다:

• 실시간 OpenAINoiseReduction 객체
• RealtimeAzureDeepNoiseSuppression 객체

RealtimeOpenAINoiseReduction

명시적인 타입 필드가 있는 OpenAI 노이즈 감소 구성으로, 모델 gpt-realtime-mini 에만 gpt-realtime 적용 가능합니다.

RealtimeAzureDeepNoiseSuppression

입력 오디오 노이즈 감소 설정.

RealtimeInputAudioEchoCancellationSettings

서버 측 오디오 처리를 위한 에코 캔슬링 구성.

Voice Configuration

RealtimeVoice

지원되는 모든 음성 구성의 연합.

이는 다음과 같습니다:

• RealtimeOpenAIVoice 객체
• RealtimeAzureVoice 객체

RealtimeOpenAIVoice

명시적인 타입 필드가 포함된 OpenAI 음성 구성.

RealtimeAzureVoice

Base for Azure 음성 구성. 이것은 여러 유형이 있는 차별된 노동조합입니다:

RealtimeAzureStandardVoice

Azure 표준 음성 구성.

RealtimeAzureCustomVoice

Azure custom voice configuration (custom voices에 선호).

Example:

{
  "type": "azure-custom",
  "name": "my-custom-voice",
  "endpoint_id": "12345678-1234-1234-1234-123456789012",
  "temperature": 0.7,
  "style": "cheerful",
  "locale": "en-US"
}

RealtimeAzurePersonalVoice

Azure 개인 음성 설정.

Turn Detection

RealtimeTurnDetection

회전 감지 설정. 이 노조는 여러 종류의 VAD를 지원하는 차별적 노조입니다.

RealtimeServerVAD

기본 VAD 기반 턴 감지.

RealtimeOpenAISemanticVAD

사용자가 말을 마쳤는지 모델을 사용해 판단하는 OpenAI 의미 VAD 구성입니다. 모델 gpt-realtime-mini 에만 gpt-realtime 제공됩니다.

RealtimeAzureSemanticVAD

Azure 의미 VAD는 사용자가 언제 말을 시작하고 말하는지를 의미 음성 모델로 결정하여 소음이 많은 환경에서 보다 강력한 탐지를 제공합니다.

RealtimeAzureSemanticVADMultilingual

Azure semantic VAD (default variant).

RealtimeEOUDetection

Azure 발화 종료(EOU)는 사용자가 말을 멈췄음을 표시하면서 자연스러운 일시정지를 허용할 수 있습니다. 발화 종료 감지는 사용자가 인지할 수 있는 지연 시간을 추가하지 않고도 조기 방향 종료 신호를 크게 줄일 수 있습니다.

Avatar Configuration

RealtimeAvatarConfig

아바타 스트리밍 및 동작 설정.

RealtimeIceServer

WebRTC 연결 협상을 위한 ICE 서버 구성.

RealtimeVideoParams

아바타의 비디오 스트리밍 파라미터.

RealtimeVideoCrop

비디오 크롭 직사각형 정의.

RealtimeVideoResolution

비디오 해상도 사양.

RealtimeAvatarScene

아바타의 줌 레벨, 위치, 회전, 이동 진폭 설정.

Animation Configuration

RealtimeAnimation

블렌드셰이프와 비셈을 포함한 애니메이션 출력 설정.

RealtimeAnimationOutputType

출력할 애니메이션 데이터 종류.

Allowed Values:

• blendshapes - 얼굴 블렌드셰이프 데이터
• viseme_id - 비세메 식별자 데이터

Session Configuration

RealtimeRequestSession

이벤트에서 session.update 사용되는 세션 구성 객체입니다.

RealtimeModality

세션 출력 방식도 지원됩니다.

Allowed Values:

• text - 텍스트 출력
• audio - 오디오 출력
• animation - 애니메이션 출력
• avatar - 아바타 비디오 출력

RealtimeAudioTimestampType

오디오 응답 콘텐츠에서 지원되는 출력 타임스탬프 유형.

Allowed Values:

• word - 출력 오디오에서 단어당 타임스탬프

ReasoningEffort

추론 모델에 대한 추론 노력을 제한합니다. 각 모델의 지원 값을 모델 문서에서 확인하세요. 추론 노력을 줄이면 응답 속도가 빨라지고 추론에 사용되는 토큰 수가 줄어듭니다.

Allowed Values:

• none - 추론 노력 없음
• minimal - 최소한의 추론 노력
• low - 낮은 추론 노력 - 적은 추론으로 더 빠른 응답
• medium - 중간 수준의 추론 노력 - 속도와 깊이의 균형
• high - 높은 추론 노력 - 더 철저한 추론, 시간이 더 걸릴 수 있음
• xhigh - 초고도의 추론 노력 - 최대 추론 깊이

Tool Configuration

저희는 함수 호출과 MCP 서버에 연결할 수 있는 MCP 도구 두 가지 유형의 도구를 지원합니다.

RealtimeTool

함수 호출을 위한 도구 정의.

RealtimeToolChoice

도구 선택 전략.

이는 다음과 같습니다:

• "auto" - 모델이 선택하게 한다
• "none" - 도구 쓰지 마
• "required" - 도구를 사용해야 합니다
• { "type": "function", "name": "function_name" } - 특정 기능을 사용하는

MCPTool

MCP 도구 구성.

RealtimeConversationResponseItem

이것은 다음 중 하나일 수 있는 유니언 유형입니다:

RealtimeConversationUserMessageItem

사용자 메시지 항목.

RealtimeConversationAssistantMessageItem

보조 메시지 항목.

RealtimeConversationSystemMessageItem

시스템 메시지 항목.

RealtimeConversationFunctionCallItem

함수 호출 요청 항목.

RealtimeConversationFunctionCallOutputItem

함수 호출 응답 항목.

RealtimeConversationMCPListToolsItem

MCP 목록 도구 응답 항목.

RealtimeConversationMCPCallItem

MCP 콜 응답 항목.

RealtimeConversationMCPApprovalRequestItem

MCP 승인 요청 항목.

RealtimeItemStatus

대화 항목 현황.

Allowed Values:

• in_progress - 현재 처리 중
• completed - 성공적으로 완료됨
• incomplete - 불완전(중단 또는 실패)

RealtimeContentPart

메시지 내 내용 부분.

RealtimeInputTextContentPart

텍스트 내용 부분.

RealtimeOutputTextContentPart

텍스트 내용 부분.

RealtimeInputAudioContentPart

오디오 콘텐츠 부분입니다.

RealtimeOutputAudioContentPart

오디오 콘텐츠 부분입니다.

Response Objects

RealtimeResponse

모델 추론 응답을 나타내는 응답 객체.

RealtimeResponseStatus

응답 상태 값.

Allowed Values:

• in_progress - 응답이 생성되고 있습니다
• completed - 응답 완료
• canceled - 응답이 취소되었습니다
• incomplete - 응답 불완전 (중단됨)
• failed - 응답 실패 및 오류

RealtimeUsage

토큰 사용 통계.

TokenDetails

상세한 토큰 사용 내역입니다.

Error Handling

RealtimeErrorDetails

오류 정보 객체.

RealtimeConversationRequestItem

conversation.item.create 이벤트를 통해 대화 내 새 항목을 생성하기 위해 이 RealtimeConversationRequestItem 객체를 사용합니다.

이것은 다음 중 하나일 수 있는 유니언 유형입니다:

RealtimeSystemMessageItem

시스템 메시지 항목입니다.

RealtimeUserMessageItem

사용자 메시지 항목입니다.

RealtimeAssistantMessageItem

보조 메시지 항목.

RealtimeFunctionCallItem

함수 호출 항목입니다.

RealtimeFunctionCallOutputItem

출력 항목을 호출하는 함수입니다.

RealtimeMCPApprovalResponseItem

MCP 승인 응답 항목입니다.

RealtimeFunctionTool

실시간 엔드포인트가 사용하는 함수 도구의 정의.

RealtimeItemStatus

Allowed Values:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

객체는 RealtimeResponseSession Realtime API에서 세션을 나타냅니다. 서버 이벤트에서 다음과 같은 것들이 사용됩니다:

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Related Resources

• 보이스 라이브 퀵스타트를 시도해 보세요
• Voice Live 상담원 퀵스타트를 시도해 보세요
• Voice Live API를 사용하는 방법에 대해 자세히 알아보기