开放 API

用 API Key 查询余额、额度、用量与模型目录,不需要登录控制台。

除了发起推理,你的 API Key 还能查账。余额、套餐配额、Key 的花费上限、逐次调用明细、模型目录与价格——都可以用同一个 sk-juc- 开头的 Key 直接读取,不需要网页会话。

这些接口全部只读。没有任何一个会改动状态,所以 Key 泄露的代价是暴露用量历史, 而不是丢钱。

两套接口,选哪一套

JuCode 提供两套内容重叠的接口。它们的差别不在功能,在于格式由谁定义。

	原生接口	new-api 兼容接口
路径	`/v1/open/*`	`/api/pricing`、`/dashboard/billing/*`、`/api/usage/token/`
格式定义者	JuCode	new-api / one-api
金额类型	十进制字符串	JSON 数字
单位是否明确	有 `currency` 字段	字段名写着 `usd`,实际是元
适合	新写的集成	已有的查余额工具、价格聚合站

新接入一律用原生接口。 兼容接口存在的唯一理由,是让 JuCode 的 Key 在那些早已写死了 one-api 路径的第三方工具里开箱可用。

兼容接口的 usd 字段装的是元

soft_limit_usd、hard_limit_usd、system_hard_limit_usd 三个字段的单位是元。这个格式里没有货币字段可以说明,而按某个汇率折成美元只会让数字和控制台对不上。所以在第三方工具里看到的 $ 符号是错的,数字本身是对的。

认证

与推理端点完全一致,没有第二套凭证:

curl https://api.jucode.cn/v1/open/balance \
  -H "Authorization: Bearer $JUCODE_API_KEY"

x-api-key 头同样接受。详见认证。

唯一的例外是 GET /api/pricing——它是公开目录, 不需要凭证。

查余额

最常见的用途。原生接口一次返回所有可能让下一个请求被拒的因素:

curl -s https://api.jucode.cn/v1/open/balance \
  -H "Authorization: Bearer $JUCODE_API_KEY" | jq

{
  "currency": "CNY",
  "balance": "128.45000000",
  "lifetime_spend": "71.55000000",
  "plan": { "has_active_plan": false },
  "api_key": {
    "name": "生产环境",
    "prefix": "sk-juc-A1b2C3d4",
    "daily_cost_limit": "50",
    "daily_cost_used": "3.21000000"
  }
}

余额、套餐配额、Key 花费上限存放在三个不同的地方,拆成三个接口只会让每个客户端都调三次再拼起来,所以合并在了一个响应里。

金额是字符串而不是数字。账本精度是 numeric(20,8),用浮点数往返会丢掉在「已花费」和「上限」之间做比较时才会显现的位数。

套餐字段何时缺席

plan.has_active_plan 为 false 时,其余套餐字段一并省略,表示当前按余额计费。配额计数器所在的 Redis 短暂不可用时也会走这个分支——此时余额仍然准确,接口不会整体失败。

兼容工具里的写法

如果你用的是现成的查余额工具,把 base URL 填成 https://api.jucode.cn,它探测的就是这两个路径:

curl -s https://api.jucode.cn/dashboard/billing/subscription \
  -H "Authorization: Bearer $JUCODE_API_KEY"
curl -s https://api.jucode.cn/dashboard/billing/usage \
  -H "Authorization: Bearer $JUCODE_API_KEY"

这一对是设计来做减法的:

剩余 = soft_limit_usd - total_usage / 100

所以 subscription 返回的是「余额 + 历史总消费」,usage 返回的是已消费额(单位分),相减正好落在真实余额上。/v1/dashboard/billing/* 是同一处理逻辑的别名, 两种路径都可用。

查用量

/v1/open/usage 按小时或天分桶,并附一份全窗口汇总:

curl -s "https://api.jucode.cn/v1/open/usage?bucket=day&start=$(date -v-7d +%s)" \
  -H "Authorization: Bearer $JUCODE_API_KEY" | jq .totals

想知道钱花在哪个模型上,换 /v1/open/usage/models;想逐次核对,用 /v1/open/logs。

窗口会被对齐,这是有意的

传入的 start / end 会向下对齐到分桶边界。小时粒度的快速路径只回答正好落在整点的窗口,响应缓存也按窗口做键——一个每次轮询都重新计算的 now - 24h 会同时错过这两者, 把轮询客户端变成对调用日志的反复全表扫描。

结果是同一个 TTL 内的多次轮询会拿到同一个窗口,而不是每次都往前挪几秒。

没有调用的时间段不会出现在 buckets 里,需要连续坐标轴请在客户端补零。查询窗口最长 92 天,超出部分从起点截断。

查模型与价格

两个接口,回答的是不同的问题。

GET /v1/models 按 Key 的允许分组过滤,返回的就是这个凭证实际能调用的模型:

curl -s https://api.jucode.cn/v1/models \
  -H "Authorization: Bearer $JUCODE_API_KEY" \
  | jq '.data[] | {id, context_window, reasoning_efforts}'

context_window、max_output_tokens、reasoning_efforts 是 JuCode 扩展字段。用它们动态适配上下文预算和推理档位,比在客户端硬编码模型能力可靠。

价格字段读哪个

/api/pricing 同时给出两套价格表达,因为它要兼容 new-api 的格式:

model_ratio / completion_ratio 等倍率字段,是 new-api 的约定。按它的惯例渲染 model_ratio × 2 得到的是每 100 万 token 多少元。
jucode_pricing 是绝对价格,单位积分 / 1000 token。

做 JuCode 集成请读 jucode_pricing。 倍率是为兼容而做的换算,输入价为 0 的模型甚至无法用倍率表达输出价。

new-api 本身没有上下文和推理档位字段

context_window、max_output_tokens、reasoning_efforts 是 JuCode 加的。new-api 没有任何逐模型的能力元数据——/api/pricing 里没有,/v1/models 里也没有,它的 Gemini 形态响应里 inputTokenLimit 恒为 null。

未知字段会被客户端忽略,所以加这三个字段不影响兼容性。

限流与缓存

账户与兼容接口的用户级限流是 120 次 / 60 秒,比推理端点的模型列表接口 (240 次 / 60 秒)低一半——余额组件会轮询,而这些查询要在调用日志上做聚合。

超限返回 429,并带 X-RateLimit-Limit 与 X-RateLimit-Remaining 响应头。

聚合类接口带 X-Cache: HIT|MISS 响应头。缓存有效期在数秒到数分钟之间,不构成接口契约,不要依赖它做一致性判断。

错误格式不统一,这是没办法的事

三套接口三种错误体,因为其中两套的格式是别人定的:

接口	认证失败	其他错误
`/v1/open/*`	`401`,`{"error": {...}}` 对象	`500`,`{"error": "字符串"}`
`/api/pricing`	不需要认证	`200`,`{"success": false, ...}`
`/dashboard/billing/*`、`/api/usage/token/`	`401`,`{"error": {...}}` 对象	`200`,`{"error": {...}}`

兼容接口在处理过程中出错时 HTTP 状态码仍然是 200,错误信息在响应体里。这是 new-api 的约定,客户端应判断响应体而不是状态码。只有认证失败才会给出真实的 401。

完整错误码表见错误码。

两套接口,选哪一套

认证

查余额

兼容工具里的写法

查用量

查模型与价格

价格字段读哪个

限流与缓存

错误格式不统一,这是没办法的事

账户接口参考

new-api 兼容接口

模型

On this page