# Sessions

## Accept call

**post** `/live/sessions/{session_id}/accept`

Accept an incoming SIP call. Supply session with type live, the model, and startup configuration. Before accepting calls, follow the [Live prompting guide](/api/docs/guides/live-prompting) to write frontend conversation instructions and a separate backend prompt. SIP media format is negotiated; omit audio.format.

### Path Parameters

- `session_id: string`

### Body Parameters

- `session: object { model, type, audio, 4 more }`

  Model and startup configuration for the Live session that answers the incoming SIP call.

  - `model: string or "gpt-live-1"`

    The Live model to use for the accepted call.

    - `string`

    - `"gpt-live-1"`

      The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter.

      - `"gpt-live-1"`

  - `type: "live"`

    The session type. Always `live`.

    - `"live"`

  - `audio: optional object { output }`

    Startup audio output configuration. SIP negotiates the media format; audio.format is only accepted for primary WebSockets. Voice cannot change after startup.

    - `output: optional object { voice }`

      Settings for speech generated by the Live model. Choose the voice before starting the session.

      - `voice: optional string or "alloy" or "ash" or "ballad" or 19 more or CustomVoice`

        The voice used for Live speech, as a built-in voice name or a custom voice object containing its ID. Defaults to `marin` and cannot change after startup.

        - `string`

        - `"alloy" or "ash" or "ballad" or 19 more`

          The voice used for Live speech, as a built-in voice name or a custom voice object containing its ID. Defaults to `marin` and cannot change after startup.

          - `"alloy"`

          - `"ash"`

          - `"ballad"`

          - `"beacon"`

          - `"bossa"`

          - `"cedar"`

          - `"cinder"`

          - `"coral"`

          - `"delta"`

          - `"echo"`

          - `"gleam"`

          - `"marin"`

          - `"meridian"`

          - `"quartz"`

          - `"ripple"`

          - `"sage"`

          - `"shimmer"`

          - `"stone"`

          - `"tempo"`

          - `"verse"`

          - `"vesper"`

          - `"willow"`

        - `CustomVoice object { id }`

          - `id: string`

  - `delegation: optional ClientDelegation or object { responses, type }  or null`

    Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend.

    - `ClientDelegation object { type }`

      Delegate tasks to your application. The Live session emits delegation events that your backend handles.

      - `type: "client"`

        The delegation owner. Always `client` for tasks handled by your application.

        - `"client"`

    - `Responses object { responses, type }`

      Delegate tasks to a Responses model managed by the Live session.

      - `responses: ResponsesDelegationConfig`

        Backend model, prompt, and tools used when the Live session delegates a task to Responses.

        - `model: string`

          The model used for server-owned Responses delegations.

        - `instructions: optional string or null`

          Instructions for the delegated Responses model, separate from Live instructions. See [backend prompting](/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt).

        - `max_output_tokens: optional number or null`

          Maximum number of output tokens for each delegated response.

        - `parallel_tool_calls: optional boolean or null`

          Whether the delegated Responses model may request multiple tool calls in a single response.

        - `reasoning: optional object { effort, summary }  or null`

          Reasoning settings passed to each delegated Responses request.

          - `effort: optional "none" or "minimal" or "low" or 3 more or null`

            How much reasoning effort the delegated Responses model should use. Supported values depend on the backend model.

            - `"none"`

            - `"minimal"`

            - `"low"`

            - `"medium"`

            - `"high"`

            - `"xhigh"`

          - `summary: optional "concise" or "detailed" or "auto" or null`

            The reasoning summary to request from the delegated Responses model, when supported.

            - `"concise"`

            - `"detailed"`

            - `"auto"`

        - `service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or null`

          Service tier for delegated Responses requests.

          - `"auto"`

          - `"default"`

          - `"fast_tier_temp_pilot"`

          - `"flex"`

          - `"priority"`

          - `"ultrafast"`

        - `text: optional object { verbosity }  or null`

          Text generation settings passed to each delegated Responses request.

          - `verbosity: optional "low" or "medium" or "high" or null`

            The amount of detail in text generated by the Responses backend. This does not configure the Live model’s spoken delivery.

            - `"low"`

            - `"medium"`

            - `"high"`

        - `tool_choice: optional "auto" or "none" or "required" or object { name, type }  or object { name, server_label, type }`

          Controls which tool the Responses backend uses when handling a task delegated by the Live model.

          - `LiveToolChoiceEnum = "auto" or "none" or "required"`

            - `"auto"`

            - `"none"`

            - `"required"`

          - `LiveFunctionToolChoiceParam object { name, type }`

            - `name: string`

            - `type: "function"`

              - `"function"`

          - `LiveMCPToolChoiceParam object { name, server_label, type }`

            - `name: string`

            - `server_label: string`

            - `type: "mcp"`

              - `"mcp"`

        - `tools: optional array of FunctionTool or object { type }`

          Tools available to the Responses backend while it handles tasks delegated by the Live model.

          - `FunctionTool object { name, type, description, 2 more }`

            A function tool available to the Responses backend when the Live model delegates a task.

            - `name: string`

              The name the delegated Responses model uses when calling this function.

            - `type: "function"`

              The tool type. Always `function`.

              - `"function"`

            - `description: optional string or null`

              What the function does and when the delegated Responses model should call it.

            - `parameters: optional map[unknown] or null`

              A JSON Schema object describing the arguments accepted by the function.

            - `strict: optional boolean or null`

              Whether the delegated Responses model must follow the function’s parameter schema exactly.

          - `WebSearch object { type }`

            A web search tool available to the Live session’s Responses backend.

            - `type: "web_search"`

              The tool type. Always `web_search`.

              - `"web_search"`

      - `type: "responses"`

        The delegation owner. Always `responses` for tasks handled by the Responses API.

        - `"responses"`

  - `input: optional array of InitialItem`

    Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total.

    - `Developer object { content, role, id, 2 more }`

      A developer message included in the initial text history of a Live session.

      - `content: array of object { text, type }`

        The message content. Supply exactly one text part for the initial Live conversation history.

        - `text: string`

          The message text to include in the Live session’s initial conversation history.

        - `type: optional "input_text"`

          The text content type. Always `input_text`.

          - `"input_text"`

      - `role: "developer"`

        The author of this history message. Always `developer`.

        - `"developer"`

      - `id: optional string or null`

        An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.

      - `status: optional "incomplete" or "completed" or null`

        The supplied message’s status. Live uses its text as history and does not resume an incomplete message.

        - `"incomplete"`

        - `"completed"`

      - `type: optional "message"`

        The history item type. Always `message`.

        - `"message"`

    - `User object { content, role, id, 2 more }`

      A user message included in the initial text history of a Live session.

      - `content: array of object { text, type }`

        The message content. Supply exactly one text part for the initial Live conversation history.

        - `text: string`

          The message text to include in the Live session’s initial conversation history.

        - `type: optional "input_text"`

          The text content type. Always `input_text`.

          - `"input_text"`

      - `role: "user"`

        The author of this history message. Always `user`.

        - `"user"`

      - `id: optional string or null`

        An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.

      - `status: optional "incomplete" or "completed" or null`

        The supplied message’s status. Live uses its text as history and does not resume an incomplete message.

        - `"incomplete"`

        - `"completed"`

      - `type: optional "message"`

        The history item type. Always `message`.

        - `"message"`

    - `Assistant object { content, role, id, 2 more }`

      An assistant message included in the initial text history of a Live session.

      - `content: array of object { text, type }  or object { text, type }`

        The message content. Supply exactly one text part for the initial Live conversation history.

        - `Text object { text, type }`

          Assistant text supplied as conversation history when starting a Live session.

          - `text: string`

            The message text to include in the Live session’s initial conversation history.

          - `type: optional "text"`

            The text content type. Always `text`.

            - `"text"`

        - `OutputText object { text, type }`

          Assistant output text supplied as conversation history when starting a Live session.

          - `text: string`

            The message text to include in the Live session’s initial conversation history.

          - `type: "output_text"`

            The text content type. Always `output_text`.

            - `"output_text"`

      - `role: "assistant"`

        The author of this history message. Always `assistant`.

        - `"assistant"`

      - `id: optional string or null`

        An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.

      - `status: optional "incomplete" or "completed" or null`

        The supplied message’s status. Live uses its text as history and does not resume an incomplete message.

        - `"incomplete"`

        - `"completed"`

      - `type: optional "message"`

        The history item type. Always `message`.

        - `"message"`

  - `instructions: optional string or null`

    Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup.

  - `store: optional boolean`

    Whether to store the session for later forking and recording download. Defaults to false for new sessions.

