​
协议转换

TokenOPS.AI 提供了OpenAI协议的兼容层，使您能够使用OpenAI SDK来测试Claude和Gemini模型。通过少量代码更改，您可以快速评估不同模型的能力。

​
快速开始

要使用OpenAI SDK兼容功能，您需要：
  1. 使用官方OpenAI SDK
  2. 更改以下配置：
    • 更新base URL指向TokenOPS.AI API
    • 使用您的TokenOPS.AI API密钥
    • 更新模型名称为Claude或Gemini模型

​
示例代码

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_TOKENOPS_API_KEY",  # 您的TokenOPS.AI API密钥
    base_url="https://api.tokenops.ai/v1/"  # TokenOPS.AI API端点
)

# 使用Claude模型
response = client.chat.completions.create(
    model="claude-3-5-sonnet-20241022",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"}
    ],
)

# 使用Gemini模型
response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {"role": "user", "content": "Hello, world!"}
    ],
)

​
协议字段映射表

​
请求字段映射

OpenAI字段Claude字段Gemini字段支持状态说明
基础字段
modelmodel接口路径参数model✅ 完全支持使用相应厂商的模型名称
messagesmessagesgenerationConfig.contents✅ 完全支持消息格式转换，详见下表
max_completion_tokensmax_tokensgenerationConfig.maxOutputTokens✅ 完全支持最大输出token数
temperaturetemperaturegenerationConfig.temperature✅ 完全支持Claude: 0-1, Gemini: 0-2
top_ptop_pgenerationConfig.topP✅ 完全支持核采样参数
streamstream流式接口✅ 完全支持流式响应
控制参数
stopstop_sequencesgenerationConfig.stopSequences✅ 完全支持停止序列
n❌ 不支持generationConfig.candidateCount🔸 部分支持Claude不支持，Gemini支持
presence_penalty❌ 不支持generationConfig.presencePenalty🔸 部分支持Claude不支持，Gemini支持
frequency_penalty❌ 不支持generationConfig.frequencyPenalty🔸 部分支持Claude不支持，Gemini支持
logit_bias❌ 忽略❌ 忽略❌ 不支持两个厂商都不支持
logprobs❌ 忽略generationConfig.logprobs✅ 完全支持两个厂商都不支持
seed❌ 忽略generationConfig.seed✅ 完全支持两个厂商都不支持
工具调用
toolstoolstools✅ 完全支持函数调用工具定义
tool_choicetool_choicetoolConfig✅ 完全支持工具选择策略
parallel_tool_calls✅ 支持✅ 支持✅ 完全支持并行工具调用
格式化输出
response_format❌ 转换为工具调用generationConfig.responseMimeType
generationConfig.responseSchema		✅ 完全支持Claude通过工具调用实现，Gemini原生支持
推理能力
reasoning_effortthinkingthinkingConfig✅ 完全支持推理能力控制
元数据
metadatametadata❌ 忽略🔸 部分支持Claude支持，Gemini不支持
user❌ 忽略❌ 忽略❌ 不支持用于跟踪用户ID

​
消息格式映射

OpenAI消息格式Claude消息格式Gemini消息格式支持状态
角色映射
system合并到系统提示系统指令✅ 完全支持
developer合并到系统提示系统指令✅ 完全支持
useruseruser✅ 完全支持
assistantassistantmodel✅ 完全支持
tooluseruser✅ 完全支持
内容类型
文本内容texttext✅ 完全支持
图像内容imageinlineData✅ 完全支持
文件内容❌ 忽略fileData/inlineData🔸 部分支持
视频内容❌ 忽略inlineData🔸 部分支持
音频内容❌ 忽略inlineData🔸 部分支持

​
响应字段映射

OpenAI字段Claude字段Gemini字段支持状态
id请求id请求id✅ 完全支持
object固定值固定值✅ 完全支持
created响应时间戳响应时间戳✅ 完全支持
model平台模型名平台模型名✅ 完全支持
choices[].message.rolerolecandidates[].content.role✅ 完全支持
choices[].message.contentcontent[].textcandidates[].content.parts.text✅ 完全支持
choices[].message.tool_callscontent[].tool_usecandidates[].content.parts[].functionCall✅ 完全支持
choices[].finish_reasonstop_reasoncandidates[].finishReason✅ 完全支持
usage.prompt_tokensusage.input_tokensusageMetadata.promptTokenCount✅ 完全支持
usage.completion_tokensusage.output_tokensusageMetadata.candidatesTokenCount✅ 完全支持
usage.total_tokens计算得出usageMetadata.totalTokenCount✅ 完全支持

​
完成原因映射

OpenAI完成原因Claude完成原因Gemini完成原因
stopend_turn/stop_sequenceSTOP/OTHER
lengthmax_tokensMAX_TOKENS
content_filtercontent_filteredSAFETY/RECITATION/PROHIBITED_CONTENT
tool_callstool_useSTOP

​
重要兼容性限制

​
Claude API限制

  1. 系统消息处理: 所有system和developer消息会被合并为单个系统提示
  2. 格式化输出: response_format通过工具调用实现，而非原生支持
  3. 推理内容: 支持推理能力，但OpenAI SDK无法返回详细的思考过程
  4. 不支持的参数: presence_penalty, frequency_penalty, n等参数被忽略

​
Gemini API限制

  1. 角色映射: assistant角色映射为model
  2. 安全设置: 自动配置安全阈值，预览模型使用较高阈值
  3. 频率惩罚: 仅1.5 Pro和Flash模型支持

​
通用限制

  1. 错误格式: 保持与OpenAI API一致的错误格式，但详细错误信息可能不同
  2. 流式响应: 支持SSE流式传输，但具体实现细节可能有差异
  3. 速率限制: 遵循各厂商的原生速率限制规则

​
最佳实践

  1. 提示词优化: 如果您的提示词针对OpenAI进行了大量调优，建议使用TokenOPS.AI控制台的提示词改进工具
  2. 错误处理: 仅将错误信息用于日志记录和调试，不要依赖具体的错误文本内容
  3. 功能测试: 在生产环境使用前，请充分测试所需的功能特性
  4. 原生API: 如需使用完整功能集（PDF处理、引用、扩展思考、提示缓存等），建议使用原生API

​
支持的模型

​
Claude模型

  • claude-sonnet-4-20250514
  • claude-opus-4-250514
  • claude-3-7-sonnet-20250219
  • claude-3-5-sonnet-20241022

​
Gemini模型

  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite
  • gemini-2.0-flash-lite-001
  • gemini-2.0-flash-001

​
扩展功能

​
推理能力支持

您可以通过添加reasoning_effort参数来启用扩展推理功能： 
response = client.chat.completions.create(
    model="claude-3-5-sonnet-20241022",
    messages=...,
    reasoning_effort="medium"  # low, medium, high
)

​
多模态支持

支持图像和文档输入（取决于具体模型）： 
response = client.chat.completions.create(
    model="claude-3-5-sonnet-20241022",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "描述这张图片"},
                {"type": "image_url", {"url": "data:image/jpeg;base64,..."}}
            ]
        }
    ]
)
如遇到任何兼容性问题，请联系技术支持。