feat(api): add support for realtime calls

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 118
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-e205b1f2da6a1f2caa229efa9ede63f2d3d2fedeeb2dd6ed3d880bafdcb0ab88.yml
-openapi_spec_hash: c8aee2469a749f6a838b40c57e4b7b06
-config_hash: 45dcba51451ba532959c020a0ddbf23c
+configured_endpoints: 122
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-fadefdc7c7e30df47c09df323669b242ff90ee08e51f304175ace5274e0aab49.yml
+openapi_spec_hash: 6d20f639d9ff8a097a34962da6218231
+config_hash: 902654e60f5d659f2bfcfd903e17c46d

MIGRATION.md

@@ -133,6 +133,7 @@ client.example.list(undefined, { headers: { ... } });
 - `client.batches.list()`
 - `client.responses.retrieve()`
 - `client.responses.inputItems.list()`
+- `client.realtime.calls.reject()`
 - `client.conversations.create()`
 - `client.conversations.items.list()`
 - `client.evals.list()`

api.md

@@ -897,6 +897,15 @@ Methods:
 
 - <code title="post /realtime/client_secrets">client.realtime.clientSecrets.<a href="./src/resources/realtime/client-secrets.ts">create</a>({ ...params }) -> ClientSecretCreateResponse</code>
 
+## Calls
+
+Methods:
+
+- <code title="post /realtime/calls/{call_id}/accept">client.realtime.calls.<a href="./src/resources/realtime/calls.ts">accept</a>(callID, { ...params }) -> void</code>
+- <code title="post /realtime/calls/{call_id}/hangup">client.realtime.calls.<a href="./src/resources/realtime/calls.ts">hangup</a>(callID) -> void</code>
+- <code title="post /realtime/calls/{call_id}/refer">client.realtime.calls.<a href="./src/resources/realtime/calls.ts">refer</a>(callID, { ...params }) -> void</code>
+- <code title="post /realtime/calls/{call_id}/reject">client.realtime.calls.<a href="./src/resources/realtime/calls.ts">reject</a>(callID, { ...params }) -> void</code>
+
 # Conversations
 
 Types:

scripts/detect-breaking-changes

