开发者 API 兼容性说明

本页说明当前按量 API 的协议范围。OpenAI Chat Completions、Responses、Images 与 Models 使用各自公开合同；Anthropic Messages、Count Tokens 与 Models 使用 Anthropic 合同。两类 Token 统计端点保持官方请求入口与成功体，但数值由 Token Factory 本地保守预估，不是供应商精确计数。 请以每个能力页列出的完整地址、请求头、请求媒体类型、响应、SSE 事件和错误为准，不把“兼容”理解为对 OpenAI 或 Anthropic 全部 API 与参数的承诺。

状态	含义	常见内容
verified	已由平台接口契约确认	公开路径、鉴权方式、请求参数和本地错误格式。
platform-local	由 Token Factory 执行	输入 Token 预估；不经过供应商路线，也不产生计费或用量扣减。
upstream-dependent	由所选模型与供应商决定	具体模型是否具有图片、音频、工具、思考等能力，以及上下文与输出上限。
limited	可以使用，但有明确条件	特定完整地址的模型范围、额度、并发、输入与输出限制。
unsupported	未列入当前支持范围	未接入的 API 路径与明确排除的有状态操作。

平台保留技术检测和健康探活用于诊断，未检测、检测失败、结果过期或健康恢复中都不会提前阻断请求。 请求满足必要协议结构与平台边界后，会按已配置的供应商接口发送；工具、思考、缓存及模型特定参数是否 受支持由供应商判断。模型出现在目录中不表示所有能力都已通过检测。

SDK 的字段序列化、代理、流式解析和自动重试还会受到具体版本影响。上线前应使用实际 SDK 版本 完成普通请求、流式输出、错误处理和有界重试验证。

OpenAI 兼容范围

当前开发者 API 包含 Chat Completions、Responses Create、Responses Compact、Responses Input Tokens、Images Generations、Images Edits 和 Models，使用 https://api.tokenfactory.cn/v1 下的对应完整地址。

Chat Completions 与 Responses 可以在原接口内承载图片输入、OCR/看图问答、内联文件、音频输入与 音频回答、Reasoning、工具调用、结构化输出和 Prompt Cache；这不是额外的 OCR、Files 或 Audio 接口。Images Generations 使用 application/json；Images Edits 使用 multipart/form-data，支持 重复 image 或 image[] 文件 part、可选 mask，并保留文件名、Content-Type、未知官方文本 part 和原始文件字节。两条 Images 操作都支持普通 JSON 或各自协议的真实 SSE。

Responses Input Tokens 由 Token Factory 本地执行，返回官方 {"object":"response.input_tokens","input_tokens":N} 成功体。input 可缺省或为 null，存在时必须 是字符串或数组；只提供 instructions 和/或普通本地 tools 也可估算，但 Token Factory 为校验 平台模型可见性仍要求 model。只有纯文本 input/instructions 以约 10% 偏差为工程目标，且不是 逐请求保证；模型专有或其他 tokenizer 仍可能偏离。普通 Tools 除可见 JSON 外还使用固定隐式预算， 非空 Reasoning 也追加固定协议预算，两者误差都可能明显更大。

图片、PDF 与文件使用固定偏高的分层占位预算并统一再增加 10%，但这些预算是启发式而非严格上界， 高压缩多页 PDF 仍可能低估。URL 与 file_id 不抓取内容，也不表示平台实现了 Files 生命周期； text/plain 的 data 按可见正文计数，未知可选字段的可见结构和文本也会参与计数。显式 item_reference、裸 {id}、type 缺省/null 且含 id 的引用都无法在本地还原服务端上下文， 提供时返回 400 invalid_request_error。当前也不支持 conversation、previous_response_id、远程 prompt 模板，以及可通过 server_url、connector 或 tunnel 动态发现远程 Schema 的 tools[].type=mcp；调用方需先把上下文与工具定义展开成本地可见字段。

Anthropic 范围

