openai/src/resources/chat/completions/completions.ts

The official TypeScript library for the OpenAI API

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../../core/resource';
import * as ChatCompletionsAPI from './completions';
import * as CompletionsAPI from '../../completions';
import * as Shared from '../../shared';
import * as MessagesAPI from './messages';
import { MessageListParams, Messages } from './messages';
import { APIPromise } from '../../../core/api-promise';
import { CursorPage, type CursorPageParams, PagePromise } from '../../../core/pagination';
import { Stream } from '../../../core/streaming';
import { RequestOptions } from '../../../internal/request-options';
import { path } from '../../../internal/utils/path';

import { ChatCompletionRunner } from '../../../lib/ChatCompletionRunner';
import { ChatCompletionStreamingRunner } from '../../../lib/ChatCompletionStreamingRunner';
import { RunnerOptions } from '../../../lib/AbstractChatCompletionRunner';
import { ChatCompletionToolRunnerParams } from '../../../lib/ChatCompletionRunner';
import { ChatCompletionStreamingToolRunnerParams } from '../../../lib/ChatCompletionStreamingRunner';
import { ChatCompletionStream, type ChatCompletionStreamParams } from '../../../lib/ChatCompletionStream';
import { ExtractParsedContentFromParams, parseChatCompletion, validateInputTools } from '../../../lib/parser';

/**
 * Given a list of messages comprising a conversation, the model will return a response.
 */
export class Completions extends APIResource {
  messages: MessagesAPI.Messages = new MessagesAPI.Messages(this._client);

  /**
   * **Starting a new project?** We recommend trying
   * [Responses](https://platform.openai.com/docs/api-reference/responses) to take
   * advantage of the latest OpenAI platform features. Compare
   * [Chat Completions with Responses](https://platform.openai.com/docs/guides/responses-vs-chat-completions?api-mode=responses).
   *
   * ---
   *
   * Creates a model response for the given chat conversation. Learn more in the
   * [text generation](https://platform.openai.com/docs/guides/text-generation),
   * [vision](https://platform.openai.com/docs/guides/vision), and
   * [audio](https://platform.openai.com/docs/guides/audio) guides.
   *
   * Parameter support can differ depending on the model used to generate the
   * response, particularly for newer reasoning models. Parameters that are only
   * supported for reasoning models are noted below. For the current state of
   * unsupported parameters in reasoning models,
   * [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
   *
   * Returns a chat completion object, or a streamed sequence of chat completion
   * chunk objects if the request is streamed.
   *
   * @example
   * ```ts
   * const chatCompletion = await client.chat.completions.create(
   *   {
   *     messages: [{ content: 'string', role: 'developer' }],
   *     model: 'gpt-5.4',
   *   },
   * );
   * ```
   */
  create(body: ChatCompletionCreateParamsNonStreaming, options?: RequestOptions): APIPromise<ChatCompletion>;
  create(
    body: ChatCompletionCreateParamsStreaming,
    options?: RequestOptions,
  ): APIPromise<Stream<ChatCompletionChunk>>;
  create(
    body: ChatCompletionCreateParamsBase,
    options?: RequestOptions,
  ): APIPromise<Stream<ChatCompletionChunk> | ChatCompletion>;
  create(
    body: ChatCompletionCreateParams,
    options?: RequestOptions,
  ): APIPromise<ChatCompletion> | APIPromise<Stream<ChatCompletionChunk>> {
    return this._client.post('/chat/completions', {
      body,
      ...options,
      stream: body.stream ?? false,
      __security: { bearerAuth: true },
    }) as APIPromise<ChatCompletion> | APIPromise<Stream<ChatCompletionChunk>>;
  }

  /**
   * Get a stored chat completion. Only Chat Completions that have been created with
   * the `store` parameter set to `true` will be returned.
   *
   * @example
   * ```ts
   * const chatCompletion =
   *   await client.chat.completions.retrieve('completion_id');
   * ```
   */
  retrieve(completionID: string, options?: RequestOptions): APIPromise<ChatCompletion> {
    return this._client.get(path`/chat/completions/${completionID}`, {
      ...options,
      __security: { bearerAuth: true },
    });
  }

  /**
   * Modify a stored chat completion. Only Chat Completions that have been created
   * with the `store` parameter set to `true` can be modified. Currently, the only
   * supported modification is to update the `metadata` field.
   *
   * @example
   * ```ts
   * const chatCompletion = await client.chat.completions.update(
   *   'completion_id',
   *   { metadata: { foo: 'string' } },
   * );
   * ```
   */
  update(
    completionID: string,
    body: ChatCompletionUpdateParams,
    options?: RequestOptions,
  ): APIPromise<ChatCompletion> {
    return this._client.post(path`/chat/completions/${completionID}`, {
      body,
      ...options,
      __security: { bearerAuth: true },
    });
  }