@@ -46,6 +46,7 @@ TEST_PATHS=(
 	tests/api-resources/responses/input-items.test.ts
 	tests/api-resources/realtime/realtime.test.ts
 	tests/api-resources/realtime/client-secrets.test.ts
+	tests/api-resources/realtime/calls.test.ts
 	tests/api-resources/conversations/conversations.test.ts
 	tests/api-resources/conversations/items.test.ts
 	tests/api-resources/evals/evals.test.ts

src/resources/realtime/calls.ts

@@ -0,0 +1,204 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as RealtimeAPI from './realtime';
+import * as ResponsesAPI from '../responses/responses';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Calls extends APIResource {
+  /**
+   * Accept an incoming SIP call and configure the realtime session that will handle
+   * it.
+   *
+   * @example
+   * ```ts
+   * await client.realtime.calls.accept('call_id', {
+   *   type: 'realtime',
+   * });
+   * ```
+   */
+  accept(callID: string, body: CallAcceptParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(path`/realtime/calls/${callID}/accept`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * End an active Realtime API call, whether it was initiated over SIP or WebRTC.
+   *
+   * @example
+   * ```ts
+   * await client.realtime.calls.hangup('call_id');
+   * ```
+   */
+  hangup(callID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(path`/realtime/calls/${callID}/hangup`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Transfer an active SIP call to a new destination using the SIP REFER verb.
+   *
+   * @example
+   * ```ts
+   * await client.realtime.calls.refer('call_id', {
+   *   target_uri: 'tel:+14155550123',
+   * });
+   * ```
+   */
+  refer(callID: string, body: CallReferParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(path`/realtime/calls/${callID}/refer`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Decline an incoming SIP call by returning a SIP status code to the caller.
+   *
+   * @example
+   * ```ts
+   * await client.realtime.calls.reject('call_id');
+   * ```
+   */
+  reject(
+    callID: string,
+    body: CallRejectParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    return this._client.post(path`/realtime/calls/${callID}/reject`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface CallAcceptParams {
+  /**
+   * The type of session to create. Always `realtime` for the Realtime API.
+   */
+  type: 'realtime';
+
+  /**
+   * Configuration for input and output audio.
+   */
+  audio?: RealtimeAPI.RealtimeAudioConfig;
+
+  /**
+   * Additional fields to include in server outputs.
+   *
+   * `item.input_audio_transcription.logprobs`: Include logprobs for input audio
+   * transcription.
+   */
+  include?: Array<'item.input_audio_transcription.logprobs'>;
+
+  /**
+   * 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.
+   */
+  instructions?: string;
+
+  /**
+   * Maximum number of output tokens for a single assistant response, inclusive of
+   * tool calls. Provide an integer between 1 and 4096 to limit output tokens, or
+   * `inf` for the maximum available tokens for a given model. Defaults to `inf`.
+   */
+  max_output_tokens?: number | 'inf';
+
+  /**
+   * The Realtime model used for this session.
+   */
+  model?:
+    | (string & {})
+    | 'gpt-realtime'
+    | 'gpt-realtime-2025-08-28'
+    | 'gpt-4o-realtime-preview'
+    | 'gpt-4o-realtime-preview-2024-10-01'
+    | 'gpt-4o-realtime-preview-2024-12-17'
+    | 'gpt-4o-realtime-preview-2025-06-03'
+    | 'gpt-4o-mini-realtime-preview'
+    | 'gpt-4o-mini-realtime-preview-2024-12-17';
+
+  /**
+   * The set of modalities the model can respond with. It defaults to `["audio"]`,
+   * indicating that the model will respond with audio plus a transcript. `["text"]`
+   * can be used to make the model respond with text only. It is not possible to
+   * request both `text` and `audio` at the same time.
+   */
+  output_modalities?: Array<'text' | 'audio'>;
+
+  /**
+   * Reference to a prompt template and its variables.
+   * [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
+   */
+  prompt?: ResponsesAPI.ResponsePrompt | null;
+
+  /**
+   * How the model chooses tools. Provide one of the string modes or force a specific
+   * function/MCP tool.
+   */
+  tool_choice?: RealtimeAPI.RealtimeToolChoiceConfig;
+
+  /**
+   * Tools available to the model.
+   */
+  tools?: RealtimeAPI.RealtimeToolsConfig;
+
+  /**
+   * Realtime API can write session traces to the
+   * [Traces Dashboard](/logs?api=traces). Set to null to disable tracing. Once
+   * tracing is enabled for a session, the configuration cannot be modified.
+   *
+   * `auto` will create a trace for the session with default values for the workflow
+   * name, group id, and metadata.
+   */
+  tracing?: RealtimeAPI.RealtimeTracingConfig | null;
+
+  /**
+   * Controls how the realtime conversation is truncated prior to model inference.
+   * The default is `auto`.
+   */
+  truncation?: RealtimeAPI.RealtimeTruncation;
+}
+
+export interface CallReferParams {
+  /**
+   * URI that should appear in the SIP Refer-To header. Supports values like
+   * `tel:+14155550123` or `sip:[email protected]`.
+   */
+  target_uri: string;
+}
+
+export interface CallRejectParams {
+  /**
+   * SIP response code to send back to the caller. Defaults to `603` (Decline) when
+   * omitted.
+   */
+  status_code?: number;
+}
+
+export declare namespace Calls {
+  export {
+    type CallAcceptParams as CallAcceptParams,
+    type CallReferParams as CallReferParams,
+    type CallRejectParams as CallRejectParams,
+  };
+}

src/resources/realtime/client-secrets.ts

@@ -10,6 +10,12 @@ import { RequestOptions } from '../../internal/request-options';
 export class ClientSecrets extends APIResource {
   /**
    * Create a Realtime client secret with an associated session configuration.
+   *
+   * @example
+   * ```ts
+   * const clientSecret =
+   *   await client.realtime.clientSecrets.create();
+   * ```
    */
   create(body: ClientSecretCreateParams, options?: RequestOptions): APIPromise<ClientSecretCreateResponse> {
     return this._client.post('/realtime/client_secrets', { body, ...options });

src/resources/realtime/index.ts

@@ -1,5 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export { Calls, type CallAcceptParams, type CallReferParams, type CallRejectParams } from './calls';
 export {
   ClientSecrets,
   type RealtimeSessionClientSecret,

src/resources/realtime/realtime.ts

@@ -3,6 +3,8 @@
 import { APIResource } from '../../core/resource';
 import * as RealtimeAPI from './realtime';
 import * as Shared from '../shared';
+import * as CallsAPI from './calls';
+import { CallAcceptParams, CallReferParams, CallRejectParams, Calls } from './calls';
 import * as ClientSecretsAPI from './client-secrets';
 import {
   ClientSecretCreateParams,
@@ -17,6 +19,7 @@ import * as ResponsesAPI from '../responses/responses';
 
 export class Realtime extends APIResource {
   clientSecrets: ClientSecretsAPI.ClientSecrets = new ClientSecretsAPI.ClientSecrets(this._client);
+  calls: CallsAPI.Calls = new CallsAPI.Calls(this._client);
 }
 
 export interface AudioTranscription {
@@ -4580,6 +4583,7 @@ export namespace TranscriptionSessionUpdatedEvent {
 }
 
 Realtime.ClientSecrets = ClientSecrets;
+Realtime.Calls = Calls;
 
 export declare namespace Realtime {
   export {
@@ -4694,4 +4698,11 @@ export declare namespace Realtime {
     type ClientSecretCreateResponse as ClientSecretCreateResponse,
     type ClientSecretCreateParams as ClientSecretCreateParams,
   };
+
+  export {
+    Calls as Calls,
+    type CallAcceptParams as CallAcceptParams,
+    type CallReferParams as CallReferParams,
+    type CallRejectParams as CallRejectParams,
+  };
 }