tessl/npm-openai

The official TypeScript library for the OpenAI API

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Chat Completions

Name: tessl/npm-openai
Author: tessl

The Chat Completions API provides conversational AI capabilities for generating model responses in chat format. It supports text, image, and audio inputs with extensive configuration options including streaming, function calling, vision, and audio generation.

Package Information

Package Name: openai
Version: 6.9.1
Language: TypeScript
Access Path: client.chat.completions

Core Imports

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

Basic Usage

// Simple chat completion
const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "developer", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" },
  ],
});

console.log(completion.choices[0].message.content);

Architecture

The Chat Completions API is organized around several key components:

Main Resource: client.chat.completions - Primary interface for creating and managing chat completions
Sub-resource: client.chat.completions.messages - Access to stored completion messages
Streaming Support: Real-time response streaming with Server-Sent Events
Helper Methods: Convenience functions for parsing, tool execution, and streaming
Type System: Comprehensive TypeScript types for all API signatures

Capabilities

Create Chat Completion

Creates a model response for a chat conversation with support for text, images, audio, and tool calling.

/**
 * Creates a model response for the given chat conversation
 * @param body - Completion creation parameters
 * @param options - Request options (headers, timeout, etc.)
 * @returns Promise resolving to ChatCompletion or Stream<ChatCompletionChunk>
 */
create(
  body: ChatCompletionCreateParamsNonStreaming,
  options?: RequestOptions
): APIPromise<ChatCompletion>;

create(
  body: ChatCompletionCreateParamsStreaming,
  options?: RequestOptions
): APIPromise<Stream<ChatCompletionChunk>>;

Basic Example:

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "What is the capital of France?" },
  ],
});

console.log(completion.choices[0].message.content);
// Output: "The capital of France is Paris."

With Multiple Messages:

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "developer", content: "You are a helpful coding assistant." },
    { role: "user", content: "How do I reverse a string in JavaScript?" },
    {
      role: "assistant",
      content: "You can use the reverse() method on an array...",
    },
    { role: "user", content: "Can you show me an example?" },
  ],
});

Retrieve Stored Completion

Get a stored chat completion by ID. Only completions created with store: true are available.

/**
 * Get a stored chat completion
 * @param completionID - The ID of the completion to retrieve
 * @param options - Request options
 * @returns Promise resolving to ChatCompletion
 */
retrieve(
  completionID: string,
  options?: RequestOptions
): APIPromise<ChatCompletion>;

Example:

const completion = await client.chat.completions.retrieve("chatcmpl_abc123");

console.log(completion.choices[0].message.content);

Update Stored Completion

Modify metadata for a stored chat completion.

/**
 * Modify a stored chat completion
 * @param completionID - The ID of the completion to update
 * @param body - Update parameters (currently only metadata)
 * @param options - Request options
 * @returns Promise resolving to updated ChatCompletion
 */
update(
  completionID: string,
  body: ChatCompletionUpdateParams,
  options?: RequestOptions
): APIPromise<ChatCompletion>;

Example:

const updated = await client.chat.completions.update("chatcmpl_abc123", {
  metadata: {
    user_id: "user_123",
    session_id: "session_456",
  },
});

List Stored Completions

List all stored chat completions with pagination support.

/**
 * List stored Chat Completions
 * @param query - List filtering parameters
 * @param options - Request options
 * @returns PagePromise for iterating through results
 */
list(
  query?: ChatCompletionListParams,
  options?: RequestOptions
): PagePromise<ChatCompletionsPage, ChatCompletion>;

Example:

// Iterate through all stored completions
for await (const completion of client.chat.completions.list()) {
  console.log(completion.id, completion.created);
}

// Filter by model and metadata
for await (const completion of client.chat.completions.list({
  model: "gpt-4o",
  metadata: { user_id: "user_123" },
  order: "desc",
})) {
  console.log(completion.id);
}

Delete Stored Completion

Delete a stored chat completion.

/**
 * Delete a stored chat completion
 * @param completionID - The ID of the completion to delete
 * @param options - Request options
 * @returns Promise resolving to deletion confirmation
 */
delete(
  completionID: string,
  options?: RequestOptions
): APIPromise<ChatCompletionDeleted>;

Example:

const deleted = await client.chat.completions.delete("chatcmpl_abc123");

console.log(deleted.deleted); // true

List Stored Messages

Get messages from a stored completion.

/**
 * Get messages in a stored chat completion
 * @param completionID - The ID of the completion
 * @param query - List parameters (pagination, ordering)
 * @param options - Request options
 * @returns PagePromise for iterating through messages
 */
client.chat.completions.messages.list(
  completionID: string,
  query?: MessageListParams,
  options?: RequestOptions
): PagePromise<ChatCompletionStoreMessagesPage, ChatCompletionStoreMessage>;

Example:

// Iterate through all messages
for await (const message of client.chat.completions.messages.list(
  "chatcmpl_abc123"
)) {
  console.log(message.role, message.content);
}

Parse with Auto-validation

Create a chat completion with automatic response parsing and validation.

/**
 * Create a completion with automatic parsing
 * @param body - Completion parameters with response_format
 * @param options - Request options
 * @returns Promise resolving to parsed completion
 */
parse<Params extends ChatCompletionParseParams, ParsedT>(
  body: Params,
  options?: RequestOptions
): APIPromise<ParsedChatCompletion<ParsedT>>;

