ORBIT API

开发者接入指南

先用固定模拟接口验证接入、状态核对和用量展示。真实模型与正式收费服务尚未开放。

准备账户与密钥

完成邮箱验证、登录并显式开通本人账户。在项目与密钥页创建新密钥时，明确选择公开模拟接口用途。已有密钥不会自动升级。

公开接口使用专用 Bearer 密钥；网页登录会话不能代替它。密钥明文只显示一次，请在自己的服务端安全保存，不要放进网页代码、URL、日志、客服消息或公共仓库。

新账户余额为零，不会自动赠送额度。密钥用途、余额、预算、允许模型和平台执行开关都满足时，才能开始新的模拟调用。

接口与当前能力

方法	路径	用途
`GET`	`/api/public-simulation/v1/models`	读取本密钥可用的固定模拟模型与模拟费率。
`POST`	`/api/public-simulation/v1/generate`	显式提交一次固定 JSON 模拟计量请求。
`GET`	`/api/public-simulation/v1/request?requestId=…`	使用原 requestId 只读核对本人请求，不继续执行。
`POST`	`/api/public-simulation/v1/stream`	独立固定 Mock SSE 协议；不是 OpenAI 流式协议。

SSE 使用严格的独立事件协议。消费端须同时验证事件顺序、请求归属和最终状态；不要把流式文字当作计费凭证。当前网页测试台仍使用 JSON。

JSON 接入模板

以下为 Bash/zsh 模板。请自行安全设置服务 Origin、专用密钥和本次新请求的 UUID 环境变量。模板不会读取本平台页面中的密钥，也不会在浏览器中执行。

认证头通过标准输入传给 curl。不要启用 verbose、trace 或自动重试；也不要把环境变量的值打印到日志。

1. 读取可用模型

printf 'Authorization: Bearer %s\n' "$ORBIT_SIM_API_KEY" | \
  curl --silent --show-error --fail-with-body --max-time 20 \
    --header @- \
    "${ORBIT_SIM_BASE_URL}/api/public-simulation/v1/models"

2. 确认后只提交一次

printf 'Authorization: Bearer %s\n' "$ORBIT_SIM_API_KEY" | \
  curl --silent --show-error --fail-with-body --max-time 20 \
    --header @- --header 'Content-Type: application/json' \
    --data "{\"mode\":\"simulation\",\"requestId\":\"${ORBIT_SIM_REQUEST_ID}\",\"model\":\"sim-general\",\"message\":\"local mock metering\",\"maxOutputTokens\":64,\"scenario\":\"success\"}" \
    "${ORBIT_SIM_BASE_URL}/api/public-simulation/v1/generate"

3. 核对同一个请求

printf 'Authorization: Bearer %s\n' "$ORBIT_SIM_API_KEY" | \
  curl --silent --show-error --fail-with-body --max-time 20 \
    --header @- --get \
    --data-urlencode "requestId=${ORBIT_SIM_REQUEST_ID}" \
    "${ORBIT_SIM_BASE_URL}/api/public-simulation/v1/request"

超时、断开与未知结果

超时、断网、502/503、坏响应或 execution: unknown 后，保留原 requestId，只用 GET 查询。不自动重发 POST，不换 ID 补调用。查询 not_found 也不能证明此前未执行。

running/review 表示已有记录，可能仍有预留；cost/actual 为 null 是待核对，不是零费用。settled/released 按实际返回解释。流式 start、delta、HTTP 200 或结束标记都不能单独证明账务完成。

当前范围

模型为 sim-general / sim-reasoning，币种为 USD_SIM。这里的费率不是商业报价；不会生成真实供应商回答。OpenAI 兼容端点、SDK 完整兼容、工具调用和真实路由仍在开发。

需要帮助

提供原请求 ID 和脱敏错误码即可。客服只能解释公开知识及原四类本人摘要；不能操作钱包、退款、密钥或运行恢复。

进入本人客服