OpenAI 协议

更新于 2026-08-27

本站完整兼容 OpenAI 协议的 wire 格式：把官方 SDK 或任意第三方客户端的 base_url 改为 https://api.ai526.com/v1，无需改动其他代码。

Base URL 与鉴权

Base URL：https://api.ai526.com/v1（必须带 /v1）。
鉴权：Authorization: Bearer sk-你的Key；也接受 x-api-key: sk-你的Key，两者等价（同时传且值不同会被拒绝）。
每个响应都带 x-request-id 头，排障凭它定位。

端点	方法	用途
`/v1/models`	GET	列出你的 Key 可用的在架模型
`/v1/chat/completions`	POST	对话补全（主力端点，支持流式 / 工具调用 / 视觉输入 / JSON 模式）
`/v1/responses`	POST	Responses 协议（Codex CLI、OpenClaw `openai-responses` 模式使用）
`/v1/embeddings`	POST	文本向量
`/v1/images/generations`	POST	文生图
`/v1/images/edits`	POST	图片编辑（multipart 表单）
`/v1/audio/speech`	POST	语音合成（TTS）
`/v1/audio/transcriptions`	POST	语音识别（STT，multipart 表单）
`/v1/videos`	POST / GET	视频生成（异步任务：创建 → 轮询 → 下载）

本站是无状态网关：不提供 Files API 与服务端会话存储，凡引用 file_id、previous_response_id 的请求会返回 400；图片 / PDF 请以 URL 或 base64 内联方式传入。

字段	类型	说明
`model`	string，必填	模型 ID，以 /v1/models 返回为准；不存在或未上架返回 404
`messages`	array，必填	支持 system / developer / user / assistant / tool 角色；user 内容支持文本、图片（URL 或 base64 dataURL）、PDF（base64）
`max_completion_tokens`	number	生成上限（含推理 tokens）；旧字段 `max_tokens` 仍兼容，两者同传时以前者为准
`temperature` / `top_p`	number	采样参数，范围 0~2 / 0~1；超范围返回 400
`stream`	boolean	SSE 流式输出
`stream_options`	object	`{"include_usage": true}` 让流末返回真实 usage；仅 stream:true 时可传
`tools` / `tool_choice`	array / mixed	函数工具调用（`type:"function"`）；`tool_choice` 支持 none / auto / required / 指定函数
`response_format`	object	`text` / `json_object` / `json_schema`（结构化输出）
`reasoning_effort`	string	推理力度档位；模型是否支持以模型文档页实测参数为准
`stop`	string \| string[]	停止序列，最多 4 个
`frequency_penalty` / `presence_penalty`	number	-2~2
`seed` / `logprobs` / `logit_bias`	—	接受并尽力透传（取决于承接模型的能力）

限制项（返回 400 的常见情况）：

每个事件一行 data: {JSON}，流以 data: [DONE] 终止；
所有 chunk 的 id、created 相同，object 为 chat.completion.chunk；
工具调用参数按 delta.tool_calls[].index 聚合拼接 arguments 片段（首片带 id / type / name，续片仅 arguments）；
传 stream_options.include_usage:true 时，[DONE] 前会追加一个 choices 为空、带完整 usage 的 chunk，方便客户端核对消耗。

所有 2xx / 429 响应带以下头（RPM 口径，取 Key 限速与分组限速的更严者）：

响应头	说明
`x-ratelimit-limit-requests`	每分钟请求上限
`x-ratelimit-remaining-requests`	当前窗口剩余次数
`x-ratelimit-reset-requests`	窗口重置秒数
`Retry-After`	仅 429 时携带，建议等待秒数

错误统一为 OpenAI 外壳：{"error": {"message", "type", "param", "code"}}。

HTTP	type / code	含义与处置
400	`invalid_request_error`	参数校验失败；按 message 与 param 修正请求
401	`authentication_error` / `invalid_api_key`	Key 缺失、无效、被禁用或已过期
402	`insufficient_quota`	余额不足；前往充值后恢复
403	`permission_error` / `model_not_allowed`	Key 的模型白名单不含该模型
404	`invalid_request_error` / `model_not_found`	模型不存在或未上架
413	`request_too_large`	请求体超限（JSON ≤ 32MB，multipart ≤ 50MB）
429	`rate_limit_error` / `rate_limit_exceeded`	RPM 超限；按 Retry-After 退避重试
429	`rate_limit_error` / `key_quota_exceeded`	该 Key 的额度上限已用尽；调整 Key 额度或换 Key
500	`api_error`	网关内部错误；请附 x-request-id 联系我们
502	`api_error` / `upstream_error`	上游临时故障且自动重试已用尽；稍后重试
503	`api_error` / `no_available_channel`	该模型暂无可用线路；关注服务状态页

失败不扣费

返回 4xx / 5xx 的请求一律不扣费；只有成功响应按真实用量结算。详见计费规则。