  /**
   * List stored Chat Completions. Only Chat Completions that have been stored with
   * the `store` parameter set to `true` will be returned.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const chatCompletion of client.chat.completions.list()) {
   *   // ...
   * }
   * ```
   */
  list(
    query: ChatCompletionListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<ChatCompletionsPage, ChatCompletion> {
    return this._client.getAPIList('/chat/completions', CursorPage<ChatCompletion>, {
      query,
      ...options,
      __security: { bearerAuth: true },
    });
  }

  /**
   * Delete a stored chat completion. Only Chat Completions that have been created
   * with the `store` parameter set to `true` can be deleted.
   *
   * @example
   * ```ts
   * const chatCompletionDeleted =
   *   await client.chat.completions.delete('completion_id');
   * ```
   */
  delete(completionID: string, options?: RequestOptions): APIPromise<ChatCompletionDeleted> {
    return this._client.delete(path`/chat/completions/${completionID}`, {
      ...options,
      __security: { bearerAuth: true },
    });
  }

  parse<Params extends ChatCompletionParseParams, ParsedT = ExtractParsedContentFromParams<Params>>(
    body: Params,
    options?: RequestOptions,
  ): APIPromise<ParsedChatCompletion<ParsedT>> {
    validateInputTools(body.tools);

    return this._client.chat.completions
      .create(body, {
        ...options,
        headers: {
          ...options?.headers,
          'X-Stainless-Helper-Method': 'chat.completions.parse',
        },
      })
      ._thenUnwrap((completion) => parseChatCompletion(completion, body));
  }

  /**
   * A convenience helper for using tool calls with the /chat/completions endpoint
   * which automatically calls the JavaScript functions you provide and sends their
   * results back to the /chat/completions endpoint, looping as long as the model
   * requests function calls.
   *
   * For more details and examples, see
   * [the docs](https://github.com/openai/openai-node#automated-function-calls)
   */
  runTools<
    Params extends ChatCompletionToolRunnerParams<any>,
    ParsedT = ExtractParsedContentFromParams<Params>,
  >(body: Params, options?: RunnerOptions): ChatCompletionRunner<ParsedT>;

  runTools<
    Params extends ChatCompletionStreamingToolRunnerParams<any>,
    ParsedT = ExtractParsedContentFromParams<Params>,
  >(body: Params, options?: RunnerOptions): ChatCompletionStreamingRunner<ParsedT>;

  runTools<
    Params extends ChatCompletionToolRunnerParams<any> | ChatCompletionStreamingToolRunnerParams<any>,
    ParsedT = ExtractParsedContentFromParams<Params>,
  >(
    body: Params,
    options?: RunnerOptions,
  ): ChatCompletionRunner<ParsedT> | ChatCompletionStreamingRunner<ParsedT> {
    if (body.stream) {
      return ChatCompletionStreamingRunner.runTools(
        this._client,
        body as ChatCompletionStreamingToolRunnerParams<any>,
        options,
      );
    }

    return ChatCompletionRunner.runTools(this._client, body as ChatCompletionToolRunnerParams<any>, options);
  }

  /**
   * Creates a chat completion stream
   */
  stream<Params extends ChatCompletionStreamParams, ParsedT = ExtractParsedContentFromParams<Params>>(
    body: Params,
    options?: RequestOptions,
  ): ChatCompletionStream<ParsedT> {
    return ChatCompletionStream.createChatCompletion(this._client, body, options);
  }
}

export interface ParsedFunction extends ChatCompletionMessageFunctionToolCall.Function {
  parsed_arguments?: unknown;
}

export interface ParsedFunctionToolCall extends ChatCompletionMessageFunctionToolCall {
  function: ParsedFunction;
}

export interface ParsedChatCompletionMessage<ParsedT> extends ChatCompletionMessage {
  parsed: ParsedT | null;
  tool_calls?: Array<ParsedFunctionToolCall>;
}

export interface ParsedChoice<ParsedT> extends ChatCompletion.Choice {
  message: ParsedChatCompletionMessage<ParsedT>;
}

export interface ParsedChatCompletion<ParsedT> extends ChatCompletion {
  choices: Array<ParsedChoice<ParsedT>>;
}

export type ChatCompletionParseParams = ChatCompletionCreateParamsNonStreaming;

export { ChatCompletionStreamingRunner } from '../../../lib/ChatCompletionStreamingRunner';
export {
  type RunnableFunctionWithParse,
  type RunnableFunctionWithoutParse,
  ParsingToolFunction,
} from '../../../lib/RunnableFunction';
export { type ChatCompletionToolRunnerParams } from '../../../lib/ChatCompletionRunner';
export { type ChatCompletionStreamingToolRunnerParams } from '../../../lib/ChatCompletionStreamingRunner';
export { ChatCompletionStream, type ChatCompletionStreamParams } from '../../../lib/ChatCompletionStream';
export { ChatCompletionRunner } from '../../../lib/ChatCompletionRunner';

export type ChatCompletionsPage = CursorPage<ChatCompletion>;

export type ChatCompletionStoreMessagesPage = CursorPage<ChatCompletionStoreMessage>;

/**
 * Represents a chat completion response returned by model, based on the provided
 * input.
 */
export interface ChatCompletion {
  /**
   * A unique identifier for the chat completion.
   */
  id: string;

  /**
   * A list of chat completion choices. Can be more than one if `n` is greater
   * than 1.
   */
  choices: Array<ChatCompletion.Choice>;

  /**
   * The Unix timestamp (in seconds) of when the chat completion was created.
   */
  created: number;

  /**
   * The model used for the chat completion.
   */
  model: string;

  /**
   * The object type, which is always `chat.completion`.
   */
  object: 'chat.completion';

  /**
   * Moderation results for the request input and generated output, if moderated
   * completions were requested.
   */
  moderation?: ChatCompletion.Moderation | null;

  /**
   * Specifies the processing type used for serving the request.
   *
   * - If set to 'auto', then the request will be processed with the service tier
   *   configured in the Project settings. Unless otherwise configured, the Project
   *   will use 'default'.
   * - If set to 'default', then the request will be processed with the standard
   *   pricing and performance for the selected model.
   * - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or
   *   '[priority](https://openai.com/api-priority-processing/)', then the request
   *   will be processed with the corresponding service tier.
   * - When not set, the default behavior is 'auto'.
   *
   * When the `service_tier` parameter is set, the response body will include the
   * `service_tier` value based on the processing mode actually used to serve the
   * request. This response value may be different from the value set in the
   * parameter.
   */
  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | 'priority' | null;