Example with Zod:

import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const CalendarEventSchema = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const completion = await client.chat.completions.parse({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content: "Create a team meeting event for next Monday with Alice and Bob",
    },
  ],
  response_format: zodResponseFormat(CalendarEventSchema, "event"),
});

const event = completion.choices[0].message.parsed;
// Fully typed and validated
console.log(event.name, event.date, event.participants);

Run Tools (Automated Function Calling)

Convenience helper that automatically calls JavaScript functions and sends results back to the model.

/**
 * Automated function calling loop
 * @param body - Completion parameters with tools
 * @param options - Runner options
 * @returns ChatCompletionRunner or ChatCompletionStreamingRunner
 */
runTools<Params extends ChatCompletionToolRunnerParams<any>>(
  body: Params,
  options?: RunnerOptions
): ChatCompletionRunner<ParsedT>;

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

Example:

const runner = await client.chat.completions.runTools({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "What's the weather in Boston and San Francisco?" },
  ],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Get the current weather for a location",
        parameters: {
          type: "object",
          properties: {
            location: { type: "string" },
          },
          required: ["location"],
        },
        function: async ({ location }) => {
          // Your implementation
          return { temperature: 72, condition: "sunny" };
        },
      },
    },
  ],
});

const finalContent = await runner.finalContent();
console.log(finalContent);

Stream Chat Completion

Create a streaming chat completion with helper methods for easy consumption.

/**
 * Create a chat completion stream
 * @param body - Streaming completion parameters
 * @param options - Request options
 * @returns ChatCompletionStream with event handlers
 */
stream<Params extends ChatCompletionStreamParams>(
  body: Params,
  options?: RequestOptions
): ChatCompletionStream<ParsedT>;

Example:

const stream = await client.chat.completions.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Write a haiku about coding" }],
});

// Listen to specific events
stream.on("content", (delta, snapshot) => {
  process.stdout.write(delta);
});

// Or iterate chunks
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

// Get final completion
const finalCompletion = await stream.finalChatCompletion();

Message Parameter Types

All message types used in the messages array parameter.

Developer Message

System-level instructions for the model (replaces system role in o1 and newer models).

/**
 * Developer-provided instructions that the model should follow
 */
interface ChatCompletionDeveloperMessageParam {
  /** The role of the message author */
  role: "developer";

  /** The contents of the developer message */
  content: string | Array<ChatCompletionContentPartText>;

  /** Optional name for the participant */
  name?: string;
}

Example:

{
  role: "developer",
  content: "You are an expert software architect. Provide detailed technical explanations."
}

System Message

System-level instructions (for models before o1).

/**
 * System instructions for the model
 */
interface ChatCompletionSystemMessageParam {
  /** The role of the message author */
  role: "system";

  /** The contents of the system message */
  content: string | Array<ChatCompletionContentPartText>;

  /** Optional name for the participant */
  name?: string;
}

Example:

{
  role: "system",
  content: "You are a helpful assistant that speaks like Shakespeare."
}

User Message

Messages from the end user, supporting text, images, audio, and files.

/**
 * Messages sent by an end user
 */
interface ChatCompletionUserMessageParam {
  /** The role of the message author */
  role: "user";

  /** The contents of the user message */
  content: string | Array<ChatCompletionContentPart>;

  /** Optional name for the participant */
  name?: string;
}

Text Example:

{
  role: "user",
  content: "Hello, how are you?"
}

Multi-modal Example:

{
  role: "user",
  content: [
    { type: "text", text: "What's in this image?" },
    {
      type: "image_url",
      image_url: {
        url: "https://example.com/image.jpg",
        detail: "high"
      }
    }
  ]
}

Assistant Message

Messages sent by the model in response to user messages.

/**
 * Messages sent by the model in response to user messages
 */
interface ChatCompletionAssistantMessageParam {
  /** The role of the message author */
  role: "assistant";

  /** The contents of the assistant message */
  content?: string | Array<ChatCompletionContentPartText | ChatCompletionContentPartRefusal> | null;

  /** Optional name for the participant */
  name?: string;

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

  /** The tool calls generated by the model */
  tool_calls?: Array<ChatCompletionMessageToolCall>;

  /** Data about a previous audio response */
  audio?: { id: string } | null;

  /** @deprecated Use tool_calls instead */
  function_call?: { name: string; arguments: string } | null;
}

Example:

{
  role: "assistant",
  content: "I'd be happy to help you with that!"
}

With Tool Calls:

{
  role: "assistant",
  content: null,
  tool_calls: [
    {
      id: "call_abc123",
      type: "function",
      function: {
        name: "get_weather",
        arguments: '{"location": "Boston"}'
      }
    }
  ]
}

Tool Message

Response to a tool call from the assistant.

/**
 * Response to a tool call
 */
interface ChatCompletionToolMessageParam {
  /** The role of the message author */
  role: "tool";

  /** The contents of the tool message */
  content: string | Array<ChatCompletionContentPartText>;

  /** Tool call that this message is responding to */
  tool_call_id: string;
}

Example:

{
  role: "tool",
  tool_call_id: "call_abc123",
  content: '{"temperature": 72, "condition": "sunny"}'
}

Function Message (Deprecated)

Legacy function response message.

/**
 * @deprecated Use tool messages instead
 */
