Repository files navigation

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

It is generated from ourOpenAPI specification withStainless.

To learn how to use the OpenAI API, check out ourAPI Reference andDocumentation.

npm install openai

deno add jsr:@openai/openainpx jsr add @openai/openai

These commands will make the module importable from the@openai/openai scope. You can alsoimport directly from JSR without an install step if you're using the Deno JavaScript runtime:

importOpenAIfrom'jsr:@openai/openai';

The full API of this library can be found inapi.md file along with manycode examples.

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

importOpenAIfrom'openai';constclient=newOpenAI({apiKey:process.env['OPENAI_API_KEY'],// This is the default and can be omitted});constresponse=awaitclient.responses.create({model:'gpt-4o',instructions:'You are a coding assistant that talks like a pirate',input:'Are semicolons optional in JavaScript?',});console.log(response.output_text);

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

importOpenAIfrom'openai';constclient=newOpenAI({apiKey:process.env['OPENAI_API_KEY'],// This is the default and can be omitted});constcompletion=awaitclient.chat.completions.create({model:'gpt-4o',messages:[{role:'developer',content:'Talk like a pirate.'},{role:'user',content:'Are semicolons optional in JavaScript?'},],});console.log(completion.choices[0].message.content);

We provide support for streaming responses using Server Sent Events (SSE).

importOpenAIfrom'openai';constclient=newOpenAI();conststream=awaitclient.responses.create({model:'gpt-4o',input:'Say "Sheep sleep deep" ten times fast!',stream:true,});forawait(consteventofstream){console.log(event);}

Request parameters that correspond to file uploads can be passed in many different forms:

• File (or an object with the same structure)
• afetchResponse (or an object with the same structure)
• anfs.ReadStream
• the return value of ourtoFile helper

importfsfrom'fs';importOpenAI,{toFile}from'openai';constclient=newOpenAI();// If you have access to Node `fs` we recommend using `fs.createReadStream()`:awaitclient.files.create({file:fs.createReadStream('input.jsonl'),purpose:'fine-tune'});// Or if you have the web `File` API you can pass a `File` instance:awaitclient.files.create({file:newFile(['my bytes'],'input.jsonl'),purpose:'fine-tune'});// You can also pass a `fetch` `Response`:awaitclient.files.create({file:awaitfetch('https://somesite/input.jsonl'),purpose:'fine-tune'});// Finally, if none of the above are convenient, you can use our `toFile` helper:awaitclient.files.create({file:awaittoFile(Buffer.from('my bytes'),'input.jsonl'),purpose:'fine-tune',});awaitclient.files.create({file:awaittoFile(newUint8Array([0,1,2]),'input.jsonl'),purpose:'fine-tune',});

Verifying webhook signatures isoptional but encouraged.

For more information about webhooks, seethe API docs.

For most use cases, you will likely want to verify the webhook and parse the payload at the same time. To achieve this, we provide the methodclient.webhooks.unwrap(), which parses a webhook request and verifies that it was sent by OpenAI. This method will throw an error if the signature is invalid.

Note that thebody parameter must be the raw JSON string sent from the server (do not parse it first). The.unwrap() method will parse this JSON for you into an event object after verifying the webhook was sent from OpenAI.

import{headers}from'next/headers';importOpenAIfrom'openai';constclient=newOpenAI({webhookSecret:process.env.OPENAI_WEBHOOK_SECRET,// env var used by default; explicit here.});exportasyncfunctionwebhook(request:Request){constheadersList=headers();constbody=awaitrequest.text();try{constevent=client.webhooks.unwrap(body,headersList);switch(event.type){case'response.completed':console.log('Response completed:',event.data);break;case'response.failed':console.log('Response failed:',event.data);break;default:console.log('Unhandled event type:',event.type);}returnResponse.json({message:'ok'});}catch(error){console.error('Invalid webhook signature:',error);returnnewResponse('Invalid signature',{status:400});}}

In some cases, you may want to verify the webhook separately from parsing the payload. If you prefer to handle these steps separately, we provide the methodclient.webhooks.verifySignature() toonly verify the signature of a webhook request. Like.unwrap(), this method will throw an error if the signature is invalid.

Note that thebody parameter must be the raw JSON string sent from the server (do not parse it first). You will then need to parse the body after verifying the signature.

import{headers}from'next/headers';importOpenAIfrom'openai';constclient=newOpenAI({webhookSecret:process.env.OPENAI_WEBHOOK_SECRET,// env var used by default; explicit here.});exportasyncfunctionwebhook(request:Request){constheadersList=headers();constbody=awaitrequest.text();try{client.webhooks.verifySignature(body,headersList);// Parse the body after verificationconstevent=JSON.parse(body);console.log('Verified event:',event);returnResponse.json({message:'ok'});}catch(error){console.error('Invalid webhook signature:',error);returnnewResponse('Invalid signature',{status:400});}}

When the library is unable to connect to the API,or if the API returns a non-success status code (i.e., 4xx or 5xx response),a subclass ofAPIError will be thrown:

constjob=awaitclient.fineTuning.jobs.create({model:'gpt-4o',training_file:'file-abc123'}).catch(async(err)=>{if(errinstanceofOpenAI.APIError){console.log(err.request_id);console.log(err.status);// 400console.log(err.name);// BadRequestErrorconsole.log(err.headers);// {server: 'nginx', ...}}else{throwerr;}});

Error codes are as follows:

For more information on debugging requests, seethese docs

All object responses in the SDK provide a_request_id property which is added from thex-request-id response header so that you can quickly log failing requests and report them back to OpenAI.

constcompletion=awaitclient.chat.completions.create({messages:[{role:'user',content:'Say this is a test'}],model:'gpt-4o',});console.log(completion._request_id);// req_123

You can also access the Request ID using the.withResponse() method:

const{data:stream, request_id}=awaitopenai.chat.completions.create({model:'gpt-4',messages:[{role:'user',content:'Say this is a test'}],stream:true,}).withResponse();

The Realtime API enables you to build low-latency, multi-modal conversational experiences. It currently supports text and audio as both input and output, as well asfunction calling through aWebSocket connection.

import{OpenAIRealtimeWebSocket}from'openai/realtime/websocket';constrt=newOpenAIRealtimeWebSocket({model:'gpt-realtime'});rt.on('response.text.delta',(event)=>process.stdout.write(event.delta));

For more information seerealtime.md.

To use this library withAzure OpenAI, use theAzureOpenAIclass instead of theOpenAI class.

import{AzureOpenAI}from'openai';import{getBearerTokenProvider,DefaultAzureCredential}from'@azure/identity';constcredential=newDefaultAzureCredential();constscope='https://cognitiveservices.azure.com/.default';constazureADTokenProvider=getBearerTokenProvider(credential,scope);constopenai=newAzureOpenAI({ azureADTokenProvider});constresult=awaitopenai.chat.completions.create({model:'gpt-4o',messages:[{role:'user',content:'Say hello!'}],});console.log(result.choices[0]!.message?.content);

Certain errors will be automatically retried 2 times by default, with a short exponential backoff.Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,429 Rate Limit, and >=500 Internal errors will all be retried by default.

You can use themaxRetries option to configure or disable this:

// Configure the default for all requests:constclient=newOpenAI({maxRetries:0,// default is 2});// Or, configure per-request:awaitclient.chat.completions.create({messages:[{role:'user',content:'How can I get the name of the current day in JavaScript?'}],model:'gpt-4o'},{maxRetries:5,});

Requests time out after 10 minutes by default. You can configure this with atimeout option:

// Configure the default for all requests:constclient=newOpenAI({timeout:20*1000,// 20 seconds (default is 10 minutes)});// Override per-request:awaitclient.chat.completions.create({messages:[{role:'user',content:'How can I list all files in a directory using Python?'}],model:'gpt-4o'},{timeout:5*1000,});

On timeout, anAPIConnectionTimeoutError is thrown.

Note that requests which time out will beretried twice by default.

For more information on debugging requests, seethese docs

All object responses in the SDK provide a_request_id property which is added from thex-request-id response header so that you can quickly log failing requests and report them back to OpenAI.

constresponse=awaitclient.responses.create({model:'gpt-4o',input:'testing 123'});console.log(response._request_id);// req_123

You can also access the Request ID using the.withResponse() method:

const{data:stream, request_id}=awaitopenai.responses.create({model:'gpt-4o',input:'Say this is a test',stream:true,}).withResponse();

List methods in the OpenAI API are paginated.You can use thefor await … of syntax to iterate through items across all pages:

asyncfunctionfetchAllFineTuningJobs(params){constallFineTuningJobs=[];// Automatically fetches more pages as needed.forawait(constfineTuningJobofclient.fineTuning.jobs.list({limit:20})){allFineTuningJobs.push(fineTuningJob);}returnallFineTuningJobs;}

Alternatively, you can request a single page at a time:

letpage=awaitclient.fineTuning.jobs.list({limit:20});for(constfineTuningJobofpage.data){console.log(fineTuningJob);}// Convenience methods are provided for manually paginating:while(page.hasNextPage()){page=awaitpage.getNextPage();// ...}

The Realtime API enables you to build low-latency, multi-modal conversational experiences. It currently supports text and audio as both input and output, as well asfunction calling through aWebSocket connection.

import{OpenAIRealtimeWebSocket}from'openai/realtime/websocket';constrt=newOpenAIRealtimeWebSocket({model:'gpt-realtime'});rt.on('response.text.delta',(event)=>process.stdout.write(event.delta));

For more information seerealtime.md.

To use this library withAzure OpenAI, use theAzureOpenAIclass instead of theOpenAI class.

import{AzureOpenAI}from'openai';import{getBearerTokenProvider,DefaultAzureCredential}from'@azure/identity';constcredential=newDefaultAzureCredential();constscope='https://cognitiveservices.azure.com/.default';constazureADTokenProvider=getBearerTokenProvider(credential,scope);constopenai=newAzureOpenAI({  azureADTokenProvider,apiVersion:'<The API version, e.g. 2024-10-01-preview>',});constresult=awaitopenai.chat.completions.create({model:'gpt-4o',messages:[{role:'user',content:'Say hello!'}],});console.log(result.choices[0]!.message?.content);

For more information on support for the Azure API, seeazure.md.

The "raw"Response returned byfetch() can be accessed through the.asResponse() method on theAPIPromise type that all methods return.This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.

You can also use the.withResponse() method to get the rawResponse along with the parsed data.Unlike.asResponse() this method consumes the body, returning once it is parsed.

constclient=newOpenAI();consthttpResponse=awaitclient.responses.create({model:'gpt-4o',input:'say this is a test.'}).asResponse();// access the underlying web standard Response objectconsole.log(httpResponse.headers.get('X-My-Header'));console.log(httpResponse.statusText);const{data:modelResponse,response:raw}=awaitclient.responses.create({model:'gpt-4o',input:'say this is a test.'}).withResponse();console.log(raw.headers.get('X-My-Header'));console.log(modelResponse);

The log level can be configured in two ways:

1. Via theOPENAI_LOG environment variable
2. Using thelogLevel client option (overrides the environment variable if set)

importOpenAIfrom'openai';constclient=newOpenAI({logLevel:'debug',// Show all log messages});

Available log levels, from most to least verbose:

• 'debug' - Show debug messages, info, warnings, and errors
• 'info' - Show info messages, warnings, and errors
• 'warn' - Show warnings and errors (default)
• 'error' - Show only errors
• 'off' - Disable all logging

At the'debug' level, all HTTP requests and responses are logged, including headers and bodies.Some authentication-related headers are redacted, but sensitive data in request and response bodiesmay still be visible.

By default, this library logs toglobalThis.console. You can also provide a custom logger.Most logging libraries are supported, includingpino,winston,bunyan,consola,signale, and@std/log. If your logger doesn't work, please open an issue.

When providing a custom logger, thelogLevel option still controls which messages are emitted, messagesbelow the configured level will not be sent to your logger.

importOpenAIfrom'openai';importpinofrom'pino';constlogger=pino();constclient=newOpenAI({logger:logger.child({name:'OpenAI'}),logLevel:'debug',// Send all messages to pino, allowing it to filter});

This library is typed for convenient access to the documented API. If you need to access undocumentedendpoints, params, or response properties, the library can still be used.

To make requests to undocumented endpoints, you can useclient.get,client.post, and other HTTP verbs.Options on the client, such as retries, will be respected when making these requests.

awaitclient.post('/some/path',{body:{some_prop:'foo'},query:{some_query_arg:'bar'},});

To make requests using undocumented parameters, you may use// @ts-expect-error on the undocumentedparameter. This library doesn't validate at runtime that the request matches the type, so any extra values yousend will be sent as-is.

client.chat.completions.create({// ...//@ts-expect-error baz is not yet publicbaz:'undocumented option',});

For requests with theGET verb, any extra params will be in the query, all other requests will send theextra param in the body.

If you want to explicitly send an extra argument, you can do so with thequery,body, andheaders requestoptions.

To access undocumented response properties, you may access the response object with// @ts-expect-error onthe response object, or cast the response object to the requisite type. Like the request params, we do notvalidate or strip extra properties from the response from the API.

If you want to use a differentfetch function, you can either polyfill the global:

importfetchfrom'my-fetch';globalThis.fetch=fetch;

Or pass it to the client:

importOpenAIfrom'openai';importfetchfrom'my-fetch';constclient=newOpenAI({ fetch});

If you want to set customfetch options without overriding thefetch function, you can provide afetchOptions object when instantiating the client or making a request. (Request-specific options override client options.)

importOpenAIfrom'openai';constclient=newOpenAI({fetchOptions:{// `RequestInit` options},});

To modify proxy behavior, you can provide customfetchOptions that add runtime-specific proxyoptions to requests:

Node^[docs]

importOpenAIfrom'openai';import*asundicifrom'undici';constproxyAgent=newundici.ProxyAgent('http://localhost:8888');constclient=newOpenAI({fetchOptions:{dispatcher:proxyAgent,},});

Bun^[docs]

importOpenAIfrom'openai';constclient=newOpenAI({fetchOptions:{proxy:'http://localhost:8888',},});

Deno^[docs]

importOpenAIfrom'npm:openai';consthttpClient=Deno.createHttpClient({proxy:{url:'http://localhost:8888'}});constclient=newOpenAI({fetchOptions:{client:httpClient,},});

This package generally followsSemVer conventions, though certain backwards-incompatible changes may be released as minor versions:

1. Changes that only affect static types, without breaking runtime behavior.
2. Changes to library internals which are technically public but not intended or documented for external use.(Please open a GitHub issue to let us know if you are relying on such internals.)
3. Changes that we do not expect to impact the vast majority of users in practice.

We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.

We are keen for your feedback; please open anissue with questions, bugs, or suggestions.

TypeScript >= 4.9 is supported.

The following runtimes are supported:

• Node.js 20 LTS or later (non-EOL) versions.

• Deno v1.28.0 or higher.

• Bun 1.0 or later.

• Cloudflare Workers.

• Vercel Edge Runtime.

• Jest 28 or greater with the"node" environment ("jsdom" is not supported at this time).

• Nitro v2.6 or greater.

• Web browsers: disabled by default to avoid exposing your secret API credentials. Enable browser support by explicitly settingdangerouslyAllowBrowser to true'.

  More explanation

  Why is this dangerous?

  Enabling thedangerouslyAllowBrowser option can be dangerous because it exposes your secret API credentials in the client-side code. Web browsers are inherently less secure than server environments,any user with access to the browser can potentially inspect, extract, and misuse these credentials. This could lead to unauthorized access using your credentials and potentially compromise sensitive data or functionality.

  When might this not be dangerous?

  In certain scenarios where enabling browser support might not pose significant risks:

  • Internal Tools: If the application is used solely within a controlled internal environment where the users are trusted, the risk of credential exposure can be mitigated.
  • Public APIs with Limited Scope: If your API has very limited scope and the exposed credentials do not grant access to sensitive data or critical operations, the potential impact of exposure is reduced.
  • Development or debugging purpose: Enabling this feature temporarily might be acceptable, provided the credentials are short-lived, aren't also used in production environments, or are frequently rotated.

Note that React Native is not supported at this time.

If you are interested in other runtime environments, please open or upvote an issue on GitHub.

Seethe contributing documentation.