Claude Platform Docs
SDK、CLI 和库库与集成

OpenAI SDK 兼容性

Anthropic 提供了一个兼容层,让您可以使用 OpenAI SDK 来测试 Claude API。只需少量代码更改,您就可以评估 Anthropic 模型的能力。

OpenAI SDK 入门

要使用 OpenAI SDK 兼容性功能,您需要:

  1. 使用官方 OpenAI SDK。
  2. 更改以下内容:
    • 更新您的基础 URL,使其指向 Claude API。
    • 将您的 API 密钥替换为 Claude Console 中的 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-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。
  • response_format 仅接受带有 strict: true 的 json_schema。设置 json_object 或 text 的请求会返回 400 错误。
  • 不支持音频和文件输入。包含 input_audio 或 file 内容部分的请求会返回 400 错误。
  • 不支持提示缓存,但 Anthropic SDK 支持提示缓存。
  • 对于通过兼容层发出的请求,API 不会生成 OpenTelemetry span。如需获取这些 span,请使用原生 Claude API。
  • 系统/开发者消息无论出现在对话中的哪个位置,都会被提升并拼接到顶层 system 字段中。如需在对话中途添加系统指令,请在原生 Claude API 中使用对话中途系统消息。
  • 根据模型的不同,如果请求将 temperature 或 top_p 设置为 Claude API 默认值以外的值,则为该请求生成的文本可能不带有文本水印。如果您依赖水印,请省略这两个参数。

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

输出质量注意事项

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

系统/开发者消息提升

OpenAI SDK 的大多数输入都可以直接映射到 Claude API 参数,但一个明显的区别在于对系统/开发者提示的处理。在 OpenAI API 中,这两种提示可以放在聊天对话中的任何位置。兼容层会获取所有系统/开发者消息,并用单个换行符(\n)将它们拼接在一起。然后,这个完整的字符串会作为顶层 system 字段提供,位于所有消息之前。

思考支持

在 Claude 5 模型和 Claude Mythos Preview 上,思考默认开启,因此您可以省略 thinking 字段。如需通过兼容层在其他模型上使用思考,请将请求体的 thinking 字段设置为 {"type": "enabled", "budget_tokens": N}。N 必须至少为 1,024,并且小于 max_tokens 或 max_completion_tokens(以您设置的为准)。

兼容层与原生 Claude API 在以下方面有所不同:

  • 响应不包含 Claude 的思考内容。原生 Claude API 可以返回摘要思考。
  • 将 thinking 设置为 {"type": "adaptive"} 会返回 400 错误。
  • 在原生 Claude API 中拒绝 enabled 的模型上,兼容层会将 enabled 转换为自适应思考。在这些模型上,budget_tokens 是必需的,但不起作用。

OpenAI SDK 没有 thinking 参数,因此以下示例将其作为请求体中的额外字段发送。

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 支持

请求字段

简单字段

字段支持状态
model使用 Claude 模型名称
max_tokens完全支持
max_completion_tokens完全支持
stream完全支持
stream_options完全支持
top_p传递给模型。Claude 4.7 及更高版本的模型以及 Claude Mythos Preview 对于除默认值 0.99 以外的任何值都会返回 400 错误,因此请省略此参数。同时设置 temperature 和 top_p 的请求也会返回 400 错误。请参阅使用 Messages API。
parallel_tool_calls完全支持
tool_choice有限支持。"required" 和指定名称的函数会强制进行工具调用。部分模型在强制工具使用时会返回 400 错误:Claude Fable 5.2、Claude Mythos 5.2、Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5.1 和 Claude Mythos 5.1。在这些模型上请使用 "auto"。请参阅强制工具使用。
stop所有非空白停止序列均有效
temperature介于 0 和 1 之间(含边界)。大于 1 的值将被限制为 1。在 Claude 4.7 及更高版本的模型以及 Claude Mythos Preview 上,任何低于 1 的值都会返回 400 错误,因此请省略此参数。请参阅使用 Messages API。
n必须恰好为 1。任何其他值都会返回 400 错误。
response_format有限支持。仅接受带有 strict: true 的 json_schema,并且适用结构化输出的 JSON Schema 限制。任何其他值(包括 json_object 和 text)都会返回 400 错误。
logprobs忽略
metadata忽略
prediction忽略
presence_penalty忽略
frequency_penalty忽略
seed忽略
service_tier忽略
audio忽略
logit_bias忽略
store忽略
user忽略
modalities忽略
top_logprobs忽略
reasoning_effort忽略

tools / functions 字段

messages 数组字段

响应字段

字段支持状态
id完全支持
choices[]长度始终为 1
choices[].finish_reason完全支持
choices[].index完全支持
choices[].message.role完全支持
choices[].message.content完全支持
choices[].message.tool_calls完全支持
object完全支持
created完全支持
model完全支持
usage.completion_tokens完全支持
usage.prompt_tokens完全支持
usage.total_tokens完全支持
usage.completion_tokens_details始终为空
usage.prompt_tokens_details始终为空
choices[].message.refusal始终为空
choices[].message.audio始终为空
logprobs始终为空
service_tier始终为空
system_fingerprint始终为空

错误消息兼容性

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

请求头兼容性

如果您的代码直接读取或设置标头,下表展示了 Claude API 如何处理 OpenAI 的标头。

标头支持状态
x-ratelimit-limit-requests不返回。请求限制位于 x-ratelimit-requests 中。
x-ratelimit-limit-tokens不返回。令牌限制位于 x-ratelimit-tokens 中。
x-ratelimit-remaining-requests完全支持
x-ratelimit-remaining-tokens完全支持
x-ratelimit-reset-requests完全支持
x-ratelimit-reset-tokens完全支持
retry-after完全支持
x-request-id完全支持。携带 Claude API 的请求 ID,以替代 request-id 标头。
openai-version不返回
openai-processing-ms不返回
authorization完全支持

可用性

OpenAI SDK 兼容性
API
  • Messages API
模型
  • 所有模型

此页面对您有帮助吗?