interface ChatCompletionFunctionMessageParam {
  /** The role of the message author */
  role: "function";

  /** The contents of the function message */
  content: string | null;

  /** The name of the function */
  name: string;
}

Content Part Types

Content parts for multi-modal messages.

Text Content

Plain text content.

/**
 * Text content part
 */
interface ChatCompletionContentPartText {
  /** The type of the content part */
  type: "text";

  /** The text content */
  text: string;
}

Example:

{ type: "text", text: "What's in this image?" }

Image Content

Image input via URL or base64 data.

/**
 * Image content part for vision
 */
interface ChatCompletionContentPartImage {
  /** The type of the content part */
  type: "image_url";

  /** Image URL configuration */
  image_url: {
    /** URL or base64 encoded image data */
    url: string;

    /** Detail level: auto, low, or high */
    detail?: "auto" | "low" | "high";
  };
}

URL Example:

{
  type: "image_url",
  image_url: {
    url: "https://example.com/image.jpg",
    detail: "high"
  }
}

Base64 Example:

{
  type: "image_url",
  image_url: {
    url: "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

Audio Content

Audio input in base64 format.

/**
 * Audio input content part
 */
interface ChatCompletionContentPartInputAudio {
  /** The type of the content part */
  type: "input_audio";

  /** Audio data configuration */
  input_audio: {
    /** Base64 encoded audio data */
    data: string;

    /** Audio format: wav or mp3 */
    format: "wav" | "mp3";
  };
}

Example:

{
  type: "input_audio",
  input_audio: {
    data: "UklGRiQAAABXQVZFZm10...",
    format: "wav"
  }
}

Refusal Content

Model refusal content.

/**
 * Refusal content part
 */
interface ChatCompletionContentPartRefusal {
  /** The type of the content part */
  type: "refusal";

  /** The refusal message */
  refusal: string;
}

File Content

File input for text generation using uploaded files or base64 encoded file data.

/**
 * File content part for file inputs
 * Learn about file inputs: https://platform.openai.com/docs/guides/text
 */
interface ChatCompletionContentPartFile {
  /** The type of the content part */
  type: "file";

  /** File data configuration */
  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;
  };
}

Using an uploaded file:

{
  type: "file",
  file: {
    file_id: "file-abc123",
    filename: "document.pdf"
  }
}

Using base64 encoded file data:

{
  type: "file",
  file: {
    file_data: "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC...",
    filename: "document.pdf"
  }
}

Tool Types

Tool definitions for function calling and custom tools.

Function Tool

Standard function calling tool.

/**
 * A function tool that can be used to generate a response
 */
interface ChatCompletionFunctionTool {
  /** The type of the tool */
  type: "function";

  /** Function definition */
  function: FunctionDefinition;
}

/**
 * Function definition
 */
interface FunctionDefinition {
  /** Function name (a-z, A-Z, 0-9, underscores, dashes, max 64 chars) */
  name: string;

  /** Description of what the function does */
  description?: string;

  /** JSON Schema object describing parameters */
  parameters?: FunctionParameters;

  /** Enable strict schema adherence */
  strict?: boolean | null;
}

/** JSON Schema for function parameters */
type FunctionParameters = { [key: string]: unknown };

Example:

const tool: ChatCompletionFunctionTool = {
  type: "function",
  function: {
    name: "get_current_weather",
    description: "Get the current weather in a given location",
    parameters: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "The city and state, e.g. San Francisco, CA",
        },
        unit: {
          type: "string",
          enum: ["celsius", "fahrenheit"],
        },
      },
      required: ["location"],
    },
    strict: true,
  },
};

Custom Tool

Custom tool with configurable input format.

/**
 * A custom tool that processes input using a specified format
 */
interface ChatCompletionCustomTool {
  /** The type of the tool */
  type: "custom";

  /** Custom tool properties */
  custom: {
    /** Tool name */
    name: string;

    /** Optional description */
    description?: string;

    /** Input format configuration */
    format?: {
      type: "text";
    } | {
      type: "grammar";
      grammar: {
        definition: string;
        syntax: "lark" | "regex";
      };
    };
  };
}

Example:

const customTool: ChatCompletionCustomTool = {
  type: "custom",
  custom: {
    name: "data_extractor",
    description: "Extract structured data from text",
    format: {
      type: "text",
    },
  },
};

Tool Choice Options

Control which tools the model can use.

/**
 * Controls which (if any) tool is called by the model
 */
type ChatCompletionToolChoiceOption =
  | "none"  // Model will not call any tool
  | "auto"  // Model can pick between message or tools
  | "required"  // Model must call one or more tools
  | ChatCompletionAllowedToolChoice  // Constrain to allowed tools
  | ChatCompletionNamedToolChoice  // Force specific function
  | ChatCompletionNamedToolChoiceCustom;  // Force specific custom tool

/**
 * Constrain to allowed tools
 */
interface ChatCompletionAllowedToolChoice {
  type: "allowed_tools";
  allowed_tools: {
    mode: "auto" | "required";
    tools: Array<{ [key: string]: unknown }>;
  };
}

/**
 * Force specific function tool
 */
interface ChatCompletionNamedToolChoice {
  type: "function";
  function: {
    name: string;
  };
}

/**
 * Force specific custom tool
 */
