GPT-Live 이벤트 API 참조

이 문서는 GPT-Live에 대한 전체 이벤트 참조입니다. 작업 기반 지침은 GPT-Live에서 실시간 음성 및 위임 작업에 GPT-Live 사용을 참조하세요.

기본 네임스페이스

GPT-Live 세션은 Foundry 리소스 엔드포인트에 /openai/v1/live 있습니다. WebSocket 클라이언트가 연결하여 /openai/v1/live/sessions 보냅니다 session.start. WebRTC 세션은 .을 사용하여 POST /openai/v1/live/sessions만들어집니다. 서버에서 사이드밴드 연결을 /openai/v1/live/sessions/{session_id}/attach연결합니다.

세션 구성

세션은 알 수 없는 필드를 거부하는 엄격한 구성 개체로 시작합니다. WebSocket 클라이언트에서 보냅니다. session.start WebRTC 세션 만들기는 생성 요청의 session 필드로 보냅니다. 둘 다 세션 개체에서 제공합니다 model .

{
  "model": "gpt-live-1",
  "instructions": "Answer briefly and ask before taking an external action.",
  "audio": {
    "output": { "voice": "marin" }
  },
  "delegation": {
    "type": "responses",
    "responses": {
      "model": "gpt-5.5",
      "instructions": "Use tools when current information is required.",
      "max_output_tokens": 2048,
      "service_tier": "priority",
      "reasoning": { "effort": "medium", "summary": "auto" },
      "text": { "verbosity": "low" },
      "tools": [
        { "type": "web_search" },
        {
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location.",
          "parameters": {
            "type": "object",
            "properties": { "location": { "type": "string" } },
            "required": ["location"],
            "additionalProperties": false
          }
        }
      ],
      "tool_choice": "auto",
      "parallel_tool_calls": true
    }
  }
}

