feat(api): update enum values, comments, and examples (#1280)

Author: stainless-app[bot]

Diff for: .stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 69
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai-b5b0e2c794b012919701c3fd43286af10fa25d33ceb8a881bec2636028f446e0.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai-3904ef6b29a89c98f93a9b7da19879695f3c440564be6384db7af1b734611ede.yml

Diff for: src/resources/audio/speech.ts

@@ -33,12 +33,12 @@ export interface SpeechCreateParams {
   model: (string & {}) | SpeechModel;
 
   /**
-   * The voice to use when generating the audio. Supported voices are `alloy`,
-   * `echo`, `fable`, `onyx`, `nova`, and `shimmer`. Previews of the voices are
-   * available in the
+   * The voice to use when generating the audio. Supported voices are `alloy`, `ash`,
+   * `coral`, `echo`, `fable`, `onyx`, `nova`, `sage` and `shimmer`. Previews of the
+   * voices are available in the
    * [Text to speech guide](https://platform.openai.com/docs/guides/text-to-speech#voice-options).
    */
-  voice: 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer';
+  voice: 'alloy' | 'ash' | 'coral' | 'echo' | 'fable' | 'onyx' | 'nova' | 'sage' | 'shimmer';
 
   /**
    * The format to audio in. Supported formats are `mp3`, `opus`, `aac`, `flac`,

Diff for: src/resources/beta/realtime/realtime.ts

@@ -173,9 +173,10 @@ export interface ConversationItemCreateEvent {
 
   /**
    * The ID of the preceding item after which the new item will be inserted. If not
-   * set, the new item will be appended to the end of the conversation. If set, it
-   * allows an item to be inserted mid-conversation. If the ID cannot be found, an
-   * error will be returned and the item will not be added.
+   * set, the new item will be appended to the end of the conversation. If set to
+   * `root`, the new item will be added to the beginning of the conversation. If set
+   * to an existing ID, it allows an item to be inserted mid-conversation. If the ID
+   * cannot be found, an error will be returned and the item will not be added.
    */
   previous_item_id?: string;
 }
@@ -1705,17 +1706,9 @@ export namespace SessionUpdateEvent {
    */
   export interface Session {
     /**
-     * The Realtime model used for this session.
-     */
-    model:
-      | 'gpt-4o-realtime-preview'
-      | 'gpt-4o-realtime-preview-2024-10-01'
-      | 'gpt-4o-realtime-preview-2024-12-17'
-      | 'gpt-4o-mini-realtime-preview'
-      | 'gpt-4o-mini-realtime-preview-2024-12-17';
-
-    /**
-     * The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
+     * The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For
+     * `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, single channel
+     * (mono), and little-endian byte order.
      */
     input_audio_format?: 'pcm16' | 'g711_ulaw' | 'g711_alaw';
 
@@ -1756,8 +1749,19 @@ export namespace SessionUpdateEvent {
      */
     modalities?: Array<'text' | 'audio'>;
 
+    /**
+     * The Realtime model used for this session.
+     */
+    model?:
+      | 'gpt-4o-realtime-preview'
+      | 'gpt-4o-realtime-preview-2024-10-01'
+      | 'gpt-4o-realtime-preview-2024-12-17'
+      | 'gpt-4o-mini-realtime-preview'
+      | 'gpt-4o-mini-realtime-preview-2024-12-17';
+
     /**
      * The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
+     * For `pcm16`, output audio is sampled at a rate of 24kHz.
      */
     output_audio_format?: 'pcm16' | 'g711_ulaw' | 'g711_alaw';
 

Diff for: src/resources/beta/realtime/sessions.ts

@@ -32,7 +32,9 @@ export interface Session {
   id?: string;
 
   /**
-   * The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
+   * The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For
+   * `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, single channel
+   * (mono), and little-endian byte order.
    */
   input_audio_format?: 'pcm16' | 'g711_ulaw' | 'g711_alaw';
 
@@ -86,6 +88,7 @@ export interface Session {
 
   /**
    * The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
+   * For `pcm16`, output audio is sampled at a rate of 24kHz.
    */
   output_audio_format?: 'pcm16' | 'g711_ulaw' | 'g711_alaw';
 
@@ -372,17 +375,9 @@ export namespace SessionCreateResponse {
 
 export interface SessionCreateParams {
   /**
-   * The Realtime model used for this session.
-   */
-  model:
-    | 'gpt-4o-realtime-preview'
-    | 'gpt-4o-realtime-preview-2024-10-01'
-    | 'gpt-4o-realtime-preview-2024-12-17'
-    | 'gpt-4o-mini-realtime-preview'
-    | 'gpt-4o-mini-realtime-preview-2024-12-17';
-
-  /**
-   * The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
+   * The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For
+   * `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, single channel
+   * (mono), and little-endian byte order.
    */
   input_audio_format?: 'pcm16' | 'g711_ulaw' | 'g711_alaw';
 
@@ -423,8 +418,19 @@ export interface SessionCreateParams {
    */
   modalities?: Array<'text' | 'audio'>;
 
+  /**
+   * The Realtime model used for this session.
+   */
+  model?:
+    | 'gpt-4o-realtime-preview'
+    | 'gpt-4o-realtime-preview-2024-10-01'
+    | 'gpt-4o-realtime-preview-2024-12-17'
+    | 'gpt-4o-mini-realtime-preview'
+    | 'gpt-4o-mini-realtime-preview-2024-12-17';
+
   /**
    * The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
+   * For `pcm16`, output audio is sampled at a rate of 24kHz.
    */
   output_audio_format?: 'pcm16' | 'g711_ulaw' | 'g711_alaw';
 

Diff for: src/resources/chat/completions.ts

@@ -76,8 +76,7 @@ export interface ChatCompletion {
   object: 'chat.completion';
 
   /**
-   * The service tier used for processing the request. This field is only included if
-   * the `service_tier` parameter is specified in the request.
+   * The service tier used for processing the request.
    */
   service_tier?: 'scale' | 'default' | null;
 
@@ -300,8 +299,7 @@ export interface ChatCompletionChunk {
   object: 'chat.completion.chunk';
 
   /**
-   * The service tier used for processing the request. This field is only included if
-   * the `service_tier` parameter is specified in the request.
+   * The service tier used for processing the request.
    */
   service_tier?: 'scale' | 'default' | null;
 
@@ -1115,9 +1113,6 @@ export interface ChatCompletionCreateParamsBase {
    * - If set to 'default', the request will be processed using the default service
    *   tier with a lower uptime SLA and no latency guarentee.
    * - When not set, the default behavior is 'auto'.
-   *
-   * When this parameter is set, the response body will include the `service_tier`
-   * utilized.
    */
   service_tier?: 'auto' | 'default' | null;
 

Diff for: src/resources/embeddings.ts

@@ -86,7 +86,8 @@ export interface EmbeddingCreateParams {
    * `text-embedding-ada-002`), cannot be an empty string, and any array must be 2048
    * dimensions or less.
    * [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken)
-   * for counting tokens.
+   * for counting tokens. Some models may also impose a limit on total number of
+   * tokens summed across inputs.
    */
   input: string | Array<string> | Array<number> | Array<Array<number>>;
 

Diff for: tests/api-resources/beta/realtime/sessions.test.ts

@@ -9,8 +9,8 @@ const client = new OpenAI({
 });
 
 describe('resource sessions', () => {
-  test('create: only required params', async () => {
-    const responsePromise = client.beta.realtime.sessions.create({ model: 'gpt-4o-realtime-preview' });
+  test('create', async () => {
+    const responsePromise = client.beta.realtime.sessions.create({});
     const rawResponse = await responsePromise.asResponse();
     expect(rawResponse).toBeInstanceOf(Response);
     const response = await responsePromise;
@@ -19,27 +19,4 @@ describe('resource sessions', () => {
     expect(dataAndResponse.data).toBe(response);
     expect(dataAndResponse.response).toBe(rawResponse);
   });
-
-  test('create: required and optional params', async () => {
-    const response = await client.beta.realtime.sessions.create({
-      model: 'gpt-4o-realtime-preview',
-      input_audio_format: 'pcm16',
-      input_audio_transcription: { model: 'model' },
-      instructions: 'instructions',
-      max_response_output_tokens: 0,
-      modalities: ['text'],
-      output_audio_format: 'pcm16',
-      temperature: 0,
-      tool_choice: 'tool_choice',
-      tools: [{ description: 'description', name: 'name', parameters: {}, type: 'function' }],
-      turn_detection: {
-        create_response: true,
-        prefix_padding_ms: 0,
-        silence_duration_ms: 0,
-        threshold: 0,
-        type: 'type',
-      },
-      voice: 'alloy',
-    });
-  });
 });

Diff for: tests/api-resources/chat/completions.test.ts

@@ -43,7 +43,7 @@ describe('resource completions', () => {
       presence_penalty: -2,
       reasoning_effort: 'low',
       response_format: { type: 'text' },
-      seed: -9007199254740991,
+      seed: 0,
       service_tier: 'auto',
       stop: 'string',
       store: true,

Diff for: tests/api-resources/completions.test.ts

@@ -32,7 +32,7 @@ describe('resource completions', () => {
       max_tokens: 16,
       n: 1,
       presence_penalty: -2,
-      seed: -9007199254740991,
+      seed: 0,
       stop: '\n',
       stream: false,
       stream_options: { include_usage: true },