interface ChatCompletionNamedToolChoiceCustom {
  type: "custom";
  custom: {
    name: string;
  };
}

Examples:

// Let model decide
tool_choice: "auto"

// Require tool use
tool_choice: "required"

// Force specific function
tool_choice: {
  type: "function",
  function: { name: "get_weather" }
}

// Constrain to allowed tools
tool_choice: {
  type: "allowed_tools",
  allowed_tools: {
    mode: "required",
    tools: [
      { type: "function", function: { name: "get_weather" } },
      { type: "function", function: { name: "get_time" } }
    ]
  }
}

Tool Call Types

Tool calls generated by the model.

/**
 * Union of all tool call types
 */
type ChatCompletionMessageToolCall =
  | ChatCompletionMessageFunctionToolCall
  | ChatCompletionMessageCustomToolCall;

/**
 * Function tool call
 */
interface ChatCompletionMessageFunctionToolCall {
  /** Tool call ID */
  id: string;

  /** Tool type */
  type: "function";

  /** Function that was called */
  function: {
    /** Function name */
    name: string;

    /** Arguments in JSON format */
    arguments: string;
  };
}

/**
 * Custom tool call
 */
interface ChatCompletionMessageCustomToolCall {
  /** Tool call ID */
  id: string;

  /** Tool type */
  type: "custom";

  /** Custom tool that was called */
  custom: {
    /** Tool name */
    name: string;

    /** Input for the tool */
    input: string;
  };
}

Response Types

Chat Completion

Complete response from the model.

/**
 * Represents a chat completion response
 */
interface ChatCompletion {
  /** Unique identifier */
  id: string;

  /** Object type: always "chat.completion" */
  object: "chat.completion";

  /** Unix timestamp of creation */
  created: number;

  /** Model used for completion */
  model: string;

  /** List of completion choices */
  choices: Array<ChatCompletion.Choice>;

  /** Usage statistics */
  usage?: CompletionUsage;

  /** Service tier used */
  service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null;

  /** @deprecated Backend configuration fingerprint */
  system_fingerprint?: string;
}

namespace ChatCompletion {
  interface Choice {
    /** Index of the choice */
    index: number;

    /** Message generated by the model */
    message: ChatCompletionMessage;

    /** Why the model stopped */
    finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | "function_call";

    /** Log probability information */
    logprobs: Logprobs | null;
  }

  interface Logprobs {
    /** Content token log probabilities */
    content: Array<ChatCompletionTokenLogprob> | null;

    /** Refusal token log probabilities */
    refusal: Array<ChatCompletionTokenLogprob> | null;
  }
}

Chat Completion Message

Message returned by the model.

/**
 * A message generated by the model
 */
interface ChatCompletionMessage {
  /** Message role */
  role: "assistant";

  /** Message content */
  content: string | null;

  /** Refusal message */
  refusal: string | null;

  /** Tool calls generated by the model */
  tool_calls?: Array<ChatCompletionMessageToolCall>;

  /** Audio response data */
  audio?: ChatCompletionAudio | null;

  /** Annotations (e.g., web search citations) */
  annotations?: Array<Annotation>;

  /** @deprecated Use tool_calls instead */
  function_call?: { name: string; arguments: string } | null;
}

/**
 * Audio response data
 */
interface ChatCompletionAudio {
  /** Audio response ID */
  id: string;

  /** Base64 encoded audio bytes */
  data: string;

  /** Unix timestamp of expiration */
  expires_at: number;

  /** Transcript of the audio */
  transcript: string;
}

/**
 * URL citation annotation
 */
interface Annotation {
  type: "url_citation";
  url_citation: {
    /** Start character index */
    start_index: number;

    /** End character index */
    end_index: number;

    /** Web resource URL */
    url: string;

    /** Web resource title */
    title: string;
  };
}

Chat Completion Chunk

Streaming chunk from the model.

/**
 * Streamed chunk of a chat completion response
 */
interface ChatCompletionChunk {
  /** Unique identifier (same for all chunks) */
  id: string;

  /** Object type: always "chat.completion.chunk" */
  object: "chat.completion.chunk";

  /** Unix timestamp of creation */
  created: number;

  /** Model used */
  model: string;

  /** List of chunk choices */
  choices: Array<ChatCompletionChunk.Choice>;

  /** Service tier used */
  service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null;

  /** @deprecated Backend configuration fingerprint */
  system_fingerprint?: string;

  /** Usage statistics (only in last chunk with stream_options) */
  usage?: CompletionUsage | null;
}

namespace ChatCompletionChunk {
  interface Choice {
    /** Choice index */
    index: number;

    /** Delta containing incremental changes */
    delta: Delta;

    /** Why the model stopped (only in final chunk) */
    finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | "function_call" | null;

    /** Log probability information */
    logprobs?: Logprobs | null;
  }

  interface Delta {
    /** Role (only in first chunk) */
    role?: "developer" | "system" | "user" | "assistant" | "tool";

    /** Content delta */
    content?: string | null;

    /** Refusal delta */
    refusal?: string | null;

    /** Tool call deltas */
    tool_calls?: Array<ToolCall>;

    /** @deprecated Function call delta */
    function_call?: { name?: string; arguments?: string };
  }

  interface ToolCall {
    /** Index of the tool call */
    index: number;

    /** Tool call ID */
    id?: string;

    /** Tool type */
    type?: "function";

