从 API Key 到第一次调用

获取 API 配置

登录行星AI 控制台后，完成充值或获得可用额度，再创建一个专用 API Key。不同应用建议使用不同 Key，便于单独停用和查看用量。

Base URL: https://api.starcloudapi.cn/v1
Authorization: Bearer sk-your-planet-ai-key

选择模型名称

请求中的 model 必须与行星AI 模型目录中的 ID 完全一致。模型列表可能随渠道和账号权限变化，文档示例只用于说明字段位置。

图像理解

使用支持图片输入的模型时，在请求中将图片作为消息内容的一部分传入。客户端若提供“图片输入”开关，请先启用后再测试。

curl https://api.starcloudapi.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-your-planet-ai-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从模型目录复制的 ID",
    "messages": [{"role":"user","content":[
      {"type":"text","text":"请描述这张图片"},
      {"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}
    ]}]
  }'

WorkBuddy / CodeBuddy

在设置中的“自定义模型”或“自定义 API”入口添加服务。协议选择 OpenAI 兼容，接口地址填写完整的 Base URL，模型字段填写模型目录中的 ID。

VS Code / Kilo Code

在扩展的 Provider、Custom API 或 OpenAI Compatible 配置中填写三项：API 地址、API Key、模型 ID。设置完成后先发送一条短消息，确认返回正常再开始长任务。

Claude

选择自定义 Anthropic Messages 或 OpenAI 兼容模式，具体以客户端版本提供的协议选项为准。若使用 Anthropic 原生协议，请按照客户端提示填写对应 Endpoint；若只支持 OpenAI 兼容，则使用行星AI 的 Chat Completions 接口。

配置完成后先执行一次“测试连接”。

Zcode

进入模型设置，新增自定义供应商。Base URL 填写 https://api.starcloudapi.cn/v1，API Key 填写用户 Key，模型列表添加当前开放的模型 ID。不要把上游账号密钥填入这里。

Trae

在模型管理中新增自定义模型，协议选择 OpenAI Compatible。部分版本会将地址字段命名为 Custom API URL 或 Endpoint，遇到自动追加路径时，关闭“完整 URL”选项并只填写 Base URL。

Codex：推荐一键导入 CCS

推荐通过 CCS 导入行星AI 的 Codex 供应商配置。这样可以减少手工填写地址、协议和模型时的错误，也便于以后在不同供应商之间切换。

9.1 准备工作

• 先安装并启动 Codex，运行 codex --version 能看到版本号。
• 安装并打开支持 ccswitch:// 导入链接的 CCS 客户端。
• 登录行星AI，确认账号有余额，并创建一个专门给 Codex 使用的 API Key。

9.2 从 API 密钥页一键导入

9.3 CCS 手工配置（备用）

如果浏览器没有拉起 CCS，可以在 CCS 中创建 Codex 自定义供应商。手工填写时使用下面的行星AI 配置：

9.4 不使用 CCS：手工配置 Codex

更稳妥的备用方式，是先在 API 密钥页点击“使用密钥”，直接复制控制台生成的 Codex 配置。若需要手工创建文件，macOS / Linux 放在 ~/.codex/，Windows 放在 %USERPROFILE%\.codex\。

model_provider = "starcloud"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"

[model_providers.starcloud]
name = "行星AI"
base_url = "https://api.starcloudapi.cn/v1"
wire_api = "responses"
requires_openai_auth = true

[features]
goals = true

{
  "OPENAI_API_KEY": "sk-your-planet-ai-key"
}

把示例 Key 替换成自己的完整 Key；模型 ID 如已调整，则以模型与价格页面和控制台生成配置为准。不要把 auth.json、真实 Key 或包含 Key 的截图提交到代码仓库。

9.5 重启与验证

1. 保存配置，确认 CCS 中已经启用行星AI。
2. 完全退出 Codex 后重新打开，再新建一个任务。
3. 在 Codex 中输入 /model，检查当前模型；然后发送一条简短请求测试。
4. 确认回复正常后，再开始长时间或高消耗任务。

9.6 Codex 常见问题

Kimi CLI

编辑本地配置文件时，选择 OpenAI 兼容协议，填写 Base URL、API Key 和模型 ID。Windows、macOS、Linux 的配置文件位置可能不同，请以客户端设置页显示的路径为准。

其他客户端与 Agent

只要客户端支持 OpenAI Compatible，通常都可以接入行星AI。通用配置顺序是：选择自定义服务 → 填写 Base URL → 填写用户 Key → 添加模型 ID → 发送短请求测试。

本地路由与中转

本地路由工具只负责把客户端请求转发到行星AI，不会替代平台鉴权。启用前确认本地端口没有被其他程序占用，并在客户端填写路由工具显示的地址。

异常排查

仍未解决时，请提供：请求时间、HTTP 状态码、Request ID、使用的模型 ID 和脱敏后的请求地址。不要发送 API Key。