API Overview

Use this reference to look up OpenAI API endpoints, request and response schemas, streaming events, client library methods, and shared behavior such as authentication, errors, rate limits, and request IDs.

Start here

1. Choose the API surface for your application:
   • Responses for direct model requests, tool use, audio, image, and text inputs, and stateful interactions.
   • Realtime API for low-latency voice or audio sessions over WebRTC, WebSocket, or SIP. Use the client events and server events references while building sessions.
   • Administration for organization workflows such as users, invites, projects, API keys, and audit logs.
2. Create credentials. Use a standard API key for application requests, an Admin API key for Administration endpoints, or workload identity federation for short-lived access tokens.
3. Install an official client library from the libraries page, or call the HTTP API directly from any environment that supports HTTP requests.
4. Make a first request with the developer quickstart or go straight to the Responses create reference.
5. Before production, review error codes, rate limits, and request ID logging below.

Authentication

The OpenAI API accepts bearer credentials from API keys or from short-lived access tokens created with workload identity federation.

Remember that your API key is a secret. Don’t share it with others or expose it in any client-side code such as browsers or apps. Load API keys from an environment variable or key management service on the server.

Provide API credentials with HTTP Bearer authentication.

Authorization: Bearer OPENAI_API_KEY_OR_ACCESS_TOKEN

If you belong to more than one organization or access projects through a legacy user API key, pass a header to specify which organization and project to use for an API request:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Organization: $ORGANIZATION_ID" \
  -H "OpenAI-Project: $PROJECT_ID"

Usage from these API requests counts as usage for the specified organization and project. Find organization and project IDs in your dashboard settings.

Debugging requests

Error codes describe failures returned from API responses. Inspect HTTP response headers for the unique ID of a request and rate limit details. Common response headers include:

API meta information

• openai-organization: The organization associated with the request
• openai-processing-ms: Time taken processing your API request
• openai-version: REST API version used for this request (currently 2020-10-01)
• x-request-id: Unique identifier for this API request (used in troubleshooting)

Rate limiting information

• x-ratelimit-limit-requests
• x-ratelimit-limit-tokens
• x-ratelimit-remaining-requests
• x-ratelimit-remaining-tokens
• x-ratelimit-reset-requests
• x-ratelimit-reset-tokens

OpenAI recommends logging request IDs in production deployments for more efficient troubleshooting with the support team, should the need arise. Official client libraries provide a property on top-level response objects containing the value of the x-request-id header.

Supplying your own request ID with X-Client-Request-Id

Along with the server-generated x-request-id, you can supply your own unique identifier for each request via the X-Client-Request-Id request header. This header isn’t added automatically; you must explicitly set it on the request.

When you include X-Client-Request-Id:

• You control the ID format (for example, a UUID or your internal trace ID), but it must contain only ASCII characters and be no more than 512 characters long; otherwise, the request will fail with a 400 error. Make this value unique per request.

• OpenAI logs this value internally for supported endpoints, including chat/completions, embeddings, responses, and more.

• In cases like timeouts or network issues when you can’t get the X-Request-Id response header, you can share the X-Client-Request-Id value with the support team to look up whether OpenAI received the request and when.

Example:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "X-Client-Request-Id: 123e4567-e89b-12d3-a456-426614174000"

Backwards compatibility

OpenAI provides stability to API users by avoiding breaking changes in major API versions whenever reasonably possible. This includes:

• The REST API (currently v1)
• First-party client libraries (released libraries adhere to semantic versioning)
• Model families (like gpt-4o or o4-mini)

Model prompting behavior between snapshots is subject to change. Model outputs are by their nature variable, so expect changes in prompting and model behavior between snapshots. The best way to ensure consistent prompting behavior and model output is to use pinned model versions, and to run evals for your applications.

Backwards-compatible API changes:

• Adding new resources (URLs) to the REST API and client libraries
• Adding new optional API parameters
• Adding new properties to JSON response objects or event data
• Changing the order of properties in a JSON response object
• Changing the length or format of opaque strings, like resource identifiers
• Adding new event types in streaming APIs

See the changelog for a list of backwards-compatible changes and rare breaking changes.