    /** Function details */
    function?: {
      name?: string;
      arguments?: string;
    };
  }

  interface Logprobs {
    /** Content token log probabilities */
    content: Array<ChatCompletionTokenLogprob> | null;

    /** Refusal token log probabilities */
    refusal: Array<ChatCompletionTokenLogprob> | null;
  }
}

Token Log Probability

Log probability information for tokens.

/**
 * Token with log probability information
 */
interface ChatCompletionTokenLogprob {
  /** The token */
  token: string;

  /** UTF-8 bytes representation */
  bytes: Array<number> | null;

  /** Log probability of this token */
  logprob: number;

  /** Most likely alternative tokens */
  top_logprobs: Array<TopLogprob>;
}

interface TopLogprob {
  /** The token */
  token: string;

  /** UTF-8 bytes representation */
  bytes: Array<number> | null;

  /** Log probability */
  logprob: number;
}

Completion Usage

Token usage statistics.

/**
 * Usage statistics for the completion request
 */
interface CompletionUsage {
  /** Number of tokens in the prompt */
  prompt_tokens: number;

  /** Number of tokens in the completion */
  completion_tokens: number;

  /** Total tokens used */
  total_tokens: number;

  /** Detailed token breakdown */
  completion_tokens_details?: {
    /** Tokens used for reasoning */
    reasoning_tokens?: number;

    /** Tokens used for audio */
    audio_tokens?: number;

    /** Accepted prediction tokens */
    accepted_prediction_tokens?: number;

    /** Rejected prediction tokens */
    rejected_prediction_tokens?: number;
  };

  prompt_tokens_details?: {
    /** Cached tokens */
    cached_tokens?: number;

    /** Audio tokens */
    audio_tokens?: number;
  };
}

Stored Completion Types

Types for stored completions.

/**
 * Message in a stored completion
 */
interface ChatCompletionStoreMessage extends ChatCompletionMessage {
  /** Message identifier */
  id: string;

  /** Content parts if provided */
  content_parts?: Array<ChatCompletionContentPartText | ChatCompletionContentPartImage> | null;
}

/**
 * Deletion confirmation
 */
interface ChatCompletionDeleted {
  /** ID of deleted completion */
  id: string;

  /** Whether deletion succeeded */
  deleted: boolean;

  /** Object type */
  object: "chat.completion.deleted";
}

Parameter Types

Chat Completion Create Parameters

Main parameters for creating a chat completion.

/**
 * Parameters for creating a chat completion
 */
interface ChatCompletionCreateParamsBase {
  /** Array of conversation messages */
  messages: Array<ChatCompletionMessageParam>;

  /** Model ID (e.g., "gpt-4o", "gpt-4o-mini") */
  model: (string & {}) | ChatModel;

  /** Enable streaming */
  stream?: boolean | null;

  /** Output modalities (text, audio) */
  modalities?: Array<"text" | "audio"> | null;

  /** Audio output parameters (required for audio modality) */
  audio?: ChatCompletionAudioParam | null;

  /** Maximum completion tokens */
  max_completion_tokens?: number | null;

  /** @deprecated Use max_completion_tokens */
  max_tokens?: number | null;

  /** Sampling temperature (0-2) */
  temperature?: number | null;

  /** Nucleus sampling parameter */
  top_p?: number | null;

  /** How many completions to generate */
  n?: number | null;

  /** Stop sequences */
  stop?: string | null | Array<string>;

  /** Frequency penalty (-2.0 to 2.0) */
  frequency_penalty?: number | null;

  /** Presence penalty (-2.0 to 2.0) */
  presence_penalty?: number | null;

  /** Token bias adjustments */
  logit_bias?: { [key: string]: number } | null;

  /** Return log probabilities */
  logprobs?: boolean | null;

  /** Number of top log probs (0-20) */
  top_logprobs?: number | null;

  /** List of available tools */
  tools?: Array<ChatCompletionTool>;

  /** Tool choice configuration */
  tool_choice?: ChatCompletionToolChoiceOption;

  /** Enable parallel function calling */
  parallel_tool_calls?: boolean;

  /** Response format configuration */
  response_format?:
    | ResponseFormatText
    | ResponseFormatJSONObject
    | ResponseFormatJSONSchema;

  /** Reasoning effort (for reasoning models) */
  reasoning_effort?: ReasoningEffort | null;

  /** Service tier selection */
  service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null;

  /** Store completion for later retrieval */
  store?: boolean | null;

  /** Metadata (16 key-value pairs max) */
  metadata?: Metadata | null;

  /** Streaming options */
  stream_options?: ChatCompletionStreamOptions | null;

  /** Prediction content for faster generation */
  prediction?: ChatCompletionPredictionContent | null;

  /** Verbosity level */
  verbosity?: "low" | "medium" | "high" | null;

  /** Web search configuration */
  web_search_options?: WebSearchOptions;

  /** @deprecated Deterministic sampling seed */
  seed?: number | null;

  /** @deprecated Use safety_identifier */
  user?: string;

  /** Safety/abuse detection identifier */
  safety_identifier?: string;

  /** Prompt cache key */
  prompt_cache_key?: string;

  /** Prompt cache retention */
  prompt_cache_retention?: "in-memory" | "24h" | null;

  /** @deprecated Function definitions (use tools) */
  functions?: Array<FunctionDefinition>;

