ORBIT API

API 参考文档

本页根据服务端实际执行的请求校验、错误表、限流策略和模型价格表生成,并由自动测试与代码逐项核对。当前开放的是固定模拟接口:只返回模拟内容,币种为 USD_SIM,不是商业报价。

下载 OpenAPI 3.1 规范 · 机器可读的接口规范(JSON),与本页、SDK 和公开入口由同一套契约生成并经测试核对。

认证

所有接口都使用公开模拟用途的专用 API 密钥,通过 HTTP 头传递。

Authorization: Bearer $ORBIT_SIM_API_KEY

密钥以 orb_sim_ 开头,总长 80 个字符,只在创建时显示一次。旧的 48 字符密钥和网页登录 Cookie 不能调用本接口。

密钥只放在你自己的服务端环境变量中。不要写进网页代码、URL、日志、客服消息或代码仓库。本页示例只引用环境变量名,不包含任何真实密钥。

本接口不使用 Cookie 认证;公开入口不会转发 Cookie 和其他自定义请求头,只转发 Authorization 和 Content-Type。

接口

基础路径 /api/public-simulation/v1。GET 请求不能带请求体;POST 请求体必须是 UTF-8 JSON,Content-Type 为 application/json。未列出的字段一律拒绝。

示例从环境变量读取 ORBIT_SIM_BASE_URL(服务 Origin)、ORBIT_SIM_API_KEY(专用密钥)和 ORBIT_SIM_REQUEST_ID(本次请求事先保存好的新 UUID)。示例不自动重试。

方法路径说明
GET/api/public-simulation/v1/models列出可用模型
POST/api/public-simulation/v1/generate提交模拟调用
GET/api/public-simulation/v1/request查询请求结果
POST/api/public-simulation/v1/stream流式模拟调用

GET /api/public-simulation/v1/models

列出可用模型 返回本密钥允许使用的模型及模拟费率。

响应 内容类型: application/json

字段类型必填约束说明
modeliteral是取值: simulation固定为 simulation。
modelsarray是最多条数: 2模型列表。
models[]object是一个模型。
models[].idenum是取值: sim-general | sim-reasoning模型 ID。
models[].priceVersionenum是取值: sim-general-v1 | sim-reasoning-v1当前价格版本。
models[].inputMicroPerMillionstring是非负整数字符串每百万输入 token 价格(百万分之一 USD_SIM)。
models[].cachedMicroPerMillionstring是非负整数字符串每百万缓存输入 token 价格(百万分之一 USD_SIM)。
models[].outputMicroPerMillionstring是非负整数字符串每百万输出 token 价格(百万分之一 USD_SIM)。

请求示例

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"

响应示例

{
  "mode": "simulation",
  "models": [
    {
      "id": "sim-general",
      "priceVersion": "sim-general-v1",
      "inputMicroPerMillion": "2000000",
      "cachedMicroPerMillion": "500000",
      "outputMicroPerMillion": "8000000"
    }
  ]
}

POST /api/public-simulation/v1/generate

提交模拟调用 提交一次 JSON 模拟调用并同步返回计费记录。requestId 是幂等键:请在发送前生成并保存。

请求体

字段类型必填约束说明
modeliteral是取值: simulation固定为 simulation。
requestIdstring是UUID(小写,版本 1–8)调用方生成的请求 UUID,同时是幂等键。
modelenum是取值: sim-general | sim-reasoning模型 ID,且必须在密钥允许的模型范围内。
messagestring是长度: 1–500输入消息,去掉首尾空白后计算长度。
maxOutputTokensinteger是范围: 1–256本次最多输出的 token 数,也决定预留金额。
scenarioenum是取值: success | upstream_error | timeout_unknown | missing_usage | overusage模拟情景,用来演练成功、上游错误、超时未知、用量缺失、超额等结果(stream_disconnect 仅流式可用)。

响应 内容类型: application/json