### Example

```http
curl https://api.openai.com/v1/live/sessions/$SESSION_ID/accept \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "session": {
            "model": "gpt-live-1",
            "type": "live"
          }
        }'
```

## Download recording

**get** `/live/sessions/{session_id}/content`

Get Live session content

### Path Parameters

- `session_id: string`

  The ID of the stored Live session to download. Use the session ID returned when the session started with storage enabled.

### Example

```http
curl https://api.openai.com/v1/live/sessions/$SESSION_ID/content \
    -H "Authorization: Bearer $OPENAI_API_KEY"
```

## Fork session

**post** `/live/sessions/{session_id}/fork`

Fork a stored Live session onto a new WebRTC connection.

### Path Parameters

- `session_id: string`

### Body Parameters

- `transport: object { sdp, type }`

  WebRTC transport with an SDP offer for the new connection to the forked session.

  - `sdp: string`

    Session Description Protocol message for the WebRTC connection.

  - `type: "webrtc"`

    The transport used for the Live session. Always `webrtc`.

    - `"webrtc"`

- `session: optional MediaSessionForkConfig`

  Optional configuration overrides for the new Live session. Omit this object or send an empty object to inherit the stored session's settings.

  - `client: optional ClientConfig`

    Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected.

    - `data_channel: DataChannelConfig`

      Client and server event permissions for the WebRTC frontend data channel.

      - `allowed_client_events: optional "all" or array of string`

        Client event types that the frontend data channel may send. Use 'all' to allow every client event; an empty array allows none. Omission preserves the existing allow-all behavior.

        - `"all"`

          - `"all"`

        - `array of string`

      - `allowed_server_events: optional "all" or array of ServerEventSelector`

        Server events that may be sent to the frontend data channel. Use 'all' to allow every server event; an empty array allows none. Omission preserves the existing allow-all behavior. Responses events use an object with type 'response.event' and a response_event selector.

        - `"all"`

          - `"all"`

        - `array of ServerEventSelector`

          - `type: string`

            The outer Live server event type. Use 'response.event' for Responses events.

          - `response_event: optional string`

            The nested Responses event type. Required when type is 'response.event'; forbidden for other event types.

  - `delegation: optional object { type, responses }`

    Update the Responses backend for an existing Live session without changing delegation ownership.

    - `type: "responses"`

      The delegation owner. Always `responses` for tasks handled by the Responses API.

      - `"responses"`

    - `responses: optional ResponsesDelegationUpdateConfig`

      Responses backend settings to update. Omitted settings keep their existing values.

      - `instructions: optional string or null`

        Instructions for the delegated Responses model, separate from Live instructions. See [backend prompting](/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt).

      - `max_output_tokens: optional number or null`

        Maximum number of output tokens for each delegated response.

      - `model: optional string`

        The Responses backend model to use for subsequent delegated requests. Omit to keep the current backend model.

      - `parallel_tool_calls: optional boolean or null`

        Whether the delegated Responses model may request multiple tool calls in a single response.

      - `reasoning: optional object { effort, summary }  or null`

        Reasoning settings passed to each delegated Responses request.

        - `effort: optional "none" or "minimal" or "low" or 3 more or null`

          How much reasoning effort the delegated Responses model should use. Supported values depend on the backend model.

          - `"none"`

          - `"minimal"`

          - `"low"`

          - `"medium"`

          - `"high"`

          - `"xhigh"`

        - `summary: optional "concise" or "detailed" or "auto" or null`

          The reasoning summary to request from the delegated Responses model, when supported.

          - `"concise"`

          - `"detailed"`

          - `"auto"`

      - `service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or null`

        Service tier for delegated Responses requests.

        - `"auto"`

        - `"default"`

        - `"fast_tier_temp_pilot"`

        - `"flex"`

        - `"priority"`

        - `"ultrafast"`

      - `text: optional object { verbosity }  or null`

        Text generation settings passed to each delegated Responses request.

        - `verbosity: optional "low" or "medium" or "high" or null`

          The amount of detail in text generated by the Responses backend. This does not configure the Live model’s spoken delivery.

          - `"low"`

          - `"medium"`

          - `"high"`

      - `tool_choice: optional "auto" or "none" or "required" or object { name, type }  or object { name, server_label, type }`

        Controls which tool the Responses backend uses when handling a task delegated by the Live model.

        - `LiveToolChoiceEnum = "auto" or "none" or "required"`

          - `"auto"`

          - `"none"`

          - `"required"`

        - `LiveFunctionToolChoiceParam object { name, type }`

          - `name: string`

          - `type: "function"`

            - `"function"`

        - `LiveMCPToolChoiceParam object { name, server_label, type }`

          - `name: string`

          - `server_label: string`

          - `type: "mcp"`

            - `"mcp"`

      - `tools: optional array of FunctionTool or object { type }`

        Tools available to the Responses backend while it handles tasks delegated by the Live model.

        - `FunctionTool object { name, type, description, 2 more }`

          A function tool available to the Responses backend when the Live model delegates a task.

          - `name: string`

            The name the delegated Responses model uses when calling this function.

          - `type: "function"`

            The tool type. Always `function`.

            - `"function"`

          - `description: optional string or null`

            What the function does and when the delegated Responses model should call it.

          - `parameters: optional map[unknown] or null`

            A JSON Schema object describing the arguments accepted by the function.

          - `strict: optional boolean or null`

            Whether the delegated Responses model must follow the function’s parameter schema exactly.

        - `WebSearch object { type }`

          A web search tool available to the Live session’s Responses backend.

          - `type: "web_search"`

            The tool type. Always `web_search`.

            - `"web_search"`

  - `store: optional boolean`

    Whether to store the forked session. Omission inherits the stored session's setting.