  /** @deprecated Function call control (use tool_choice) */
  function_call?: "none" | "auto" | { name: string };
}

/**
 * Non-streaming parameters
 */
interface ChatCompletionCreateParamsNonStreaming
  extends ChatCompletionCreateParamsBase {
  stream?: false | null;
}

/**
 * Streaming parameters
 */
interface ChatCompletionCreateParamsStreaming
  extends ChatCompletionCreateParamsBase {
  stream: true;
}

Audio Parameters

Audio output configuration.

/**
 * Parameters for audio output
 */
interface ChatCompletionAudioParam {
  /** Audio format */
  format: "wav" | "aac" | "mp3" | "flac" | "opus" | "pcm16";

  /** Voice selection */
  voice:
    | (string & {})
    | "alloy"
    | "ash"
    | "ballad"
    | "coral"
    | "echo"
    | "sage"
    | "shimmer"
    | "verse"
    | "marin"
    | "cedar";
}

Example:

const completion = await client.chat.completions.create({
  model: "gpt-4o-audio-preview",
  modalities: ["text", "audio"],
  audio: {
    voice: "alloy",
    format: "mp3",
  },
  messages: [
    { role: "user", content: "Tell me a short story" },
  ],
});

// Access audio data
const audioData = completion.choices[0].message.audio?.data;
const transcript = completion.choices[0].message.audio?.transcript;

Stream Options

Configuration for streaming responses.

/**
 * Options for streaming response
 */
interface ChatCompletionStreamOptions {
  /** Include usage statistics in final chunk */
  include_usage?: boolean;

  /** Enable stream obfuscation for security */
  include_obfuscation?: boolean;
}

Example:

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
  stream: true,
  stream_options: {
    include_usage: true,
  },
});

for await (const chunk of stream) {
  // Last chunk will include usage statistics
  if (chunk.usage) {
    console.log("Total tokens:", chunk.usage.total_tokens);
  }
}

Prediction Content

Predicted output for faster generation.

/**
 * Static predicted output content
 */
interface ChatCompletionPredictionContent {
  /** Prediction type */
  type: "content";

  /** Content to match */
  content: string | Array<ChatCompletionContentPartText>;
}

Example:

// When regenerating a file
const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content: "Rewrite this file with better comments",
    },
  ],
  prediction: {
    type: "content",
    content: existingFileContent, // The content being regenerated
  },
});

Web Search Options

Configuration for web search tool.

/**
 * Web search tool configuration
 */
interface WebSearchOptions {
  /** Context window size for search results */
  search_context_size?: "low" | "medium" | "high";

  /** Approximate user location */
  user_location?: {
    type: "approximate";
    approximate: {
      /** City name */
      city?: string;

      /** Two-letter ISO country code */
      country?: string;

      /** Region/state name */
      region?: string;

      /** IANA timezone */
      timezone?: string;
    };
  } | null;
}

Example:

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "What are the best restaurants near me?" },
  ],
  web_search_options: {
    search_context_size: "high",
    user_location: {
      type: "approximate",
      approximate: {
        city: "San Francisco",
        region: "California",
        country: "US",
        timezone: "America/Los_Angeles",
      },
    },
  },
});

Update Parameters

Parameters for updating stored completions.

/**
 * Parameters for updating a stored completion
 */
interface ChatCompletionUpdateParams {
  /** Metadata to update */
  metadata: Metadata | null;
}

List Parameters

Parameters for listing stored completions.

/**
 * Parameters for listing stored completions
 */
interface ChatCompletionListParams extends CursorPageParams {
  /** Filter by model */
  model?: string;

  /** Filter by metadata */
  metadata?: Metadata | null;

  /** Sort order (asc or desc) */
  order?: "asc" | "desc";

  /** Cursor for pagination */
  after?: string;

  /** Page size limit */
  limit?: number;
}

Message List Parameters

Parameters for listing stored messages.

/**
 * Parameters for listing messages in a stored completion
 */
interface MessageListParams extends CursorPageParams {
  /** Sort order (asc or desc) */
  order?: "asc" | "desc";

  /** Cursor for pagination */
  after?: string;

  /** Page size limit */
  limit?: number;
}

Advanced Features

Streaming with Event Handlers

Fine-grained control over streaming events.

/**
 * Stream events
 */
interface ChatCompletionStreamEvents {
  /** Content delta and snapshot */
  content: (delta: string, snapshot: string) => void;

  /** Raw chunk events */
  chunk: (chunk: ChatCompletionChunk, snapshot: ChatCompletionSnapshot) => void;

  /** Content delta event */
  "content.delta": (props: ContentDeltaEvent) => void;

  /** Content completed */
  "content.done": (props: ContentDoneEvent) => void;

  /** Refusal delta */
  "refusal.delta": (props: RefusalDeltaEvent) => void;

  /** Refusal completed */
  "refusal.done": (props: RefusalDoneEvent) => void;

  /** Tool call arguments delta */
  "tool_calls.function.arguments.delta": (props: FunctionToolCallArgumentsDeltaEvent) => void;

  /** Tool call arguments completed */
  "tool_calls.function.arguments.done": (props: FunctionToolCallArgumentsDoneEvent) => void;

  /** Log probs content delta */
  "logprobs.content.delta": (props: LogProbsContentDeltaEvent) => void;

