OpenAI TypeScript and JavaScript API Library

This library provides convenient access to the OpenAI REST API from TypeScript or JavaScript.

It is generated from our OpenAPI specification.

To learn how to use the OpenAI API, check out our API Reference and Documentation.

Installation

npm install openai

Installation with Deno

Deno can import the package directly from npm:

import OpenAI from 'npm:openai';

Usage

The full API of this library can be found in api.md file along with many code examples.

The primary API for interacting with OpenAI models is the Responses API. You can generate text from the model with the code below.

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});

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);

Multi-turn conversations

When you manage Responses API conversation history manually, preserve output items in order. Filtering response.output to messages can drop required reasoning or tool-call items and cause the next request to fail.

Use the SDK's toResponseInputItems() helper to normalize all replayable output items before adding them to the next request. For simple continuation, you can pass previous_response_id instead.

See the manual conversation state example and conversation state guide.

The previous standard (supported indefinitely) for generating text is the Chat Completions API. You can use that API to generate text from the model with the code below.

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});

const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [
    { role: 'developer', content: 'Talk like a pirate.' },
    { role: 'user', content: 'Are semicolons optional in JavaScript?' },
  ],
});

console.log(completion.choices[0].message.content);

Vision

Use the Responses API to analyze images and generate text about visual content.

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});

const response = await client.responses.create({
  model: 'gpt-5.5',
  input: [
    {
      role: 'user',
      content: [
        { type: 'input_text', text: 'What is in this image?' },
        {
          type: 'input_image',
          detail: 'auto',
          image_url:
            'https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg',
        },
      ],
    },
  ],
});

console.log(response.output_text);

Workload Identity Authentication

For secure, automated environments like cloud-managed Kubernetes, Azure, and GCP, you can use workload identity authentication with short-lived tokens from cloud identity providers instead of long-lived API keys.

The workloadIdentity parameter is mutually exclusive with apiKey.

For subject-token workload identity, the required fields are identityProviderId, serviceAccountId, and provider. X.509 workload identity instead uses an enrolled client certificate and its separately configured transport.

Kubernetes (service account tokens)

import OpenAI from 'openai';
import { k8sServiceAccountTokenProvider } from 'openai/auth';

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: k8sServiceAccountTokenProvider('/var/run/secrets/kubernetes.io/serviceaccount/token'),
  },
});

const response = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Hello!' }],
});

Azure (managed identity)

import OpenAI from 'openai';
import { azureManagedIdentityTokenProvider } from 'openai/auth';

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: azureManagedIdentityTokenProvider(),
  },
});

GCP (compute engine metadata)

import OpenAI from 'openai';
import { gcpIDTokenProvider } from 'openai/auth';

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: gcpIDTokenProvider(),
  },
});

Custom subject token provider

import OpenAI from 'openai';

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: {
      tokenType: 'jwt',
      getToken: async () => {
        return 'your-jwt-token';
      },
    },
  },
});

You can also customize the subject-token refresh buffer (default is 1200 seconds (20 minutes) before expiration; the effective buffer is capped at half of the actual token lifetime):

import OpenAI from 'openai';
import { k8sServiceAccountTokenProvider } from 'openai/auth';

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: k8sServiceAccountTokenProvider('/var/token'),
    refreshBufferSeconds: 120.0,
  },
});

This is the beginning of the README. Read the rest at the original. Read the full README ↗