常见问题

API Key 到底要不要加后缀

不要加。Portdan / Sub2 后端用收到的 Key 字符串做精确匹配；控制台显示什么，客户端就填什么。

错误示例：

sk-your-api-key#claude
sk-your-api-key#gemini
sk-your-api-key:openai
sk-your-api-key/v1
sk-your-api-key 后面多一个空格

正确示例：

sk-your-api-key

协议选择由两个因素决定：你请求的路径，以及这个 Key 绑定的分组平台。不是由 Key 后缀决定。

Base URL 到底填哪个

按客户端类型填写：

场景	填写值
OpenAI Compatible 客户端 / OpenAI SDK	https://portdan.com/v1
Claude Code / Anthropic SDK	https://portdan.com
Gemini CLI	https://portdan.com
Gemini 直接 HTTP / OpenCode Gemini	https://portdan.com/v1beta
Codex / CC Switch 导入	https://portdan.com
Antigravity Claude / Gemini CLI	https://portdan.com/antigravity

只有当工具明确写着「OpenAI Base URL」时才填 https://portdan.com/v1。工具写「根地址」「Host」「Endpoint」并由工具自行拼路径时，通常填 https://portdan.com 或对应的协议根地址。

为什么返回 401

401 是鉴权失败。检查：

• API Key 是否完整且没有任何后缀。
• 请求头是否为 Authorization: Bearer <API_KEY>，或客户端要求的等价 Key 字段。
• API Key 是否过期、删除或属于其他账号。
• 复制时是否多了空格、换行、中文引号。
• 主 /v1 接口不要把 Key 放到 URL query 里。

为什么返回 404

常见原因：

• Base URL 填错。
• 把完整接口地址填进了 Base URL。
• 模型名不存在。
• 当前 Key 的分组平台不支持该接口。例如非 OpenAI 分组调用 /embeddings 会返回不支持。
• 客户端拼接路径异常。

OpenAI Compatible 正确 Base URL：

https://portdan.com/v1

不要填成：

https://portdan.com/v1/chat/completions

为什么模型列表正常但聊天失败

可能原因：

• 目标模型暂时不可用。
• 令牌分组有模型列表权限，但没有调用额度。
• 请求参数使用了模型不支持的能力。
• 输入太长。
• 客户端缓存了旧模型名。
• 用了错误协议。例如 Gemini 原生客户端应走 /v1beta，不是 OpenAI Chat Completions。

Gemini 能不能用 query 参数传 Key

Gemini 原生路径 /v1beta 和 /antigravity/v1beta 兼容 ?key=<API_KEY>，但更推荐使用请求头：

x-goog-api-key: <API_KEY>

不要使用 api_key query 参数；它会被拒绝。

为什么扣费比预期高

检查是否出现这些情况：

• 客户端自动带入了大量历史消息。
• Agent 工具调用循环重试。
• 服务端没有限制最大重试次数。
• 使用了高价模型处理简单任务。
• 长文档未切块，整篇重复发送。

API Key 泄露怎么办

立即进入控制台删除该令牌，并创建新令牌。不要尝试继续使用已泄露的 Key。

支持哪些模型

以控制台模型列表为准。你也可以调用：

curl https://portdan.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

怎么联系客服

• Telegram：TODO: 填写 Telegram 支持群链接
• 公告频道：TODO: 填写公告频道链接
• Email：TODO: 填写客服邮箱或工单入口

提交问题时请带上客户端名称、协议类型、Base URL、模型名、请求时间、错误码和错误信息。不要提供完整 API Key。