openai node
v4.73.0
This library provides convenient access to the OpenAI REST API from TypeScript or JavaScript.
It is generated from our OpenAPI specification with Stainless.
To learn how to use the OpenAI API, check out our API Reference and Documentation.
npm install openaideno add jsr:@openai/openai
npx jsr add @openai/openaiThese commands will make the module importable from the @openai/openai scope:
You can also import directly from JSR without an install step if you're using the Deno JavaScript runtime:
import OpenAI from 'jsr:@openai/openai';The full API of this library can be found in api.md file along with many code examples. The code below shows how to get started using the chat completions API.
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});
async function main() {
const chatCompletion = await client.chat.completions.create({
messages: [{ role: 'user', content: 'Say this is a test' }],
model: 'gpt-4o',
});
}
main();We provide support for streaming responses using Server Sent Events (SSE).
import OpenAI from 'openai';
const client = new OpenAI();
async function main() {
const stream = await client.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Say this is a test' }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content || '');
}
}
main();If you need to cancel a stream, you can break from the loop
or call stream.controller.abort().
This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});
async function main() {
const params: OpenAI.Chat.ChatCompletionCreateParams = {
messages: [{ role: 'user', content: 'Say this is a test' }],
model: 'gpt-4o',
};
const chatCompletion: OpenAI.Chat.ChatCompletion = await client.chat.completions.create(params);
}
main();Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
Important
Previous versions of this SDK used a Configuration class. See the v3 to v4 migration guide.
When interacting with the API some actions such as starting a Run and adding files to vector stores are asynchronous and take time to complete. The SDK includes helper functions which will poll the status until it reaches a terminal state and then return the resulting object. If an API method results in an action which could benefit from polling there will be a corresponding version of the method ending in 'AndPoll'.
For instance to create a Run and poll until it reaches a terminal state you can run:
const run = await openai.beta.threads.runs.createAndPoll(thread.id, {
assistant_id: assistantId,
});More information on the lifecycle of a Run can be found in the Run Lifecycle Documentation
When creating and interacting with vector stores, you can use the polling helpers to monitor the status of operations. For convenience, we also provide a bulk upload helper to allow you to simultaneously upload several files at once.
const fileList = [
createReadStream('/home/data/example.pdf'),
...
];
const batch = await openai.vectorStores.fileBatches.uploadAndPoll(vectorStore.id, {files: fileList});The SDK also includes helpers to process streams and handle the incoming events.
const run = openai.beta.threads.runs
.stream(thread.id, {
assistant_id: assistant.id,
})
.on('textCreated', (text) => process.stdout.write('nassistant > '))
.on('textDelta', (textDelta, snapshot) => process.stdout.write(textDelta.value))
.on('toolCallCreated', (toolCall) => process.stdout.write(`nassistant > ${toolCall.type}nn`))
.on('toolCallDelta', (toolCallDelta, snapshot) => {
if (toolCallDelta.type === 'code_interpreter') {
if (toolCallDelta.code_interpreter.input) {
process.stdout.write(toolCallDelta.code_interpreter.input);
}
if (toolCallDelta.code_interpreter.outputs) {
process.stdout.write('noutput >n');
toolCallDelta.code_interpreter.outputs.forEach((output) => {
if (output.type === 'logs') {
process.stdout.write(`n${output.logs}n`);
}
});
}
}
});More information on streaming helpers can be found in the dedicated documentation: helpers.md
This library provides several conveniences for streaming chat completions, for example:
import OpenAI from 'openai';
const openai = new OpenAI();
async function main() {
const stream = await openai.beta.chat.completions.stream({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Say this is a test' }],
stream: true,
});
stream.on('content', (delta, snapshot) => {
process.stdout.write(delta);
});
// or, equivalently:
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content || '');
}
const chatCompletion = await stream.finalChatCompletion();
console.log(chatCompletion); // {id: "…", choices: […], …}
}
main();Streaming with openai.beta.chat.completions.stream({…}) exposes
various helpers for your convenience including event handlers and promises.
Alternatively, you can use openai.chat.completions.create({ stream: true, … })
which only returns an async iterable of the chunks in the stream and thus uses less memory
(it does not build up a final chat completion object for you).
If you need to cancel a stream, you can break from a for await loop or call stream.abort().
We provide the openai.beta.chat.completions.runTools({…})
convenience helper for using function tool calls with the /chat/completions endpoint
which automatically call the JavaScript functions you provide
and sends their results back to the /chat/completions endpoint,
looping as long as the model requests tool calls.
If you pass a parse function, it will automatically parse the arguments for you
and returns any parsing errors to the model to attempt auto-recovery.
Otherwise, the args will be passed to the function you provide as a string.
If you pass tool_choice: {function: {name: …}} instead of auto,
it returns immediately after calling that function (and only loops to auto-recover parsing errors).
import OpenAI from 'openai';
const client = new OpenAI();
async function main() {
const runner = client.beta.chat.completions
.runTools({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'How is the weather this week?' }],
tools: [
{
type: 'function',
function: {
function: getCurrentLocation,
parameters: { type: 'object', properties: {} },
},
},
{
type: 'function',
function: {
function: getWeather,
parse: JSON.parse, // or use a validation library like zod for typesafe parsing.
parameters: {
type: 'object',
properties: {
location: { type: 'string' },
},
},
},
},
],
})
.on('message', (message) => console.log(message));
const finalContent = await runner.finalContent();
console.log();
console.log('Final content:', finalContent);
}
async function getCurrentLocation() {
return 'Boston'; // Simulate lookup
}
async function getWeather(args: { location: string }) {
const { location } = args;
// … do lookup …
return { temperature, precipitation };
}
main();
// {role: "user", content: "How's the weather this week?"}
// {role: "assistant", tool_calls: [{type: "function", function: {name: "getCurrentLocation", arguments: "{}"}, id: "123"}
// {role: "tool", name: "getCurrentLocation", content: "Boston", tool_call_id: "123"}
// {role: "assistant", tool_calls: [{type: "function", function: {name: "getWeather", arguments: '{"location": "Boston"}'}, id: "1234"}]}
// {role: "tool", name: "getWeather", content: '{"temperature": "50degF", "preciptation": "high"}', tool_call_id: "1234"}
// {role: "assistant", content: "It's looking cold and rainy - you might want to wear a jacket!"}
//
// Final content: "It's looking cold and rainy - you might want to wear a jacket!"Like with .stream(), we provide a variety of helpers and events.
Note that runFunctions was previously available as well, but has been deprecated in favor of runTools.
Read more about various examples such as with integrating with zod, next.js, and proxying a stream to the browser.
Request parameters that correspond to file uploads can be passed in many different forms:
File (or an object with the same structure)fetch Response (or an object with the same structure)fs.ReadStream
toFile helperimport fs from 'fs';
import fetch from 'node-fetch';
import OpenAI, { toFile } from 'openai';
const client = new OpenAI();
// If you have access to Node `fs` we recommend using `fs.createReadStream()`:
await client.files.create({ file: fs.createReadStream('input.jsonl'), purpose: 'fine-tune' });
// Or if you have the web `File` API you can pass a `File` instance:
await client.files.create({ file: new File(['my bytes'], 'input.jsonl'), purpose: 'fine-tune' });
// You can also pass a `fetch` `Response`:
await client.files.create({ file: await fetch('https://somesite/input.jsonl'), purpose: 'fine-tune' });
// Finally, if none of the above are convenient, you can use our `toFile` helper:
await client.files.create({
file: await toFile(Buffer.from('my bytes'), 'input.jsonl'),
purpose: 'fine-tune',
});
await client.files.create({
file: await toFile(new Uint8Array([0, 1, 2]), 'input.jsonl'),
purpose: 'fine-tune',
});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 of APIError will be thrown:
async function main() {
const job = await client.fineTuning.jobs
.create({ model: 'gpt-4o', training_file: 'file-abc123' })
.catch(async (err) => {
if (err instanceof OpenAI.APIError) {
console.log(err.status); // 400
console.log(err.name); // BadRequestError
console.log(err.headers); // {server: 'nginx', ...}
} else {
throw err;
}
});
}
main();Error codes are as followed:
| Status Code | Error Type |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| >=500 | InternalServerError |
| N/A | APIConnectionError |
For more information on debugging requests, see these docs
All object responses in the SDK provide a _request_id property which is added from the x-request-id response header so that you can quickly log failing requests and report them back to OpenAI.
const completion = await client.chat.completions.create({ messages: [{ role: 'user', content: 'Say this is a test' }], model: 'gpt-4o' });
console.log(completion._request_id) // req_123To use this library with Azure OpenAI, use the AzureOpenAI
class instead of the OpenAI class.
Important
The Azure API shape slightly differs from the core API shape which means that the static types for responses / params won't always be correct.
import { AzureOpenAI } from 'openai';
import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity';
const credential = new DefaultAzureCredential();
const scope = 'https://cognitiveservices.azure.com/.default';
const azureADTokenProvider = getBearerTokenProvider(credential, scope);
const openai = new AzureOpenAI({ azureADTokenProvider });
const result = await openai.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 the maxRetries option to configure or disable this:
// Configure the default for all requests:
const client = new OpenAI({
maxRetries: 0, // default is 2
});
// Or, configure per-request:
await client.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 a timeout option:
// Configure the default for all requests:
const client = new OpenAI({
timeout: 20 * 1000, // 20 seconds (default is 10 minutes)
});
// Override per-request:
await client.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, an APIConnectionTimeoutError is thrown.
Note that requests which time out will be retried twice by default.
List methods in the OpenAI API are paginated.
You can use the for await … of syntax to iterate through items across all pages:
async function fetchAllFineTuningJobs(params) {
const allFineTuningJobs = [];
// Automatically fetches more pages as needed.
for await (const fineTuningJob of client.fineTuning.jobs.list({ limit: 20 })) {
allFineTuningJobs.push(fineTuningJob);
}
return allFineTuningJobs;
}Alternatively, you can request a single page at a time:
