OpenAI Realtime API

openapi: 3.2.0
info:
  title: OpenAI Realtime API
  description: The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details.
  version: 2.3.0
  termsOfService: https://openai.com/policies/terms-of-use
  contact:
    name: OpenAI Support
    url: https://help.openai.com/
  license:
    name: MIT
    url: https://github.com/openai/openai-openapi/blob/master/LICENSE
servers:
- url: https://api.openai.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Realtime
paths:
  /realtime/calls:
    post:
      summary: 'Create a new Realtime API call over WebRTC and receive the SDP answer needed

        to complete the peer connection.'
      operationId: create-realtime-call
      tags:
      - Realtime
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RealtimeCallCreateRequest'
            encoding:
              sdp:
                contentType: application/sdp
              session:
                contentType: application/json
          application/sdp:
            schema:
              type: string
              description: 'WebRTC SDP offer. Use this variant when you have previously created an

                ephemeral **session token** and are authenticating the request with it.

                Realtime session parameters will be retrieved from the session token.'
      responses:
        '201':
          description: Realtime call created successfully.
          headers:
            Location:
              description: Relative URL containing the call ID for subsequent control requests.
              schema:
                type: string
          content:
            application/sdp:
              schema:
                type: string
                description: SDP answer produced by OpenAI for the peer connection.
      x-oaiMeta:
        name: Create call
        group: realtime
        returns: 'Returns `201 Created` with the SDP answer in the response body. The

          `Location` response header includes the call ID for follow-up requests,

          e.g., establishing a monitoring WebSocket or hanging up the call.'
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/realtime/calls \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -F \"sdp=<offer.sdp;type=application/sdp\" \\\n  -F 'session={\"type\":\"realtime\",\"model\":\"gpt-realtime\"};type=application/json'"
            python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ.get(\"OPENAI_API_KEY\"),  # This is the default and can be omitted\n)\ncall = client.realtime.calls.create(\n    sdp=\"sdp\",\n)\nprint(call)\ncontent = call.read()\nprint(content)"
          response: 'v=0

            o=- 4227147428 1719357865 IN IP4 127.0.0.1

            s=-

            c=IN IP4 0.0.0.0

            t=0 0

            a=group:BUNDLE 0 1

            a=msid-semantic:WMS *

            a=fingerprint:sha-256 CA:92:52:51:B4:91:3B:34:DD:9C:0B:FB:76:19:7E:3B:F1:21:0F:32:2C:38:01:72:5D:3F:78:C7:5F:8B:C7:36

            m=audio 9 UDP/TLS/RTP/SAVPF 111 0 8

            a=mid:0

            a=ice-ufrag:kZ2qkHXX/u11

            a=ice-pwd:uoD16Di5OGx3VbqgA3ymjEQV2kwiOjw6

            a=setup:active

            a=rtcp-mux

            a=rtpmap:111 opus/48000/2

            a=candidate:993865896 1 udp 2130706431 4.155.146.196 3478 typ host ufrag kZ2qkHXX/u11

            a=candidate:1432411780 1 tcp 1671430143 4.155.146.196 443 typ host tcptype passive ufrag kZ2qkHXX/u11

            m=application 9 UDP/DTLS/SCTP webrtc-datachannel

            a=mid:1

            a=sctp-port:5000'
  /realtime/calls/{call_id}/accept:
    post:
      summary: 'Accept an incoming SIP call and configure the realtime session that will

        handle it.'
      operationId: accept-realtime-call
      tags:
      - Realtime
      parameters:
      - in: path
        name: call_id
        required: true
        schema:
          type: string
        description: 'The identifier for the call provided in the

          [`realtime.call.incoming`](/docs/api-reference/webhook-events/realtime/call/incoming)

          webhook.'
      requestBody:
        required: true
        description: Session configuration to apply before the caller is bridged to the model.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeSessionCreateRequestGA'
      responses:
        '200':
          description: Call accepted successfully.
      x-oaiMeta:
        name: Accept call
        group: realtime-calls
        returns: 'Returns `200 OK` once OpenAI starts ringing the SIP leg with the supplied

          session configuration.'
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/realtime/calls/$CALL_ID/accept \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"type\": \"realtime\",\n        \"model\": \"gpt-realtime\",\n        \"instructions\": \"You are Alex, a friendly concierge for Example Corp.\",\n      }'"
            node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.realtime.calls.accept('call_id', { type: 'realtime' });"
            python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ.get(\"OPENAI_API_KEY\"),  # This is the default and can be omitted\n)\nclient.realtime.calls.accept(\n    call_id=\"call_id\",\n    type=\"realtime\",\n)"
            go: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n\t\"github.com/openai/openai-go/realtime\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Realtime.Calls.Accept(\n\t\tcontext.TODO(),\n\t\t\"call_id\",\n\t\trealtime.CallAcceptParams{\n\t\t\tRealtimeSessionCreateRequest: realtime.RealtimeSessionCreateRequestParam{},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
            java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.realtime.RealtimeSessionCreateRequest;\nimport com.openai.models.realtime.calls.CallAcceptParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n        CallAcceptParams params = CallAcceptParams.builder()\n            .callId(\"call_id\")\n            .realtimeSessionCreateRequest(RealtimeSessionCreateRequest.builder().build())\n            .build();\n        client.realtime().calls().accept(params);\n    }\n}"
            ruby: 'require "openai"


              openai = OpenAI::Client.new(api_key: "My API Key")


              result = openai.realtime.calls.accept("call_id", type: :realtime)


              puts(result)'
          response: ''
  /realtime/calls/{call_id}/hangup:
    post:
      summary: 'End an active Realtime API call, whether it was initiated over SIP or

        WebRTC.'
      operationId: hangup-realtime-call
      tags:
      - Realtime
      parameters:
      - in: path
        name: call_id
        required: true
        schema:
          type: string
        description: 'The identifier for the call. For SIP calls, use the value provided in the

          [`realtime.call.incoming`](/docs/api-reference/webhook-events/realtime/call/incoming)

          webhook. For WebRTC sessions, reuse the call ID returned in the `Location`

          header when creating the call with

          [`POST /v1/realtime/calls`](/docs/api-reference/realtime/create-call).'
      responses:
        '200':
          description: Call hangup initiated successfully.
      x-oaiMeta:
        name: Hang up call
        group: realtime-calls
        returns: Returns `200 OK` when OpenAI begins terminating the realtime call.
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/realtime/calls/$CALL_ID/hangup \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\""
            node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.realtime.calls.hangup('call_id');"
            python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ.get(\"OPENAI_API_KEY\"),  # This is the default and can be omitted\n)\nclient.realtime.calls.hangup(\n    \"call_id\",\n)"
            go: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Realtime.Calls.Hangup(context.TODO(), \"call_id\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
            java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.realtime.calls.CallHangupParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n        client.realtime().calls().hangup(\"call_id\");\n    }\n}"
            ruby: 'require "openai"


              openai = OpenAI::Client.new(api_key: "My API Key")


              result = openai.realtime.calls.hangup("call_id")


              puts(result)'
          response: ''
  /realtime/calls/{call_id}/refer:
    post:
      summary: Transfer an active SIP call to a new destination using the SIP REFER verb.
      operationId: refer-realtime-call
      tags:
      - Realtime
      parameters:
      - in: path
        name: call_id
        required: true
        schema:
          type: string
        description: 'The identifier for the call provided in the

          [`realtime.call.incoming`](/docs/api-reference/webhook-events/realtime/call/incoming)

          webhook.'
      requestBody:
        required: true
        description: Destination URI for the REFER request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeCallReferRequest'
      responses:
        '200':
          description: Call referred successfully.
      x-oaiMeta:
        name: Refer call
        group: realtime-calls
        returns: Returns `200 OK` once the REFER is handed off to your SIP provider.
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/realtime/calls/$CALL_ID/refer \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"target_uri\": \"tel:+14155550123\"}'"
            node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.realtime.calls.refer('call_id', { target_uri: 'tel:+14155550123' });"
            python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ.get(\"OPENAI_API_KEY\"),  # This is the default and can be omitted\n)\nclient.realtime.calls.refer(\n    call_id=\"call_id\",\n    target_uri=\"tel:+14155550123\",\n)"
            go: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n\t\"github.com/openai/openai-go/realtime\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Realtime.Calls.Refer(\n\t\tcontext.TODO(),\n\t\t\"call_id\",\n\t\trealtime.CallReferParams{\n\t\t\tTargetUri: \"tel:+14155550123\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
            java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.realtime.calls.CallReferParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n        CallReferParams params = CallReferParams.builder()\n            .callId(\"call_id\")\n            .targetUri(\"tel:+14155550123\")\n            .build();\n        client.realtime().calls().refer(params);\n    }\n}"
            ruby: 'require "openai"


              openai = OpenAI::Client.new(api_key: "My API Key")


              result = openai.realtime.calls.refer("call_id", target_uri: "tel:+14155550123")


              puts(result)'
          response: ''
  /realtime/calls/{call_id}/reject:
    post:
      summary: Decline an incoming SIP call by returning a SIP status code to the caller.
      operationId: reject-realtime-call
      tags:
      - Realtime
      parameters:
      - in: path
        name: call_id
        required: true
        schema:
          type: string
        description: 'The identifier for the call provided in the

          [`realtime.call.incoming`](/docs/api-reference/webhook-events/realtime/call/incoming)

          webhook.'
      requestBody:
        required: false
        description: 'Provide an optional SIP status code. When omitted the API responds with

          `603 Decline`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeCallRejectRequest'
      responses:
        '200':
          description: Call rejected successfully.
      x-oaiMeta:
        name: Reject call
        group: realtime-calls
        returns: Returns `200 OK` after OpenAI sends the SIP status code to the caller.
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/realtime/calls/$CALL_ID/reject \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"status_code\": 486}'"
            node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.realtime.calls.reject('call_id');"
            python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ.get(\"OPENAI_API_KEY\"),  # This is the default and can be omitted\n)\nclient.realtime.calls.reject(\n    call_id=\"call_id\",\n)"
            go: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n\t\"github.com/openai/openai-go/realtime\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Realtime.Calls.Reject(\n\t\tcontext.TODO(),\n\t\t\"call_id\",\n\t\trealtime.CallRejectParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
            java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.realtime.calls.CallRejectParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n        client.realtime().calls().reject(\"call_id\");\n    }\n}"
            ruby: 'require "openai"


              openai = OpenAI::Client.new(api_key: "My API Key")


              result = openai.realtime.calls.reject("call_id")


              puts(result)'
          response: ''
  /realtime/client_secrets:
    post:
      summary: 'Create a Realtime client secret with an associated session configuration.


        Client secrets are short-lived tokens that can be passed to a client app,

        such as a web frontend or mobile client, which grants access to the Realtime API without

        leaking your main API key. You can configure a custom TTL for each client secret.


        You can also attach session configuration options to the client secret, which will be

        applied to any sessions created using that client secret, but these can also be overridden

        by the client connection.


        [Learn more about authentication with client secrets over WebRTC](/docs/guides/realtime-webrtc).


        Returns the created client secret and the effective session object. The client secret is a string that looks like `ek_1234`.

        '
      operationId: create-realtime-client-secret
      tags:
      - Realtime
      requestBody:
        description: Create a client secret with the given session configuration.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeCreateClientSecretRequest'
      responses:
        '200':
          description: Client secret created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeCreateClientSecretResponse'
      x-oaiMeta:
        name: Create client secret
        group: realtime
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/realtime/client_secrets \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"expires_after\": {\n      \"anchor\": \"created_at\",\n      \"seconds\": 600\n    },\n    \"session\": {\n      \"type\": \"realtime\",\n      \"model\": \"gpt-realtime\",\n      \"instructions\": \"You are a friendly assistant.\"\n    }\n  }'\n"
            node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted\n});\n\nconst clientSecret = await client.realtime.clientSecrets.create();\n\nconsole.log(clientSecret.expires_at);"
            python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ.get(\"OPENAI_API_KEY\"),  # This is the default and can be omitted\n)\nclient_secret = client.realtime.client_secrets.create()\nprint(client_secret.expires_at)"
            go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n\t\"github.com/openai/openai-go/realtime\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tclientSecret, err := client.Realtime.ClientSecrets.New(context.TODO(), realtime.ClientSecretNewParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", clientSecret.ExpiresAt)\n}\n"
            java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.realtime.clientsecrets.ClientSecretCreateParams;\nimport com.openai.models.realtime.clientsecrets.ClientSecretCreateResponse;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n        ClientSecretCreateResponse clientSecret = client.realtime().clientSecrets().create();\n    }\n}"
            ruby: 'require "openai"


              openai = OpenAI::Client.new(api_key: "My API Key")


              client_secret = openai.realtime.client_secrets.create


              puts(client_secret)'
          response: "{\n  \"value\": \"ek_68af296e8e408191a1120ab6383263c2\",\n  \"expires_at\": 1756310470,\n  \"session\": {\n    \"type\": \"realtime\",\n    \"object\": \"realtime.session\",\n    \"id\": \"sess_C9CiUVUzUzYIssh3ELY1d\",\n    \"model\": \"gpt-realtime\",\n    \"output_modalities\": [\n      \"audio\"\n    ],\n    \"instructions\": \"You are a friendly assistant.\",\n    \"tools\": [],\n    \"tool_choice\": \"auto\",\n    \"max_output_tokens\": \"inf\",\n    \"tracing\": null,\n    \"truncation\": \"auto\",\n    \"prompt\": null,\n    \"expires_at\": 0,\n    \"audio\": {\n      \"input\": {\n        \"format\": {\n          \"type\": \"audio/pcm\",\n          \"rate\": 24000\n        },\n        \"transcription\": null,\n        \"noise_reduction\": null,\n        \"turn_detection\": {\n          \"type\": \"server_vad\",\n        }\n      },\n      \"output\": {\n        \"format\": {\n          \"type\": \"audio/pcm\",\n          \"rate\": 24000\n        },\n        \"voice\": \"alloy\",\n        \"speed\": 1.0\n      }\n    },\n    \"include\": null\n  }\n}\n"
  /realtime/sessions:
    post:
      summary: 'Create an ephemeral API token for use in client-side applications with the

        Realtime API. Can be configured with the same session parameters as the

        `session.update` client event.


        It responds with a session object, plus a `client_secret` key which contains

        a usable ephemeral API token that can be used to authenticate browser clients

        for the Realtime API.


        Returns the created Realtime session object, plus an ephemeral key.

        '
      operationId: create-realtime-session
      tags:
      - Realtime
      requestBody:
        description: Create an ephemeral API key with the given session configuration.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeSessionCreateRequest'
      responses:
        '200':
          description: Session created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeSessionCreateResponse'
      x-oaiMeta:
        name: Create session
        group: realtime
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/realtime/sessions \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"gpt-realtime\",\n    \"modalities\": [\"audio\", \"text\"],\n    \"instructions\": \"You are a friendly assistant.\"\n  }'\n"
          response: "{\n  \"id\": \"sess_001\",\n  \"object\": \"realtime.session\",\n  \"model\": \"gpt-realtime-2025-08-25\",\n  \"modalities\": [\"audio\", \"text\"],\n  \"instructions\": \"You are a friendly assistant.\",\n  \"voice\": \"alloy\",\n  \"input_audio_format\": \"pcm16\",\n  \"output_audio_format\": \"pcm16\",\n  \"input_audio_transcription\": {\n      \"model\": \"whisper-1\"\n  },\n  \"turn_detection\": null,\n  \"tools\": [],\n  \"tool_choice\": \"none\",\n  \"temperature\": 0.7,\n  \"max_response_output_tokens\": 200,\n  \"speed\": 1.1,\n  \"tracing\": \"auto\",\n  \"client_secret\": {\n    \"value\": \"ek_abc123\", \n    \"expires_at\": 1234567890\n  }\n}\n"
  /realtime/transcription_sessions:
    post:
      summary: "Create an ephemeral API token for use in client-side applications with the\nRealtime API specifically for realtime transcriptions. \nCan be configured with the same session parameters as the `transcription_session.update` client event.\n\nIt responds with a session object, plus a `client_secret` key which contains\na usable ephemeral API token that can be used to authenticate browser clients\nfor the Realtime API.\n\nReturns the created Realtime transcription session object, plus an ephemeral key.\n"
      operationId: create-realtime-transcription-session
      tags:
      - Realtime
      requestBody:
        description: Create an ephemeral API key with the given session configuration.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeTranscriptionSessionCreateRequest'
      responses:
        '200':
          description: Session created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeTranscriptionSessionCreateResponse'
      x-oaiMeta:
        name: Create transcription session
        group: realtime
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/realtime/transcription_sessions \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'\n"
          response: "{\n  \"id\": \"sess_BBwZc7cFV3XizEyKGDCGL\",\n  \"object\": \"realtime.transcription_session\",\n  \"modalities\": [\"audio\", \"text\"],\n  \"turn_detection\": {\n    \"type\": \"server_vad\",\n    \"threshold\": 0.5,\n    \"prefix_padding_ms\": 300,\n    \"silence_duration_ms\": 200\n  },\n  \"input_audio_format\": \"pcm16\",\n  \"input_audio_transcription\": {\n    \"model\": \"gpt-4o-transcribe\",\n    \"language\": null,\n    \"prompt\": \"\"\n  },\n  \"client_secret\": null\n}\n"
  /realtime/translations/client_secrets:
    post:
      summary: 'Create a Realtime translation client secret with an associated translation session configuration.


        Client secrets are short-lived tokens that can be passed to a client app,

        such as a web frontend or mobile client, which grants access to the Realtime

        Translation API without leaking your main API key. You can configure a custom

        TTL for each client secret.


        Returns the created client secret and the effective translation session object.

        The client secret is a string that looks like `ek_1234`.

        '
      operationId: create-realtime-translation-client-secret
      tags:
      - Realtime
      requestBody:
        description: Create a client secret with the given translation session configuration.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeTranslationClientSecretCreateRequest'
      responses:
        '200':
          description: Translation client secret created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeTranslationClientSecretCreateResponse'
      x-oaiMeta:
        name: Create translation client secret
        group: realtime
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/realtime/translations/client_secrets \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"expires_after\": {\n      \"anchor\": \"created_at\",\n      \"seconds\": 600\n    },\n    \"session\": {\n      \"model\": \"gpt-realtime-translate\",\n      \"audio\": {\n        \"input\": {\n          \"transcription\": {\n            \"model\": \"gpt-realtime-whisper\"\n          },\n          \"noise_reduction\": null\n        },\n        \"output\": {\n          \"language\": \"es\"\n        }\n      }\n    }\n  }'\n"
          response: "{\n  \"value\": \"ek_68af296e8e408191a1120ab6383263c2\",\n  \"expires_at\": 1756310470,\n  \"session\": {\n    \"id\": \"sess_C9CiUVUzUzYIssh3ELY1d\",\n    \"type\": \"translation\",\n    \"expires_at\": 1756310470,\n    \"model\": \"gpt-realtime-translate\",\n    \"audio\": {\n      \"input\": {\n        \"transcription\": {\n          \"model\": \"gpt-realtime-whisper\"\n        },\n        \"noise_reduction\": null\n      },\n      \"output\": {\n        \"language\": \"es\"\n      }\n    }\n  }\n}\n"
components:
  schemas:
    RealtimeCreateClientSecretResponse:
      type: object
      title: Realtime session and client secret
      description: 'Response from creating a session and client secret for the Realtime API.

        '
      properties:
        value:
          type: string
          description: The generated client secret value.
        expires_at:
          type: integer
          format: unixtime
          description: Expiration timestamp for the client secret, in seconds since epoch.
        session:
          title: Session configuration
          description: 'The session configuration for either a realtime or transcription session.

            '
          oneOf:
          - $ref: '#/components/schemas/RealtimeSessionCreateResponseGA'
          - $ref: '#/components/schemas/RealtimeTranscriptionSessionCreateResponseGA'
          discriminator:
            propertyName: type
      required:
      - value
      - expires_at
      - session
      x-oaiMeta:
        name: Session response object
        group: realtime
        example: "{\n  \"value\": \"ek_68af296e8e408191a1120ab6383263c2\",\n  \"expires_at\": 1756310470,\n  \"session\": {\n    \"type\": \"realtime\",\n    \"object\": \"realtime.session\",\n    \"id\": \"sess_C9CiUVUzUzYIssh3ELY1d\",\n    \"model\": \"gpt-realtime-2025-08-25\",\n    \"output_modalities\": [\n      \"audio\"\n    ],\n    \"instructions\": \"You are a friendly assistant.\",\n    \"tools\": [],\n    \"tool_choice\": \"auto\",\n    \"max_output_tokens\": \"inf\",\n    \"tracing\": null,\n    \"truncation\": \"auto\",\n    \"prompt\": null,\n    \"expires_at\": 0,\n    \"audio\": {\n      \"input\": {\n        \"format\": {\n          \"type\": \"audio/pcm\",\n          \"rate\": 24000\n        },\n        \"transcription\": null,\n        \"noise_reduction\": null,\n        \"turn_detection\": {\n          \"type\": \"server_vad\",\n          \"threshold\": 0.5,\n          \"prefix_padding_ms\": 300,\n          \"silence_duration_ms\": 200,\n          \"idle_timeout_ms\": null,\n          \"create_response\": true,\n          \"interrupt_response\": true\n        }\n      },\n      \"output\": {\n        \"format\": {\n          \"type\": \"audio/pcm\",\n          \"rate\": 24000\n        },\n        \"voice\": \"alloy\",\n        \"speed\": 1.0\n      }\n    },\n    \"include\": null\n  }\n}\n"
    RealtimeSessionCreateRequest:
      type: object
      description: 'A new Realtime session configuration, with an ephemeral key. Default TTL

        for keys is one minute.

        '
      properties:
        client_secret:
          type: object
          description: Ephemeral key returned by the API.
          properties:
            value:
              type: string
              description: 'Ephemeral key usable in client environments to authenticate connections

                to the Realtime API. Use this in client-side environments rather than

                a standard API token, which should only be used server-side.

                '
            expires_at:
              type: integer
              format: unixtime
              description: 'Timestamp for when the token expires. Currently, all tokens expire

                after one minute.

                '
          required:
          - value
          - expires_at
        modalities:
          description: 'The set of modalities the model can respond with. To disable audio,

            set this to ["text"].

            '
          items:
            type: string
            enum:
            - text
            - audio
        instructions:
          type: string
          description: 'The default system instructions (i.e. system message) prepended to model calls. This field allows the client to guide the model on desired responses. The model can be instructed on response content and format, (e.g. "be extremely succinct", "act friendly", "here are examples of good responses") and on audio behavior (e.g. "talk quickly", "inject emotion into your voice", "laugh frequently"). The instructions are not guaranteed to be followed by the model, but they provide guidance to the model on the desired behavior.

            Note that the server sets default instructions which will be used if this field is not set and are visible in the `session.created` event at the start of the session.

            '
        voice:
          $ref: '#/components/schemas/VoiceIdsOrCustomVoice'
          description: 'The voice the model uses to respond. Supported built-in voices are

            `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`,

            `marin`, and `cedar`. You may also provide a custom voice object with an

            `id`, for example `{ "id": "voice_1234" }`. Voice cannot be changed during

            the session once the model has responded with audio at least once.

            '
        input_audio_format:
          type: string
          description: 'The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.

            '
        output_audio_format:
          type: string
          description: 'The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.

           

# --- truncated at 32 KB (138 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-realtime-api-openapi.yml