### Returns

- `session: object { id }`

  The newly created Live session. Use its ID for session controls and sideband connections.

  - `id: string`

    Opaque session identifier. Preserve the returned value unchanged, including its prefix.

- `transport: object { sdp, type }`

  WebRTC transport with the SDP answer.

  - `sdp: string`

    Session Description Protocol message for the WebRTC connection.

  - `type: "webrtc"`

    The transport used for the Live session. Always `webrtc`.

    - `"webrtc"`

### Example

```http
curl https://api.openai.com/v1/live/sessions/$SESSION_ID/fork \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "transport": {
            "sdp": "x",
            "type": "webrtc"
          }
        }'
```

#### Response

```json
{
  "session": {
    "id": "id"
  },
  "transport": {
    "sdp": "x",
    "type": "webrtc"
  }
}
```

### Example

```http
curl https://api.openai.com/v1/live/sessions/live_123/fork \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session":{},"transport":{"type":"webrtc","sdp":"<SDP offer>"}}'
```

## Hang up session

**post** `/live/sessions/{session_id}/hangup`

End a SIP call identified by session_id.

### Path Parameters

- `session_id: string`

### Example

```http
curl https://api.openai.com/v1/live/sessions/$SESSION_ID/hangup \
    -X POST \
    -H "Authorization: Bearer $OPENAI_API_KEY"
```