字段类型必填约束说明
modeliteral是取值: simulation固定为 simulation。
replayedboolean是true 表示同一 requestId 的原记录被重放,没有再次执行。
recordobject是请求的计费记录。
record.idstring是UUID(小写,版本 1–8)调用记录 ID。
record.requestIdstring是UUID(小写,版本 1–8)原请求 ID。
record.keyIdstring是UUID(小写,版本 1–8)发起请求的密钥 ID。
record.usageIdstring是UUID(小写,版本 1–8)对应的用量记录 ID。
record.modelenum是取值: sim-general | sim-reasoning使用的模型。
record.priceVersionenum是取值: sim-general-v1 | sim-reasoning-v1计费时使用的价格版本。
record.maxOutputTokensinteger是范围: 1–256请求中的 maxOutputTokens。
record.stateenum是取值: running | settled | released | reviewrunning 执行中;settled 已结算;released 已释放未收费;review 待人工核对。
record.reasonenum是取值: provider_pending | metered | confirmed_not_executed | usage_unknown | usage_exceeds_contract状态原因:provider_pending、metered、confirmed_not_executed、usage_unknown、usage_exceeds_contract。
record.meterobject是可为 null实际计量的 token 数;未知时为 null。
record.meter.inputinteger是范围: 0–1000000输入 token 数(含缓存命中)。
record.meter.cachedinteger是范围: 0–1000000命中缓存的输入 token 数,不超过 input。
record.meter.outputinteger是范围: 0–1000000输出 token 数。
record.coststring是非负整数字符串 · 可为 null按价格版本计算的费用(百万分之一 USD_SIM);未结算时为 null。
record.reservedstring是非负整数字符串提交时预留的金额(百万分之一 USD_SIM)。
record.actualstring是非负整数字符串 · 可为 null实际扣费(百万分之一 USD_SIM);未结算时为 null,不代表零。
record.usageStateenum是取值: held | settled | released预留状态:held 仍在预留;settled 已扣费;released 已释放。
record.createdAtstring是ISO 8601 时间(UTC) · 长度: 0–32记录创建时间。
record.updatedAtstring是ISO 8601 时间(UTC) · 长度: 0–32记录最后更新时间。
record.transportenum是取值: json | streamjson 或 stream,表示通过哪个接口提交。
record.streamStatusenum是取值: finished | client_cancelled | upstream_interrupted | usage_missing | deadline_exceeded | protocol_error · 可为 null流式结束状态;JSON 请求为 null。

请求示例

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"

响应示例

{
  "mode": "simulation",
  "replayed": false,
  "record": {
    "id": "22222222-2222-4222-8222-222222222222",
    "requestId": "11111111-1111-4111-8111-111111111111",
    "keyId": "33333333-3333-4333-8333-333333333333",
    "usageId": "44444444-4444-4444-8444-444444444444",
    "model": "sim-general",
    "priceVersion": "sim-general-v1",
    "maxOutputTokens": 64,
    "state": "settled",
    "reason": "metered",
    "meter": {
      "input": 300,
      "cached": 64,
      "output": 64
    },
    "cost": "1016",
    "reserved": "1536",
    "actual": "1016",
    "usageState": "settled",
    "createdAt": "2026-11-09T00:00:00.000Z",
    "updatedAt": "2026-11-09T00:00:01.000Z",
    "transport": "json",
    "streamStatus": null
  }
}

GET /api/public-simulation/v1/request

查询请求结果 用原 requestId 只读查询本密钥的请求记录,不会继续执行或重试。

查询参数

字段类型必填约束说明
requestIdstring是UUID(小写,版本 1–8)调用方生成的请求 UUID,同时是幂等键。

响应 内容类型: application/json

当 state=not_found

字段类型必填约束说明
modeliteral是取值: simulation固定为 simulation。
stateliteral是取值: not_foundfound 找到记录;not_found 没有找到(不能证明未执行)。

当 state=found