  /** Log probs content completed */
  "logprobs.content.done": (props: LogProbsContentDoneEvent) => void;

  /** Log probs refusal delta */
  "logprobs.refusal.delta": (props: LogProbsRefusalDeltaEvent) => void;

  /** Log probs refusal completed */
  "logprobs.refusal.done": (props: LogProbsRefusalDoneEvent) => void;
}

Example:

const stream = await client.chat.completions.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Write a poem" }],
});

// Listen to specific events
stream.on("content.delta", ({ delta, snapshot }) => {
  console.log("Delta:", delta);
  console.log("Full content so far:", snapshot);
});

stream.on("tool_calls.function.arguments.delta", ({ name, arguments_delta }) => {
  console.log(`Tool ${name} args:`, arguments_delta);
});

// Wait for completion
const finalCompletion = await stream.finalChatCompletion();

Vision (Image Inputs)

Process images with vision-capable models.

Example:

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "What's in this image? Please describe in detail.",
        },
        {
          type: "image_url",
          image_url: {
            url: "https://example.com/image.jpg",
            detail: "high", // or "low" for faster processing
          },
        },
      ],
    },
  ],
});

console.log(completion.choices[0].message.content);

Multiple Images:

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Compare these two images:" },
        { type: "image_url", image_url: { url: imageUrl1 } },
        { type: "image_url", image_url: { url: imageUrl2 } },
      ],
    },
  ],
});

Function Calling

Let the model call functions to get information.

Example:

const tools = [
  {
    type: "function" as const,
    function: {
      name: "get_current_weather",
      description: "Get the current weather in a given location",
      parameters: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "The city and state, e.g. San Francisco, CA",
          },
          unit: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
          },
        },
        required: ["location"],
      },
    },
  },
  {
    type: "function" as const,
    function: {
      name: "get_n_day_weather_forecast",
      description: "Get an N-day weather forecast",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string" },
          format: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
          },
          num_days: {
            type: "integer",
            description: "Number of days to forecast",
          },
        },
        required: ["location", "num_days"],
      },
    },
  },
];

const messages: ChatCompletionMessageParam[] = [
  {
    role: "user",
    content: "What's the weather like in Boston today and the 5 day forecast?",
  },
];

// First API call
const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: messages,
  tools: tools,
  tool_choice: "auto",
});

const responseMessage = response.choices[0].message;
messages.push(responseMessage);

// Check if the model wants to call a function
if (responseMessage.tool_calls) {
  // Call each function
  for (const toolCall of responseMessage.tool_calls) {
    const functionName = toolCall.function.name;
    const functionArgs = JSON.parse(toolCall.function.arguments);

    let functionResponse;
    if (functionName === "get_current_weather") {
      functionResponse = getCurrentWeather(functionArgs.location, functionArgs.unit);
    } else if (functionName === "get_n_day_weather_forecast") {
      functionResponse = getForecast(
        functionArgs.location,
        functionArgs.format,
        functionArgs.num_days
      );
    }

    // Add function response to messages
    messages.push({
      role: "tool",
      tool_call_id: toolCall.id,
      content: JSON.stringify(functionResponse),
    });
  }

  // Get final response from model
  const finalResponse = await client.chat.completions.create({
    model: "gpt-4o",
    messages: messages,
  });

  console.log(finalResponse.choices[0].message.content);
}

function getCurrentWeather(location: string, unit?: string) {
  return {
    location,
    temperature: "72",
    unit: unit || "fahrenheit",
    forecast: ["sunny", "windy"],
  };
}

function getForecast(location: string, format: string, numDays: number) {
  return {
    location,
    format,
    num_days: numDays,
    forecast: ["sunny", "cloudy", "rainy", "sunny", "partly cloudy"],
  };
}

Structured Outputs with JSON Schema

Generate strictly validated JSON responses.

Example:

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content: "Extract the event details: Team meeting on Monday at 2pm with Alice and Bob",
    },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "calendar_event",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          date: { type: "string" },
          time: { type: "string" },
          participants: {
            type: "array",
            items: { type: "string" },
          },
        },
        required: ["name", "date", "participants"],
        additionalProperties: false,
      },
    },
  },
});

const event = JSON.parse(completion.choices[0].message.content);
console.log(event);
// { name: "Team meeting", date: "Monday", time: "2pm", participants: ["Alice", "Bob"] }

Reasoning Models

Use reasoning models with configurable effort levels.

Example:

// Using o3 model with reasoning
const completion = await client.chat.completions.create({
  model: "o3",
  messages: [
    {
      role: "user",
      content: "Solve this logic puzzle: If all roses are flowers and some flowers fade quickly, can we conclude that some roses fade quickly?",
    },
  ],
  reasoning_effort: "high", // or "low", "medium"
});

console.log(completion.choices[0].message.content);
console.log("Reasoning tokens:", completion.usage?.completion_tokens_details?.reasoning_tokens);

Audio Generation

Generate audio responses.

Example:

const completion = await client.chat.completions.create({
  model: "gpt-4o-audio-preview",
  modalities: ["text", "audio"],
  audio: {
    voice: "alloy",
    format: "mp3",
  },
  messages: [
    {
      role: "user",
      content: "Tell me a bedtime story about a friendly dragon",
    },
  ],
});

