YUNLU / GETTING STARTED

从账户到第一次调用。

云路 API 使用指南

GPT 与 Claude 已接入

已验证 GPT 5.6 Sol、Terra、Luna,GPT 6.0 Astra、Sol、Luna 与 GPT 6.1 Sol。请求中分别使用 gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-6-luna、gpt-6-sol、gpt-6-astra、gpt-6.1-sol。Claude 模型包括 claude-opus-5-5、claude-opus-5 与 claude-sonnet-5;调用前请核对模型权限、价格和余额。

01

注册与登录

  1. 新用户进入注册页面,填写邮箱并获取验证码,再按提示创建账户。注册验证码与密码找回链接有效期均为 10 分钟。
  2. 已有账户进入登录页面。使用你注册时的登录方式;验证码或其他验证要求以页面提示为准。
  3. 登录后进入控制台,确认当前账户,再进行余额和密钥操作。
02

月套餐、余额与兑换码

打开钱包,查看实际开放的站内月套餐、账户余额、充值方式和交易记录。套餐价格、额度、有效期、用量重置规则及支付方式以页面展示为准。平台套餐用于本站调用,与上游账号自己的订阅分开管理。

选择可用月套餐

如果页面已上架月套餐,先核对适用分组、额度、有效期和重置规则,再按实际开放的支付方式购买。购买后检查套餐是否生效。

套餐额度与钱包余额的使用顺序,以控制台设置为准。

在线充值与兑换码

  1. 在钱包选择充值额度与 Stripe,核对美元额度、人民币实付金额及可获赠金。
  2. 进入 Stripe 收银台,选择实际显示的银行卡、Apple Pay 或 Google Pay 完成付款。
  3. 支付结果核验成功后自动到账,返回钱包核对余额与订单记录;付款后暂未到账时,请保留订单号联系支持,避免重复付款。

Apple Pay 和 Google Pay 按设备、浏览器及钱包资格显示。支付宝正在审核,微信支付暂未接入。有有效兑换码时,仍可在钱包填写并兑换。

新用户注册后 48 小时内首次确认成功的充值,按档位赠金,每账号一次;以已核验的付款记录及活动规则为准。

调用前先确认模型和计费

有套餐或余额并不代表所有模型都可调用。请按实际开放的模型、套餐和充值方式购买,自动支付开通情况以钱包为准。不要将兑换码或支付凭据填入 API 密钥字段。

打开套餐与余额
03

创建 API 密钥

  1. 进入API 密钥页面,创建一个用于当前应用的密钥,并设置便于识别的名称。
  2. 按实际需要设置额度、有效期、模型范围等限制;可用选项以控制台为准。
  3. 保存创建结果中的密钥,在应用或服务端环境变量中使用。不同应用建议使用独立密钥。
  4. 测试完成后到用量日志核对调用记录。发现泄露时,立即在密钥页面禁用或删除该密钥并重新创建。
密钥只用于你的应用

不要将真实密钥写入公开网页、浏览器前端代码、截图或代码仓库。以下示例使用占位符,门户不会要求输入或保存你的密钥。

前往密钥管理
04

按模型协议配置工具

OpenAI API 中转接入 · Claude API 中转接入 · Cherry Studio API 配置教程

GPT 模型支持 Responses 接口与 OpenAI 兼容聊天接口;Claude 模型支持 Anthropic Messages 与兼容聊天接口。请使用支持对应协议、自定义 Base URL 和 API 密钥的客户端。请先在控制台确认模型权限;普通文字聊天也可使用 Chat Completions,由网关转换为 Responses;网页游乐场支持流式与普通回复。工具、附件等扩展功能请先确认兼容性。

SDK BASE URLhttps://api.yunluapi.com/v1
Responses 客户端连接字段
字段填写内容
Base URLhttps://api.yunluapi.com/v1
API Key你在云路 API 控制台创建的密钥
Model控制台实际启用的模型名称,区分大小写并保持完整
接口类型Codex 服务选 Responses,最终请求路径为 /v1/responses

部分客户端要求填写域名根地址,并自行添加 /v1。遇到这种情况,按客户端说明填写 https://api.yunluapi.com,检查最终请求路径。客户端填平台密钥,无需登录或选择池内的上游账号。Anthropic SDK 的根地址填 https://api.yunluapi.com,最终请求路径为 /v1/messages;OpenAI 兼容聊天路径为 /v1/chat/completions。不要让 SDK 重复拼接 /v1。

05

发送一次 Responses 测试请求

先将密钥设为本机环境变量 YUNLU_API_KEY,再把 YOUR_AVAILABLE_MODEL 替换为控制台确认可用的模型名称。以下使用流式 Responses,可先用 gpt-6-luna 发起一次小请求,核对返回结果与消费日志。

curl -N https://api.yunluapi.com/v1/responses \
  -H "Authorization: Bearer $YUNLU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AVAILABLE_MODEL",
    "instructions": "You are a helpful coding assistant.",
    "input": [{"role": "user", "content": "请用一句话解释 Python 列表推导式。"}],
    "store": false,
    "stream": true
  }'

适用于 macOS / Linux shell;Windows 可使用 Bash 或参考对应终端的语法。

流式输出结束后,到用量日志核对模型、输入输出用量,以及套餐消耗或余额扣费。出现 response.failed 或错误事件时,不能仅凭收到 HTTP 200 判断请求成功。SDK 流式事件说明可参考 OpenAI 官方文档。

06

排查调用问题

鉴权失败 / 401
检查是否填写云路 API 密钥,是否有多余空格,以及密钥是否已失效或被禁用。登录密码、兑换码不能用作 API Key。
余额或额度不足
查看账户余额和当前密钥额度。充值成功后再次核对到账记录;密钥的独立限额也可能阻止调用。
模型或渠道不可用
确认完整模型名称、密钥权限和渠道启用状态。若模型权限正确仍不可用,请让管理员检查账号授权、上游额度与渠道状态。
路径错误 / 404
检查是否重复拼接 /v1,并确认客户端选择了正确的接口类型。
请求过多 / 429 或超时
查看调用日志,适当降低并发,按提示等待后重试。避免立即无限重试;向管理员反馈时间、模型和错误信息时隐藏密钥。
07

用户与原生账号池的分工

客户选择本站实际开放的月套餐或余额方式,创建平台密钥,再让工具调用统一网关。New API 根据分组、模型和可用渠道选择一个上游账号或 API 渠道;上游返回结果后,平台记录请求并结算用量。客户无需导入或共享上游账号。

管理员说明

管理员在 New API 的渠道管理维护账号池。GPT 订阅账号选择 ChatGPT Subscription (Codex) 类型,每账号一个渠道;通过获授权的 OAuth JSON 配置,核对模型、分组、优先级与权重,再测试 Responses 调用。已开放模型及客户端接入方式请以模型广场和当前控制台为准。

每个平台按至少 10 个上游账号规划,并支持继续增加渠道;这是容量规划,实际已接入数量以后台为准。多个账号可参与请求分配,但优先级、权重、限额和渠道状态会影响结果,不保证请求数相等或持续无限可用。

账号 OAuth 凭据、刷新令牌和上游 API 密钥仅供管理员在受保护的后台使用,不能发给客户、写入门户或公开仓库。当前 GPT 与 Claude 渠道已接入并有调用验收记录。增加账号时,继续采用每账号一个渠道,并单独完成测试后启用。