OpenAI SDK 兼容性 · LHQ 的网络日志

注意

此兼容层主要用于测试和比较模型能力，对于大多数用例而言，它不被视为长期或可用于生产环境的解决方案。尽管我们力求使其保持完整功能且不引入破坏性变更，但优先考虑的是 Claude API 的可靠性和有效性。

有关已知兼容性限制的更多信息，请参阅重要的 OpenAI 兼容性限制。

如果您在使用 OpenAI SDK 兼容性功能时遇到任何问题，请通过此兼容性反馈表单分享您的反馈。

提示

为了获得最佳体验并使用完整的 Claude API 功能集（PDF 处理、引用、思考和提示缓存），请使用原生 Claude API。

OpenAI SDK 入门

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

使用官方 OpenAI SDK。
更改以下内容：
- 更新您的 base URL，使其指向 Claude API。
- 将您的 API 密钥替换为 Claude Console 中的 Claude API 密钥。
- 如果您的密钥是未限定于某个工作区的个人或服务账户密钥，还需在每个请求中发送 anthropic-workspace-id 标头（例如，Python SDK 中的 default_headers 或 TypeScript 中的 defaultHeaders）；请参阅选择工作区。
- 更新您的模型名称以使用 Claude 模型。
查阅以下各节，了解支持哪些功能。

快速入门示例

Python

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)

TypeScript

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.ANTHROPIC_API_KEY, // Your Claude API key
  baseURL: "https://api.anthropic.com/v1/" // Claude API endpoint
});

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

console.log(response.choices[0].message.content);

using System.ClientModel;
using OpenAI;
using OpenAI.Chat;

ChatClient chatClient = new(
    model: "claude-opus-5-5", // Claude model name
    credential: new ApiKeyCredential(
        Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")), // Your Claude API key
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://api.anthropic.com/v1/") // the Claude API endpoint
    });

ChatCompletion completion = chatClient.CompleteChat(
    new SystemChatMessage("You are a helpful assistant."),
    new UserChatMessage("Who are you?"));

Console.WriteLine(completion.Content[0].Text);

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),   // Your Claude API key
		option.WithBaseURL("https://api.anthropic.com/v1/"), // the Claude API endpoint
	)

	response, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: "claude-opus-5-5", // Claude model name
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.SystemMessage("You are a helpful assistant."),
			openai.UserMessage("Who are you?"),
		},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(response.Choices[0].Message.Content)
}

Java

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

public class QuickStart {
    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.builder()
            .apiKey(System.getenv("ANTHROPIC_API_KEY")) // Your Claude API key
            .baseUrl("https://api.anthropic.com/v1/") // the Claude API endpoint
            .build();

        ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
            .model("claude-opus-5-5") // Claude model name
            .addSystemMessage("You are a helpful assistant.")
            .addUserMessage("Who are you?")
            .build();

        ChatCompletion completion = client.chat().completions().create(params);
        System.out.println(completion.choices().get(0).message().content().orElse(""));
    }
}

PHP

OpenAI 没有官方的 PHP SDK。要在 PHP 中使用 Claude，请改用 Claude PHP SDK。

Ruby

require "openai"

openai = OpenAI::Client.new(
  api_key: ENV["ANTHROPIC_API_KEY"], # Your Claude API key
  base_url: "https://api.anthropic.com/v1/" # the Claude API endpoint
)

response = openai.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?"}
  ]
)

puts response.choices.first.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 支持提示缓存。
系统/开发者消息无论出现在对话中的哪个位置，都会被提升并拼接到顶层 system 字段中。如需在对话中途添加系统指令，请在原生 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 参数，因此以下示例将其作为请求体中的额外字段发送。

Python

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

TypeScript

const response = await openai.chat.completions.create({
  messages: [{ role: "user", content: "Who are you?" }],
  model: "claude-sonnet-4-6",
  // @ts-expect-error
  thinking: { type: "enabled", budget_tokens: 2000 }
});