  /**
   * @deprecated This fingerprint represents the backend configuration that the model
   * runs with.
   *
   * Can be used in conjunction with the `seed` request parameter to understand when
   * backend changes have been made that might impact determinism.
   */
  system_fingerprint?: string;

  /**
   * Usage statistics for the completion request.
   */
  usage?: CompletionsAPI.CompletionUsage;
}

export namespace ChatCompletion {
  export interface Choice {
    /**
     * The reason the model stopped generating tokens. This will be `stop` if the model
     * hit a natural stop point or a provided stop sequence, `length` if the maximum
     * number of tokens specified in the request was reached, `content_filter` if
     * content was omitted due to a flag from our content filters, `tool_calls` if the
     * model called a tool, or `function_call` (deprecated) if the model called a
     * function. Read the [Model Spec](https://model-spec.openai.com/2025-12-18.html)
     * for more.
     */
    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call';

    /**
     * The index of the choice in the list of choices.
     */
    index: number;

    /**
     * Log probability information for the choice.
     */
    logprobs: Choice.Logprobs | null;

    /**
     * A chat completion message generated by the model.
     */
    message: ChatCompletionsAPI.ChatCompletionMessage;
  }

  export namespace Choice {
    /**
     * Log probability information for the choice.
     */
    export interface Logprobs {
      /**
       * A list of message content tokens with log probability information.
       */
      content: Array<ChatCompletionsAPI.ChatCompletionTokenLogprob> | null;

      /**
       * A list of message refusal tokens with log probability information.
       */
      refusal: Array<ChatCompletionsAPI.ChatCompletionTokenLogprob> | null;
    }
  }

  /**
   * Moderation results for the request input and generated output, if moderated
   * completions were requested.
   */
  export interface Moderation {
    /**
     * Moderation for the request input.
     */
    input: Moderation.ModerationResults | Moderation.Error;

    /**
     * Moderation for the generated output.
     */
    output: Moderation.ModerationResults | Moderation.Error;
  }

  export namespace Moderation {
    /**
     * Successful moderation results for the request input or generated output.
     */
    export interface ModerationResults {
      /**
       * The moderation model used to generate the results.
       */
      model: string;

      /**
       * A list of moderation results.
       */
      results: Array<ModerationResults.Result>;

      /**
       * The object type, which is always `moderation_results`.
       */
      type: 'moderation_results';
    }

    export namespace ModerationResults {
      /**
       * A moderation result produced for the response input or output.
       */
      export interface Result {
        /**
         * A dictionary of moderation categories to booleans, True if the input is flagged
         * under this category.
         */
        categories: { [key: string]: boolean };

        /**
         * Which modalities of input are reflected by the score for each category.
         */
        category_applied_input_types: { [key: string]: Array<'text' | 'image'> };

        /**
         * A dictionary of moderation categories to scores.
         */
        category_scores: { [key: string]: number };

        /**
         * A boolean indicating whether the content was flagged by any category.
         */
        flagged: boolean;

        /**
         * The moderation model that produced this result.
         */
        model: string;

        /**
         * The object type, which was always `moderation_result` for successful moderation
         * results.
         */
        type: 'moderation_result';
      }
    }

    /**
     * An error produced while attempting moderation.
     */
    export interface Error {
      /**
       * The error code.
       */
      code: string;

      /**
       * The error message.
       */
      message: string;

      /**
       * The object type, which is always `error`.
       */
      type: 'error';
    }

    /**
     * Successful moderation results for the request input or generated output.
     */
    export interface ModerationResults {
      /**
       * The moderation model used to generate the results.
       */
      model: string;

      /**
       * A list of moderation results.
       */
      results: Array<ModerationResults.Result>;

      /**
       * The object type, which is always `moderation_results`.
       */
      type: 'moderation_results';
    }

    export namespace ModerationResults {
      /**
       * A moderation result produced for the response input or output.
       */
      export interface Result {
        /**
         * A dictionary of moderation categories to booleans, True if the input is flagged
         * under this category.
         */
        categories: { [key: string]: boolean };

        /**
         * Which modalities of input are reflected by the score for each category.
         */
        category_applied_input_types: { [key: string]: Array<'text' | 'image'> };

        /**
         * A dictionary of moderation categories to scores.
         */
        category_scores: { [key: string]: number };

        /**
         * A boolean indicating whether the content was flagged by any category.
         */
        flagged: boolean;

        /**
         * The moderation model that produced this result.
         */
        model: string;

        /**
         * The object type, which was always `moderation_result` for successful moderation
         * results.
         */
        type: 'moderation_result';
      }
    }

    /**
     * An error produced while attempting moderation.
     */
    export interface Error {
      /**
       * The error code.
       */
      code: string;

      /**
       * The error message.
       */
      message: string;

      /**
       * The object type, which is always `error`.
       */
      type: 'error';
    }
  }
}

/**
 * Constrains the tools available to the model to a pre-defined set.
 */
export interface ChatCompletionAllowedToolChoice {
  /**
   * Constrains the tools available to the model to a pre-defined set.
   */
  allowed_tools: ChatCompletionAllowedTools;

