Developer quickstart

Purpose and Scope

Use this page when you want the shortest path from an empty TypeScript or JavaScript project to a successful OpenAI API request with the official SDK. The repository README frames the package as the official TypeScript and JavaScript library for convenient access to the OpenAI REST API, generated from the OpenAPI specification with Stainless. For a first request, the important path is deliberately small: install the package, provide an API key through the environment, construct an OpenAI client, call the Responses API, and print the generated output. Sources: README.md, package.json, src/index.ts

The quickstart uses the Responses API because the README identifies it as the primary API for interacting with OpenAI models. That matters for new applications: Responses is the model interaction surface that supports plain text generation, richer input arrays such as image inputs, and the conversation-state patterns that later pages describe. Chat Completions remains supported and is shown in the README as the previous standard, but a new first request should start with Responses unless you are maintaining an existing message-based chat workflow. Sources: README.md

Relevant Source Files

• README.md — Defines the SDK’s purpose, installation commands, first Responses API request, API-key defaulting behavior, JSR/Deno import notes, vision example, and Chat Completions fallback example.
• package.json — Identifies the published package name, TypeScript declaration entrypoint, CommonJS package type, ESM and CommonJS export targets, scripts, and optional peer dependencies used by advanced scenarios.
• src/index.ts — Shows the public root exports: default OpenAI client, named OpenAI and ClientOptions exports, upload helpers, pagination promises, error classes, AzureOpenAI, and BedrockOpenAI.
• ecosystem-tests/browser-direct-import/public/index.js — Demonstrates direct browser import from the built module, explicit browser opt-in with dangerouslyAllowBrowser, and test-harness API-key injection through a query parameter.
• ecosystem-tests/ts-browser-webpack/src/index.ts — Demonstrates bundler import of OpenAI from openai, typed resource imports, browser opt-in, custom fetch/provider testing, and browser-oriented upload typing checks.
• ecosystem-tests/vercel-edge/src/pages/index.tsx — Locates the Vercel Edge ecosystem fixture requested for this page and shows the minimal Next page shell used by that scenario.

First Request Flow

Start by creating an API key in the OpenAI dashboard and exporting it into the shell that will run your application. The official quickstart guidance says SDKs are configured to read the API key from the system environment, and the repository README mirrors that behavior with a client constructor where apiKey is set to the environment variable and commented as the default that can be omitted. Keeping the key in the environment avoids hard-coding secrets in source files and keeps the same code usable in local terminals, CI, and server deployments. Sources: README.md

npm install openai
export OPENAI_API_KEY=sk-...

Then create a small module and import the default client from the package root. The README’s first example constructs a client, calls client.responses.create, passes a model, instructions, and input, and prints response.output_text. The key shape to learn is that instructions describe the assistant behavior while input is the user task or conversation content. The SDK returns a typed response object, and the quickstart uses the convenience output_text property so the first example can focus on the request and the generated answer rather than walking the full output item structure. Sources: README.md, src/index.ts

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'],
});
 
const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions: 'You are a coding assistant that talks like a pirate',
  input: 'Are semicolons optional in JavaScript?',
});
 
console.log(response.output_text);

Core Primitives

The first primitive is the package root. package.json publishes the package as openai and exposes both import and require targets, while src/index.ts exports OpenAI as the default export and also re-exports the named OpenAI class and ClientOptions type. That means the same conceptual client is available to modern ESM TypeScript, JavaScript, and CommonJS consumers through the package’s generated distribution. The root export also exposes APIPromise, PagePromise, upload helpers, error classes, AzureOpenAI, and BedrockOpenAI, but the quickstart only needs the default OpenAI client. Sources: package.json, src/index.ts

The second primitive is authentication. For the standard OpenAI API path, the README’s constructor example passes apiKey from process.env and states that this is the default and can be omitted. In a server-side quickstart, prefer omitting the option once OPENAI_API_KEY is set, or passing it explicitly from a trusted configuration layer. Browser fixtures in the repository use dangerouslyAllowBrowser and query-string API-key injection only for ecosystem testing. Treat that opt-in as a signal that browser exposure is dangerous for real secrets, not as a production pattern. Sources: README.md, ecosystem-tests/browser-direct-import/public/index.js, ecosystem-tests/ts-browser-webpack/src/index.ts