Field	Notes
`model`	Required. WebSocket `session.start` 및 WebRTC 만들기 모두에 대한 세션 개체에서 설정합니다. 시작 후 변경할 수 없습니다.
`instructions`	시스템 지침입니다. 시작 후 변경할 수 없음; 를 사용하여 `session.instructions.append`더 추가합니다.
`audio.output.voice`	출력 음성입니다. 기본값은 `marin` 시작 후 변경할 수 없습니다.
`delegation`	`{ type: "client" }` 또는 `{ type: "responses", responses: {...} }` 중 하나입니다. 클라이언트 위임을 생략하거나 `null` 선택합니다.
`delegation.responses.service_tier`	수락, `default`또는 `flexpriority`.`auto`
`delegation.responses.tools`	일반 도구 항목으로 구성된 함수 및 호스트된 도구(예 `web_search`:

라이브 세션 업데이트

시작 session.update 후 스파스입니다. 생략된 필드는 현재 값을 유지하고 설정만 delegation.responses 변경할 수 있습니다. 위임은 하나의 전체 개체로 대체됩니다. 중첩된 위임 필드는 독립적으로 패치되지 않습니다. 시작 필드 model, instructions및 inputaudio 업데이트 필드가 아닙니다.

성공적인 업데이트는 전체 공개 세션 리소스를 사용하여 생성됩니다 session.updated . 성공적인 승인은 에코 event_id되지 않고 상관 관계에만 사용됩니다 client_event_id .

오디오 형식

WebSocket 입력 및 출력은 24,000Hz에서 샘플링된 원시, 헤더리스, 모노, 서명된 16비트 little-endian PCM을 사용합니다. WAV 파일이나 다른 오디오 컨테이너가 아닌 원시 PCM 바이트를 Base64로 인코딩합니다. 각 샘플은 2바이트이므로 디코딩된 페이로드는 짝수 바이트를 포함해야 합니다.

WebRTC에서 오디오는 JSON 오디오 이벤트 대신 협상된 미디어 트랙을 사용하며 JSON 타이밍 필드를 전달하지 않습니다.

클라이언트 이벤트

이벤트	Transport	설명
`session.start`	WebSocket	초기 세션 구성을 보내고 생성합니다 `session.started`.
`session.update`	모든 JSON 스트림	스파스 업데이트를 적용하고 `delegation.responses` 생성합니다 `session.updated`.
`session.input_audio.append`	WebSocket만	비어있지 않은 base64 PCM16 모노 오디오를 추가합니다. 승인되지 않습니다.
`session.input_audio.mute` / `session.input_audio.unmute`	모든 JSON 스트림	호출자 입력을 음소거하거나 음소거 해제하고 생성합니다 `session.input_audio.muted` / `session.input_audio.unmuted`.
`session.instructions.append`	모든 JSON 스트림	신뢰할 수 있는 지침을 추가하고 생성합니다 `session.instructions.appended`.
`session.thinking.append`	모든 JSON 스트림	조용한 컨텍스트를 추가하고 생성합니다 `session.thinking.appended`.
`session.commentary.append`	모든 JSON 스트림	모델에 대한 콘텐츠를 추가하여 말하고 생성합니다 `session.commentary.appended`.
`response.item.create`	모든 JSON 스트림	응답 위임을 사용하여 백 엔드에 대한 함수 결과 또는 사용자 메시지를 제출합니다.
`response.create`	모든 JSON 스트림	응답 위임을 사용하여 백 엔드 응답을 실행하거나 계속합니다.
`session.close`	모든 JSON 스트림	정상 종료를 시작하고 생성한 `session.closed`다음 전송을 닫습니다.

session.instructions.append, session.thinking.append및 session.commentary.append 이벤트는 각각 최대 500개의 토큰과 필수 delegation_id토큰의 일반 문자열 content 을 사용합니다. 일반 세션 컨텍스트 또는 클라이언트 위임 ID를 사용하여 null 해당 작업을 업데이트합니다.

서버 이벤트

이벤트	설명
`session.started`	시작 구성.
`session.updated`	이후 스파스 업데이트가 적용되었습니다. 에는 전체 공개 세션 리소스가 포함되어 있습니다.
`session.output_audio.delta`	Timed base64로 인코딩된 원시 모노 24kHz 서명 PCM16 little-endian 출력 오디오(WebSocket만 해당).
`session.input_transcript.delta` / `session.output_transcript.delta`	시간 제한 입력 또는 출력 기록 조각입니다.
`session.instructions.appended` / `session.thinking.appended` / `session.commentary.appended`	삽입을 위해 컨텍스트 추가가 허용되었습니다.
`session.input_audio.muted` / `session.input_audio.unmuted`	음소거 또는 음소거 해제 명령이 적용되었습니다.
`session.delegation.created`	GPT-Live 위임된 작업의 클라이언트 또는 응답 대상 단위를 만들었습니다.
`response.event`	중첩된 응답 위임 이벤트를 전달하는 봉투; 중첩된 `event.type` 디스패치를 수행하고 외부를 유지합니다 `delegation_id`.
`session.usage.updated`	분당 약 1회 내보내는 누적 세션 사용량입니다.
`session.closed`	최종 누적 사용량 및 `reason`을 포함하여 정상 종료가 완료되었습니다.
`error`	시작, 유효성 검사, 명령 또는 위임된 응답 오류; `error.client_event_id` 는 실패한 명령과 상관 관계가 있습니다.

session.started

{
  "type": "session.started",
  "session": {
    "id": "sess_123",
    "expires_at": 1782518400,
    "model": "gpt-live-1",
    "instructions": "Be concise.",
    "audio": { "output": { "voice": "marin" } },
    "delegation": { "type": "client" }
  }
}

session.output_audio.delta

start_ms 서버 end_ms 타임라인을 사용하므로 범위 간의 간격은 생략된 침묵을 나타냅니다. 출력 오디오 완료 이벤트는 없습니다.

{
  "type": "session.output_audio.delta",
  "delta": "<base64-encoded-24khz-pcm16le-mono-audio>",
  "start_ms": 0,
  "end_ms": 100
}

session.input_transcript.delta / session.output_transcript.delta

각 이벤트는 세션 타임라인에 범위가 있는 start_ms / end_ms 조각을 전달 delta 합니다. 조각 경계는 의미 체계 턴 경계가 아닌 오디오 주기를 반영하며 사용자 및 도우미 조각은 인터리브할 수 있습니다.

{
  "type": "session.input_transcript.delta",
  "delta": "What is the",
  "start_ms": 600,
  "end_ms": 800
}

session.delegation.created

개체는 delegation 다음typetarget을 수행합니다.id 클라이언트 위임의 delegation_id 경우 이후 session.commentary.append 또는 session.thinking.append 이벤트로 사용합니다delegation.id. 응답 위임 response_id 의 경우 봉투에 나오는 응답 수명 주기에 response.event 위임을 바인딩합니다. 전체 흐름 은 GPT-Live의 대리자 작업을 참조하세요.

{
  "type": "session.delegation.created",
  "offset_ms": 1000,
  "delegation": {
    "id": "item_delegation_123",
    "type": "delegation",
    "target": "client"
  }
}

session.usage.updated / session.closed

session.usage.updated 는 컨텍스트 창 사용률과 함께 누적 음성 지속 시간(초)을 보고합니다. 합계가 아니라 스냅샷을 실행합니다. session.closed 는 최종 사용량과 .를 reason전달합니다.

{
  "type": "session.usage.updated",
  "usage": { "seconds": 12 },
  "context_window": { "usage_ratio": 0.42 }
}

{
  "type": "session.closed",
  "reason": "close_requested",
  "usage": { "seconds": 128 }
}

이 reason 필드는 세션이 종료connection_lostclose_requestedexpiredcontentremote_hangup된 이유를 설명합니다. 백 엔드 토큰 사용은 별개입니다. 에 전달된 중첩된 response.completed 이벤트에서 읽습니다 response.event.

오류 처리

모든 GPT-Live 오류는 하나의 오류 봉투를 사용합니다. error.client_event_id 는 오류가 클라이언트 명령과 상관될 수 있는 경우에만 존재합니다. param 은 특정 필드가 실패를 일으키지 않을 때 생략됩니다. 시작 오류로 인해 .session.started 명령 오류가 이미 시작된 세션을 반드시 닫는 것은 아닙니다.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_audio",
    "message": "PCM16 audio must contain an even number of bytes",
    "param": "audio",
    "client_event_id": "event_audio_1"
  }
}

WebSocket 수명 주기 완료

// 1. Client startup
{ "type": "session.start",
  "session": {
    "model": "gpt-live-1",
    "instructions": "Be concise.",
    "delegation": { "type": "client" }
  }
}

// 2. Server startup acknowledgment
{ "type": "session.started",
  "session": {
    "id": "sess_123",
    "model": "gpt-live-1",
    "instructions": "Be concise.",
    "audio": { "output": { "voice": "marin" } },
    "delegation": { "type": "client" }
  }
}

// 3. Client audio, repeated as data becomes available
{ "type": "session.input_audio.append",
  "audio": "<base64-encoded-24khz-pcm16le-mono-audio>"
}

// 4. Server events may interleave
{ "type": "session.input_transcript.delta",
  "delta": "Hello",
  "start_ms": 600,
  "end_ms": 800
}
{ "type": "session.output_audio.delta",
  "delta": "<base64-encoded-24khz-pcm16le-mono-audio>",
  "start_ms": 0,
  "end_ms": 100
}

// 5. Client shutdown; keep reading until session.closed
{ "type": "session.close" }

피드백

이 페이지가 도움이 되었나요?

2026-09-11 에 마지막으로 업데이트됨