OpenAI SDK 兼容性

OpenAI SDK 入门

要使用 OpenAI SDK 兼容性功能，您需要：

1. 使用官方 OpenAI SDK
2. 进行以下更改
   • 更新您的 base URL，使其指向 Claude API
   • 将您的 API 密钥替换为 Claude API 密钥
   • 如果您的密钥是可访问多个工作区的个人密钥或服务账户密钥，还需在每个请求中发送 anthropic-workspace-id 请求头（例如，Python SDK 中的 default_headers 或 TypeScript 中的 defaultHeaders）；请参阅选择工作区
   • 更新您的模型名称以使用 Claude 模型
3. 查看以下各节以了解支持哪些功能

快速入门示例

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",  # Claude model name
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"},
    ],
)

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

重要的 OpenAI 兼容性限制

API 行为

以下是与使用 OpenAI 相比最显著的差异：

• 函数调用的 strict 参数会被忽略，这意味着工具使用的 JSON 不保证遵循所提供的 schema。如需保证 schema 一致性，请使用原生 Claude API 的结构化输出。
• 不支持音频输入；它将被忽略并从输入中移除
• 不支持提示缓存，但 Anthropic SDK 中支持该功能
• 系统/开发者消息会被提升并拼接到对话的开头，因为 Anthropic 仅支持单条初始系统消息。

大多数不受支持的字段会被静默忽略，而不会产生错误。这些内容均在以下各节中有详细说明。

输出质量注意事项

如果您对提示进行了大量调整，那么它很可能是专门针对 OpenAI 调优的。请考虑参照提示最佳实践指南为 Claude 重新调整提示。

系统/开发者消息提升

OpenAI SDK 的大多数输入都能直接映射到 Anthropic 的 API 参数，但一个明显的区别在于对 system prompt（系统提示）/开发者提示的处理。通过 OpenAI，这两种提示可以放置在聊天对话的任意位置。由于 Anthropic 仅支持一条初始系统消息，API 会获取所有系统/开发者消息，并用单个换行符（\n）将它们拼接在一起。然后，这个完整的字符串会作为单条系统消息放在消息列表的开头。

思考支持

您可以通过添加 thinking 参数来启用思考。在当前模型上，思考是自适应的，由 Claude 决定何时思考以及思考的深度；在 Claude 5 模型上，思考默认开启；手动配置的 extended thinking（扩展思考）是一种旧版模式。尽管思考能够提升 Claude 在复杂任务上的推理能力，但 OpenAI SDK 不会返回 Claude 的详细思考过程。如需完整的思考功能（包括访问 Claude 的逐步推理输出），请使用原生 Claude API。

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}},
)

速率限制

速率限制遵循 Anthropic 针对 /v1/messages 端点的标准限制。

详细的 OpenAI 兼容 API 支持

请求字段

简单字段

tools / functions 字段

messages 数组字段

响应字段

错误消息兼容性

兼容层与 OpenAI API 保持一致的错误格式。但是，详细的错误消息不会完全相同。请仅将错误消息用于日志记录和调试。

请求头兼容性

虽然 OpenAI SDK 会自动管理请求头，但以下是 Claude API 支持的完整请求头列表，供需要直接处理它们的开发者参考。