basant307/AI_Governance_Project

1# OpenAI TypeScript and JavaScript API Library2 3[![NPM version](<https://img.shields.io/npm/v/openai.svg?label=npm%20(stable)>)](https://npmjs.org/package/openai) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/openai) [![JSR Version](https://jsr.io/badges/@openai/openai)](https://jsr.io/@openai/openai)4 5This library provides convenient access to the OpenAI REST API from TypeScript or JavaScript.6 7It is generated from our [OpenAPI specification](https://github.com/openai/openai-openapi) with [Stainless](https://stainlessapi.com/).8 9To learn how to use the OpenAI API, check out our [API Reference](https://platform.openai.com/docs/api-reference) and [Documentation](https://platform.openai.com/docs).10 11## Installation12 13```sh14npm install openai15```16 17### Installation from JSR18 19```sh20deno add jsr:@openai/openai21npx jsr add @openai/openai22```23 24These commands will make the module importable from the `@openai/openai` scope. You can also [import directly from JSR](https://jsr.io/docs/using-packages#importing-with-jsr-specifiers) without an install step if you're using the Deno JavaScript runtime:25 26```ts27import OpenAI from 'jsr:@openai/openai';28```29 30## Usage31 32The full API of this library can be found in [api.md file](api.md) along with many [code examples](https://github.com/openai/openai-node/tree/master/examples).33 34The primary API for interacting with OpenAI models is the [Responses API](https://platform.openai.com/docs/api-reference/responses). You can generate text from the model with the code below.35 36```ts37import OpenAI from 'openai';38 39const client = new OpenAI({40  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted41});42 43const response = await client.responses.create({44  model: 'gpt-4o',45  instructions: 'You are a coding assistant that talks like a pirate',46  input: 'Are semicolons optional in JavaScript?',47});48 49console.log(response.output_text);50```51 52The previous standard (supported indefinitely) for generating text is the [Chat Completions API](https://platform.openai.com/docs/api-reference/chat). You can use that API to generate text from the model with the code below.53 54```ts55import OpenAI from 'openai';56 57const client = new OpenAI({58  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted59});60 61const completion = await client.chat.completions.create({62  model: 'gpt-4o',63  messages: [64    { role: 'developer', content: 'Talk like a pirate.' },65    { role: 'user', content: 'Are semicolons optional in JavaScript?' },66  ],67});68 69console.log(completion.choices[0].message.content);70```71 72## Streaming responses73 74We provide support for streaming responses using Server Sent Events (SSE).75 76```ts77import OpenAI from 'openai';78 79const client = new OpenAI();80 81const stream = await client.responses.create({82  model: 'gpt-4o',83  input: 'Say "Sheep sleep deep" ten times fast!',84  stream: true,85});86 87for await (const event of stream) {88  console.log(event);89}90```91 92## File uploads93 94Request parameters that correspond to file uploads can be passed in many different forms:95 96- `File` (or an object with the same structure)97- a `fetch` `Response` (or an object with the same structure)98- an `fs.ReadStream`99- the return value of our `toFile` helper100 101```ts102import fs from 'fs';103import OpenAI, { toFile } from 'openai';104 105const client = new OpenAI();106 107// If you have access to Node `fs` we recommend using `fs.createReadStream()`:108await client.files.create({ file: fs.createReadStream('input.jsonl'), purpose: 'fine-tune' });109 110// Or if you have the web `File` API you can pass a `File` instance:111await client.files.create({ file: new File(['my bytes'], 'input.jsonl'), purpose: 'fine-tune' });112 113// You can also pass a `fetch` `Response`:114await client.files.create({ file: await fetch('https://somesite/input.jsonl'), purpose: 'fine-tune' });115 116// Finally, if none of the above are convenient, you can use our `toFile` helper:117await client.files.create({118  file: await toFile(Buffer.from('my bytes'), 'input.jsonl'),119  purpose: 'fine-tune',120});121await client.files.create({122  file: await toFile(new Uint8Array([0, 1, 2]), 'input.jsonl'),123  purpose: 'fine-tune',124});125```126 127## Webhook Verification128 129Verifying webhook signatures is _optional but encouraged_.130 131For more information about webhooks, see [the API docs](https://platform.openai.com/docs/guides/webhooks).132 133### Parsing webhook payloads134 135For 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 method `client.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.136 137Note that the `body` 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.138 139```ts140import { headers } from 'next/headers';141import OpenAI from 'openai';142 143const client = new OpenAI({144  webhookSecret: process.env.OPENAI_WEBHOOK_SECRET, // env var used by default; explicit here.145});146 147export async function webhook(request: Request) {148  const headersList = headers();149  const body = await request.text();150 151  try {152    const event = client.webhooks.unwrap(body, headersList);153 154    switch (event.type) {155      case 'response.completed':156        console.log('Response completed:', event.data);157        break;158      case 'response.failed':159        console.log('Response failed:', event.data);160        break;161      default:162        console.log('Unhandled event type:', event.type);163    }164 165    return Response.json({ message: 'ok' });166  } catch (error) {167    console.error('Invalid webhook signature:', error);168    return new Response('Invalid signature', { status: 400 });169  }170}171```172 173### Verifying webhook payloads directly174 175In 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 method `client.webhooks.verifySignature()` to _only verify_ the signature of a webhook request. Like `.unwrap()`, this method will throw an error if the signature is invalid.176 177Note that the `body` 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.178 179```ts180import { headers } from 'next/headers';181import OpenAI from 'openai';182 183const client = new OpenAI({184  webhookSecret: process.env.OPENAI_WEBHOOK_SECRET, // env var used by default; explicit here.185});186 187export async function webhook(request: Request) {188  const headersList = headers();189  const body = await request.text();190 191  try {192    client.webhooks.verifySignature(body, headersList);193 194    // Parse the body after verification195    const event = JSON.parse(body);196    console.log('Verified event:', event);197 198    return Response.json({ message: 'ok' });199  } catch (error) {200    console.error('Invalid webhook signature:', error);201    return new Response('Invalid signature', { status: 400 });202  }203}204```205 206## Handling errors207 208When the library is unable to connect to the API,209or if the API returns a non-success status code (i.e., 4xx or 5xx response),210a subclass of `APIError` will be thrown:211 212<!-- prettier-ignore -->213```ts214const job = await client.fineTuning.jobs215  .create({ model: 'gpt-4o', training_file: 'file-abc123' })216  .catch(async (err) => {217    if (err instanceof OpenAI.APIError) {218      console.log(err.request_id);219      console.log(err.status); // 400220      console.log(err.name); // BadRequestError221      console.log(err.headers); // {server: 'nginx', ...}222    } else {223      throw err;224    }225  });226```227 228Error codes are as follows:229 230| Status Code | Error Type                 |231| ----------- | -------------------------- |232| 400         | `BadRequestError`          |233| 401         | `AuthenticationError`      |234| 403         | `PermissionDeniedError`    |235| 404         | `NotFoundError`            |236| 422         | `UnprocessableEntityError` |237| 429         | `RateLimitError`           |238| >=500       | `InternalServerError`      |239| N/A         | `APIConnectionError`       |240 241## Request IDs242 243> For more information on debugging requests, see [these docs](https://platform.openai.com/docs/api-reference/debugging-requests)244 245All 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.246 247```ts248const completion = await client.chat.completions.create({249  messages: [{ role: 'user', content: 'Say this is a test' }],250  model: 'gpt-4o',251});252console.log(completion._request_id); // req_123253```254 255You can also access the Request ID using the `.withResponse()` method:256 257```ts258const { data: stream, request_id } = await openai.chat.completions259  .create({260    model: 'gpt-4',261    messages: [{ role: 'user', content: 'Say this is a test' }],262    stream: true,263  })264  .withResponse();265```266 267## Realtime API Beta268 269The 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 as [function calling](https://platform.openai.com/docs/guides/function-calling) through a `WebSocket` connection.270 271```ts272import { OpenAIRealtimeWebSocket } from 'openai/beta/realtime/websocket';273 274const rt = new OpenAIRealtimeWebSocket({ model: 'gpt-4o-realtime-preview-2024-12-17' });275 276rt.on('response.text.delta', (event) => process.stdout.write(event.delta));277```278 279For more information see [realtime.md](realtime.md).280 281## Microsoft Azure OpenAI282 283To use this library with [Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/overview), use the `AzureOpenAI`284class instead of the `OpenAI` class.285 286> [!IMPORTANT]287> The Azure API shape slightly differs from the core API shape which means that the static types for responses / params288> won't always be correct.289 290```ts291import { AzureOpenAI } from 'openai';292import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity';293 294const credential = new DefaultAzureCredential();295const scope = 'https://cognitiveservices.azure.com/.default';296const azureADTokenProvider = getBearerTokenProvider(credential, scope);297 298const openai = new AzureOpenAI({ azureADTokenProvider });299 300const result = await openai.chat.completions.create({301  model: 'gpt-4o',302  messages: [{ role: 'user', content: 'Say hello!' }],303});304 305console.log(result.choices[0]!.message?.content);306```307 308### Retries309 310Certain errors will be automatically retried 2 times by default, with a short exponential backoff.311Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,312429 Rate Limit, and >=500 Internal errors will all be retried by default.313 314You can use the `maxRetries` option to configure or disable this:315 316<!-- prettier-ignore -->317```js318// Configure the default for all requests:319const client = new OpenAI({320  maxRetries: 0, // default is 2321});322 323// Or, configure per-request:324await client.chat.completions.create({ messages: [{ role: 'user', content: 'How can I get the name of the current day in JavaScript?' }], model: 'gpt-4o' }, {325  maxRetries: 5,326});327```328 329### Timeouts330 331Requests time out after 10 minutes by default. You can configure this with a `timeout` option:332 333<!-- prettier-ignore -->334```ts335// Configure the default for all requests:336const client = new OpenAI({337  timeout: 20 * 1000, // 20 seconds (default is 10 minutes)338});339 340// Override per-request:341await client.chat.completions.create({ messages: [{ role: 'user', content: 'How can I list all files in a directory using Python?' }], model: 'gpt-4o' }, {342  timeout: 5 * 1000,343});344```345 346On timeout, an `APIConnectionTimeoutError` is thrown.347 348Note that requests which time out will be [retried twice by default](#retries).349 350## Request IDs351 352> For more information on debugging requests, see [these docs](https://platform.openai.com/docs/api-reference/debugging-requests)353 354All 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.355 356```ts357const response = await client.responses.create({ model: 'gpt-4o', input: 'testing 123' });358console.log(response._request_id); // req_123359```360 361You can also access the Request ID using the `.withResponse()` method:362 363```ts364const { data: stream, request_id } = await openai.responses365  .create({366    model: 'gpt-4o',367    input: 'Say this is a test',368    stream: true,369  })370  .withResponse();371```372 373## Auto-pagination374 375List methods in the OpenAI API are paginated.376You can use the `for await … of` syntax to iterate through items across all pages:377 378```ts379async function fetchAllFineTuningJobs(params) {380  const allFineTuningJobs = [];381  // Automatically fetches more pages as needed.382  for await (const fineTuningJob of client.fineTuning.jobs.list({ limit: 20 })) {383    allFineTuningJobs.push(fineTuningJob);384  }385  return allFineTuningJobs;386}387```388 389Alternatively, you can request a single page at a time:390 391```ts392let page = await client.fineTuning.jobs.list({ limit: 20 });393for (const fineTuningJob of page.data) {394  console.log(fineTuningJob);395}396 397// Convenience methods are provided for manually paginating:398while (page.hasNextPage()) {399  page = await page.getNextPage();400  // ...401}402```403 404## Realtime API Beta405 406The 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 as [function calling](https://platform.openai.com/docs/guides/function-calling) through a `WebSocket` connection.407 408```ts409import { OpenAIRealtimeWebSocket } from 'openai/beta/realtime/websocket';410 411const rt = new OpenAIRealtimeWebSocket({ model: 'gpt-4o-realtime-preview-2024-12-17' });412 413rt.on('response.text.delta', (event) => process.stdout.write(event.delta));414```415 416For more information see [realtime.md](realtime.md).417 418## Microsoft Azure OpenAI419 420To use this library with [Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/overview), use the `AzureOpenAI`421class instead of the `OpenAI` class.422 423> [!IMPORTANT]424> The Azure API shape slightly differs from the core API shape which means that the static types for responses / params425> won't always be correct.426 427```ts428import { AzureOpenAI } from 'openai';429import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity';430 431const credential = new DefaultAzureCredential();432const scope = 'https://cognitiveservices.azure.com/.default';433const azureADTokenProvider = getBearerTokenProvider(credential, scope);434 435const openai = new AzureOpenAI({436  azureADTokenProvider,437  apiVersion: '<The API version, e.g. 2024-10-01-preview>',438});439 440const result = await openai.chat.completions.create({441  model: 'gpt-4o',442  messages: [{ role: 'user', content: 'Say hello!' }],443});444 445console.log(result.choices[0]!.message?.content);446```447 448For more information on support for the Azure API, see [azure.md](azure.md).449 450## Advanced Usage451 452### Accessing raw Response data (e.g., headers)453 454The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.455This 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.456 457You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.458Unlike `.asResponse()` this method consumes the body, returning once it is parsed.459 460<!-- prettier-ignore -->461```ts462const client = new OpenAI();463 464const httpResponse = await client.responses465  .create({ model: 'gpt-4o', input: 'say this is a test.' })466  .asResponse();467 468// access the underlying web standard Response object469console.log(httpResponse.headers.get('X-My-Header'));470console.log(httpResponse.statusText);471 472const { data: modelResponse, response: raw } = await client.responses473  .create({ model: 'gpt-4o', input: 'say this is a test.' })474  .withResponse();475console.log(raw.headers.get('X-My-Header'));476console.log(modelResponse);477```478 479### Logging480 481> [!IMPORTANT]482> All log messages are intended for debugging only. The format and content of log messages483> may change between releases.484 485#### Log levels486 487The log level can be configured in two ways:488 4891. Via the `OPENAI_LOG` environment variable4902. Using the `logLevel` client option (overrides the environment variable if set)491 492```ts493import OpenAI from 'openai';494 495const client = new OpenAI({496  logLevel: 'debug', // Show all log messages497});498```499 500Available log levels, from most to least verbose:501 502- `'debug'` - Show debug messages, info, warnings, and errors503- `'info'` - Show info messages, warnings, and errors504- `'warn'` - Show warnings and errors (default)505- `'error'` - Show only errors506- `'off'` - Disable all logging507 508At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.509Some authentication-related headers are redacted, but sensitive data in request and response bodies510may still be visible.511 512#### Custom logger513 514By default, this library logs to `globalThis.console`. You can also provide a custom logger.515Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.516 517When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages518below the configured level will not be sent to your logger.519 520```ts521import OpenAI from 'openai';522import pino from 'pino';523 524const logger = pino();525 526const client = new OpenAI({527  logger: logger.child({ name: 'OpenAI' }),528  logLevel: 'debug', // Send all messages to pino, allowing it to filter529});530```531 532### Making custom/undocumented requests533 534This library is typed for convenient access to the documented API. If you need to access undocumented535endpoints, params, or response properties, the library can still be used.536 537#### Undocumented endpoints538 539To make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.540Options on the client, such as retries, will be respected when making these requests.541 542```ts543await client.post('/some/path', {544  body: { some_prop: 'foo' },545  query: { some_query_arg: 'bar' },546});547```548 549#### Undocumented request params550 551To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented552parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you553send will be sent as-is.554 555```ts556client.chat.completions.create({557  // ...558  // @ts-expect-error baz is not yet public559  baz: 'undocumented option',560});561```562 563For requests with the `GET` verb, any extra params will be in the query, all other requests will send the564extra param in the body.565 566If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request567options.568 569#### Undocumented response properties570 571To access undocumented response properties, you may access the response object with `// @ts-expect-error` on572the response object, or cast the response object to the requisite type. Like the request params, we do not573validate or strip extra properties from the response from the API.574 575### Customizing the fetch client576 577If you want to use a different `fetch` function, you can either polyfill the global:578 579```ts580import fetch from 'my-fetch';581 582globalThis.fetch = fetch;583```584 585Or pass it to the client:586 587```ts588import OpenAI from 'openai';589import fetch from 'my-fetch';590 591const client = new OpenAI({ fetch });592```593 594### Fetch options595 596If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)597 598```ts599import OpenAI from 'openai';600 601const client = new OpenAI({602  fetchOptions: {603    // `RequestInit` options604  },605});606```607 608#### Configuring proxies609 610To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy611options to requests:612 613<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>614 615```ts616import OpenAI from 'openai';617import * as undici from 'undici';618 619const proxyAgent = new undici.ProxyAgent('http://localhost:8888');620const client = new OpenAI({621  fetchOptions: {622    dispatcher: proxyAgent,623  },624});625```626 627<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>628 629```ts630import OpenAI from 'openai';631 632const client = new OpenAI({633  fetchOptions: {634    proxy: 'http://localhost:8888',635  },636});637```638 639<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>640 641```ts642import OpenAI from 'npm:openai';643 644const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });645const client = new OpenAI({646  fetchOptions: {647    client: httpClient,648  },649});650```651 652## Frequently Asked Questions653 654## Semantic versioning655 656This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:657 6581. Changes that only affect static types, without breaking runtime behavior.6592. 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.)_6603. Changes that we do not expect to impact the vast majority of users in practice.661 662We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.663 664We are keen for your feedback; please open an [issue](https://www.github.com/openai/openai-node/issues) with questions, bugs, or suggestions.665 666## Requirements667 668TypeScript >= 4.9 is supported.669 670The following runtimes are supported:671 672- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.673- Deno v1.28.0 or higher.674- Bun 1.0 or later.675- Cloudflare Workers.676- Vercel Edge Runtime.677- Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time).678- Nitro v2.6 or greater.679- Web browsers: disabled by default to avoid exposing your secret API credentials. Enable browser support by explicitly setting `dangerouslyAllowBrowser` to true'.680  <details>681    <summary>More explanation</summary>682 683  ### Why is this dangerous?684 685  Enabling the `dangerouslyAllowBrowser` 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,686  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.687 688  ### When might this not be dangerous?689 690  In certain scenarios where enabling browser support might not pose significant risks:691 692  - 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.693  - 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.694  - 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.695 696</details>697 698Note that React Native is not supported at this time.699 700If you are interested in other runtime environments, please open or upvote an issue on GitHub.701 702## Contributing703 704See [the contributing documentation](./CONTRIBUTING.md).705