Examples overview
Purpose and Scope
The examples area is the fastest way to move from the SDK README to runnable TypeScript and JavaScript usage patterns. The README introduces the package as the official TypeScript and JavaScript library for the OpenAI REST API, then points readers to the generated API reference and the repository examples for code samples. In practice, the examples directory should be treated as a companion workspace: it depends on the local SDK package, carries extra libraries needed by specific demos, and shows how typed client calls look when placed in executable scripts. Sources: README.md, examples/package.json
This page helps you decide which example pattern to start from, what dependencies are already available inside the examples package, and how the example code maps back to the SDK’s public API. It is intentionally not a complete API reference. Instead, it explains the examples workspace as a learning and validation surface: use the README for the main installation and client-construction path, use the examples package for runnable demonstrations, and use typed example files when you need concrete parameter shapes or streaming iteration patterns. Sources: README.md, examples/types.ts
Relevant Source Files
- examples/package.json — Defines the examples workspace package, its private package metadata, and the dependencies used by runnable examples, including the local SDK package and supporting libraries.
- examples/types.ts — Provides a representative executable TypeScript example that imports the OpenAI client, constructs typed Chat Completions parameters, and demonstrates both non-streaming and streaming calls.
- README.md — Establishes the SDK purpose, installation options, primary usage examples, and the README-to-examples navigation path for developers learning the package.
Example Workspace Dependencies
The examples package is named openai-examples and is marked private, which signals that it exists for repository-local demonstration rather than publication as a reusable package. Its most important dependency is openai with a file reference to the parent repository, so examples exercise the SDK implementation from the checkout instead of pulling an unrelated registry version. That local linkage is useful when testing a branch, reviewing generated API changes, or confirming that an example still compiles against the current package surface. The package also includes dotenv for environment-driven configuration, which fits the README’s default API-key pattern. Sources: examples/package.json, README.md
Several dependencies reveal the kinds of examples the workspace is prepared to host. The presence of express and Next indicates that examples may cover server-style or web-framework integrations, while @azure/identity supports Azure OpenAI authentication scenarios. zod-to-json-schema is included for examples that turn Zod schemas into JSON Schema, a common pattern for structured outputs and tool definitions. The devDependencies are mostly type packages for Express, body parsing, and Web APIs, which makes the examples friendlier in TypeScript projects that touch browser-like request and response types as well as Node server handlers. Sources: examples/package.json
Core SDK Patterns Shown by the Examples
The README establishes the broad learning path: install the package, import the default OpenAI client, configure the API key from the environment, and call a model-facing resource. Its primary sample uses the Responses API, passing a model, instructions, and input, then reading output text from the response object. That example is the recommended starting point for new text generation workflows because the README describes Responses as the primary API for interacting with OpenAI models. Examples should be read in that same order: first learn the client, then choose the specific resource shape your application needs. Sources: README.md
The typed example file demonstrates a complementary Chat Completions path. It imports OpenAI from the package, constructs a client with default environment-based authentication, and explicitly annotates request parameters as OpenAI Chat ChatCompletionCreateParams. The non-streaming request passes a model and a single user message, then prints the first returned message’s content. This is useful when you are migrating existing chat workflows or want to see how generated TypeScript namespaces expose request types. It also shows that examples can be both runnable scripts and compact type references. Sources: examples/types.ts
Streaming is shown as a variation on the same Chat Completions request shape. The streaming parameter object adds the stream flag, sends the request through the same create method, and then uses asynchronous iteration over chunks. Each chunk contributes incremental delta content, which the example writes to standard output before ending with a newline. That small flow captures the main mental model for SDK streaming examples: the method call returns an async iterable stream, application code consumes events or chunks in order, and output assembly is handled by the caller when using low-level iteration. Sources: examples/types.ts
How to Choose an Example
Start with the README sample when your task is simply to verify credentials and make a first request. It shows the default import path, the normal client constructor, and the convention of reading the API key from the environment. Move to the examples workspace when you need something more specific than a single README snippet: framework integration, Azure credentials, schema conversion, or a typed script that demonstrates generated request types. Because the examples package depends on the parent SDK via a local file reference, it is also the right place to test behavior while modifying the repository itself. Sources: README.md, examples/package.json
If you already know you need Chat Completions compatibility, the typed example is a concise reference for the older message-based API. The README explicitly describes Chat Completions as the previous standard that remains supported, while the typed example shows its create method, messages array, and response choice access pattern. For new applications, compare that with the README’s Responses API sample before copying code. The practical rule is to use Responses for new model interactions unless you are maintaining or integrating with a chat-completions-shaped workflow that already expects messages and choices. Sources: README.md, examples/types.ts
Task Flow for Running and Adapting Examples
A typical workflow begins by installing the repository dependencies, setting the OPENAI_API_KEY environment variable, and running the example script you want to inspect. The example file itself documents that the client gets its API key from the environment, so you do not need to hard-code credentials in source. After the script runs, adapt one field at a time: change the prompt or message content first, then the model, then optional behavior such as streaming. This incremental approach makes it easier to distinguish SDK usage errors from model-output differences or application logic changes. Sources: examples/types.ts, README.md
When adapting examples into an application, keep the boundary between SDK code and application code clear. The OpenAI client construction and resource method calls are the portable pieces. The console printing, standard-output streaming, Express handlers, or Next integration code are application scaffolding that should match your runtime. The examples package dependencies are a clue to which scaffolding is already represented in the workspace, but the public SDK contract remains the imported OpenAI client and the generated resource methods shown in README and typed examples. Sources: examples/package.json, examples/types.ts, README.md
Compact Reference
| Area | What to look for | Source signal |
|---|---|---|
| SDK import | Default OpenAI client import for TypeScript and JavaScript projects | README.md, examples/types.ts |
| Authentication | Environment-based API key configuration through the client defaults | README.md, examples/types.ts |
| Primary model API | Responses API sample with instructions, input, and output text | README.md |
| Compatibility API | Chat Completions sample using messages and choices | README.md, examples/types.ts |
| Streaming pattern | Async iteration over streamed Chat Completions chunks | examples/types.ts |
| Example dependencies | dotenv, Express, Next, Azure Identity, and schema tooling | examples/package.json |
Next Steps
Use this page as a directory-level orientation, then continue to the API-specific page that matches the example you plan to adapt. Read the Responses pages for new model workflows, the Chat Completions pages for message-based compatibility, the structured output and tool-calling pages when schema dependencies matter, and the Azure page when @azure/identity is relevant. If an example fails, first verify the environment variable and package installation, then reduce the script back to the smallest README-style request before reintroducing framework code or streaming behavior. Sources: README.md, examples/package.json, examples/types.ts