const audioData = completion.choices[0].message.audio?.data;
const transcript = completion.choices[0].message.audio?.transcript;

// Save audio file
if (audioData) {
  const buffer = Buffer.from(audioData, "base64");
  fs.writeFileSync("story.mp3", buffer);
}

Prompt Caching

Optimize costs by caching prompt prefixes.

Example:

// First request establishes cache
const completion1 = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "developer",
      content: veryLongSystemPrompt, // This will be cached
    },
    { role: "user", content: "First question" },
  ],
  prompt_cache_key: "my-app-v1",
  prompt_cache_retention: "24h", // Keep cached for 24 hours
});

// Subsequent requests reuse cache
const completion2 = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "developer",
      content: veryLongSystemPrompt, // Cache hit!
    },
    { role: "user", content: "Second question" },
  ],
  prompt_cache_key: "my-app-v1",
});

Helper Types

Chat Model Union Type

All available chat models.

/**
 * Chat-capable models
 */
type ChatModel =
  // GPT-5.1 series
  | "gpt-5.1"
  | "gpt-5.1-2025-11-13"
  | "gpt-5.1-codex"
  | "gpt-5.1-mini"
  | "gpt-5.1-chat-latest"
  // GPT-5 series
  | "gpt-5"
  | "gpt-5-mini"
  | "gpt-5-nano"
  | "gpt-5-2025-08-07"
  | "gpt-5-mini-2025-08-07"
  | "gpt-5-nano-2025-08-07"
  | "gpt-5-chat-latest"
  // GPT-4.1 series
  | "gpt-4.1"
  | "gpt-4.1-mini"
  | "gpt-4.1-nano"
  | "gpt-4.1-2025-04-14"
  | "gpt-4.1-mini-2025-04-14"
  | "gpt-4.1-nano-2025-04-14"
  // O-series models
  | "o4-mini"
  | "o4-mini-2025-04-16"
  | "o3"
  | "o3-2025-04-16"
  | "o3-mini"
  | "o3-mini-2025-01-31"
  | "o1"
  | "o1-2024-12-17"
  | "o1-preview"
  | "o1-preview-2024-09-12"
  | "o1-mini"
  | "o1-mini-2024-09-12"
  // GPT-4o series
  | "gpt-4o"
  | "gpt-4o-2024-11-20"
  | "gpt-4o-2024-08-06"
  | "gpt-4o-2024-05-13"
  | "gpt-4o-audio-preview"
  | "gpt-4o-audio-preview-2024-10-01"
  | "gpt-4o-audio-preview-2024-12-17"
  | "gpt-4o-audio-preview-2025-06-03"
  | "gpt-4o-mini-audio-preview"
  | "gpt-4o-mini-audio-preview-2024-12-17"
  | "gpt-4o-search-preview"
  | "gpt-4o-mini-search-preview"
  | "gpt-4o-search-preview-2025-03-11"
  | "gpt-4o-mini-search-preview-2025-03-11"
  | "chatgpt-4o-latest"
  | "codex-mini-latest"
  | "gpt-4o-mini"
  | "gpt-4o-mini-2024-07-18"
  // GPT-4 series
  | "gpt-4-turbo"
  | "gpt-4-turbo-2024-04-09"
  | "gpt-4-0125-preview"
  | "gpt-4-turbo-preview"
  | "gpt-4-1106-preview"
  | "gpt-4-vision-preview"
  | "gpt-4"
  | "gpt-4-0314"
  | "gpt-4-0613"
  | "gpt-4-32k"
  | "gpt-4-32k-0314"
  | "gpt-4-32k-0613"
  // GPT-3.5 series
  | "gpt-3.5-turbo"
  | "gpt-3.5-turbo-16k"
  | "gpt-3.5-turbo-0301"
  | "gpt-3.5-turbo-0613"
  | "gpt-3.5-turbo-1106"
  | "gpt-3.5-turbo-0125"
  | "gpt-3.5-turbo-16k-0613"
  // Custom/fine-tuned models
  | (string & {})

Reasoning Effort

Effort levels for reasoning models.

/**
 * Reasoning effort configuration
 */
type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | null;

Chat Completion Role

All valid message roles.

/**
 * Role of message author
 */
type ChatCompletionRole = "developer" | "system" | "user" | "assistant" | "tool" | "function";

Modality

Output modalities.

/**
 * Output modality types
 */
type ChatCompletionModality = "text" | "audio";

Metadata

Key-value metadata storage.

/**
 * Metadata for storing additional information
 * Maximum 16 key-value pairs
 * Keys: max 64 characters
 * Values: max 512 characters
 */
type Metadata = { [key: string]: string };

Response Format Types

Response format options.

/**
 * Text response format
 */
interface ResponseFormatText {
  type: "text";
}

/**
 * JSON object response format
 */
interface ResponseFormatJSONObject {
  type: "json_object";
}

/**
 * JSON Schema response format (Structured Outputs)
 */
interface ResponseFormatJSONSchema {
  type: "json_schema";
  json_schema: {
    name: string;
    description?: string;
    schema?: { [key: string]: unknown };
    strict?: boolean | null;
  };
}

/**
 * Grammar-constrained text
 */
interface ResponseFormatTextGrammar {
  type: "grammar";
  grammar: string;
}

/**
 * Python code generation
 */
interface ResponseFormatTextPython {
  type: "python";
}

Pagination Types