字段类型必填约束说明
modeliteral是取值: simulation固定为 simulation。
stateliteral是取值: foundfound 找到记录;not_found 没有找到(不能证明未执行)。
recordobject是请求的计费记录。
record.idstring是UUID(小写,版本 1–8)调用记录 ID。
record.requestIdstring是UUID(小写,版本 1–8)原请求 ID。
record.keyIdstring是UUID(小写,版本 1–8)发起请求的密钥 ID。
record.usageIdstring是UUID(小写,版本 1–8)对应的用量记录 ID。
record.modelenum是取值: sim-general | sim-reasoning使用的模型。
record.priceVersionenum是取值: sim-general-v1 | sim-reasoning-v1计费时使用的价格版本。
record.maxOutputTokensinteger是范围: 1–256请求中的 maxOutputTokens。
record.stateenum是取值: running | settled | released | reviewrunning 执行中;settled 已结算;released 已释放未收费;review 待人工核对。
record.reasonenum是取值: provider_pending | metered | confirmed_not_executed | usage_unknown | usage_exceeds_contract状态原因:provider_pending、metered、confirmed_not_executed、usage_unknown、usage_exceeds_contract。
record.meterobject是可为 null实际计量的 token 数;未知时为 null。
record.meter.inputinteger是范围: 0–1000000输入 token 数(含缓存命中)。
record.meter.cachedinteger是范围: 0–1000000命中缓存的输入 token 数,不超过 input。
record.meter.outputinteger是范围: 0–1000000输出 token 数。
record.coststring是非负整数字符串 · 可为 null按价格版本计算的费用(百万分之一 USD_SIM);未结算时为 null。
record.reservedstring是非负整数字符串提交时预留的金额(百万分之一 USD_SIM)。
record.actualstring是非负整数字符串 · 可为 null实际扣费(百万分之一 USD_SIM);未结算时为 null,不代表零。
record.usageStateenum是取值: held | settled | released预留状态:held 仍在预留;settled 已扣费;released 已释放。
record.createdAtstring是ISO 8601 时间(UTC) · 长度: 0–32记录创建时间。
record.updatedAtstring是ISO 8601 时间(UTC) · 长度: 0–32记录最后更新时间。
record.transportenum是取值: json | streamjson 或 stream,表示通过哪个接口提交。
record.streamStatusenum是取值: finished | client_cancelled | upstream_interrupted | usage_missing | deadline_exceeded | protocol_error · 可为 null流式结束状态;JSON 请求为 null。

请求示例

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"

响应示例

{
  "mode": "simulation",
  "state": "not_found"
}

POST /api/public-simulation/v1/stream

流式模拟调用 与 generate 相同的计费规则,以固定 Mock SSE 协议返回。不是 OpenAI 流式协议。

请求体

字段类型必填约束说明
modeliteral是取值: simulation固定为 simulation。
requestIdstring是UUID(小写,版本 1–8)调用方生成的请求 UUID,同时是幂等键。
modelenum是取值: sim-general | sim-reasoning模型 ID,且必须在密钥允许的模型范围内。
messagestring是长度: 1–500输入消息,去掉首尾空白后计算长度。
maxOutputTokensinteger是范围: 1–256本次最多输出的 token 数,也决定预留金额。
scenarioenum是取值: success | upstream_error | timeout_unknown | missing_usage | overusage | stream_disconnect模拟情景,用来演练成功、上游错误、超时未知、用量缺失、超额等结果(stream_disconnect 仅流式可用)。

响应 内容类型: text/event-stream

当 type=start

字段类型必填约束说明
typeliteral是取值: start帧类型。
modeliteral是取值: simulation固定为 simulation。
requestIdstring是UUID(小写,版本 1–8)调用方生成的请求 UUID,同时是幂等键。
generationIdstring是UUID(小写,版本 1–8)本次调用记录 ID。
keyIdstring是UUID(小写,版本 1–8)发起请求的密钥 ID。
modelenum是取值: sim-general | sim-reasoning模型 ID,且必须在密钥允许的模型范围内。
maxOutputTokensinteger是范围: 1–256本次最多输出的 token 数,也决定预留金额。

当 type=delta

字段类型必填约束说明
typeliteral是取值: delta帧类型。
modeliteral是取值: simulation固定为 simulation。
textstring是长度: 1–4096一段模拟输出文字。

当 type=fault

字段类型必填约束说明
typeliteral是取值: fault帧类型。
modeliteral是取值: simulation固定为 simulation。
codeenum是取值: STREAM_CANCELLED | STREAM_INTERRUPTED | STREAM_USAGE_MISSING | STREAM_DEADLINE | STREAM_PROTOCOL | STREAM_UNAVAILABLE流式错误码,见下表。

当 type=result