## Transfer call

**post** `/live/sessions/{session_id}/refer`

Transfer a SIP call to another destination. Supply a nonblank target_uri for the SIP Refer-To header.

### Path Parameters

- `session_id: string`

### Body Parameters

- `target_uri: string`

  Nonblank URI for the SIP Refer-To header, such as tel:+14155550123 or sip:agent@example.com.

### Example

```http
curl https://api.openai.com/v1/live/sessions/$SESSION_ID/refer \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "target_uri": "tel:+14155550123"
        }'
```

## Reject call

**post** `/live/sessions/{session_id}/reject`

Reject an incoming SIP call. Send a required SIP rejection status_code between 300 and 699.

### Path Parameters

- `session_id: string`

### Body Parameters

- `status_code: number`

  SIP rejection status sent to the caller. This field is required.

### Example

```http
curl https://api.openai.com/v1/live/sessions/$SESSION_ID/reject \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "status_code": 486
        }'
```

## Domain Types

### Session Fork Response

- `SessionForkResponse object { session, transport }`

  The created Live session identifier and WebRTC answer. Apply transport.sdp as the peer's remote answer and wait for session.started on the data channel before sending commands.

  - `session: object { id }`

    The newly created Live session. Use its ID for session controls and sideband connections.

    - `id: string`

      Opaque session identifier. Preserve the returned value unchanged, including its prefix.

  - `transport: object { sdp, type }`

    WebRTC transport with the SDP answer.

    - `sdp: string`

      Session Description Protocol message for the WebRTC connection.

    - `type: "webrtc"`

      The transport used for the Live session. Always `webrtc`.

      - `"webrtc"`