llama-stack-client 0.4.4 → 0.4.5

package/dist/resources/chat/completions.d.ts

@@ -6,8 +6,6 @@ import * as ChatAPI from "./chat.js";
 import { Stream } from "../../streaming.js";
 export declare class Completions extends APIResource {
     /**
-     * Create chat completions.
-     *
      * Generate an OpenAI-compatible chat completion for the given messages using the
      * specified model.
      */
@@ -15,8 +13,6 @@ export declare class Completions extends APIResource {
     create(body: CompletionCreateParamsStreaming, options?: Core.RequestOptions): APIPromise<Stream<ChatAPI.ChatCompletionChunk>>;
     create(body: CompletionCreateParamsBase, options?: Core.RequestOptions): APIPromise<Stream<ChatAPI.ChatCompletionChunk> | CompletionCreateResponse>;
     /**
-     * Get chat completion.
-     *
      * Describe a chat completion by its ID.
      */
     retrieve(completionId: string, options?: Core.RequestOptions): Core.APIPromise<CompletionRetrieveResponse>;
@@ -30,10 +26,25 @@ export declare class Completions extends APIResource {
  * Response from an OpenAI-compatible chat completion request.
  */
 export interface CompletionCreateResponse {
+    /**
+     * The ID of the chat completion.
+     */
     id: string;
+    /**
+     * List of choices.
+     */
     choices: Array<CompletionCreateResponse.Choice>;
+    /**
+     * The Unix timestamp in seconds when the chat completion was created.
+     */
     created: number;
+    /**
+     * The model that was used to generate the chat completion.
+     */
     model: string;
+    /**
+     * The object type.
+     */
     object?: 'chat.completion';
     /**
      * Usage information for OpenAI chat completion.
@@ -45,10 +56,16 @@ export declare namespace CompletionCreateResponse {
      * A choice from an OpenAI-compatible chat completion response.
      */
     interface Choice {
-        finish_reason: string;
+        /**
+         * The reason the model stopped generating.
+         */
+        finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call';
+        /**
+         * The index of the choice.
+         */
         index: number;
         /**
-         * A message from the user in an OpenAI-compatible chat completion request.
+         * The message from the model.
          */
         message: Choice.OpenAIUserMessageParamOutput | Choice.OpenAISystemMessageParam | Choice.OpenAIAssistantMessageParamOutput | Choice.OpenAIToolMessageParam | Choice.OpenAIDeveloperMessageParam;
         /**
@@ -62,8 +79,17 @@ export declare namespace CompletionCreateResponse {
          * A message from the user in an OpenAI-compatible chat completion request.
          */
         interface OpenAIUserMessageParamOutput {
+            /**
+             * The content of the message, which can include text and other media.
+             */
             content: string | Array<OpenAIUserMessageParamOutput.OpenAIChatCompletionContentPartTextParam | OpenAIUserMessageParamOutput.OpenAIChatCompletionContentPartImageParam | OpenAIUserMessageParamOutput.OpenAIFile>;
+            /**
+             * The name of the user message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'user' to identify this as a user message.
+             */
             role?: 'user';
         }
         namespace OpenAIUserMessageParamOutput {
@@ -71,7 +97,13 @@ export declare namespace CompletionCreateResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface OpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
             /**
@@ -79,28 +111,55 @@ export declare namespace CompletionCreateResponse {
              */
             interface OpenAIChatCompletionContentPartImageParam {
                 /**
-                 * Image URL specification for OpenAI-compatible chat completion messages.
+                 * Image URL specification and processing details.
                  */
                 image_url: OpenAIChatCompletionContentPartImageParam.ImageURL;
+                /**
+                 * Must be 'image_url' to identify this as image content.
+                 */
                 type?: 'image_url';
             }
             namespace OpenAIChatCompletionContentPartImageParam {
                 /**
-                 * Image URL specification for OpenAI-compatible chat completion messages.
+                 * Image URL specification and processing details.
                  */
                 interface ImageURL {
+                    /**
+                     * URL of the image to include in the message.
+                     */
                     url: string;
-                    detail?: string | null;
+                    /**
+                     * Level of detail for image processing. Can be 'low', 'high', or 'auto'.
+                     */
+                    detail?: 'low' | 'high' | 'auto' | null;
                 }
             }
             interface OpenAIFile {
+                /**
+                 * File specification.
+                 */
                 file: OpenAIFile.File;
+                /**
+                 * Must be 'file' to identify this as file content.
+                 */
                 type?: 'file';
             }
             namespace OpenAIFile {
+                /**
+                 * File specification.
+                 */
                 interface File {
+                    /**
+                     * Base64-encoded file data.
+                     */
                     file_data?: string | null;
+                    /**
+                     * ID of an uploaded file.
+                     */
                     file_id?: string | null;
+                    /**
+                     * Name of the file.
+                     */
                     filename?: string | null;
                 }
             }
@@ -109,8 +168,18 @@ export declare namespace CompletionCreateResponse {
          * A system message providing instructions or context to the model.
          */
         interface OpenAISystemMessageParam {
+            /**
+             * The content of the 'system prompt'. If multiple system messages are provided,
+             * they are concatenated.
+             */
             content: string | Array<OpenAISystemMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+            /**
+             * The name of the system message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'system' to identify this as a system message.
+             */
             role?: 'system';
         }
         namespace OpenAISystemMessageParam {
@@ -118,7 +187,13 @@ export declare namespace CompletionCreateResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
         }
@@ -127,9 +202,21 @@ export declare namespace CompletionCreateResponse {
          * chat completion request.
          */
         interface OpenAIAssistantMessageParamOutput {
+            /**
+             * The content of the model's response.
+             */
             content?: string | Array<OpenAIAssistantMessageParamOutput.ListOpenAIChatCompletionContentPartTextParam> | null;
+            /**
+             * The name of the assistant message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'assistant' to identify this as the model's response.
+             */
             role?: 'assistant';
+            /**
+             * List of tool calls. Each tool call is an OpenAIChatCompletionToolCall object.
+             */
             tool_calls?: Array<OpenAIAssistantMessageParamOutput.ToolCall> | null;
         }
         namespace OpenAIAssistantMessageParamOutput {
@@ -137,19 +224,34 @@ export declare namespace CompletionCreateResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
             /**
              * Tool call specification for OpenAI-compatible chat completion responses.
              */
             interface ToolCall {
+                /**
+                 * Unique identifier for the tool call.
+                 */
                 id?: string | null;
                 /**
                  * Function call details for OpenAI-compatible tool calls.
                  */
                 function?: ToolCall.Function | null;
+                /**
+                 * Index of the tool call in the list.
+                 */
                 index?: number | null;
+                /**
+                 * Must be 'function' to identify this as a function call.
+                 */
                 type?: 'function';
             }
             namespace ToolCall {
@@ -157,7 +259,13 @@ export declare namespace CompletionCreateResponse {
                  * Function call details for OpenAI-compatible tool calls.
                  */
                 interface Function {
+                    /**
+                     * Arguments to pass to the function as a JSON string.
+                     */
                     arguments?: string | null;
+                    /**
+                     * Name of the function to call.
+                     */
                     name?: string | null;
                 }
             }
@@ -167,8 +275,17 @@ export declare namespace CompletionCreateResponse {
          * chat completion request.
          */
         interface OpenAIToolMessageParam {
+            /**
+             * The response content from the tool.
+             */
             content: string | Array<OpenAIToolMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+            /**
+             * Unique identifier for the tool call this response is for.
+             */
             tool_call_id: string;
+            /**
+             * Must be 'tool' to identify this as a tool response.
+             */
             role?: 'tool';
         }
         namespace OpenAIToolMessageParam {
@@ -176,7 +293,13 @@ export declare namespace CompletionCreateResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
         }
@@ -184,8 +307,17 @@ export declare namespace CompletionCreateResponse {
          * A message from the developer in an OpenAI-compatible chat completion request.
          */
         interface OpenAIDeveloperMessageParam {
+            /**
+             * The content of the developer message.
+             */
             content: string | Array<OpenAIDeveloperMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+            /**
+             * The name of the developer message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'developer' to identify this as a developer message.
+             */
             role?: 'developer';
         }
         namespace OpenAIDeveloperMessageParam {
@@ -193,7 +325,13 @@ export declare namespace CompletionCreateResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
         }
@@ -202,61 +340,97 @@ export declare namespace CompletionCreateResponse {
          * chat completion response.
          */
         interface Logprobs {
+            /**
+             * The log probabilities for the tokens in the message.
+             */
             content?: Array<Logprobs.Content> | null;
+            /**
+             * The log probabilities for the refusal tokens.
+             */
             refusal?: Array<Logprobs.Refusal> | null;
         }
         namespace Logprobs {
             /**
              * The log probability for a token from an OpenAI-compatible chat completion
              * response.
-             *
-             * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-             * probability of the token :top_logprobs: The top log probabilities for the token
              */
             interface Content {
+                /**
+                 * The token.
+                 */
                 token: string;
+                /**
+                 * The log probability of the token.
+                 */
                 logprob: number;
-                top_logprobs: Array<Content.TopLogprob>;
+                /**
+                 * The bytes for the token.
+                 */
                 bytes?: Array<number> | null;
+                /**
+                 * The top log probabilities for the token.
+                 */
+                top_logprobs?: Array<Content.TopLogprob> | null;
             }
             namespace Content {
                 /**
                  * The top log probability for a token from an OpenAI-compatible chat completion
                  * response.
-                 *
-                 * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-                 * probability of the token
                  */
                 interface TopLogprob {
+                    /**
+                     * The token.
+                     */
                     token: string;
+                    /**
+                     * The log probability of the token.
+                     */
                     logprob: number;
+                    /**
+                     * The bytes for the token.
+                     */
                     bytes?: Array<number> | null;
                 }
             }
             /**
              * The log probability for a token from an OpenAI-compatible chat completion
              * response.
-             *
-             * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-             * probability of the token :top_logprobs: The top log probabilities for the token
              */
             interface Refusal {
+                /**
+                 * The token.
+                 */
                 token: string;
+                /**
+                 * The log probability of the token.
+                 */
                 logprob: number;
-                top_logprobs: Array<Refusal.TopLogprob>;
+                /**
+                 * The bytes for the token.
+                 */
                 bytes?: Array<number> | null;
+                /**
+                 * The top log probabilities for the token.
+                 */
+                top_logprobs?: Array<Refusal.TopLogprob> | null;
             }
             namespace Refusal {
                 /**
                  * The top log probability for a token from an OpenAI-compatible chat completion
                  * response.
-                 *
-                 * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-                 * probability of the token
                  */
                 interface TopLogprob {
+                    /**
+                     * The token.
+                     */
                     token: string;
+                    /**
+                     * The log probability of the token.
+                     */
                     logprob: number;
+                    /**
+                     * The bytes for the token.
+                     */
                     bytes?: Array<number> | null;
                 }
             }
@@ -266,8 +440,17 @@ export declare namespace CompletionCreateResponse {
      * Usage information for OpenAI chat completion.
      */
     interface Usage {
+        /**
+         * Number of tokens in the completion.
+         */
         completion_tokens: number;
+        /**
+         * Number of tokens in the prompt.
+         */
         prompt_tokens: number;
+        /**
+         * Total tokens used (prompt + completion).
+         */
         total_tokens: number;
         /**
          * Token details for output tokens in OpenAI chat completion usage.
@@ -283,22 +466,46 @@ export declare namespace CompletionCreateResponse {
          * Token details for output tokens in OpenAI chat completion usage.
          */
         interface CompletionTokensDetails {
+            /**
+             * Number of tokens used for reasoning (o1/o3 models).
+             */
             reasoning_tokens?: number | null;
         }
         /**
          * Token details for prompt tokens in OpenAI chat completion usage.
          */
         interface PromptTokensDetails {
+            /**
+             * Number of tokens retrieved from cache.
+             */
             cached_tokens?: number | null;
         }
     }
 }
 export interface CompletionRetrieveResponse {
+    /**
+     * The ID of the chat completion.
+     */
     id: string;
+    /**
+     * List of choices.
+     */
     choices: Array<CompletionRetrieveResponse.Choice>;
+    /**
+     * The Unix timestamp in seconds when the chat completion was created.
+     */
     created: number;
+    /**
+     * The input messages used to generate this completion.
+     */
     input_messages: Array<CompletionRetrieveResponse.OpenAIUserMessageParamOutput | CompletionRetrieveResponse.OpenAISystemMessageParam | CompletionRetrieveResponse.OpenAIAssistantMessageParamOutput | CompletionRetrieveResponse.OpenAIToolMessageParam | CompletionRetrieveResponse.OpenAIDeveloperMessageParam>;
+    /**
+     * The model that was used to generate the chat completion.
+     */
     model: string;
+    /**
+     * The object type.
+     */
     object?: 'chat.completion';
     /**
      * Usage information for OpenAI chat completion.
@@ -310,10 +517,16 @@ export declare namespace CompletionRetrieveResponse {
      * A choice from an OpenAI-compatible chat completion response.
      */
     interface Choice {
-        finish_reason: string;
+        /**
+         * The reason the model stopped generating.
+         */
+        finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call';
+        /**
+         * The index of the choice.
+         */
         index: number;
         /**
-         * A message from the user in an OpenAI-compatible chat completion request.
+         * The message from the model.
          */
         message: Choice.OpenAIUserMessageParamOutput | Choice.OpenAISystemMessageParam | Choice.OpenAIAssistantMessageParamOutput | Choice.OpenAIToolMessageParam | Choice.OpenAIDeveloperMessageParam;
         /**
@@ -327,8 +540,17 @@ export declare namespace CompletionRetrieveResponse {
          * A message from the user in an OpenAI-compatible chat completion request.
          */
         interface OpenAIUserMessageParamOutput {
+            /**
+             * The content of the message, which can include text and other media.
+             */
             content: string | Array<OpenAIUserMessageParamOutput.OpenAIChatCompletionContentPartTextParam | OpenAIUserMessageParamOutput.OpenAIChatCompletionContentPartImageParam | OpenAIUserMessageParamOutput.OpenAIFile>;
+            /**
+             * The name of the user message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'user' to identify this as a user message.
+             */
             role?: 'user';
         }
         namespace OpenAIUserMessageParamOutput {
@@ -336,7 +558,13 @@ export declare namespace CompletionRetrieveResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface OpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
             /**
@@ -344,28 +572,55 @@ export declare namespace CompletionRetrieveResponse {
              */
             interface OpenAIChatCompletionContentPartImageParam {
                 /**
-                 * Image URL specification for OpenAI-compatible chat completion messages.
+                 * Image URL specification and processing details.
                  */
                 image_url: OpenAIChatCompletionContentPartImageParam.ImageURL;
+                /**
+                 * Must be 'image_url' to identify this as image content.
+                 */
                 type?: 'image_url';
             }
             namespace OpenAIChatCompletionContentPartImageParam {
                 /**
-                 * Image URL specification for OpenAI-compatible chat completion messages.
+                 * Image URL specification and processing details.
                  */
                 interface ImageURL {
+                    /**
+                     * URL of the image to include in the message.
+                     */
                     url: string;
-                    detail?: string | null;
+                    /**
+                     * Level of detail for image processing. Can be 'low', 'high', or 'auto'.
+                     */
+                    detail?: 'low' | 'high' | 'auto' | null;
                 }
             }
             interface OpenAIFile {
+                /**
+                 * File specification.
+                 */
                 file: OpenAIFile.File;
+                /**
+                 * Must be 'file' to identify this as file content.
+                 */
                 type?: 'file';
             }
             namespace OpenAIFile {
+                /**
+                 * File specification.
+                 */
                 interface File {
+                    /**
+                     * Base64-encoded file data.
+                     */
                     file_data?: string | null;
+                    /**
+                     * ID of an uploaded file.
+                     */
                     file_id?: string | null;
+                    /**
+                     * Name of the file.
+                     */
                     filename?: string | null;
                 }
             }
@@ -374,8 +629,18 @@ export declare namespace CompletionRetrieveResponse {
          * A system message providing instructions or context to the model.
          */
         interface OpenAISystemMessageParam {
+            /**
+             * The content of the 'system prompt'. If multiple system messages are provided,
+             * they are concatenated.
+             */
             content: string | Array<OpenAISystemMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+            /**
+             * The name of the system message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'system' to identify this as a system message.
+             */
             role?: 'system';
         }
         namespace OpenAISystemMessageParam {
@@ -383,7 +648,13 @@ export declare namespace CompletionRetrieveResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
         }
@@ -392,9 +663,21 @@ export declare namespace CompletionRetrieveResponse {
          * chat completion request.
          */
         interface OpenAIAssistantMessageParamOutput {
+            /**
+             * The content of the model's response.
+             */
             content?: string | Array<OpenAIAssistantMessageParamOutput.ListOpenAIChatCompletionContentPartTextParam> | null;
+            /**
+             * The name of the assistant message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'assistant' to identify this as the model's response.
+             */
             role?: 'assistant';
+            /**
+             * List of tool calls. Each tool call is an OpenAIChatCompletionToolCall object.
+             */
             tool_calls?: Array<OpenAIAssistantMessageParamOutput.ToolCall> | null;
         }
         namespace OpenAIAssistantMessageParamOutput {
@@ -402,19 +685,34 @@ export declare namespace CompletionRetrieveResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
             /**
              * Tool call specification for OpenAI-compatible chat completion responses.
              */
             interface ToolCall {
+                /**
+                 * Unique identifier for the tool call.
+                 */
                 id?: string | null;
                 /**
                  * Function call details for OpenAI-compatible tool calls.
                  */
                 function?: ToolCall.Function | null;
+                /**
+                 * Index of the tool call in the list.
+                 */
                 index?: number | null;
+                /**
+                 * Must be 'function' to identify this as a function call.
+                 */
                 type?: 'function';
             }
             namespace ToolCall {
@@ -422,7 +720,13 @@ export declare namespace CompletionRetrieveResponse {
                  * Function call details for OpenAI-compatible tool calls.
                  */
                 interface Function {
+                    /**
+                     * Arguments to pass to the function as a JSON string.
+                     */
                     arguments?: string | null;
+                    /**
+                     * Name of the function to call.
+                     */
                     name?: string | null;
                 }
             }
@@ -432,8 +736,17 @@ export declare namespace CompletionRetrieveResponse {
          * chat completion request.
          */
         interface OpenAIToolMessageParam {
+            /**
+             * The response content from the tool.
+             */
             content: string | Array<OpenAIToolMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+            /**
+             * Unique identifier for the tool call this response is for.
+             */
             tool_call_id: string;
+            /**
+             * Must be 'tool' to identify this as a tool response.
+             */
             role?: 'tool';
         }
         namespace OpenAIToolMessageParam {
@@ -441,7 +754,13 @@ export declare namespace CompletionRetrieveResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
         }
@@ -449,8 +768,17 @@ export declare namespace CompletionRetrieveResponse {
          * A message from the developer in an OpenAI-compatible chat completion request.
          */
         interface OpenAIDeveloperMessageParam {
+            /**
+             * The content of the developer message.
+             */
             content: string | Array<OpenAIDeveloperMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+            /**
+             * The name of the developer message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'developer' to identify this as a developer message.
+             */
             role?: 'developer';
         }
         namespace OpenAIDeveloperMessageParam {
@@ -458,7 +786,13 @@ export declare namespace CompletionRetrieveResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
         }
@@ -467,61 +801,97 @@ export declare namespace CompletionRetrieveResponse {
          * chat completion response.
          */
         interface Logprobs {
+            /**
+             * The log probabilities for the tokens in the message.
+             */
             content?: Array<Logprobs.Content> | null;
+            /**
+             * The log probabilities for the refusal tokens.
+             */
             refusal?: Array<Logprobs.Refusal> | null;
         }
         namespace Logprobs {
             /**
              * The log probability for a token from an OpenAI-compatible chat completion
              * response.
-             *
-             * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-             * probability of the token :top_logprobs: The top log probabilities for the token
              */
             interface Content {
+                /**
+                 * The token.
+                 */
                 token: string;
+                /**
+                 * The log probability of the token.
+                 */
                 logprob: number;
-                top_logprobs: Array<Content.TopLogprob>;
+                /**
+                 * The bytes for the token.
+                 */
                 bytes?: Array<number> | null;
+                /**
+                 * The top log probabilities for the token.
+                 */
+                top_logprobs?: Array<Content.TopLogprob> | null;
             }
             namespace Content {
                 /**
                  * The top log probability for a token from an OpenAI-compatible chat completion
                  * response.
-                 *
-                 * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-                 * probability of the token
                  */
                 interface TopLogprob {
+                    /**
+                     * The token.
+                     */
                     token: string;
+                    /**
+                     * The log probability of the token.
+                     */
                     logprob: number;
+                    /**
+                     * The bytes for the token.
+                     */
                     bytes?: Array<number> | null;
                 }
             }
             /**
              * The log probability for a token from an OpenAI-compatible chat completion
              * response.
-             *
-             * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-             * probability of the token :top_logprobs: The top log probabilities for the token
              */
             interface Refusal {
+                /**
+                 * The token.
+                 */
                 token: string;
+                /**
+                 * The log probability of the token.
+                 */
                 logprob: number;
-                top_logprobs: Array<Refusal.TopLogprob>;
+                /**
+                 * The bytes for the token.
+                 */
                 bytes?: Array<number> | null;
+                /**
+                 * The top log probabilities for the token.
+                 */
+                top_logprobs?: Array<Refusal.TopLogprob> | null;
             }
             namespace Refusal {
                 /**
                  * The top log probability for a token from an OpenAI-compatible chat completion
                  * response.
-                 *
-                 * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-                 * probability of the token
                  */
                 interface TopLogprob {
+                    /**
+                     * The token.
+                     */
                     token: string;
+                    /**
+                     * The log probability of the token.
+                     */
                     logprob: number;
+                    /**
+                     * The bytes for the token.
+                     */
                     bytes?: Array<number> | null;
                 }
             }
@@ -531,8 +901,17 @@ export declare namespace CompletionRetrieveResponse {
      * A message from the user in an OpenAI-compatible chat completion request.
      */
     interface OpenAIUserMessageParamOutput {
+        /**
+         * The content of the message, which can include text and other media.
+         */
         content: string | Array<OpenAIUserMessageParamOutput.OpenAIChatCompletionContentPartTextParam | OpenAIUserMessageParamOutput.OpenAIChatCompletionContentPartImageParam | OpenAIUserMessageParamOutput.OpenAIFile>;
+        /**
+         * The name of the user message participant.
+         */
         name?: string | null;
+        /**
+         * Must be 'user' to identify this as a user message.
+         */
         role?: 'user';
     }
     namespace OpenAIUserMessageParamOutput {
@@ -540,7 +919,13 @@ export declare namespace CompletionRetrieveResponse {
          * Text content part for OpenAI-compatible chat completion messages.
          */
         interface OpenAIChatCompletionContentPartTextParam {
+            /**
+             * The text content of the message.
+             */
             text: string;
+            /**
+             * Must be 'text' to identify this as text content.
+             */
             type?: 'text';
         }
         /**
@@ -548,28 +933,55 @@ export declare namespace CompletionRetrieveResponse {
          */
         interface OpenAIChatCompletionContentPartImageParam {
             /**
-             * Image URL specification for OpenAI-compatible chat completion messages.
+             * Image URL specification and processing details.
              */
             image_url: OpenAIChatCompletionContentPartImageParam.ImageURL;
+            /**
+             * Must be 'image_url' to identify this as image content.
+             */
             type?: 'image_url';
         }
         namespace OpenAIChatCompletionContentPartImageParam {
             /**
-             * Image URL specification for OpenAI-compatible chat completion messages.
+             * Image URL specification and processing details.
              */
             interface ImageURL {
+                /**
+                 * URL of the image to include in the message.
+                 */
                 url: string;
-                detail?: string | null;
+                /**
+                 * Level of detail for image processing. Can be 'low', 'high', or 'auto'.
+                 */
+                detail?: 'low' | 'high' | 'auto' | null;
             }
         }
         interface OpenAIFile {
+            /**
+             * File specification.
+             */
             file: OpenAIFile.File;
+            /**
+             * Must be 'file' to identify this as file content.
+             */
             type?: 'file';
         }
         namespace OpenAIFile {
+            /**
+             * File specification.
+             */
             interface File {
+                /**
+                 * Base64-encoded file data.
+                 */
                 file_data?: string | null;
+                /**
+                 * ID of an uploaded file.
+                 */
                 file_id?: string | null;
+                /**
+                 * Name of the file.
+                 */
                 filename?: string | null;
             }
         }
@@ -578,8 +990,18 @@ export declare namespace CompletionRetrieveResponse {
      * A system message providing instructions or context to the model.
      */
     interface OpenAISystemMessageParam {
+        /**
+         * The content of the 'system prompt'. If multiple system messages are provided,
+         * they are concatenated.
+         */
         content: string | Array<OpenAISystemMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+        /**
+         * The name of the system message participant.
+         */
         name?: string | null;
+        /**
+         * Must be 'system' to identify this as a system message.
+         */
         role?: 'system';
     }
     namespace OpenAISystemMessageParam {
@@ -587,7 +1009,13 @@ export declare namespace CompletionRetrieveResponse {
          * Text content part for OpenAI-compatible chat completion messages.
          */
         interface ListOpenAIChatCompletionContentPartTextParam {
+            /**
+             * The text content of the message.
+             */
             text: string;
+            /**
+             * Must be 'text' to identify this as text content.
+             */
             type?: 'text';
         }
     }
@@ -596,9 +1024,21 @@ export declare namespace CompletionRetrieveResponse {
      * chat completion request.
      */
     interface OpenAIAssistantMessageParamOutput {
+        /**
+         * The content of the model's response.
+         */
         content?: string | Array<OpenAIAssistantMessageParamOutput.ListOpenAIChatCompletionContentPartTextParam> | null;
+        /**
+         * The name of the assistant message participant.
+         */
         name?: string | null;
+        /**
+         * Must be 'assistant' to identify this as the model's response.
+         */
         role?: 'assistant';
+        /**
+         * List of tool calls. Each tool call is an OpenAIChatCompletionToolCall object.
+         */
         tool_calls?: Array<OpenAIAssistantMessageParamOutput.ToolCall> | null;
     }
     namespace OpenAIAssistantMessageParamOutput {
@@ -606,19 +1046,34 @@ export declare namespace CompletionRetrieveResponse {
          * Text content part for OpenAI-compatible chat completion messages.
          */
         interface ListOpenAIChatCompletionContentPartTextParam {
+            /**
+             * The text content of the message.
+             */
             text: string;
+            /**
+             * Must be 'text' to identify this as text content.
+             */
             type?: 'text';
         }
         /**
          * Tool call specification for OpenAI-compatible chat completion responses.
          */
         interface ToolCall {
+            /**
+             * Unique identifier for the tool call.
+             */
             id?: string | null;
             /**
              * Function call details for OpenAI-compatible tool calls.
              */
             function?: ToolCall.Function | null;
+            /**
+             * Index of the tool call in the list.
+             */
             index?: number | null;
+            /**
+             * Must be 'function' to identify this as a function call.
+             */
             type?: 'function';
         }
         namespace ToolCall {
@@ -626,7 +1081,13 @@ export declare namespace CompletionRetrieveResponse {
              * Function call details for OpenAI-compatible tool calls.
              */
             interface Function {
+                /**
+                 * Arguments to pass to the function as a JSON string.
+                 */
                 arguments?: string | null;
+                /**
+                 * Name of the function to call.
+                 */
                 name?: string | null;
             }
         }
@@ -636,8 +1097,17 @@ export declare namespace CompletionRetrieveResponse {
      * chat completion request.
      */
     interface OpenAIToolMessageParam {
+        /**
+         * The response content from the tool.
+         */
         content: string | Array<OpenAIToolMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+        /**
+         * Unique identifier for the tool call this response is for.
+         */
         tool_call_id: string;
+        /**
+         * Must be 'tool' to identify this as a tool response.
+         */
         role?: 'tool';
     }
     namespace OpenAIToolMessageParam {
@@ -645,7 +1115,13 @@ export declare namespace CompletionRetrieveResponse {
          * Text content part for OpenAI-compatible chat completion messages.
          */
         interface ListOpenAIChatCompletionContentPartTextParam {
+            /**
+             * The text content of the message.
+             */
             text: string;
+            /**
+             * Must be 'text' to identify this as text content.
+             */
             type?: 'text';
         }
     }
@@ -653,8 +1129,17 @@ export declare namespace CompletionRetrieveResponse {
      * A message from the developer in an OpenAI-compatible chat completion request.
      */
     interface OpenAIDeveloperMessageParam {
+        /**
+         * The content of the developer message.
+         */
         content: string | Array<OpenAIDeveloperMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+        /**
+         * The name of the developer message participant.
+         */
         name?: string | null;
+        /**
+         * Must be 'developer' to identify this as a developer message.
+         */
         role?: 'developer';
     }
     namespace OpenAIDeveloperMessageParam {
@@ -662,7 +1147,13 @@ export declare namespace CompletionRetrieveResponse {
          * Text content part for OpenAI-compatible chat completion messages.
          */
         interface ListOpenAIChatCompletionContentPartTextParam {
+            /**
+             * The text content of the message.
+             */
             text: string;
+            /**
+             * Must be 'text' to identify this as text content.
+             */
             type?: 'text';
         }
     }
@@ -670,8 +1161,17 @@ export declare namespace CompletionRetrieveResponse {
      * Usage information for OpenAI chat completion.
      */
     interface Usage {
+        /**
+         * Number of tokens in the completion.
+         */
         completion_tokens: number;
+        /**
+         * Number of tokens in the prompt.
+         */
         prompt_tokens: number;
+        /**
+         * Total tokens used (prompt + completion).
+         */
         total_tokens: number;
         /**
          * Token details for output tokens in OpenAI chat completion usage.
@@ -687,12 +1187,18 @@ export declare namespace CompletionRetrieveResponse {
          * Token details for output tokens in OpenAI chat completion usage.
          */
         interface CompletionTokensDetails {
+            /**
+             * Number of tokens used for reasoning (o1/o3 models).
+             */
             reasoning_tokens?: number | null;
         }
         /**
          * Token details for prompt tokens in OpenAI chat completion usage.
          */
         interface PromptTokensDetails {
+            /**
+             * Number of tokens retrieved from cache.
+             */
             cached_tokens?: number | null;
         }
     }
@@ -701,19 +1207,52 @@ export declare namespace CompletionRetrieveResponse {
  * Response from listing OpenAI-compatible chat completions.
  */
 export interface CompletionListResponse {
+    /**
+     * List of chat completion objects with their input messages.
+     */
     data: Array<CompletionListResponse.Data>;
+    /**
+     * ID of the first completion in this list.
+     */
     first_id: string;
+    /**
+     * Whether there are more completions available beyond this list.
+     */
     has_more: boolean;
+    /**
+     * ID of the last completion in this list.
+     */
     last_id: string;
+    /**
+     * Must be 'list' to identify this as a list response.
+     */
     object?: 'list';
 }
 export declare namespace CompletionListResponse {
     interface Data {
+        /**
+         * The ID of the chat completion.
+         */
         id: string;
+        /**
+         * List of choices.
+         */
         choices: Array<Data.Choice>;
+        /**
+         * The Unix timestamp in seconds when the chat completion was created.
+         */
         created: number;
+        /**
+         * The input messages used to generate this completion.
+         */
         input_messages: Array<Data.OpenAIUserMessageParamOutput | Data.OpenAISystemMessageParam | Data.OpenAIAssistantMessageParamOutput | Data.OpenAIToolMessageParam | Data.OpenAIDeveloperMessageParam>;
+        /**
+         * The model that was used to generate the chat completion.
+         */
         model: string;
+        /**
+         * The object type.
+         */
         object?: 'chat.completion';
         /**
          * Usage information for OpenAI chat completion.
@@ -725,10 +1264,16 @@ export declare namespace CompletionListResponse {
          * A choice from an OpenAI-compatible chat completion response.
          */
         interface Choice {
-            finish_reason: string;
+            /**
+             * The reason the model stopped generating.
+             */
+            finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call';
+            /**
+             * The index of the choice.
+             */
             index: number;
             /**
-             * A message from the user in an OpenAI-compatible chat completion request.
+             * The message from the model.
              */
             message: Choice.OpenAIUserMessageParamOutput | Choice.OpenAISystemMessageParam | Choice.OpenAIAssistantMessageParamOutput | Choice.OpenAIToolMessageParam | Choice.OpenAIDeveloperMessageParam;
             /**
@@ -742,8 +1287,17 @@ export declare namespace CompletionListResponse {
              * A message from the user in an OpenAI-compatible chat completion request.
              */
             interface OpenAIUserMessageParamOutput {
+                /**
+                 * The content of the message, which can include text and other media.
+                 */
                 content: string | Array<OpenAIUserMessageParamOutput.OpenAIChatCompletionContentPartTextParam | OpenAIUserMessageParamOutput.OpenAIChatCompletionContentPartImageParam | OpenAIUserMessageParamOutput.OpenAIFile>;
+                /**
+                 * The name of the user message participant.
+                 */
                 name?: string | null;
+                /**
+                 * Must be 'user' to identify this as a user message.
+                 */
                 role?: 'user';
             }
             namespace OpenAIUserMessageParamOutput {
@@ -751,7 +1305,13 @@ export declare namespace CompletionListResponse {
                  * Text content part for OpenAI-compatible chat completion messages.
                  */
                 interface OpenAIChatCompletionContentPartTextParam {
+                    /**
+                     * The text content of the message.
+                     */
                     text: string;
+                    /**
+                     * Must be 'text' to identify this as text content.
+                     */
                     type?: 'text';
                 }
                 /**
@@ -759,28 +1319,55 @@ export declare namespace CompletionListResponse {
                  */
                 interface OpenAIChatCompletionContentPartImageParam {
                     /**
-                     * Image URL specification for OpenAI-compatible chat completion messages.
+                     * Image URL specification and processing details.
                      */
                     image_url: OpenAIChatCompletionContentPartImageParam.ImageURL;
+                    /**
+                     * Must be 'image_url' to identify this as image content.
+                     */
                     type?: 'image_url';
                 }
                 namespace OpenAIChatCompletionContentPartImageParam {
                     /**
-                     * Image URL specification for OpenAI-compatible chat completion messages.
+                     * Image URL specification and processing details.
                      */
                     interface ImageURL {
+                        /**
+                         * URL of the image to include in the message.
+                         */
                         url: string;
-                        detail?: string | null;
+                        /**
+                         * Level of detail for image processing. Can be 'low', 'high', or 'auto'.
+                         */
+                        detail?: 'low' | 'high' | 'auto' | null;
                     }
                 }
                 interface OpenAIFile {
+                    /**
+                     * File specification.
+                     */
                     file: OpenAIFile.File;
+                    /**
+                     * Must be 'file' to identify this as file content.
+                     */
                     type?: 'file';
                 }
                 namespace OpenAIFile {
+                    /**
+                     * File specification.
+                     */
                     interface File {
+                        /**
+                         * Base64-encoded file data.
+                         */
                         file_data?: string | null;
+                        /**
+                         * ID of an uploaded file.
+                         */
                         file_id?: string | null;
+                        /**
+                         * Name of the file.
+                         */
                         filename?: string | null;
                     }
                 }
@@ -789,8 +1376,18 @@ export declare namespace CompletionListResponse {
              * A system message providing instructions or context to the model.
              */
             interface OpenAISystemMessageParam {
+                /**
+                 * The content of the 'system prompt'. If multiple system messages are provided,
+                 * they are concatenated.
+                 */
                 content: string | Array<OpenAISystemMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+                /**
+                 * The name of the system message participant.
+                 */
                 name?: string | null;
+                /**
+                 * Must be 'system' to identify this as a system message.
+                 */
                 role?: 'system';
             }
             namespace OpenAISystemMessageParam {
@@ -798,7 +1395,13 @@ export declare namespace CompletionListResponse {
                  * Text content part for OpenAI-compatible chat completion messages.
                  */
                 interface ListOpenAIChatCompletionContentPartTextParam {
+                    /**
+                     * The text content of the message.
+                     */
                     text: string;
+                    /**
+                     * Must be 'text' to identify this as text content.
+                     */
                     type?: 'text';
                 }
             }
@@ -807,9 +1410,21 @@ export declare namespace CompletionListResponse {
              * chat completion request.
              */
             interface OpenAIAssistantMessageParamOutput {
+                /**
+                 * The content of the model's response.
+                 */
                 content?: string | Array<OpenAIAssistantMessageParamOutput.ListOpenAIChatCompletionContentPartTextParam> | null;
+                /**
+                 * The name of the assistant message participant.
+                 */
                 name?: string | null;
+                /**
+                 * Must be 'assistant' to identify this as the model's response.
+                 */
                 role?: 'assistant';
+                /**
+                 * List of tool calls. Each tool call is an OpenAIChatCompletionToolCall object.
+                 */
                 tool_calls?: Array<OpenAIAssistantMessageParamOutput.ToolCall> | null;
             }
             namespace OpenAIAssistantMessageParamOutput {
@@ -817,19 +1432,34 @@ export declare namespace CompletionListResponse {
                  * Text content part for OpenAI-compatible chat completion messages.
                  */
                 interface ListOpenAIChatCompletionContentPartTextParam {
+                    /**
+                     * The text content of the message.
+                     */
                     text: string;
+                    /**
+                     * Must be 'text' to identify this as text content.
+                     */
                     type?: 'text';
                 }
                 /**
                  * Tool call specification for OpenAI-compatible chat completion responses.
                  */
                 interface ToolCall {
+                    /**
+                     * Unique identifier for the tool call.
+                     */
                     id?: string | null;
                     /**
                      * Function call details for OpenAI-compatible tool calls.
                      */
                     function?: ToolCall.Function | null;
+                    /**
+                     * Index of the tool call in the list.
+                     */
                     index?: number | null;
+                    /**
+                     * Must be 'function' to identify this as a function call.
+                     */
                     type?: 'function';
                 }
                 namespace ToolCall {
@@ -837,7 +1467,13 @@ export declare namespace CompletionListResponse {
                      * Function call details for OpenAI-compatible tool calls.
                      */
                     interface Function {
+                        /**
+                         * Arguments to pass to the function as a JSON string.
+                         */
                         arguments?: string | null;
+                        /**
+                         * Name of the function to call.
+                         */
                         name?: string | null;
                     }
                 }
@@ -847,8 +1483,17 @@ export declare namespace CompletionListResponse {
              * chat completion request.
              */
             interface OpenAIToolMessageParam {
+                /**
+                 * The response content from the tool.
+                 */
                 content: string | Array<OpenAIToolMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+                /**
+                 * Unique identifier for the tool call this response is for.
+                 */
                 tool_call_id: string;
+                /**
+                 * Must be 'tool' to identify this as a tool response.
+                 */
                 role?: 'tool';
             }
             namespace OpenAIToolMessageParam {
@@ -856,7 +1501,13 @@ export declare namespace CompletionListResponse {
                  * Text content part for OpenAI-compatible chat completion messages.
                  */
                 interface ListOpenAIChatCompletionContentPartTextParam {
+                    /**
+                     * The text content of the message.
+                     */
                     text: string;
+                    /**
+                     * Must be 'text' to identify this as text content.
+                     */
                     type?: 'text';
                 }
             }
@@ -864,8 +1515,17 @@ export declare namespace CompletionListResponse {
              * A message from the developer in an OpenAI-compatible chat completion request.
              */
             interface OpenAIDeveloperMessageParam {
+                /**
+                 * The content of the developer message.
+                 */
                 content: string | Array<OpenAIDeveloperMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+                /**
+                 * The name of the developer message participant.
+                 */
                 name?: string | null;
+                /**
+                 * Must be 'developer' to identify this as a developer message.
+                 */
                 role?: 'developer';
             }
             namespace OpenAIDeveloperMessageParam {
@@ -873,7 +1533,13 @@ export declare namespace CompletionListResponse {
                  * Text content part for OpenAI-compatible chat completion messages.
                  */
                 interface ListOpenAIChatCompletionContentPartTextParam {
+                    /**
+                     * The text content of the message.
+                     */
                     text: string;
+                    /**
+                     * Must be 'text' to identify this as text content.
+                     */
                     type?: 'text';
                 }
             }
@@ -882,61 +1548,97 @@ export declare namespace CompletionListResponse {
              * chat completion response.
              */
             interface Logprobs {
+                /**
+                 * The log probabilities for the tokens in the message.
+                 */
                 content?: Array<Logprobs.Content> | null;
+                /**
+                 * The log probabilities for the refusal tokens.
+                 */
                 refusal?: Array<Logprobs.Refusal> | null;
             }
             namespace Logprobs {
                 /**
                  * The log probability for a token from an OpenAI-compatible chat completion
                  * response.
-                 *
-                 * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-                 * probability of the token :top_logprobs: The top log probabilities for the token
                  */
                 interface Content {
+                    /**
+                     * The token.
+                     */
                     token: string;
+                    /**
+                     * The log probability of the token.
+                     */
                     logprob: number;
-                    top_logprobs: Array<Content.TopLogprob>;
+                    /**
+                     * The bytes for the token.
+                     */
                     bytes?: Array<number> | null;
+                    /**
+                     * The top log probabilities for the token.
+                     */
+                    top_logprobs?: Array<Content.TopLogprob> | null;
                 }
                 namespace Content {
                     /**
                      * The top log probability for a token from an OpenAI-compatible chat completion
                      * response.
-                     *
-                     * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-                     * probability of the token
                      */
                     interface TopLogprob {
+                        /**
+                         * The token.
+                         */
                         token: string;
+                        /**
+                         * The log probability of the token.
+                         */
                         logprob: number;
+                        /**
+                         * The bytes for the token.
+                         */
                         bytes?: Array<number> | null;
                     }
                 }
                 /**
                  * The log probability for a token from an OpenAI-compatible chat completion
                  * response.
-                 *
-                 * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-                 * probability of the token :top_logprobs: The top log probabilities for the token
                  */
                 interface Refusal {
+                    /**
+                     * The token.
+                     */
                     token: string;
+                    /**
+                     * The log probability of the token.
+                     */
                     logprob: number;
-                    top_logprobs: Array<Refusal.TopLogprob>;
+                    /**
+                     * The bytes for the token.
+                     */
                     bytes?: Array<number> | null;
+                    /**
+                     * The top log probabilities for the token.
+                     */
+                    top_logprobs?: Array<Refusal.TopLogprob> | null;
                 }
                 namespace Refusal {
                     /**
                      * The top log probability for a token from an OpenAI-compatible chat completion
                      * response.
-                     *
-                     * :token: The token :bytes: (Optional) The bytes for the token :logprob: The log
-                     * probability of the token
                      */
                     interface TopLogprob {
+                        /**
+                         * The token.
+                         */
                         token: string;
+                        /**
+                         * The log probability of the token.
+                         */
                         logprob: number;
+                        /**
+                         * The bytes for the token.
+                         */
                         bytes?: Array<number> | null;
                     }
                 }
@@ -946,8 +1648,17 @@ export declare namespace CompletionListResponse {
          * A message from the user in an OpenAI-compatible chat completion request.
          */
         interface OpenAIUserMessageParamOutput {
+            /**
+             * The content of the message, which can include text and other media.
+             */
             content: string | Array<OpenAIUserMessageParamOutput.OpenAIChatCompletionContentPartTextParam | OpenAIUserMessageParamOutput.OpenAIChatCompletionContentPartImageParam | OpenAIUserMessageParamOutput.OpenAIFile>;
+            /**
+             * The name of the user message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'user' to identify this as a user message.
+             */
             role?: 'user';
         }
         namespace OpenAIUserMessageParamOutput {
@@ -955,7 +1666,13 @@ export declare namespace CompletionListResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface OpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
             /**
@@ -963,28 +1680,55 @@ export declare namespace CompletionListResponse {
              */
             interface OpenAIChatCompletionContentPartImageParam {
                 /**
-                 * Image URL specification for OpenAI-compatible chat completion messages.
+                 * Image URL specification and processing details.
                  */
                 image_url: OpenAIChatCompletionContentPartImageParam.ImageURL;
+                /**
+                 * Must be 'image_url' to identify this as image content.
+                 */
                 type?: 'image_url';
             }
             namespace OpenAIChatCompletionContentPartImageParam {
                 /**
-                 * Image URL specification for OpenAI-compatible chat completion messages.
+                 * Image URL specification and processing details.
                  */
                 interface ImageURL {
+                    /**
+                     * URL of the image to include in the message.
+                     */
                     url: string;
-                    detail?: string | null;
+                    /**
+                     * Level of detail for image processing. Can be 'low', 'high', or 'auto'.
+                     */
+                    detail?: 'low' | 'high' | 'auto' | null;
                 }
             }
             interface OpenAIFile {
+                /**
+                 * File specification.
+                 */
                 file: OpenAIFile.File;
+                /**
+                 * Must be 'file' to identify this as file content.
+                 */
                 type?: 'file';
             }
             namespace OpenAIFile {
+                /**
+                 * File specification.
+                 */
                 interface File {
+                    /**
+                     * Base64-encoded file data.
+                     */
                     file_data?: string | null;
+                    /**
+                     * ID of an uploaded file.
+                     */
                     file_id?: string | null;
+                    /**
+                     * Name of the file.
+                     */
                     filename?: string | null;
                 }
             }
@@ -993,8 +1737,18 @@ export declare namespace CompletionListResponse {
          * A system message providing instructions or context to the model.
          */
         interface OpenAISystemMessageParam {
+            /**
+             * The content of the 'system prompt'. If multiple system messages are provided,
+             * they are concatenated.
+             */
             content: string | Array<OpenAISystemMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+            /**
+             * The name of the system message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'system' to identify this as a system message.
+             */
             role?: 'system';
         }
         namespace OpenAISystemMessageParam {
@@ -1002,7 +1756,13 @@ export declare namespace CompletionListResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
         }
@@ -1011,9 +1771,21 @@ export declare namespace CompletionListResponse {
          * chat completion request.
          */
         interface OpenAIAssistantMessageParamOutput {
+            /**
+             * The content of the model's response.
+             */
             content?: string | Array<OpenAIAssistantMessageParamOutput.ListOpenAIChatCompletionContentPartTextParam> | null;
+            /**
+             * The name of the assistant message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'assistant' to identify this as the model's response.
+             */
             role?: 'assistant';
+            /**
+             * List of tool calls. Each tool call is an OpenAIChatCompletionToolCall object.
+             */
             tool_calls?: Array<OpenAIAssistantMessageParamOutput.ToolCall> | null;
         }
         namespace OpenAIAssistantMessageParamOutput {
@@ -1021,19 +1793,34 @@ export declare namespace CompletionListResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
             /**
              * Tool call specification for OpenAI-compatible chat completion responses.
              */
             interface ToolCall {
+                /**
+                 * Unique identifier for the tool call.
+                 */
                 id?: string | null;
                 /**
                  * Function call details for OpenAI-compatible tool calls.
                  */
                 function?: ToolCall.Function | null;
+                /**
+                 * Index of the tool call in the list.
+                 */
                 index?: number | null;
+                /**
+                 * Must be 'function' to identify this as a function call.
+                 */
                 type?: 'function';
             }
             namespace ToolCall {
@@ -1041,7 +1828,13 @@ export declare namespace CompletionListResponse {
                  * Function call details for OpenAI-compatible tool calls.
                  */
                 interface Function {
+                    /**
+                     * Arguments to pass to the function as a JSON string.
+                     */
                     arguments?: string | null;
+                    /**
+                     * Name of the function to call.
+                     */
                     name?: string | null;
                 }
             }
@@ -1051,8 +1844,17 @@ export declare namespace CompletionListResponse {
          * chat completion request.
          */
         interface OpenAIToolMessageParam {
+            /**
+             * The response content from the tool.
+             */
             content: string | Array<OpenAIToolMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+            /**
+             * Unique identifier for the tool call this response is for.
+             */
             tool_call_id: string;
+            /**
+             * Must be 'tool' to identify this as a tool response.
+             */
             role?: 'tool';
         }
         namespace OpenAIToolMessageParam {
@@ -1060,7 +1862,13 @@ export declare namespace CompletionListResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
         }
@@ -1068,8 +1876,17 @@ export declare namespace CompletionListResponse {
          * A message from the developer in an OpenAI-compatible chat completion request.
          */
         interface OpenAIDeveloperMessageParam {
+            /**
+             * The content of the developer message.
+             */
             content: string | Array<OpenAIDeveloperMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+            /**
+             * The name of the developer message participant.
+             */
             name?: string | null;
+            /**
+             * Must be 'developer' to identify this as a developer message.
+             */
             role?: 'developer';
         }
         namespace OpenAIDeveloperMessageParam {
@@ -1077,7 +1894,13 @@ export declare namespace CompletionListResponse {
              * Text content part for OpenAI-compatible chat completion messages.
              */
             interface ListOpenAIChatCompletionContentPartTextParam {
+                /**
+                 * The text content of the message.
+                 */
                 text: string;
+                /**
+                 * Must be 'text' to identify this as text content.
+                 */
                 type?: 'text';
             }
         }
@@ -1085,8 +1908,17 @@ export declare namespace CompletionListResponse {
          * Usage information for OpenAI chat completion.
          */
         interface Usage {
+            /**
+             * Number of tokens in the completion.
+             */
             completion_tokens: number;
+            /**
+             * Number of tokens in the prompt.
+             */
             prompt_tokens: number;
+            /**
+             * Total tokens used (prompt + completion).
+             */
             total_tokens: number;
             /**
              * Token details for output tokens in OpenAI chat completion usage.
@@ -1102,12 +1934,18 @@ export declare namespace CompletionListResponse {
              * Token details for output tokens in OpenAI chat completion usage.
              */
             interface CompletionTokensDetails {
+                /**
+                 * Number of tokens used for reasoning (o1/o3 models).
+                 */
                 reasoning_tokens?: number | null;
             }
             /**
              * Token details for prompt tokens in OpenAI chat completion usage.
              */
             interface PromptTokensDetails {
+                /**
+                 * Number of tokens retrieved from cache.
+                 */
                 cached_tokens?: number | null;
             }
         }
@@ -1115,43 +1953,117 @@ export declare namespace CompletionListResponse {
 }
 export type CompletionCreateParams = CompletionCreateParamsNonStreaming | CompletionCreateParamsStreaming;
 export interface CompletionCreateParamsBase {
+    /**
+     * List of messages in the conversation.
+     */
     messages: Array<CompletionCreateParams.OpenAIUserMessageParamInput | CompletionCreateParams.OpenAISystemMessageParam | CompletionCreateParams.OpenAIAssistantMessageParamInput | CompletionCreateParams.OpenAIToolMessageParam | CompletionCreateParams.OpenAIDeveloperMessageParam>;
+    /**
+     * The identifier of the model to use.
+     */
     model: string;
+    /**
+     * The penalty for repeated tokens.
+     */
     frequency_penalty?: number | null;
+    /**
+     * The function call to use.
+     */
     function_call?: string | {
         [key: string]: unknown;
     } | null;
+    /**
+     * List of functions to use.
+     */
     functions?: Array<{
         [key: string]: unknown;
     }> | null;
+    /**
+     * The logit bias to use.
+     */
     logit_bias?: {
         [key: string]: number;
     } | null;
+    /**
+     * The log probabilities to use.
+     */
     logprobs?: boolean | null;
+    /**
+     * The maximum number of tokens to generate.
+     */
     max_completion_tokens?: number | null;
+    /**
+     * The maximum number of tokens to generate.
+     */
     max_tokens?: number | null;
+    /**
+     * The number of completions to generate.
+     */
     n?: number | null;
+    /**
+     * Whether to parallelize tool calls.
+     */
     parallel_tool_calls?: boolean | null;
+    /**
+     * The penalty for repeated tokens.
+     */
     presence_penalty?: number | null;
     /**
-     * Text response format for OpenAI-compatible chat completion requests.
+     * The effort level for reasoning models.
+     */
+    reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | null;
+    /**
+     * The response format to use.
      */
     response_format?: CompletionCreateParams.OpenAIResponseFormatText | CompletionCreateParams.OpenAIResponseFormatJsonSchema | CompletionCreateParams.OpenAIResponseFormatJsonObject | null;
+    /**
+     * A stable identifier used for safety monitoring and abuse detection.
+     */
+    safety_identifier?: string | null;
+    /**
+     * The seed to use.
+     */
     seed?: number | null;
+    /**
+     * The stop tokens to use.
+     */
     stop?: string | Array<string> | null;
+    /**
+     * Whether to stream the response.
+     */
     stream?: boolean | null;
+    /**
+     * The stream options to use.
+     */
     stream_options?: {
         [key: string]: unknown;
     } | null;
+    /**
+     * The temperature to use.
+     */
     temperature?: number | null;
+    /**
+     * The tool choice to use.
+     */
     tool_choice?: string | {
         [key: string]: unknown;
     } | null;
+    /**
+     * The tools to use.
+     */
     tools?: Array<{
         [key: string]: unknown;
     }> | null;
+    /**
+     * The top log probabilities to use.
+     */
     top_logprobs?: number | null;
+    /**
+     * The top p to use.
+     */
     top_p?: number | null;
+    /**
+     * The user to use.
+     */
     user?: string | null;
     [k: string]: unknown;
 }
@@ -1160,8 +2072,17 @@ export declare namespace CompletionCreateParams {
      * A message from the user in an OpenAI-compatible chat completion request.
      */
     interface OpenAIUserMessageParamInput {
+        /**
+         * The content of the message, which can include text and other media.
+         */
         content: string | Array<OpenAIUserMessageParamInput.OpenAIChatCompletionContentPartTextParam | OpenAIUserMessageParamInput.OpenAIChatCompletionContentPartImageParam | OpenAIUserMessageParamInput.OpenAIFile>;
+        /**
+         * The name of the user message participant.
+         */
         name?: string | null;
+        /**
+         * Must be 'user' to identify this as a user message.
+         */
         role?: 'user';
     }
     namespace OpenAIUserMessageParamInput {
@@ -1169,7 +2090,13 @@ export declare namespace CompletionCreateParams {
          * Text content part for OpenAI-compatible chat completion messages.
          */
         interface OpenAIChatCompletionContentPartTextParam {
+            /**
+             * The text content of the message.
+             */
             text: string;
+            /**
+             * Must be 'text' to identify this as text content.
+             */
             type?: 'text';
         }
         /**
@@ -1177,28 +2104,55 @@ export declare namespace CompletionCreateParams {
          */
         interface OpenAIChatCompletionContentPartImageParam {
             /**
-             * Image URL specification for OpenAI-compatible chat completion messages.
+             * Image URL specification and processing details.
              */
             image_url: OpenAIChatCompletionContentPartImageParam.ImageURL;
+            /**
+             * Must be 'image_url' to identify this as image content.
+             */
             type?: 'image_url';
         }
         namespace OpenAIChatCompletionContentPartImageParam {
             /**
-             * Image URL specification for OpenAI-compatible chat completion messages.
+             * Image URL specification and processing details.
              */
             interface ImageURL {
+                /**
+                 * URL of the image to include in the message.
+                 */
                 url: string;
-                detail?: string | null;
+                /**
+                 * Level of detail for image processing. Can be 'low', 'high', or 'auto'.
+                 */
+                detail?: 'low' | 'high' | 'auto' | null;
             }
         }
         interface OpenAIFile {
+            /**
+             * File specification.
+             */
             file: OpenAIFile.File;
+            /**
+             * Must be 'file' to identify this as file content.
+             */
             type?: 'file';
         }
         namespace OpenAIFile {
+            /**
+             * File specification.
+             */
             interface File {
+                /**
+                 * Base64-encoded file data.
+                 */
                 file_data?: string | null;
+                /**
+                 * ID of an uploaded file.
+                 */
                 file_id?: string | null;
+                /**
+                 * Name of the file.
+                 */
                 filename?: string | null;
             }
         }
@@ -1207,8 +2161,18 @@ export declare namespace CompletionCreateParams {
      * A system message providing instructions or context to the model.
      */
     interface OpenAISystemMessageParam {
+        /**
+         * The content of the 'system prompt'. If multiple system messages are provided,
+         * they are concatenated.
+         */
         content: string | Array<OpenAISystemMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+        /**
+         * The name of the system message participant.
+         */
         name?: string | null;
+        /**
+         * Must be 'system' to identify this as a system message.
+         */
         role?: 'system';
     }
     namespace OpenAISystemMessageParam {
@@ -1216,7 +2180,13 @@ export declare namespace CompletionCreateParams {
          * Text content part for OpenAI-compatible chat completion messages.
          */
         interface ListOpenAIChatCompletionContentPartTextParam {
+            /**
+             * The text content of the message.
+             */
             text: string;
+            /**
+             * Must be 'text' to identify this as text content.
+             */
             type?: 'text';
         }
     }
@@ -1225,9 +2195,21 @@ export declare namespace CompletionCreateParams {
      * chat completion request.
      */
     interface OpenAIAssistantMessageParamInput {
+        /**
+         * The content of the model's response.
+         */
         content?: string | Array<OpenAIAssistantMessageParamInput.ListOpenAIChatCompletionContentPartTextParam> | null;
+        /**
+         * The name of the assistant message participant.
+         */
         name?: string | null;
+        /**
+         * Must be 'assistant' to identify this as the model's response.
+         */
         role?: 'assistant';
+        /**
+         * List of tool calls. Each tool call is an OpenAIChatCompletionToolCall object.
+         */
         tool_calls?: Array<OpenAIAssistantMessageParamInput.ToolCall> | null;
     }
     namespace OpenAIAssistantMessageParamInput {
@@ -1235,19 +2217,34 @@ export declare namespace CompletionCreateParams {
          * Text content part for OpenAI-compatible chat completion messages.
          */
         interface ListOpenAIChatCompletionContentPartTextParam {
+            /**
+             * The text content of the message.
+             */
             text: string;
+            /**
+             * Must be 'text' to identify this as text content.
+             */
             type?: 'text';
         }
         /**
          * Tool call specification for OpenAI-compatible chat completion responses.
          */
         interface ToolCall {
+            /**
+             * Unique identifier for the tool call.
+             */
             id?: string | null;
             /**
              * Function call details for OpenAI-compatible tool calls.
              */
             function?: ToolCall.Function | null;
+            /**
+             * Index of the tool call in the list.
+             */
             index?: number | null;
+            /**
+             * Must be 'function' to identify this as a function call.
+             */
             type?: 'function';
         }
         namespace ToolCall {
@@ -1255,7 +2252,13 @@ export declare namespace CompletionCreateParams {
              * Function call details for OpenAI-compatible tool calls.
              */
             interface Function {
+                /**
+                 * Arguments to pass to the function as a JSON string.
+                 */
                 arguments?: string | null;
+                /**
+                 * Name of the function to call.
+                 */
                 name?: string | null;
             }
         }
@@ -1265,8 +2268,17 @@ export declare namespace CompletionCreateParams {
      * chat completion request.
      */
     interface OpenAIToolMessageParam {
+        /**
+         * The response content from the tool.
+         */
         content: string | Array<OpenAIToolMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+        /**
+         * Unique identifier for the tool call this response is for.
+         */
         tool_call_id: string;
+        /**
+         * Must be 'tool' to identify this as a tool response.
+         */
         role?: 'tool';
     }
     namespace OpenAIToolMessageParam {
@@ -1274,7 +2286,13 @@ export declare namespace CompletionCreateParams {
          * Text content part for OpenAI-compatible chat completion messages.
          */
         interface ListOpenAIChatCompletionContentPartTextParam {
+            /**
+             * The text content of the message.
+             */
             text: string;
+            /**
+             * Must be 'text' to identify this as text content.
+             */
             type?: 'text';
         }
     }
@@ -1282,8 +2300,17 @@ export declare namespace CompletionCreateParams {
      * A message from the developer in an OpenAI-compatible chat completion request.
      */
     interface OpenAIDeveloperMessageParam {
+        /**
+         * The content of the developer message.
+         */
         content: string | Array<OpenAIDeveloperMessageParam.ListOpenAIChatCompletionContentPartTextParam>;
+        /**
+         * The name of the developer message participant.
+         */
         name?: string | null;
+        /**
+         * Must be 'developer' to identify this as a developer message.
+         */
         role?: 'developer';
     }
     namespace OpenAIDeveloperMessageParam {
@@ -1291,7 +2318,13 @@ export declare namespace CompletionCreateParams {
          * Text content part for OpenAI-compatible chat completion messages.
          */
         interface ListOpenAIChatCompletionContentPartTextParam {
+            /**
+             * The text content of the message.
+             */
             text: string;
+            /**
+             * Must be 'text' to identify this as text content.
+             */
             type?: 'text';
         }
     }
@@ -1299,6 +2332,9 @@ export declare namespace CompletionCreateParams {
      * Text response format for OpenAI-compatible chat completion requests.
      */
     interface OpenAIResponseFormatText {
+        /**
+         * Must be 'text' to indicate plain text response format.
+         */
         type?: 'text';
     }
     /**
@@ -1306,14 +2342,17 @@ export declare namespace CompletionCreateParams {
      */
     interface OpenAIResponseFormatJsonSchema {
         /**
-         * JSON schema specification for OpenAI-compatible structured response format.
+         * The JSON schema specification for the response.
          */
         json_schema: OpenAIResponseFormatJsonSchema.JsonSchema;
+        /**
+         * Must be 'json_schema' to indicate structured JSON response format.
+         */
         type?: 'json_schema';
     }
     namespace OpenAIResponseFormatJsonSchema {
         /**
-         * JSON schema specification for OpenAI-compatible structured response format.
+         * The JSON schema specification for the response.
          */
         interface JsonSchema {
             description?: string | null;
@@ -1328,22 +2367,40 @@ export declare namespace CompletionCreateParams {
      * JSON object response format for OpenAI-compatible chat completion requests.
      */
     interface OpenAIResponseFormatJsonObject {
+        /**
+         * Must be 'json_object' to indicate generic JSON object response format.
+         */
         type?: 'json_object';
     }
     type CompletionCreateParamsNonStreaming = CompletionsAPI.CompletionCreateParamsNonStreaming;
     type CompletionCreateParamsStreaming = CompletionsAPI.CompletionCreateParamsStreaming;
 }
 export interface CompletionCreateParamsNonStreaming extends CompletionCreateParamsBase {
+    /**
+     * Whether to stream the response.
+     */
     stream?: false | null;
     [k: string]: unknown;
 }
 export interface CompletionCreateParamsStreaming extends CompletionCreateParamsBase {
+    /**
+     * Whether to stream the response.
+     */
     stream: true;
     [k: string]: unknown;
 }
 export interface CompletionListParams {
+    /**
+     * The ID of the last chat completion to return.
+     */
     after?: string | null;
+    /**
+     * The maximum number of chat completions to return.
+     */
     limit?: number | null;
+    /**
+     * The model to filter by.
+     */
     model?: string | null;
     /**
      * Sort order for paginated responses.