字段类型必填约束说明
typeliteral是取值: result帧类型。
modeliteral是取值: simulation固定为 simulation。
recordobject是请求的计费记录。
record.idstring是UUID(小写,版本 1–8)调用记录 ID。
record.requestIdstring是UUID(小写,版本 1–8)原请求 ID。
record.keyIdstring是UUID(小写,版本 1–8)发起请求的密钥 ID。
record.usageIdstring是UUID(小写,版本 1–8)对应的用量记录 ID。
record.modelenum是取值: sim-general | sim-reasoning使用的模型。
record.priceVersionenum是取值: sim-general-v1 | sim-reasoning-v1计费时使用的价格版本。
record.maxOutputTokensinteger是范围: 1–256请求中的 maxOutputTokens。
record.stateenum是取值: running | settled | released | reviewrunning 执行中;settled 已结算;released 已释放未收费;review 待人工核对。
record.reasonenum是取值: provider_pending | metered | confirmed_not_executed | usage_unknown | usage_exceeds_contract状态原因:provider_pending、metered、confirmed_not_executed、usage_unknown、usage_exceeds_contract。
record.meterobject是可为 null实际计量的 token 数;未知时为 null。
record.meter.inputinteger是范围: 0–1000000输入 token 数(含缓存命中)。
record.meter.cachedinteger是范围: 0–1000000命中缓存的输入 token 数,不超过 input。
record.meter.outputinteger是范围: 0–1000000输出 token 数。
record.coststring是非负整数字符串 · 可为 null按价格版本计算的费用(百万分之一 USD_SIM);未结算时为 null。
record.reservedstring是非负整数字符串提交时预留的金额(百万分之一 USD_SIM)。
record.actualstring是非负整数字符串 · 可为 null实际扣费(百万分之一 USD_SIM);未结算时为 null,不代表零。
record.usageStateenum是取值: held | settled | released预留状态:held 仍在预留;settled 已扣费;released 已释放。
record.createdAtstring是ISO 8601 时间(UTC) · 长度: 0–32记录创建时间。
record.updatedAtstring是ISO 8601 时间(UTC) · 长度: 0–32记录最后更新时间。
record.transportenum是取值: json | streamjson 或 stream,表示通过哪个接口提交。
record.streamStatusenum是取值: finished | client_cancelled | upstream_interrupted | usage_missing | deadline_exceeded | protocol_error · 可为 null流式结束状态;JSON 请求为 null。

当 type=end

字段类型必填约束说明
typeliteral是取值: end帧类型。
modeliteral是取值: simulation固定为 simulation。
generationIdstring是UUID(小写,版本 1–8)本次调用记录 ID。

请求示例

printf 'Authorization: Bearer %s\n' "$ORBIT_SIM_API_KEY" | \
  curl --silent --show-error --fail-with-body --no-buffer --max-time 60 \
    --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/stream"

错误码

出错时返回 JSON 错误体,HTTP 状态码见下表。按 code 处理,不要按错误文字处理。

错误体格式

{
  "error": {
    "code": "PUBLIC_SIMULATION_RATE_LIMITED",
    "execution": "not_started"
  }
}

execution 为 not_started 表示服务端确认这次请求没有开始执行;为 unknown 表示无法确认,可能已经预留或计费。unknown 时保留原 requestId,只用 GET /request 核对,不要换新 ID 重发。