  /**
   * Allowed tool configuration type. Always `allowed_tools`.
   */
  type: 'allowed_tools';
}

/**
 * Messages sent by the model in response to user messages.
 */
export interface ChatCompletionAssistantMessageParam {
  /**
   * The role of the messages author, in this case `assistant`.
   */
  role: 'assistant';

  /**
   * Data about a previous audio response from the model.
   * [Learn more](https://platform.openai.com/docs/guides/audio).
   */
  audio?: ChatCompletionAssistantMessageParam.Audio | null;

  /**
   * The contents of the assistant message. Required unless `tool_calls` or
   * `function_call` is specified.
   */
  content?: string | Array<ChatCompletionContentPartText | ChatCompletionContentPartRefusal> | null;

  /**
   * @deprecated Deprecated and replaced by `tool_calls`. The name and arguments of a
   * function that should be called, as generated by the model.
   */
  function_call?: ChatCompletionAssistantMessageParam.FunctionCall | null;

  /**
   * An optional name for the participant. Provides the model information to
   * differentiate between participants of the same role.
   */
  name?: string;

  /**
   * The refusal message by the assistant.
   */
  refusal?: string | null;

  /**
   * The tool calls generated by the model, such as function calls.
   */
  tool_calls?: Array<ChatCompletionMessageToolCall>;
}

export namespace ChatCompletionAssistantMessageParam {
  /**
   * Data about a previous audio response from the model.
   * [Learn more](https://platform.openai.com/docs/guides/audio).
   */
  export interface Audio {
    /**
     * Unique identifier for a previous audio response from the model.
     */
    id: string;
  }

  /**
   * @deprecated Deprecated and replaced by `tool_calls`. The name and arguments of a
   * function that should be called, as generated by the model.
   */
  export interface FunctionCall {
    /**
     * The arguments to call the function with, as generated by the model in JSON
     * format. Note that the model does not always generate valid JSON, and may
     * hallucinate parameters not defined by your function schema. Validate the
     * arguments in your code before calling your function.
     */
    arguments: string;

    /**
     * The name of the function to call.
     */
    name: string;
  }
}

/**
 * If the audio output modality is requested, this object contains data about the
 * audio response from the model.
 * [Learn more](https://platform.openai.com/docs/guides/audio).
 */
export interface ChatCompletionAudio {
  /**
   * Unique identifier for this audio response.
   */
  id: string;

  /**
   * Base64 encoded audio bytes generated by the model, in the format specified in
   * the request.
   */
  data: string;

  /**
   * The Unix timestamp (in seconds) for when this audio response will no longer be
   * accessible on the server for use in multi-turn conversations.
   */
  expires_at: number;

  /**
   * Transcript of the audio generated by the model.
   */
  transcript: string;
}

/**
 * Parameters for audio output. Required when audio output is requested with
 * `modalities: ["audio"]`.
 * [Learn more](https://platform.openai.com/docs/guides/audio).
 */
export interface ChatCompletionAudioParam {
  /**
   * Specifies the output audio format. Must be one of `wav`, `mp3`, `flac`, `opus`,
   * or `pcm16`.
   */
  format: 'wav' | 'aac' | 'mp3' | 'flac' | 'opus' | 'pcm16';

  /**
   * The voice the model uses to respond. Supported built-in voices are `alloy`,
   * `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`, `sage`, `shimmer`,
   * `marin`, and `cedar`. You may also provide a custom voice object with an `id`,
   * for example `{ "id": "voice_1234" }`.
   */
  voice:
    | string
    | 'alloy'
    | 'ash'
    | 'ballad'
    | 'coral'
    | 'echo'
    | 'sage'
    | 'shimmer'
    | 'verse'
    | 'marin'
    | 'cedar'
    | ChatCompletionAudioParam.ID;
}

export namespace ChatCompletionAudioParam {
  /**
   * Custom voice reference.
   */
  export interface ID {
    /**
     * The custom voice ID, e.g. `voice_1234`.
     */
    id: string;
  }
}

/**
 * Represents a streamed chunk of a chat completion response returned by the model,
 * based on the provided input.
 * [Learn more](https://platform.openai.com/docs/guides/streaming-responses).
 */
export interface ChatCompletionChunk {
  /**
   * A unique identifier for the chat completion. Each chunk has the same ID.
   */
  id: string;

  /**
   * A list of chat completion choices. Can contain more than one elements if `n` is
   * greater than 1. Can also be empty for the last chunk if you set
   * `stream_options: {"include_usage": true}`.
   */
  choices: Array<ChatCompletionChunk.Choice>;

  /**
   * The Unix timestamp (in seconds) of when the chat completion was created. Each
   * chunk has the same timestamp.
   */
  created: number;

  /**
   * The model to generate the completion.
   */
  model: string;

  /**
   * The object type, which is always `chat.completion.chunk`.
   */
  object: 'chat.completion.chunk';

  /**
   * Moderation results for the request input and generated output. Present on the
   * moderation chunk when moderated completions are requested.
   */
  moderation?: ChatCompletionChunk.Moderation | null;

  /**
   * Specifies the processing type used for serving the request.
   *
   * - If set to 'auto', then the request will be processed with the service tier
   *   configured in the Project settings. Unless otherwise configured, the Project
   *   will use 'default'.
   * - If set to 'default', then the request will be processed with the standard
   *   pricing and performance for the selected model.
   * - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or
   *   '[priority](https://openai.com/api-priority-processing/)', then the request
   *   will be processed with the corresponding service tier.
   * - When not set, the default behavior is 'auto'.
   *
   * When the `service_tier` parameter is set, the response body will include the
   * `service_tier` value based on the processing mode actually used to serve the
   * request. This response value may be different from the value set in the
   * parameter.
   */
  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | 'priority' | null;

