概览

模型

JoyToken 的模型不是一串静态名称。模型广场由 router-service 的模型池提供，包含 model_key、tier、provider、能力标签、行业标签、MCI 评分和客户侧计费费率。聊天请求可以直接指定模型，也可以使用 model: "auto" 交给 router-service 选择。

模型列表接口

模型广场当前公开 HTTP 路径：

GET /api/v1/models

这个接口由 front-gateway 暴露，当前不要求 API Key。请求链路是：

GET /api/v1/models
  -> front-gateway
  -> admin-bff ModelService/ListModels
  -> router-service ListModels
  -> model pool snapshot

返回结构由 front-gateway 包一层统一响应：

Response shape
1{
2  "code": 0,
3  "message": "success",
4  "data": {
5    "models": []
6  }
7}

如果 admin-bff 未配置，接口会返回 50300 admin-bff not available。

查询参数

查询参数含义
tier按模型档位筛选，例如 economy、standard、premium
provider按模型提供商筛选，对应路由器模型池里的 provider
feature_tag按能力标签筛选，例如 chat、code、vision、embedding
packSKU 或场景筛选。SKU 会匹配 tags，行业场景会匹配行业标签
industry_packs多个行业场景标签，可重复传参
List standard coding models
$curl "https://api-dev.joytokens.ai/api/v1/models?tier=standard&feature_tag=code"
List software development models
$curl "https://api-dev.joytokens.ai/api/v1/models?industry_packs=software_development_tools"

模型字段

字段含义
model_id路由器内部模型 ID
model_key开发者在聊天请求里通常填写的模型名
display_nameConsole 和模型广场展示名
tier模型所属计费和路由档位
provider模型提供商
tagsSKU 标签，例如 lock、spot、auction、first
feature_tags能力标签，例如 chat、code、vision
scenario_tags行业场景标签，对应路由器模型池里的 industry_packs
mci_scoreMCI 综合评分，当前保持百分制
customer_input_mtok客户侧输入价格，单位 Cr / MTok
customer_output_mtok客户侧输出价格，单位 Cr / MTok
customer_cacheread_mtok客户侧 cache read 价格，单位 Cr / MTok
customer_cachewrite_mtok客户侧 cache write 价格，单位 Cr / MTok

在请求中选择模型

聊天补全支持两种主路径：

方式写法适合场景
固定模型"model": "GLM-5"你已经完成评测，希望请求稳定命中某个模型
自动路由"model": "auto"你希望 JoyToken 根据策略、tier、请求特征和模型池状态选择
Fixed model
1{
2  "model": "GLM-5",
3  "messages": [
4    { "role": "user", "content": "Write a concise onboarding message." }
5  ]
6}
Auto model
1{
2  "model": "auto",
3  "tier": "standard",
4  "messages": [
5    { "role": "user", "content": "Write a concise onboarding message." }
6  ]
7}

从产品角度，公开文档应优先推荐 auto，因为 JoyToken 的核心价值是路由、策略和成本治理。只有在你明确需要可重复评测、合规固定或固定成本曲线时，再使用具体 model_key。

选型建议

目标建议
快速接入用 model: "auto"，并设置合适的 tier
成本优先策略限定 economy 或使用 COST_FIRST
质量优先策略使用 QUALITY_FIRST 或固定到已评测模型
视觉输入选择包含 vision 的模型；路由器也会根据图片输入补充 required_feature_tags
代码场景使用 feature_tag=code 或行业包 software_development_tools 先筛选模型
生产稳定性用独立 API Key + 固定模型或受控策略做灰度

和 API Key 策略的关系

模型列表展示的是模型池可用模型，不代表每个 API Key 都可以调用所有模型。最终是否可用还会受这些约束影响：

  • API Key 绑定的 tier。
  • 策略快照的 allowed_tiers / tiers。
  • model_blacklist。
  • API Key fixed_model。
  • IP 白名单/黑名单。
  • 钱包余额、预算和预冻结额度。

如果模型列表能看到某个模型，但请求被拒绝，优先检查 API Key 策略和 tier 是否允许该模型。