The third primitive is the request body. A Responses request combines model selection with task-specific fields such as instructions and input. The README’s vision example shows that input can be an array containing role and content entries, including input_text and input_image items, so the first text request is not a separate one-off API style; it is the simplest member of a broader Responses shape. Once you add tools, external integrations, or richer content, keep the same client and expand the request object rather than switching libraries. Sources: README.md

Connections, MCP, and OpenAPI-backed actions are not required for the first request, but they are useful next concepts when the model needs to reach external systems. Think of the quickstart call as a local SDK request from your application to the OpenAI API. MCP and OpenAPI action surfaces add integration boundaries where tools or services can be described and invoked as part of an agent or response workflow. Learn the plain Responses request first, then add integrations deliberately so authentication, permissions, and tool behavior remain understandable. Sources: README.md, src/index.ts

System-to-Code Mapping

The repository’s generated entrypoint keeps the quickstart stable even though the SDK contains many resources. src/index.ts is intentionally a root barrel: it exports the client, core promise and pagination helpers, upload utilities, and typed error classes from deeper modules. package.json then maps the package root to dist/index.mjs for import and dist/index.js for require. As a result, quickstart code should not import from generated internal resource paths unless it needs a specific type. Start from the root import, then let editor autocomplete guide you into typed resources. Sources: package.json, src/index.ts

Runtime Notes

For Node and server runtimes, the README example is the safest starting point because the API key stays in process environment and never needs to leave the backend. The package metadata exposes both ESM and CommonJS builds, so most project templates can import the client without special wiring. If you are using Deno or a JSR-oriented workflow, the README documents JSR installation and direct JSR import options under the @openai/openai scope. Those installation choices change how the module is resolved, not the client shape used for the first Responses request. Sources: README.md, package.json

The browser ecosystem tests are useful for understanding constraints, not for copying secret-handling patterns. Both direct browser import and webpack examples construct a client with dangerouslyAllowBrowser: true, and the supplied snippets obtain an API key from URLSearchParams. That is appropriate for controlled test pages that need to exercise bundling, upload types, raw response behavior, or provider behavior, but a production browser application should normally call your own backend instead of embedding an OpenAI API key in client-side code. The quickstart should therefore run on the server first. Sources: ecosystem-tests/browser-direct-import/public/index.js, ecosystem-tests/ts-browser-webpack/src/index.ts

Troubleshooting the First Run

If the request fails before reaching the model, check the environment variable first. A missing or misspelled OPENAI_API_KEY is the most common quickstart problem because the client constructor can rely on that default. If the import fails, verify that the openai package is installed in the same project that runs the script and that your runtime understands the module form you are using. The package export map supports both import and require through generated distribution files, but project-specific TypeScript, bundler, or runtime settings still need to resolve the package root. Sources: README.md, package.json

If the request succeeds but your application needs conversation memory, do not start by filtering only message-looking output items. The README warns that manually managed Responses API history should preserve output items in order, because dropping reasoning or tool-call items can make a later request fail. For a first request, printing output_text is correct. For a second turn, either use previous_response_id for simple continuation or move to the conversation-state guide and the SDK helper mentioned in the README. That sequence keeps the quickstart small while avoiding a common multi-turn edge case. Sources: README.md

Next Steps

After the first Responses request works, choose the next page based on the problem you are solving. Read Installation if you need JSR, Deno, or package-manager details. Read Client configuration and authentication before deploying, because production services often need organization or project headers, custom fetch behavior, timeouts, and retries. Read Responses API concepts for streaming, tools, image input, and response item access. If you are maintaining legacy message-based code, read Chat Completions instead of rewriting everything immediately. For browser or edge deployment questions, continue with the runtime-focused pages before exposing any user-facing workflow. Sources: README.md, package.json, ecosystem-tests/browser-direct-import/public/index.js, ecosystem-tests/ts-browser-webpack/src/index.ts, ecosystem-tests/vercel-edge/src/pages/index.tsx