  /**
   * @deprecated This fingerprint represents the backend configuration that the model
   * runs with. Can be used in conjunction with the `seed` request parameter to
   * understand when backend changes have been made that might impact determinism.
   */
  system_fingerprint?: string;

  /**
   * An optional field that will only be present when you set
   * `stream_options: {"include_usage": true}` in your request. When present, it
   * contains a null value **except for the last chunk** which contains the token
   * usage statistics for the entire request.
   *
   * **NOTE:** If the stream is interrupted or cancelled, you may not receive the
   * final usage chunk which contains the total token usage for the request.
   */
  usage?: CompletionsAPI.CompletionUsage | null;
}

export namespace ChatCompletionChunk {
  export interface Choice {
    /**
     * A chat completion delta generated by streamed model responses.
     */
    delta: Choice.Delta;

    /**
     * The reason the model stopped generating tokens. This will be `stop` if the model
     * hit a natural stop point or a provided stop sequence, `length` if the maximum
     * number of tokens specified in the request was reached, `content_filter` if
     * content was omitted due to a flag from our content filters, `tool_calls` if the
     * model called a tool, or `function_call` (deprecated) if the model called a
     * function.
     */
    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call' | null;

    /**
     * The index of the choice in the list of choices.
     */
    index: number;

    /**
     * Log probability information for the choice.
     */
    logprobs?: Choice.Logprobs | null;
  }

  export namespace Choice {
    /**
     * A chat completion delta generated by streamed model responses.
     */
    export interface Delta {
      /**
       * The contents of the chunk message.
       */
      content?: string | null;

      /**
       * @deprecated Deprecated and replaced by `tool_calls`. The name and arguments of a
       * function that should be called, as generated by the model.
       */
      function_call?: Delta.FunctionCall;

      /**
       * The refusal message generated by the model.
       */
      refusal?: string | null;

      /**
       * The role of the author of this message.
       */
      role?: 'developer' | 'system' | 'user' | 'assistant' | 'tool';

      tool_calls?: Array<Delta.ToolCall>;
    }

    export namespace Delta {
      /**
       * @deprecated Deprecated and replaced by `tool_calls`. The name and arguments of a
       * function that should be called, as generated by the model.
       */
      export interface FunctionCall {
        /**
         * The arguments to call the function with, as generated by the model in JSON
         * format. Note that the model does not always generate valid JSON, and may
         * hallucinate parameters not defined by your function schema. Validate the
         * arguments in your code before calling your function.
         */
        arguments?: string;

        /**
         * The name of the function to call.
         */
        name?: string;
      }

      export interface ToolCall {
        index: number;

        /**
         * The ID of the tool call.
         */
        id?: string;

        function?: ToolCall.Function;

        /**
         * The type of the tool. Currently, only `function` is supported.
         */
        type?: 'function';
      }

      export namespace ToolCall {
        export interface Function {
          /**
           * The arguments to call the function with, as generated by the model in JSON
           * format. Note that the model does not always generate valid JSON, and may
           * hallucinate parameters not defined by your function schema. Validate the
           * arguments in your code before calling your function.
           */
          arguments?: string;

          /**
           * The name of the function to call.
           */
          name?: string;
        }
      }
    }

    /**
     * Log probability information for the choice.
     */
    export interface Logprobs {
      /**
       * A list of message content tokens with log probability information.
       */
      content: Array<ChatCompletionsAPI.ChatCompletionTokenLogprob> | null;

      /**
       * A list of message refusal tokens with log probability information.
       */
      refusal: Array<ChatCompletionsAPI.ChatCompletionTokenLogprob> | null;
    }
  }

  /**
   * Moderation results for the request input and generated output. Present on the
   * moderation chunk when moderated completions are requested.
   */
  export interface Moderation {
    /**
     * Moderation for the request input.
     */
    input: Moderation.ModerationResults | Moderation.Error;

    /**
     * Moderation for the generated output.
     */
    output: Moderation.ModerationResults | Moderation.Error;
  }

  export namespace Moderation {
    /**
     * Successful moderation results for the request input or generated output.
     */
    export interface ModerationResults {
      /**
       * The moderation model used to generate the results.
       */
      model: string;

      /**
       * A list of moderation results.
       */
      results: Array<ModerationResults.Result>;

      /**
       * The object type, which is always `moderation_results`.
       */
      type: 'moderation_results';
    }

    export namespace ModerationResults {
      /**
       * A moderation result produced for the response input or output.
       */
      export interface Result {
        /**
         * A dictionary of moderation categories to booleans, True if the input is flagged
         * under this category.
         */
        categories: { [key: string]: boolean };

        /**
         * Which modalities of input are reflected by the score for each category.
         */
        category_applied_input_types: { [key: string]: Array<'text' | 'image'> };

        /**
         * A dictionary of moderation categories to scores.
         */
        category_scores: { [key: string]: number };

        /**
         * A boolean indicating whether the content was flagged by any category.
         */
        flagged: boolean;

        /**
         * The moderation model that produced this result.
         */
        model: string;

        /**
         * The object type, which was always `moderation_result` for successful moderation
         * results.
         */
        type: 'moderation_result';
      }
    }

    /**
     * An error produced while attempting moderation.
     */
    export interface Error {
      /**
       * The error code.
       */
      code: string;

      /**
       * The error message.
       */
      message: string;

