V1 API 通用约定

V1 开放 API 的鉴权、计费、公共对象与错误响应格式

本文说明 V1 开放 API（/v1/*）的鉴权、计费、公共对象与错误响应格式。

适用范围：对外开放的 /v1 Relay 接口，共 12 条。

通用约定

Base URL

https://www.yunsell.com

接口直接挂载在域名根路径，例如 POST https://www.yunsell.com/v1/chat/completions。

鉴权

全部 /v1 公开接口统一使用 Bearer Token：

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

规则	说明
令牌校验	校验 API Key 有效性、用户状态、余额/配额
IP 白名单	若令牌配置了 IP 白名单，则校验请求来源
指定渠道	管理员可在 Key 后追加 `-{channelId}`（如 `sk-xxx-6`）；普通用户禁止
鉴权失败	返回 HTTP `401` / `403`

例外：GET /v1/videos/{task_id}/content 同时支持 管理台 Session 与 Bearer Token。

Content-Type

场景	Content-Type
JSON 请求	`application/json`
图像编辑 / 带文件的视频创建	`multipart/form-data`
TTS 响应	`audio/mpeg`、`audio/wav` 等（取决于 `response_format`）
Chat / Responses 流式	`text/event-stream`（SSE）

计费

网关根据请求体中的 model（或路径参数）自动选择上游渠道
支持按 Token、按次、按秒等计费策略
不同 API Key 可见模型列表可能不同

公共响应对象

`usage`（Token 计费）

文本类接口（Chat / Completions / Responses）响应中常见：

字段	类型	说明
`prompt_tokens`	integer	输入 Token 数（Completions / Chat）
`completion_tokens`	integer	输出 Token 数（Completions / Chat）
`total_tokens`	integer	总 Token 数
`input_tokens`	integer	输入 Token 数（Responses）
`output_tokens`	integer	输出 Token 数（Responses）
`prompt_cache_hit_tokens`	integer	命中缓存的输入 Token（部分模型）
`prompt_tokens_details`	object	输入 Token 明细
`prompt_tokens_details.cached_tokens`	integer	缓存 Token 数
`prompt_tokens_details.text_tokens`	integer	文本 Token 数
`prompt_tokens_details.audio_tokens`	integer	音频 Token 数
`prompt_tokens_details.image_tokens`	integer	图像 Token 数
`completion_tokens_details`	object	输出 Token 明细
`completion_tokens_details.reasoning_tokens`	integer	推理 Token 数
`completion_tokens_details.text_tokens`	integer	文本 Token 数

`usage`（按次计费，图像）

字段	类型	说明
`quota_type`	integer	计费类型标识
`quota`	integer	本次消耗额度
`request_count`	integer	请求次数，通常为 1
`prompt_tokens`	integer	输入 Token（图像接口通常为 0）
`completion_tokens`	integer	输出 Token（图像接口通常为 0）
`total_tokens`	integer	总 Token（图像接口通常为 0）

错误响应

标准错误（文本 / 图像 / 音频 / 视频 content）

HTTP 状态码：400、401、403、404、429、500 等。

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "param": "model"
  }
}

字段	类型	说明
`error.message`	string	人类可读的错误描述
`error.type`	string	错误类型，如 `invalid_request_error`、`insufficient_quota`
`error.code`	string	错误码，如 `invalid_request`、`model_not_found`
`error.param`	string	引发错误的请求字段名（若有）
`error.metadata`	object	扩展元数据（部分上游返回）

任务类错误（视频任务创建 / 查询失败）

HTTP 状态码：400、429 等。

{
  "code": "invalid_request",
  "message": "model is required"
}

字段	类型	说明
`code`	string	错误码，常见 `invalid_request`
`message`	string	错误描述

HTTP 429 时 message 为：当前分组上游负载已饱和，请稍后再试。

网关扩展错误（模型列表、音色列表等）

HTTP 状态码：200（业务失败）或 400。

{
  "success": false,
  "message": "get user group failed"
}

字段	类型	说明
`success`	boolean	是否成功，`false` 表示失败
`message`	string	错误描述

令牌余额与消费记录

除 Relay 接口外，V1 还提供两条查询接口，鉴权方式与其它 /v1 接口一致：Authorization: Bearer sk-xxxxxxxx。仅可查询当前 Bearer 令牌自身的数据。

方法	路径	说明
GET	`/v1/token/balance`	查询令牌余额（⚡）
GET	`/v1/token/consume`	查询当前 API Key 消费记录（分页）

鉴权方式：统一使用 Bearer Token，令牌信息由鉴权中间件解析，无需再传 key 参数。

GET `/v1/token/balance`

查询当前 Bearer 令牌的余额，返回以 ⚡ 为单位的剩余额度与已用额度。

鉴权：Authorization: Bearer sk-xxxxxxxx

请求参数

无 query 参数。

请求示例（curl）

curl https://www.yunsell.com/v1/token/balance \
  -H "Authorization: Bearer sk-xxxxx"

响应体

HTTP 200

{
  "success": true,
  "message": "",
  "data": {
    "id": 1,
    "name": "API Token",
    "remain_quota_usd": 0.2,
    "used_quota_usd": 0.1,
    "unlimited_quota": false
  }
}

响应字段

字段	类型	说明
`success`	boolean	是否成功
`message`	string	提示信息
`data.id`	integer	令牌 ID
`data.name`	string	令牌名称
`data.remain_quota_usd`	number	剩余额度（⚡）。无限额度令牌固定返回 `0`
`data.used_quota_usd`	number	已用额度（⚡）
`data.unlimited_quota`	boolean	是否无限额度

GET `/v1/token/consume`

分页查询当前 Bearer API Key 的消费记录（仅 type = 2 消费）。按 token_id 过滤，不返回所属用户的充值 / 收入等钱包类记录，也不汇总该用户下其它 Key 的消费。

鉴权：Authorization: Bearer sk-xxxxxxxx

请求参数

参数	类型	必填	说明
`page`	integer	否	页码，默认 `1`
`page_size`	integer	否	每页条数，默认 `10`，最大 `100`
`time_range`	string	否	时间范围快捷筛选，仅允许 `all`、`today`、`yesterday`、`week`、`month`。优先级高于 `start_timestamp` / `end_timestamp`
`start_timestamp`	integer	否	开始时间戳（`time_range` 为空时生效）
`end_timestamp`	integer	否	结束时间戳（`time_range` 为空时生效）
`model_name`	string	否	模型名称筛选
`request_id`	string	否	请求 ID 筛选
`upstream_request_id`	string	否	上游请求 ID 筛选

请求示例（curl）

curl "https://www.yunsell.com/v1/token/consume?page=1&page_size=10&time_range=today" \
  -H "Authorization: Bearer sk-xxxxx"

响应体

HTTP 200

{
  "success": true,
  "message": "",
  "code": 0,
  "data": {
    "page": 1,
    "page_size": 10,
    "total": 100,
    "items": [
      {
        "id": 1,
        "created_at": 1700000000,
        "type": 2,
        "type_name": "消费",
        "content": "模型推理",
        "token_name": "default",
        "model_name": "gpt-3.5-turbo",
        "app_name": "",
        "usage_name": "gpt-3.5-turbo",
        "quota_usd": 0.002,
        "quota_type": 2
      }
    ]
  }
}

响应字段

字段	类型	说明
`success`	boolean	是否成功
`message`	string	提示信息
`code`	integer	状态码，`0` 表示成功，`-1` 表示业务失败
`data.page`	integer	当前页码
`data.page_size`	integer	每页条数
`data.total`	integer	总记录数
`data.items`	array	消费记录列表
`data.items[].id`	integer	日志 ID
`data.items[].created_at`	integer	创建时间戳
`data.items[].type`	integer	日志类型，固定为 `2`（消费）
`data.items[].type_name`	string	日志类型名称，固定为 `消费`
`data.items[].content`	string	日志内容
`data.items[].token_name`	string	令牌名称
`data.items[].model_name`	string	模型名称
`data.items[].app_name`	string	应用名称（若来自 Apps 应用）
`data.items[].usage_name`	string	使用模型名称，或 Apps 应用名称
`data.items[].quota_usd`	number	消费配额（⚡）
`data.items[].quota_type`	integer	额度变动类型（`0` 无变动、`1` 增加、`2` 减少）