Chat Completions reference

Purpose and Scope

This page is the SDK reference for the client.chat.completions resource in openai-node. It is for developers maintaining message-based generation code, migrating older chat workflows forward without changing their conversation shape, or checking exact TypeScript names for chat-specific request and response objects. In this SDK, Chat Completions are organized under the chat namespace and use a list of role-tagged messages rather than a single freeform prompt. That message list is the main contract to understand before you tune generation options, enable tools, stream chunks, or inspect stored completion messages.

Sources: api.md, src/resources/chat/completions/index.ts, tests/api-resources/chat/completions/completions.test.ts

The Chat Completions API remains distinct from the newer Responses API. The Responses API is the primary model interaction surface elsewhere in the SDK, but Chat Completions is still represented as a full generated resource with its own create, retrieve, update, list, delete, and message-list operations. The generated export barrel in src/resources/chat/completions/index.ts makes the chat-specific resource, parameter types, response types, chunk types, message parameter variants, tool-choice types, and nested Messages resource available through the public package type namespace. Use this page when you need method-level behavior or type names rather than broad product guidance.

Sources: src/resources/chat/completions/index.ts

Relevant Source Files

• api.md - Generated API reference file for the package; use it as the broad method and type index when checking public SDK signatures.
• src/resources/chat/completions/index.ts - Export barrel for the Chat Completions resource, generated types, create parameter variants, page types, and nested messages resource.
• tests/api-resources/chat/completions/completions.test.ts - Generated resource tests showing supported client.chat.completions methods, required create fields, optional create fields, response helpers, and request-options behavior.
• tests/api-resources/chat/completions/messages.test.ts - Generated resource tests showing the nested client.chat.completions.messages.list call and its pagination parameters.

Resource Model

The public entry point is client.chat.completions, backed by the generated Completions class and exported from the chat completions module. The same module re-exports many domain types, including ChatCompletion, ChatCompletionChunk, ChatCompletionMessage, ChatCompletionMessageParam, and role-specific message parameter types such as developer, system, user, assistant, tool, and function messages. This organization matters in TypeScript because most applications pass a structural object to create, but larger codebases often want explicit parameter types for reusable helpers, test fixtures, and streaming/non-streaming overloads.

Sources: src/resources/chat/completions/index.ts

The nested messages resource hangs below a stored chat completion rather than below the general chat namespace. Its public call shape is client.chat.completions.messages.list('completion_id', params?, options?), where the completion identifier selects which stored completion to inspect. The generated tests exercise this call both without parameters and with pagination fields. That makes message listing a retrieval workflow, not a generation workflow: you first create or otherwise identify a completion, then list its stored messages with cursor and ordering options when the API supports stored-message inspection.

Sources: tests/api-resources/chat/completions/messages.test.ts

Method Reference

The minimum create request shown by the generated tests contains two fields: model and messages. The tested message uses role developer and string content, which reflects the SDK’s support for newer instruction-style chat roles in addition to user, assistant, system, tool, and function variants exported from the module. A practical non-streaming call therefore starts by choosing a model and providing an ordered message array. The returned object is not a raw Response; it is parsed SDK data, while .asResponse() and .withResponse() remain available when callers need HTTP-level details.

Sources: tests/api-resources/chat/completions/completions.test.ts, src/resources/chat/completions/index.ts

const completion = await client.chat.completions.create({
  model: 'gpt-5.4',
  messages: [{ role: 'developer', content: 'Talk like a concise reviewer.' }],
});
 
console.log(completion.choices[0]?.message?.content);

The generated tests also show the SDK’s response-wrapper helpers. A create, retrieve, or update call can be awaited directly to receive parsed data. The same promise-like object can be inspected with .asResponse() to access the underlying Web Response, or .withResponse() to receive both parsed data and the raw response together. These helpers are useful when application code needs headers, status information, or debugging context without giving up typed resource results. They also establish a consistent pattern across the methods exercised for Chat Completions.

Sources: tests/api-resources/chat/completions/completions.test.ts

Create Parameters and Generated Types

ChatCompletionCreateParams is the umbrella parameter type exported by the module, with ChatCompletionCreateParamsNonStreaming and ChatCompletionCreateParamsStreaming available when code needs to preserve the relationship between the stream flag and the return type. The exported response-side types mirror that split: ChatCompletion represents a completed non-streaming response, while ChatCompletionChunk represents incremental streaming events. Tool-related exports include allowed and named tool-choice variants, function and custom tool definitions, message tool-call types, and ChatCompletionStreamOptions for stream behavior.