      /**
       * The object type, which is always `error`.
       */
      type: 'error';
    }

    /**
     * Successful moderation results for the request input or generated output.
     */
    export interface ModerationResults {
      /**
       * The moderation model used to generate the results.
       */
      model: string;

      /**
       * A list of moderation results.
       */
      results: Array<ModerationResults.Result>;

      /**
       * The object type, which is always `moderation_results`.
       */
      type: 'moderation_results';
    }

    export namespace ModerationResults {
      /**
       * A moderation result produced for the response input or output.
       */
      export interface Result {
        /**
         * A dictionary of moderation categories to booleans, True if the input is flagged
         * under this category.
         */
        categories: { [key: string]: boolean };

        /**
         * Which modalities of input are reflected by the score for each category.
         */
        category_applied_input_types: { [key: string]: Array<'text' | 'image'> };

        /**
         * A dictionary of moderation categories to scores.
         */
        category_scores: { [key: string]: number };

        /**
         * A boolean indicating whether the content was flagged by any category.
         */
        flagged: boolean;

        /**
         * The moderation model that produced this result.
         */
        model: string;

        /**
         * The object type, which was always `moderation_result` for successful moderation
         * results.
         */
        type: 'moderation_result';
      }
    }

    /**
     * An error produced while attempting moderation.
     */
    export interface Error {
      /**
       * The error code.
       */
      code: string;

      /**
       * The error message.
       */
      message: string;

      /**
       * The object type, which is always `error`.
       */
      type: 'error';
    }
  }
}

/**
 * Learn about
 * [text inputs](https://platform.openai.com/docs/guides/text-generation).
 */
export type ChatCompletionContentPart =
  | ChatCompletionContentPartText
  | ChatCompletionContentPartImage
  | ChatCompletionContentPartInputAudio
  | ChatCompletionContentPart.File;

export namespace ChatCompletionContentPart {
  /**
   * Learn about [file inputs](https://platform.openai.com/docs/guides/text) for text
   * generation.
   */
  export interface File {
    file: File.File;

    /**
     * The type of the content part. Always `file`.
     */
    type: 'file';
  }

  export namespace File {
    export interface File {
      /**
       * The base64 encoded file data, used when passing the file to the model as a
       * string.
       */
      file_data?: string;

      /**
       * The ID of an uploaded file to use as input.
       */
      file_id?: string;

      /**
       * The name of the file, used when passing the file to the model as a string.
       */
      filename?: string;
    }
  }
}

/**
 * Learn about [image inputs](https://platform.openai.com/docs/guides/vision).
 */
export interface ChatCompletionContentPartImage {
  image_url: ChatCompletionContentPartImage.ImageURL;

  /**
   * The type of the content part.
   */
  type: 'image_url';
}

export namespace ChatCompletionContentPartImage {
  export interface ImageURL {
    /**
     * Either a URL of the image or the base64 encoded image data.
     */
    url: string;

    /**
     * Specifies the detail level of the image. Learn more in the
     * [Vision guide](https://platform.openai.com/docs/guides/vision#low-or-high-fidelity-image-understanding).
     */
    detail?: 'auto' | 'low' | 'high';
  }
}

/**
 * Learn about [audio inputs](https://platform.openai.com/docs/guides/audio).
 */
export interface ChatCompletionContentPartInputAudio {
  input_audio: ChatCompletionContentPartInputAudio.InputAudio;

  /**
   * The type of the content part. Always `input_audio`.
   */
  type: 'input_audio';
}

export namespace ChatCompletionContentPartInputAudio {
  export interface InputAudio {
    /**
     * Base64 encoded audio data.
     */
    data: string;

    /**
     * The format of the encoded audio data. Currently supports "wav" and "mp3".
     */
    format: 'wav' | 'mp3';
  }
}

export interface ChatCompletionContentPartRefusal {
  /**
   * The refusal message generated by the model.
   */
  refusal: string;

  /**
   * The type of the content part.
   */
  type: 'refusal';
}

/**
 * Learn about
 * [text inputs](https://platform.openai.com/docs/guides/text-generation).
 */
export interface ChatCompletionContentPartText {
  /**
   * The text content.
   */
  text: string;

  /**
   * The type of the content part.
   */
  type: 'text';
}

/**
 * A custom tool that processes input using a specified format.
 */
export interface ChatCompletionCustomTool {
  /**
   * Properties of the custom tool.
   */
  custom: ChatCompletionCustomTool.Custom;

  /**
   * The type of the custom tool. Always `custom`.
   */
  type: 'custom';
}

export namespace ChatCompletionCustomTool {
  /**
   * Properties of the custom tool.
   */
  export interface Custom {
    /**
     * The name of the custom tool, used to identify it in tool calls.
     */
    name: string;

    /**
     * Optional description of the custom tool, used to provide more context.
     */
    description?: string;

    /**
     * The input format for the custom tool. Default is unconstrained text.
     */
    format?: Custom.Text | Custom.Grammar;
  }

  export namespace Custom {
    /**
     * Unconstrained free-form text.
     */
    export interface Text {
      /**
       * Unconstrained text format. Always `text`.
       */
      type: 'text';
    }

    /**
     * A grammar defined by the user.
     */
    export interface Grammar {
      /**
       * Your chosen grammar.
       */
      grammar: Grammar.Grammar;

      /**
       * Grammar format. Always `grammar`.
       */
      type: 'grammar';
    }

    export namespace Grammar {
      /**
       * Your chosen grammar.
       */
      export interface Grammar {
        /**
         * The grammar definition.
         */
        definition: string;

