Chat Completions

Purpose and Scope

Chat Completions is the SDK surface for message-based text generation workflows that predate the newer Responses API but remain important for existing applications, examples, and migration paths. Instead of sending one freeform prompt, callers provide an ordered list of messages, each with a role and content. That shape lets an application separate developer guidance, user input, assistant replies, tool messages, and function-related context. In this SDK, the surface is exposed under the chat namespace and is generated from the OpenAPI specification, so the public TypeScript types track the REST API contract. Sources: src/resources/chat/completions/index.ts, src/resources/chat/completions/completions.ts

Use this page when maintaining applications that already call Chat Completions, when adding streaming to a chat workflow, or when comparing Chat Completions with the legacy prompt-based Completions endpoint. The important distinction is the input contract: Chat Completions works with conversational message arrays, while the older Completions endpoint works with a prompt string and returns text choices. The repository keeps both resources available as separate generated modules, which makes backwards-compatible adoption explicit rather than hiding the legacy endpoint behind the chat API. Sources: src/resources/chat/completions.ts, src/resources/completions.ts

Relevant Source Files

• src/resources/chat/completions/index.ts - Barrel export for the Chat Completions resource, generated response types, request parameter types, tool-related message types, streaming options, pages, and the nested messages resource.
• src/resources/chat/completions.ts - Top-level chat completions module that re-exports the generated index for package consumers and internal namespace wiring.
• src/resources/chat/completions/completions.ts - Generated implementation and type home for chat completion creation, update, listing, deletion, and related chat completion shapes.
• src/resources/chat/completions/messages.ts - Nested resource for listing messages from stored chat completions, including cursor pagination and sort order parameters.
• src/resources/completions.ts - Legacy prompt-based Completions resource, useful for understanding the backwards-compatible endpoint that differs from Chat Completions.

Core Model and Types

The Chat Completions type surface is intentionally broad because the API covers more than a single assistant reply. The index export includes result objects, chunks for streaming, message parameter variants, roles, content parts, audio-related content, tool choices, function tool calls, custom tool calls, token log probabilities, store message pages, and separate parameter types for streaming and non-streaming creation. For application code, that means request construction can be strongly typed before the request leaves the process, and response handling can distinguish a full completion from incremental stream chunks. Sources: src/resources/chat/completions/index.ts

A typical request has a model and a messages array. The first messages often establish behavior, and later messages carry user input or prior assistant output. The generated exports distinguish system, developer, user, assistant, tool, and function message parameter shapes, so code can model conversation history without collapsing every entry into an unstructured string. Tool-enabled workflows also remain part of the same surface: exported tool choice and tool call types let a caller describe whether the model may call tools, name a specific tool, or report tool call outputs back into the message sequence. Sources: src/resources/chat/completions/index.ts, src/resources/chat/completions/completions.ts

import OpenAI from 'openai';
 
const client = new OpenAI();
 
const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [
    { role: 'developer', content: 'Answer in a concise support style.' },
    { role: 'user', content: 'How do I reset my API key?' },
  ],
});
 
console.log(completion.choices[0]?.message?.content);

Streaming and Stored Message Flow

Streaming uses the same chat completion creation entry point but changes the request and response contract. The exported parameter types separate streaming from non-streaming creation, and the index also exports the chunk type used for incremental output. In application code, this matters because a non-streaming result is handled after the full response is available, while a streaming result is consumed as events or chunks arrive. The common pattern is to render each delta as soon as it appears, then preserve any final message or tool-call state needed for the next turn. Sources: src/resources/chat/completions/index.ts, src/resources/chat/completions/completions.ts

const stream = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Say hello in one sentence.' }],
  stream: true,
});
 
for await (const part of stream) {
  process.stdout.write(part.choices[0]?.delta?.content ?? '');
}

Stored chat completions add a second workflow after creation. The nested messages resource can list messages for a stored completion, but only completions created with storage enabled are returned by that endpoint. The method accepts a completion identifier, optional cursor pagination parameters, and an order option whose values are ascending or descending. Internally, the resource calls the chat completion messages path and returns a cursor page promise, so callers can use asynchronous iteration and let the SDK fetch additional pages as needed. Sources: src/resources/chat/completions/messages.ts

Backwards Compatibility with Prompt Completions

The legacy Completions resource remains separate and is useful when maintaining older prompt-oriented code. Its create method posts to the completions endpoint, accepts non-streaming or streaming parameter variants, and returns either a completion object or a stream of completion objects depending on the stream flag. The response shape is text-oriented: choices contain generated text, finish reasons, optional log probabilities, and usage information. This differs from Chat Completions, where choices contain chat messages or streaming deltas rather than plain text. Sources: src/resources/completions.ts

That separation is a practical migration aid. A prompt-based call can often be translated by moving the prompt into a user message and moving stable behavioral instructions into a developer or system message. However, the output access pattern changes from reading text on a choice to reading message content on a choice. Streaming also changes shape: legacy streamed and non-streamed completion objects share the same response shape, while chat streaming is represented with chat completion chunks. Code that abstracts both endpoints should normalize these differences deliberately rather than assuming the same choice structure. Sources: src/resources/chat/completions/index.ts, src/resources/completions.ts

Compact Reference

Implementation Details and Next Steps

Because this SDK is generated, the most stable way to reason about Chat Completions is through the exported resource names and types rather than hand-written helper assumptions. The barrel module gathers the public contract, the top-level chat module re-exports it for consumers, the completions implementation owns the generated chat methods, and the messages module handles stored-message pagination. When adding a feature, start by choosing the correct endpoint family, then decide whether the request is streaming, whether messages should be stored, and whether tool-related message types are part of the conversation. Sources: src/resources/chat/completions/index.ts, src/resources/chat/completions.ts, src/resources/chat/completions/messages.ts

For new product work, also compare this page with the Responses API concepts page, because Responses is the primary model interaction surface in the current SDK documentation. Keep Chat Completions for compatibility, for applications already built around message arrays, or for integrations that depend on chat-specific helpers and generated types. If you are migrating legacy prompt completions, read the reference pages for both Chat Completions and Completions before changing response parsing, streaming loops, or stored history behavior. Sources: src/resources/chat/completions/completions.ts, src/resources/completions.ts