用户帮助

本文档面向 API 用户，帮助你快速上手 CodexForge API 服务、了解用量配额和排查常见问题。

最后更新：2026-03-05

快速开始

只需三步即可开始使用 CodexForge API：

获取 API 密钥向管理员获取你的 API Key（格式：sk-xxxx）。

配置客户端将 API 地址和 Key 配置到你的应用中。CodexForge 完全兼容 OpenAI API 格式，大多数 OpenAI SDK 和工具都可以直接使用。

发送第一个请求使用 curl 或任何 HTTP 客户端测试：

curl http://你的服务器地址:8082/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

常见客户端配置

客户端 / 工具	配置方式
OpenAI Python SDK	`openai.base_url = "http://服务器:8082/v1"` `openai.api_key = "sk-你的密钥"`
Cursor / Windsurf	设置中填入 API Base URL 和 Key
ChatGPT-Next-Web	设置 → 自定义 API → 填入地址和密钥
任何 OpenAI 兼容客户端	将 API 地址改为 `http://服务器:8082`，填入 Key 即可

CodexForge 完全兼容 OpenAI API 格式，无需修改代码逻辑，只需更换 API 地址和密钥。

用户门户

用户门户（/user）是你的个人控制台，用 API Key 登录即可查看用量和配额。

信息面板

总请求数 — 你的 Key 累计发送的 API 请求总数
余额 — 当前剩余余额（USD），仅在余额模式下显示
已用 Tokens — 累计消耗的 Token 总数
配额模式 — 当前 Key 的配额计费方式

配额与用量

详细展示各维度的用量和剩余配额，包括：

余额使用进度条
Token 用量（输入/输出分别统计）
重置周期信息（如每日/每月重置）

速率限制

显示当前 Key 的速率限制配置：

RPM（每分钟请求数）限制和当前使用量
RPD（每日请求数）限制和当前使用量
最大并发数限制

每日用量图表

柱状图展示近 30 天的每日 Token 使用趋势，帮助你了解使用规律。

API 使用指南

认证方式

所有 API 请求必须在 HTTP Header 中携带 API Key：

Authorization: Bearer sk-你的密钥

支持的端点

端点	方法	说明
`/v1/chat/completions`	POST	聊天补全（标准 OpenAI 格式），支持流式和非流式
`/v1/responses`	POST	Codex Responses API（OpenAI 新格式）
`/v1/models`	GET	获取可用模型列表

请求格式 — Chat Completions

{
  "model": "gpt-4.1-mini",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "max_tokens": 1000
}

流式响应

设置 "stream": true 即可获得 SSE（Server-Sent Events）流式响应，与 OpenAI 官方格式完全一致。

响应格式

响应格式与 OpenAI 官方 API 完全一致，包括 choices、usage 等字段。你的现有代码无需任何修改。

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "gpt-4.1-mini",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello! How can I help you?"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

可用模型

通过 GET /v1/models 可查询当前可用的模型列表。

curl http://服务器地址:8082/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

管理员可随时调整可用模型。如果你请求的模型不在列表中或被禁止访问，将收到 403 错误。

如果你的 Key 设置了模型白名单或黑名单，/v1/models 返回的是管理员配置的完整模型列表，但实际调用时只能使用白名单中的模型。

配额与限额

每个 API Key 可能有独立的配额限制，用量在每次请求完成后自动扣减。

配额模式

模式	说明	超限行为
none	无限制，不扣费不限量	—
balance	余额模式，按模型定价扣减余额（USD）	余额耗尽返回 429
token_total	总 Token 限额	累计 Token 达上限返回 429
token_io	输入/输出 Token 分别限额	任一维度超限返回 429
hybrid	混合模式（余额 + Token 双限）	任一维度超限返回 429

重置周期

配额用量可能会按周期自动重置：

none — 不重置，用量持续累加直到手动充值
daily — 每日零点（服务器时区）自动清零
monthly — 每月 1 日零点自动清零

你可以在用户门户中查看重置周期和下次重置时间。

速率限制

除了配额（用多少），还可能有速率限制（用多快）：

RPM — 每分钟最大请求数（滑动窗口），超限返回 429
RPD — 每日最大请求数，超限返回 429
最大并发 — 同时处理的请求上限，超限返回 429
单次最大 Token — 单次请求 max_tokens 的上限，超限返回 400