        /**
         * The syntax of the grammar definition. One of `lark` or `regex`.
         */
        syntax: 'lark' | 'regex';
      }
    }
  }
}

export interface ChatCompletionDeleted {
  /**
   * The ID of the chat completion that was deleted.
   */
  id: string;

  /**
   * Whether the chat completion was deleted.
   */
  deleted: boolean;

  /**
   * The type of object being deleted.
   */
  object: 'chat.completion.deleted';
}

/**
 * Developer-provided instructions that the model should follow, regardless of
 * messages sent by the user. With o1 models and newer, `developer` messages
 * replace the previous `system` messages.
 */
export interface ChatCompletionDeveloperMessageParam {
  /**
   * The contents of the developer message.
   */
  content: string | Array<ChatCompletionContentPartText>;

  /**
   * The role of the messages author, in this case `developer`.
   */
  role: 'developer';

  /**
   * An optional name for the participant. Provides the model information to
   * differentiate between participants of the same role.
   */
  name?: string;
}

/**
 * Specifying a particular function via `{"name": "my_function"}` forces the model
 * to call that function.
 */
export interface ChatCompletionFunctionCallOption {
  /**
   * The name of the function to call.
   */
  name: string;
}

/**
 * @deprecated
 */
export interface ChatCompletionFunctionMessageParam {
  /**
   * The contents of the function message.
   */
  content: string | null;

  /**
   * The name of the function to call.
   */
  name: string;

  /**
   * The role of the messages author, in this case `function`.
   */
  role: 'function';
}

/**
 * A function tool that can be used to generate a response.
 */
export interface ChatCompletionFunctionTool {
  function: Shared.FunctionDefinition;

  /**
   * The type of the tool. Currently, only `function` is supported.
   */
  type: 'function';
}

/**
 * A chat completion message generated by the model.
 */
export interface ChatCompletionMessage {
  /**
   * The contents of the message.
   */
  content: string | null;

  /**
   * The refusal message generated by the model.
   */
  refusal: string | null;

  /**
   * The role of the author of this message.
   */
  role: 'assistant';

  /**
   * Annotations for the message, when applicable, as when using the
   * [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).
   */
  annotations?: Array<ChatCompletionMessage.Annotation>;

  /**
   * If the audio output modality is requested, this object contains data about the
   * audio response from the model.
   * [Learn more](https://platform.openai.com/docs/guides/audio).
   */
  audio?: ChatCompletionAudio | null;

  /**
   * @deprecated Deprecated and replaced by `tool_calls`. The name and arguments of a
   * function that should be called, as generated by the model.
   */
  function_call?: ChatCompletionMessage.FunctionCall | null;

  /**
   * The tool calls generated by the model, such as function calls.
   */
  tool_calls?: Array<ChatCompletionMessageToolCall>;
}

export namespace ChatCompletionMessage {
  /**
   * A URL citation when using web search.
   */
  export interface Annotation {
    /**
     * The type of the URL citation. Always `url_citation`.
     */
    type: 'url_citation';

    /**
     * A URL citation when using web search.
     */
    url_citation: Annotation.URLCitation;
  }

  export namespace Annotation {
    /**
     * A URL citation when using web search.
     */
    export interface URLCitation {
      /**
       * The index of the last character of the URL citation in the message.
       */
      end_index: number;

      /**
       * The index of the first character of the URL citation in the message.
       */
      start_index: number;

      /**
       * The title of the web resource.
       */
      title: string;

      /**
       * The URL of the web resource.
       */
      url: string;
    }
  }

  /**
   * @deprecated Deprecated and replaced by `tool_calls`. The name and arguments of a
   * function that should be called, as generated by the model.
   */
  export interface FunctionCall {
    /**
     * The arguments to call the function with, as generated by the model in JSON
     * format. Note that the model does not always generate valid JSON, and may
     * hallucinate parameters not defined by your function schema. Validate the
     * arguments in your code before calling your function.
     */
    arguments: string;

    /**
     * The name of the function to call.
     */
    name: string;
  }
}

/**
 * A call to a custom tool created by the model.
 */
export interface ChatCompletionMessageCustomToolCall {
  /**
   * The ID of the tool call.
   */
  id: string;

  /**
   * The custom tool that the model called.
   */
  custom: ChatCompletionMessageCustomToolCall.Custom;

  /**
   * The type of the tool. Always `custom`.
   */
  type: 'custom';
}

export namespace ChatCompletionMessageCustomToolCall {
  /**
   * The custom tool that the model called.
   */
  export interface Custom {
    /**
     * The input for the custom tool call generated by the model.
     */
    input: string;

    /**
     * The name of the custom tool to call.
     */
    name: string;
  }
}

/**
 * A call to a function tool created by the model.
 */
export interface ChatCompletionMessageFunctionToolCall {
  /**
   * The ID of the tool call.
   */
  id: string;

  /**
   * The function that the model called.
   */
  function: ChatCompletionMessageFunctionToolCall.Function;

  /**
   * The type of the tool. Currently, only `function` is supported.
   */
  type: 'function';
}

export namespace ChatCompletionMessageFunctionToolCall {
  /**
   * The function that the model called.
   */
  export interface Function {
    /**
     * The arguments to call the function with, as generated by the model in JSON
     * format. Note that the model does not always generate valid JSON, and may
     * hallucinate parameters not defined by your function schema. Validate the
     * arguments in your code before calling your function.
     */
    arguments: string;

