您需要提前准备的内容
模型可用性
- 由您的访问分组决定：每个 API Key 只能调用其模型访问分组下启用的模型。同一账户下的两个 Key 看到的模型列表可能不同。
- 模型目录是权威来源：
GET /v1/models、/claude/v1/models和/gemini/:version/models返回的正是当前 Key 真正可以调用的模型。不在列表中的即为不可用。 - 单 Key 限制：可以在 Key 的详情面板中进一步限定其可用模型——即使某个模型在您的分组内，对该 Key 仍可能被禁止。
- 任务服务：Midjourney、Suno、RecraftAI、Kling 等能力取决于您的部署是否启用了对应通道。
配额与计费
- 配额不足立即拒绝：在请求到达模型之前会先校验并预扣配额。任一层级（个人、团队或所有者余额）不足时，调用即被拒绝。
- 两阶段结算：请求时预扣，完成后按实际用量结算；失败时回滚预留的配额。
- 配额池相互独立：个人上下文和团队上下文彼此独立。自动化之前请确认您当前所处的空间。
速率限制
速率限制作用于两个维度：按 IP 地址（普通 API 流量、上传和下载各自独立计数，阈值按部署配置）和按账户（由您的访问分组决定——默认分组为每分钟 600 次请求）。超出任一维度都会返回429，并带有 Retry-After 响应头。
无论如何都建议按此设计：
- 在
429时实现指数退避 - 将批量负载分散执行，而非并发峰值式发起
- 在 API 支持的场景下优先使用批量接口
模型中转流量按配额计量，而非由通用 API 限流器管控——对高并发推理而言，真正起作用的限制是您的余额以及上游服务商自身的限制。
协议与入口说明
- OpenAI 兼容
/v1/*：接受 OpenAI 风格的请求体。覆盖面广——chat completions、responses、embeddings、images、audio、moderations、files、batches 等。 - 原生路径：
/claude/v1/messages和/gemini/:version/models/:model保留各服务商自有的协议、字段和模型 ID。请配合官方 Claude/Gemini SDK 使用。 - 任务接口：Midjourney、Suno、RecraftAI 和 Kling 遵循”提交 → 轮询 task id”的异步模式；单次请求不会直接返回最终产物。
- 参数透传：服务商特有参数（reasoning effort、Claude thinking、Gemini 搜索与代码执行）原样透传——请保持官方格式。
较新的 OpenAI 推理模型（
gpt-5 系列、o1/o3/o4）在 Chat Completions 上需要使用 max_completion_tokens 而非 max_tokens。稳定性说明
- 通道健康度：自动重试和通道切换需要至少有一个健康的备选通道；当某个模型的所有通道都不可用时，请求会失败。
- 长时间流式调用：网络错误或超时会导致流关闭——请在客户端实现超时与重连处理。
权限与上下文
- 空间上下文：调用在个人或团队上下文中执行，各自拥有独立的配额池和模型可见范围。
- 角色：管理团队配额、查看团队级用量、调整成员额度取决于您的团队角色——参阅角色与权限。
- 日志可见性：成员可以看到自己的调用记录；团队级日志和统计需要相应权限。
使用前检查清单
- 确认当前空间（个人还是团队）以及余额是否充足
- 通过模型目录端点列出模型，确认目标模型出现在列表中
- 对于任务服务，确认您的部署已启用相应通道
- 在正式流量之前预估用量并预留配额