Client and resource model

Purpose and Scope

The OpenAI TypeScript and JavaScript SDK exposes the REST API as an object-oriented client whose properties mirror API resource families. Instead of constructing URLs by hand, application code creates an OpenAI client and calls resource methods such as responses creation or chat completions creation. The README frames this package as convenient access to the OpenAI REST API, generated from the OpenAPI specification with Stainless, and points readers to the generated API reference for the complete surface. Sources: README.md, api.md

This page explains how that generated model is organized so developers can move from example code to less common endpoints without guessing naming conventions. A resource is a grouped API area, such as responses, files, images, batches, evals, or vector stores. A nested namespace is a resource contained below another resource family, such as chat completions. A method is the callable operation under that namespace, and the returned value is typed from generated response interfaces exported by the package. Sources: README.md, src/resources/index.ts

Relevant Source Files

• README.md — Introduces the SDK, states that it is generated from the OpenAPI specification, links to the full API reference, and demonstrates top-level and nested client calls.
• api.md — Serves as the generated API reference companion for the full SDK surface named by the README.
• src/resources/index.ts — Re-exports generated resource classes and their request, response, page, and event types from individual resource modules.
• src/client.ts — Imports the generated resources, pagination primitives, upload support, APIPromise, request options, errors, authentication, and platform headers used by the OpenAI client implementation.

Core Resource Shape

The most visible client shape is the default import used in README examples. Code imports OpenAI, constructs a client, and calls methods from resource properties. The primary example uses responses creation with a model, instructions, and input, then reads the convenience output text from the returned response. The chat example uses a nested path through chat and completions, then reads the first choice message content. These examples show the naming contract: client properties are nouns, methods are verbs, and response objects expose typed fields matching the API response. Sources: README.md

The resource barrel file makes that contract concrete by exporting many top-level resource classes and their associated types. It exports classes such as Batches, Completions, Containers, Embeddings, Evals, Files, Images, Models, Moderations, Realtime, Responses, Skills, Uploads, VectorStores, and Videos. For many of those resources it also exports generated request and response names, including create parameter types, list parameter types, page types, deleted-object types, streaming event types, and domain-specific model aliases. This is why TypeScript users can rely on importable SDK types instead of duplicating request and response schemas in application code. Sources: src/resources/index.ts

System-to-Code Mapping

SDK concept	Where it appears	Developer-facing meaning
Package client	README.md, src/client.ts	The OpenAI class is constructed once with authentication and options, then reused for resource calls.
Resource namespaces	src/resources/index.ts	Generated classes represent API families such as Responses, Files, Models, Images, and VectorStores.
Nested namespaces	README.md, src/client.ts	Calls can traverse deeper groups, as in chat completions, when the API family has subresources.
Typed params and responses	src/resources/index.ts	Types such as create params, list params, pages, events, and response objects are exported alongside resource classes.
Generated API reference	README.md, api.md	The reference file is the catalog for the full method and type surface beyond quickstart examples.

Execution Flow

A normal request starts with client construction. The README example passes an API key from the environment, while noting that this value is the default and can be omitted when the standard environment variable is present. After construction, the application chooses a resource namespace based on the platform task. For model interaction, the README recommends the Responses API as the primary surface. The caller provides a model and input payload, awaits the method result, and then reads typed response properties rather than parsing raw JSON manually. Sources: README.md

The same pattern scales across older and specialized surfaces. The README identifies Chat Completions as the previous standard for text generation and shows the nested method path through chat completions. The caller supplies a message array, including developer and user roles, and receives a completion object with choices and messages. This nested example is important because it shows that resource grouping is not limited to one level; the generated client preserves API hierarchy while still giving callers regular TypeScript methods and objects. Sources: README.md, src/client.ts

The client implementation imports internal request option handling, query serialization, platform headers, upload helpers, pagination classes, OpenAI-specific errors, authentication support, and APIPromise. That import set shows the generated resource model is not just a directory of endpoint functions. Resource methods plug into a shared transport layer that can finalize request options, attach environment and platform metadata, process pagination responses, handle uploads, and surface errors consistently. As a result, different resources should feel uniform even when their request bodies or return types differ. Sources: src/client.ts

API Components

Use the resource barrel as the fastest way to understand what the SDK exposes at the public type level. It exports shared modules and chat resources first, then a long list of top-level API families. Each exported family generally pairs a class name with generated types named after API objects and operations. For example, the batches export includes batch object, error, usage, create params, list params, and page types. The images export includes response objects, model aliases, create variation params, edit params, generate params, and streaming event types. Sources: src/resources/index.ts

The client source imports those same classes and types into the OpenAI client implementation, which is the connection point between generated resource modules and the package entrypoint used by applications. It imports direct resources such as Completions, Embeddings, Files, Images, Models, Moderations, and Videos, and it also imports broader namespace classes such as Admin, Audio, Beta, Chat, Conversations, FineTuning, Realtime, Responses, Uploads, and VectorStores. This mixture explains why some calls appear as direct top-level methods while others live under a namespace with additional subresources. Sources: src/client.ts, src/resources/index.ts

Working With Typed Responses

The README examples demonstrate two common response-access styles. Responses calls can expose an aggregate text convenience property, which is useful for straightforward text generation and multimodal prompts. Chat completions return a choices collection, so callers index into the first choice and then read the message content. These are not arbitrary helper shapes invented in examples; they reflect the generated typed response objects exported from the resource modules and documented in the API reference. When using TypeScript, prefer those exported parameter and response types for reusable wrappers, tests, and service boundaries. Sources: README.md, src/resources/index.ts

For multi-turn model work, the resource model also affects how state is replayed. The README warns that filtering response output down to messages can remove reasoning or tool-call items required by a later request. It recommends preserving replayable output items with the provided helper or using a previous response identifier for simple continuation. That guidance is part of the same design philosophy: client resources return structured objects that may include more than visible text, and applications should pass the correct typed items forward instead of assuming every workflow is plain message history. Sources: README.md

Practical Next Steps

Start with the README examples to learn the call shape, then use the generated API reference when you need a method, parameter object, or response type that is not shown in the quickstart. In application code, keep one configured OpenAI client near your service boundary, choose the resource namespace that matches the API task, and let the generated types describe request and response payloads. If you are building model interactions first, continue with the Responses API page; if you are maintaining older message-based flows, use the Chat Completions reference next. Sources: README.md, api.md, src/resources/index.ts