OpenAI SDK compatibility

Getting started with the OpenAI SDK

To use the OpenAI SDK compatibility feature, you need to:

1. Use an official OpenAI SDK.
2. Change the following:
   • Update your base URL to point to the Claude API.
   • Replace your API key with a Claude API key from the Claude Console.
   • If your key is a personal or service account key that isn’t scoped to a workspace, also send the anthropic-workspace-id header on every request (for example, default_headers in the Python SDK or defaultHeaders in TypeScript); see Select a workspace.
   • Update your model name to use a Claude model.
3. Review the following sections for what features are supported.

Quick start example

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),  # Your Claude API key
    base_url="https://api.anthropic.com/v1/",  # the Claude API endpoint
)

response = client.chat.completions.create(
    model="claude-opus-5-5",  # Claude model name
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"},
    ],
)

print(response.choices[0].message.content)

Important OpenAI compatibility limitations

API behavior

Here are the most substantial differences from using OpenAI:

• The strict parameter for function calling is ignored, which means the tool use JSON is not guaranteed to follow the supplied schema. For guaranteed schema conformance, use the native Claude API with structured outputs.
• response_format accepts only json_schema with strict: true. A request that sets json_object or text returns a 400 error.
• Audio and file inputs are not supported. A request that includes an input_audio or file content part returns a 400 error.
• Prompt caching is not supported, but it is supported in the Anthropic SDKs.
• System/developer messages are hoisted and concatenated into the top-level system field, wherever they appear in the conversation. To add system instructions partway through a conversation, use mid-conversation system messages in the native Claude API.
• Depending on the model, text generated for a request that sets temperature or top_p to a value other than the Claude API’s default might not carry the text watermark. If you rely on the watermark, omit both parameters.

Most unsupported fields are silently ignored rather than producing errors. These are all documented in the following sections.

Output quality considerations

If you’ve adjusted your prompt extensively, it’s likely to be well-tuned to OpenAI specifically. Consider reworking it for Claude using the prompting best practices guide.

System / developer message hoisting

Most of the inputs to the OpenAI SDK clearly map directly to Claude API parameters, but one distinct difference is the handling of system / developer prompts. These two prompts can be put throughout a chat conversation in the OpenAI API. The compatibility layer takes all system/developer messages and concatenates them together with a single newline (\n) in between them. This full string is then supplied as the top-level system field, ahead of every message.

Thinking support

On Claude 5 models and Claude Mythos Preview, thinking is on by default, so you can omit the thinking field. To use thinking on other models through the compatibility layer, set the thinking field of the request body to {"type": "enabled", "budget_tokens": N}. N must be at least 1,024 and less than max_tokens or max_completion_tokens, whichever you set.

The compatibility layer differs from the native Claude API in the following ways:

• The response doesn’t include Claude’s thinking. The native Claude API can return summarized thinking.
• Setting thinking to {"type": "adaptive"} returns a 400 error.
• On models that reject enabled in the native Claude API, the compatibility layer converts enabled to adaptive thinking. On those models, budget_tokens is required but has no effect.

The OpenAI SDK has no thinking parameter, so the following example sends it as an extra field in the request body.

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Who are you?"}],
    extra_body={"thinking": {"type": "enabled", "budget_tokens": 2000}},
)

Rate limits

Rate limits follow Anthropic’s standard limits for the /v1/messages endpoint.

Detailed OpenAI compatible API support

Request fields

Simple fields

tools / functions fields

messages array fields

Response fields

Error message compatibility

The compatibility layer maintains consistent error formats with the OpenAI API. However, the detailed error messages are not equivalent. Only use the error messages for logging and debugging.

Header compatibility

If your code reads or sets headers directly, the following table shows how the Claude API handles OpenAI’s headers.

Availability

OpenAI SDK compatibility is available on every model.

API support