Sources: src/resources/chat/completions/index.ts

The optional create fields exercised in tests cover several independent concerns. Generation controls include penalties, token limits, temperature, top_p, seed, stop, reasoning_effort, verbosity, and service-tier selection. Output controls include modalities, audio, response_format, logprobs, top_logprobs, and prediction content. Tooling controls include legacy functions and function_call as well as modern tools, tool_choice, and parallel_tool_calls. Operational fields include metadata, store, prompt-cache settings, moderation settings, safety identifier, user identifier, and web-search options with approximate user location.

Sources: tests/api-resources/chat/completions/completions.test.ts

const response = await client.chat.completions.create({
  model: 'gpt-5.4',
  messages: [{ role: 'developer', content: 'Summarize the release note.' }],
  temperature: 1,
  tool_choice: 'none',
  stream: false,
  metadata: { ticket: 'docs-review' },
});

Because these types are generated from the OpenAPI specification, the reference surface is intentionally broad and strongly named rather than hand-curated around one tutorial path. Prefer the narrowest type that communicates your function’s behavior. A helper that always streams should accept or return ChatCompletionCreateParamsStreaming; a helper that never streams should use ChatCompletionCreateParamsNonStreaming; and a helper that branches dynamically can use the general ChatCompletionCreateParams. This keeps downstream code honest about whether it should consume a final choices array or iterate chunks as they arrive.

Sources: src/resources/chat/completions/index.ts, api.md

Streaming Behavior

Streaming is selected at request time by setting stream: true in the create parameters. The module exports ChatCompletionChunk, ChatCompletionStreamOptions, and streaming create parameter types so TypeScript callers can model incremental output explicitly. In a streaming call, the application should iterate the returned stream and read each chunk’s delta content rather than expecting a final assistant message immediately. Non-streaming calls, by contrast, resolve to a ChatCompletion whose assistant message content is available under the selected choice.

Sources: src/resources/chat/completions/index.ts, tests/api-resources/chat/completions/completions.test.ts

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

When adding streaming to existing code, treat it as a return-type change rather than a cosmetic option. A function that used to return ChatCompletion may now return an async iterable stream of chunks, so the caller must accumulate text, update UI state, or dispatch events as chunks arrive. The tests demonstrate that the SDK already distinguishes raw response access from parsed data access; streaming adds a second distinction between final parsed data and incremental parsed chunks. Keeping those distinctions explicit avoids confusing HTTP response streaming with model-output streaming.

Sources: tests/api-resources/chat/completions/completions.test.ts, src/resources/chat/completions/index.ts

Stored Completion Messages and Pagination

Stored completion message listing is exposed through client.chat.completions.messages.list. The generated messages test calls it with only a completion_id, then calls it again with after, limit, and order. Those parameters define the page window and traversal direction for message inspection. Request options remain a separate final argument, as shown by the test that passes a custom path option and expects an OpenAI.NotFoundError. This separation is important: pagination parameters describe API data, while request options affect transport behavior.

Sources: tests/api-resources/chat/completions/messages.test.ts

const page = await client.chat.completions.messages.list('completion_id', {
  after: 'cursor-id',
  limit: 20,
  order: 'asc',
});

Use message listing when your application stores chat completions and later needs to inspect the exact messages associated with one completion. Do not confuse it with the messages array passed to create: create-time messages are request input, while the nested messages list is a read operation scoped to an existing completion id. For application-level conversation state, keep your own ordered history unless you intentionally rely on stored completion resources and their message-list endpoint.

Sources: tests/api-resources/chat/completions/messages.test.ts

Testing Signals and Next Steps

The generated tests are useful compatibility signals because they exercise required and optional parameters, method availability, response-helper behavior, and request-options plumbing against a mock API base URL. They do not replace the generated API reference, but they show the SDK contract that contributors expect to keep stable: create accepts the broad generated parameter object, resource methods return parsed data with raw-response helpers, and nested message listing accepts both pagination parameters and request options. If a change breaks these patterns, it is likely to affect real user code.

Sources: tests/api-resources/chat/completions/completions.test.ts, tests/api-resources/chat/completions/messages.test.ts

For implementation work, start with api.md when you need the full generated signature list, then use src/resources/chat/completions/index.ts to confirm exported type names. For behavior-sensitive changes, update or add tests beside tests/api-resources/chat/completions/completions.test.ts and tests/api-resources/chat/completions/messages.test.ts. For conceptual migration decisions, compare this page with the Responses API concepts page: Chat Completions is message-based and familiar, while Responses is the newer central surface for model input, tools, and output handling.