https://api.tokenfactory.cn/anthropic 下提供 Messages、Count Tokens、Models 列表和 Models 详情。Messages 支持图片、内联 PDF/文档、工具、Thinking、结构化输出和 Prompt Cache；Count Tokens 由 Token Factory 本地预估并返回官方 {"input_tokens":N} 成功体，不调用供应商。messages 必填且必须是数组， 但允许为空；非空时每项包含 role 与 content，role 接受 user/assistant/system。消息内 system 仅用于官方支持的模型与位置，初始系统提示仍使用顶层 system；tools 只接受数组或 null。 只有纯文本 messages/system 以约 10% 偏差为工程目标且不是逐请求保证，模型专有或其他 tokenizer 仍可能偏离；Tools 会在可见 JSON 外按工具类型追加确定性的隐式 system/toolset 预算，Thinking、Tools 和多模态的误差可能明显更大。document 内容块的 source.type=text、media_type=text/plain 时，会按 data 可见正文计数；URL/file_id 不抓取， 未知可选字段的可见结构与文本会参与计数。图片、PDF 和其他内联文档使用固定偏高的分层占位预算， 不是严格上界，高压缩多页 PDF 仍可能低估。

所有 Anthropic 操作都接受 x-api-key 或 Bearer API Key（二选一）；anthropic-version 为可选， 缺省时按 2023-06-01 处理，发送其他值返回 400。Messages 和 Count Tokens 另接受可选 anthropic-beta。 Models 列表支持 after_id、before_id 与 limit 游标分页；详情使用 model_id 路径参数。响应和错误信封以对应操作页为准。

模型发现完整地址为：

• GET /anthropic/v1/models
• GET /anthropic/v1/models/{model_id}

响应开放边界

模型供应商返回的内容细节和官方新增字段可能随模型与上游协议演进，操作页中的成功报文是代表性 示例。平台按对应协议检查必要结构，对可无歧义对应的字段和可空缺省进行归一化，保留合法扩展字段； 无法收敛的响应输出标准错误。模型生成内容是否满足业务预期或请求的 JSON Schema，不作为平台报文格式 校验的成功条件。思考签名作为不透明字段原样保留，缺失时可补空字符串，不生成非空证明。 可计费生成成功仍须取得可信 Usage，按图片张数计费的 Images 成功须取得真实且大于零的输出图片数； 缺计量返回明确错误，不估算收费。流式已经输出后出现错误，以协议错误事件结束，不补成成功或自动重发。 客户端应忽略不认识的附加字段，但可依赖操作页标为必需的字段。

两类 Token 预估的 input_tokens 只用于发起生成请求前的上下文预算和限长判断，绝不作为余额账单或供应商 Usage。成功响应头 x-tokenfactory-token-estimate 会给出当前算法版本。

地址与错误边界

实际请求按所调用的完整 URL 执行，不会自动改走另一个地址。需要供应商的生成操作会把非 2xx 响应 归一化为当前公开协议的错误信封，只转发安全响应头；成功与错误响应会声明请求 ID，限流时按实际情况包含 Retry-After 或安全的 rate-limit 头。连接失败、超时和部分流中断仍需结合 错误处理与流式和重试判断是否能安全重放。

Token 预估操作不经过供应商，因此不会返回供应路由、上游连接、上游超时或供应商限流错误。

当前明确不支持

• 生成接口中的 file_id 和 Files 上传、查询、删除等生命周期；Token 预估接口仅把 file_id 当作未知外部内容使用固定预算。
• 独立 Audio API 与 Realtime；音频输入和音频回答只存在于支持它们的 Chat/Responses 模型调用中。
• Responses background、Conversations 与 WebSocket 模式。
• Images Variations、视频理解、视频生成、音色克隆和音色管理。
• 文本或多模态 Embeddings 与 Rerank；/v1/embeddings 和 /v1/rerank 均不属于公开 API。
• 原生 Gemini 协议及API 文档未列出的其他路径。

第三方工具接入

Claude Code、桌面客户端和编码代理填写的是 Base URL，不属于本 API 文档的开发者操作清单。 相关协议、权益和配置请前往工具与集成。