当遇到 429 错误时，请稍等片刻再重试。如果是配额耗尽，请联系管理员充值或等待下一个重置周期。

错误码参考

API 返回标准 JSON 错误格式，与 OpenAI 官方一致：

{"error": {"message": "...", "type": "...", "code": "..."}}

认证与权限错误

HTTP 状态码	error.code	说明	解决方案
401	`missing_api_key`	请求未携带 API Key	在 Header 中添加 `Authorization: Bearer sk-xxx`
401	`invalid_api_key`	API Key 不存在或格式错误	检查 Key 是否正确，联系管理员确认
401	`api_key_expired`	API Key 已过期	联系管理员续期或获取新 Key
403	`api_key_disabled`	API Key 被禁用	联系管理员启用
403	`model_not_allowed`	无权使用该模型	检查模型名称，或联系管理员调整模型白名单

配额与速率错误

HTTP 状态码	error.code	说明	解决方案
429	`quota_exceeded`	配额已用尽（余额/Token）	联系管理员充值，或等待重置周期
429	`rate_limit_rpm`	每分钟请求数超限	降低请求频率，等待 1 分钟
429	`rate_limit_rpd`	每日请求数超限	等待次日重置
429	`concurrent_limit`	并发请求数超限	减少同时请求数，等待进行中的请求完成
400	`max_tokens_exceeded`	单次请求 max_tokens 超限	降低 `max_tokens` 参数值

服务错误

HTTP 状态码	error.code	说明	解决方案
503	`no_available_accounts`	服务暂时不可用	等待片刻后重试，如持续出现请联系管理员
503	`upstream_unavailable`	上游服务不可用	等待片刻后重试

常见问题

Q: 支持哪些编程语言？

CodexForge 兼容 OpenAI API 格式，支持所有语言的 OpenAI SDK，包括 Python、Node.js、Go、Java、Rust 等。也可直接通过 HTTP 请求调用。

Q: 可以用在 Cursor / Windsurf / ChatGPT-Next-Web 等工具中吗？

可以。只要工具支持自定义 OpenAI API 地址（Base URL），就可以使用 CodexForge。在设置中将 API 地址改为 CodexForge 的地址，填入你的 Key 即可。

Q: 流式响应支持吗？

完全支持。设置 "stream": true 即可获得与 OpenAI 完全一致的 SSE 流式响应。

Q: 为什么请求返回 429？

429 表示你触发了某种限制，可能是：

配额用尽（余额为零或 Token 超限）→ 联系管理员充值
速率超限（RPM/RPD）→ 降低请求频率
并发超限 → 减少同时请求数

在用户门户中可以查看当前的配额和速率使用情况。

Q: 为什么请求返回 503？

503 表示服务暂时不可用，通常是因为上游服务临时故障。请等待几秒后重试。如果持续出现，请联系管理员。

Q: 我的余额什么时候会重置？

取决于管理员为你的 Key 设置的重置周期：

none — 不会自动重置，需要管理员手动充值
daily — 每天零点自动恢复到初始额度
monthly — 每月 1 日零点自动恢复

具体设置可在用户门户中查看。

Q: 如何查看我还剩多少额度？

登录用户门户（/user），首页即显示余额、Token 用量和配额进度条。

Q: API 地址是什么？

默认为 http://服务器IP:8082。如果管理员配置了域名和 HTTPS，请使用管理员提供的地址。兼容路径格式：

http://服务器:8082/v1/chat/completions
http://服务器:8082/v1/responses
http://服务器:8082/v1/models

用户帮助

目录

快速开始

常见客户端配置

用户门户

登录

信息面板

配额与用量

速率限制

每日用量图表

最近请求

API 使用指南

认证方式

支持的端点

请求格式 — Chat Completions

流式响应

响应格式

可用模型

配额与限额

配额模式

重置周期

速率限制

错误码参考

认证与权限错误

配额与速率错误

服务错误

常见问题

Q: 支持哪些编程语言？

Q: 可以用在 Cursor / Windsurf / ChatGPT-Next-Web 等工具中吗？

Q: 流式响应支持吗？

Q: 为什么请求返回 429？

Q: 为什么请求返回 503？

Q: 我的余额什么时候会重置？

Q: 如何查看我还剩多少额度？

Q: API 地址是什么？