// .NET SDK 没有类似 Python 的 extra_body 参数，因此本示例
// 使用 SDK 文档中记载的协议方法发送 thinking 参数
// （即原始 JSON 请求体）。
BinaryData input = BinaryData.FromString("""
    {
      "model": "claude-sonnet-4-6",
      "messages": [{ "role": "user", "content": "Who are you?" }],
      "thinking": { "type": "enabled", "budget_tokens": 2000 }
    }
    """);

using BinaryContent content = BinaryContent.Create(input);
ClientResult result = chatClient.CompleteChat(content);

response, err := client.Chat.Completions.New(
	context.Background(),
	openai.ChatCompletionNewParams{
		Model: "claude-sonnet-4-6",
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("Who are you?"),
		},
	},
	option.WithJSONSet("thinking", map[string]any{"type": "enabled", "budget_tokens": 2000}),
)

Java

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model("claude-sonnet-4-6")
    .addUserMessage("Who are you?")
    .putAdditionalBodyProperty("thinking",
        JsonValue.from(Map.of("type", "enabled", "budget_tokens", 2000)))
    .build();

ChatCompletion completion = client.chat().completions().create(params);

PHP

OpenAI 没有官方的 PHP SDK。要在 PHP 中使用 Claude，请改用 Claude PHP SDK。

Ruby

response = openai.chat.completions.create(
  model: "claude-sonnet-4-6",
  messages: [{role: "user", content: "Who are you?"}],
  request_options: {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"` 和指定名称的函数会强制进行工具调用。Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5.1 和 Claude Mythos 5.1 不支持强制工具使用，会返回 400 错误，因此在这些模型上请使用 `"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` 字段

显示字段

Tools

tools[n].function 字段

字段	支持状态
`name`	完全支持
`description`	完全支持
`parameters`	完全支持
`strict`	忽略。如需严格的 schema 验证，请在原生 Claude API 中使用结构化输出。

Functions

functions[n] 字段

说明

OpenAI 已弃用 functions 字段，并建议改用 tools。

字段	支持状态
`name`	完全支持
`description`	完全支持
`parameters`	完全支持
`strict`	忽略。如需严格的 schema 验证，请在原生 Claude API 中使用结构化输出。

`messages` 数组字段

显示字段

Developer 角色

messages[n].role == "developer" 的字段

说明

开发者消息会被提升到对话开头，作为初始系统消息的一部分。

字段	支持状态
`content`	完全支持，但会被提升
`name`	忽略

System 角色

messages[n].role == "system" 的字段

说明

系统消息会被提升到对话开头，作为初始系统消息的一部分。

字段	支持状态
`content`	完全支持，但会被提升
`name`	忽略

User 角色

messages[n].role == "user" 的字段

字段	变体	子字段	支持状态
`content`	`string`		完全支持
	`array`, `type == "text"`		完全支持
	`array`, `type == "image_url"`	`url`	完全支持
		`detail`	忽略
	`array`, `type == "input_audio"`		返回 400 错误
	`array`, `type == "file"`		返回 400 错误
`name`			忽略

Assistant 角色

messages[n].role == "assistant" 的字段

字段	变体	支持状态
`content`	`string`	完全支持
	`array`, `type == "text"`	完全支持
	`array`, `type == "refusal"`	忽略
`tool_calls`		完全支持
`function_call`		完全支持
`audio`		忽略
`refusal`		忽略

Tool 角色

messages[n].role == "tool" 的字段

字段	变体	支持状态
`content`	`string`	完全支持
	`array`, `type == "text"`	完全支持
`tool_call_id`		完全支持
`name`		忽略

Function 角色

messages[n].role == "function" 的字段

字段	变体	支持状态
`content`	`string`	完全支持
`name`		必需，但其值会被忽略

响应字段

字段	支持状态
`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

可用性：可用

状态	云平台
可用	Claude API