    /**
     * The name of the function to call.
     */
    name: string;
  }
}

/**
 * Developer-provided instructions that the model should follow, regardless of
 * messages sent by the user. With o1 models and newer, `developer` messages
 * replace the previous `system` messages.
 */
export type ChatCompletionMessageParam =
  | ChatCompletionDeveloperMessageParam
  | ChatCompletionSystemMessageParam
  | ChatCompletionUserMessageParam
  | ChatCompletionAssistantMessageParam
  | ChatCompletionToolMessageParam
  | ChatCompletionFunctionMessageParam;

/**
 * A call to a function tool created by the model.
 */
export type ChatCompletionMessageToolCall =
  | ChatCompletionMessageFunctionToolCall
  | ChatCompletionMessageCustomToolCall;

export type ChatCompletionModality = 'text' | 'audio';

/**
 * Specifies a tool the model should use. Use to force the model to call a specific
 * function.
 */
export interface ChatCompletionNamedToolChoice {
  function: ChatCompletionNamedToolChoice.Function;

  /**
   * For function calling, the type is always `function`.
   */
  type: 'function';
}

export namespace ChatCompletionNamedToolChoice {
  export interface Function {
    /**
     * The name of the function to call.
     */
    name: string;
  }
}

/**
 * Specifies a tool the model should use. Use to force the model to call a specific
 * custom tool.
 */
export interface ChatCompletionNamedToolChoiceCustom {
  custom: ChatCompletionNamedToolChoiceCustom.Custom;

  /**
   * For custom tool calling, the type is always `custom`.
   */
  type: 'custom';
}

export namespace ChatCompletionNamedToolChoiceCustom {
  export interface Custom {
    /**
     * The name of the custom tool to call.
     */
    name: string;
  }
}

/**
 * Static predicted output content, such as the content of a text file that is
 * being regenerated.
 */
export interface ChatCompletionPredictionContent {
  /**
   * The content that should be matched when generating a model response. If
   * generated tokens would match this content, the entire model response can be
   * returned much more quickly.
   */
  content: string | Array<ChatCompletionContentPartText>;

  /**
   * The type of the predicted content you want to provide. This type is currently
   * always `content`.
   */
  type: 'content';
}

/**
 * The role of the author of a message
 */
export type ChatCompletionRole = 'developer' | 'system' | 'user' | 'assistant' | 'tool' | 'function';

/**
 * A chat completion message generated by the model.
 */
export interface ChatCompletionStoreMessage extends ChatCompletionMessage {
  /**
   * The identifier of the chat message.
   */
  id: string;

  /**
   * If a content parts array was provided, this is an array of `text` and
   * `image_url` parts. Otherwise, null.
   */
  content_parts?: Array<ChatCompletionContentPartText | ChatCompletionContentPartImage> | null;
}

/**
 * Options for streaming response. Only set this when you set `stream: true`.
 */
export interface ChatCompletionStreamOptions {
  /**
   * When true, stream obfuscation will be enabled. Stream obfuscation adds random
   * characters to an `obfuscation` field on streaming delta events to normalize
   * payload sizes as a mitigation to certain side-channel attacks. These obfuscation
   * fields are included by default, but add a small amount of overhead to the data
   * stream. You can set `include_obfuscation` to false to optimize for bandwidth if
   * you trust the network links between your application and the OpenAI API.
   */
  include_obfuscation?: boolean;

  /**
   * If set, an additional chunk will be streamed before the `data: [DONE]` message.
   * The `usage` field on this chunk shows the token usage statistics for the entire
   * request, and the `choices` field will always be an empty array.
   *
   * All other chunks will also include a `usage` field, but with a null value.
   * **NOTE:** If the stream is interrupted, you may not receive the final usage
   * chunk which contains the total token usage for the request.
   */
  include_usage?: boolean;
}

/**
 * Developer-provided instructions that the model should follow, regardless of
 * messages sent by the user. With o1 models and newer, use `developer` messages
 * for this purpose instead.
 */
export interface ChatCompletionSystemMessageParam {
  /**
   * The contents of the system message.
   */
  content: string | Array<ChatCompletionContentPartText>;

  /**
   * The role of the messages author, in this case `system`.
   */
  role: 'system';

  /**
   * An optional name for the participant. Provides the model information to
   * differentiate between participants of the same role.
   */
  name?: string;
}

export interface ChatCompletionTokenLogprob {
  /**
   * The token.
   */
  token: string;

  /**
   * A list of integers representing the UTF-8 bytes representation of the token.
   * Useful in instances where characters are represented by multiple tokens and
   * their byte representations must be combined to generate the correct text
   * representation. Can be `null` if there is no bytes representation for the token.
   */
  bytes: Array<number> | null;

  /**
   * The log probability of this token, if it is within the top 20 most likely
   * tokens. Otherwise, the value `-9999.0` is used to signify that the token is very
   * unlikely.
   */
  logprob: number;

  /**
   * List of the most likely tokens and their log probability, at this token
   * position. The number of entries may be fewer than the requested `top_logprobs`.
   */
  top_logprobs: Array<ChatCompletionTokenLogprob.TopLogprob>;
}

export namespace ChatCompletionTokenLogprob {
  export interface TopLogprob {
    /**
     * The token.
     */
    token: string;

    /**
     * A list of integers representing the UTF-8 bytes representation of the token.
     * Useful in instances where characters are represented by multiple tokens and
     * their byte representations must be combined to generate the correct text
     * representation. Can be `null` if there is no bytes representation for the token.
     */
    bytes: Array<number> | null;

    /**
     * The log probability of this token, if it is within the top 20 most likely