错误码HTTP 状态含义建议处理
PUBLIC_SIMULATION_INVALID接口层400 / 405 / 413 / 415请求格式不对:路径参数、查询参数、请求体、方法(405)、大小(413)或 Content-Type(415)不符合要求。按本页修正请求后再发送。
PUBLIC_SIMULATION_UNAUTHENTICATED接口层401缺少密钥、密钥格式不对、已撤销、已过期或已暂停。检查 Authorization 头和密钥状态。
PUBLIC_SIMULATION_FORBIDDEN接口层403请求来源不被允许(例如跨站浏览器请求)。从你自己的服务端调用,不要在浏览器里直接调用。
PUBLIC_SIMULATION_NOT_FOUND接口层404接口路径不存在。检查路径和版本号。
PUBLIC_SIMULATION_RATE_LIMITED接口层429超过每密钥或平台的请求频率限制。等待 Retry-After 秒后再发送新请求。
PUBLIC_SIMULATION_UNAVAILABLE接口层502 / 503服务暂时不可用或响应无法确认。保留 requestId,用 GET /request 核对,不要直接重发。
SIMULATION_INVALID账户与计费层400计费层拒绝了请求内容。检查请求字段。
SIMULATION_NOT_FOUND账户与计费层404账户或相关记录不存在。确认账户已开通。
SIMULATION_KEY_INVALID账户与计费层403密钥在计费层无效。在控制台检查密钥。
SIMULATION_KEY_FORBIDDEN账户与计费层403密钥没有公开接口用途或状态不允许。创建公开模拟接口用途的新密钥。
SIMULATION_MODEL_NOT_ALLOWED账户与计费层403该密钥不允许使用此模型。换用允许的模型,或调整密钥设置。
SIMULATION_INSUFFICIENT_BALANCE账户与计费层409可用余额不足以预留本次费用。降低 maxOutputTokens 或补充余额。
SIMULATION_ACCOUNT_FROZEN账户与计费层409账户已冻结。联系客服。
SIMULATION_KEY_BUDGET账户与计费层409超过密钥预算上限。调整密钥预算或换用其他密钥。
SIMULATION_IDEMPOTENCY_CONFLICT账户与计费层409同一 requestId 已用于不同的请求内容。新请求请用新的 requestId;核对旧请求用 GET /request。
SIMULATION_CAPACITY账户与计费层409账户同时进行中的调用过多。等待进行中的调用结束后再提交。
SIMULATION_QUOTA账户与计费层429超过并发数、每分钟请求数或每分钟 token 上限。上限可能来自平台对账户或密钥的设置,也可能来自你自己为密钥或项目设置的更严限额。错误体只有 code 和 execution,不区分是哪一层限制。等待 Retry-After 秒后再提交新请求;在限流设置页可以查看自己设的限额和最近 24 小时的限流命中。

下列服务端内部错误不会原样返回给调用方,公开入口统一返回 502 PUBLIC_SIMULATION_UNAVAILABLE(execution 为 unknown):平台暂停新执行、记录一致性检查失败、计费层不可用。按未知结果处理。

限流与大小限制

下列数值直接来自服务端固定策略,调用方不能修改。

被限流时响应带 Retry-After 头(秒)。窗口按整分钟对齐,请等待该秒数后再发送新的请求;对原请求的核对请用 GET /request。

你可以为单个密钥或项目设置更严的每分钟请求数、每分钟 token 数和并发数;这些限额不能超过平台上限,触发时同样返回 429 SIMULATION_QUOTA。 前往限流设置

模型与价格

价格取自计费使用的同一份售价表。每次请求记录当时的价格版本。

单位:USD_SIM / 每百万 token

模型价格版本输入缓存输入输出
sim-generalsim-general-v12.000.508.00
sim-reasoningsim-reasoning-v18.002.0024.00

查看完整模型目录

流式协议

POST /stream 返回 text/event-stream,每帧是一行 data: 加 JSON,帧之间空一行,不使用 event/id/retry 字段。顺序为 start → delta(0 到多次)→ fault(可选)→ result → end。只有收到 result 且随后收到 end,才能把 result 中的记录当作最终结果;同一 requestId 重放时返回 JSON 回执。

fault 帧错误码

错误码含义
STREAM_CANCELLED客户端取消了流。
STREAM_INTERRUPTED上游中断。
STREAM_USAGE_MISSING没有拿到用量,进入核对。
STREAM_DEADLINE超过流式时限。
STREAM_PROTOCOL流协议错误。
STREAM_UNAVAILABLE流式服务暂时不可用。

超时与未知结果

超时、断网、502/503、响应格式不对或 execution 为 unknown 时:保留原 requestId,只用 GET /request 查询;不要自动重发 POST,也不要换 ID 补调用。用同一 requestId 和完全相同的请求体再次 POST 会得到原记录(replayed 为 true),请求体不同则返回 409 SIMULATION_IDEMPOTENCY_CONFLICT。查询结果 not_found 不能证明此前没有执行。cost 或 actual 为 null 表示待核对,不是零费用。

当前范围

目前只有 sim-general 和 sim-reasoning 两个固定模拟模型。OpenAI 兼容端点、工具调用、结构化输出和真实模型路由仍在开发中,开放后会在本页更新。