Overview

Models

JoyToken models are not a static list of names. The model marketplace is backed by the router-service model pool and includes model_key, tier, provider, capability tags, scenario tags, MCI score, and customer-facing rates. Chat requests can specify a model directly or use model: "auto" and let router-service choose.

Model List API

The current public model marketplace path is:

GET /api/v1/models

This endpoint is exposed by front-gateway and currently does not require an API key. Request flow:

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

The response is wrapped by front-gateway:

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

If admin-bff is not configured, the endpoint returns 50300 admin-bff not available.

Query Parameters

QueryMeaning
tierFilter by model tier, such as economy, standard, or premium
providerFilter by provider from the router model pool
feature_tagFilter by capability, such as chat, code, vision, or embedding
packSKU or scenario filter. SKU matches tags; industry scenarios match scenario tags
industry_packsMultiple industry scenario tags; pass the parameter repeatedly
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 Fields

FieldMeaning
model_idRouter-internal model ID
model_keyModel name developers usually put in chat requests
display_nameDisplay name in Console and model marketplace
tierBilling and routing tier
providerModel provider
tagsSKU tags, such as lock, spot, auction, first
feature_tagsCapability tags, such as chat, code, vision
scenario_tagsScenario tags that correspond to router industry_packs
mci_scoreMCI score, currently kept on a 100-point scale
customer_input_mtokCustomer input price in Cr / MTok
customer_output_mtokCustomer output price in Cr / MTok
customer_cacheread_mtokCustomer cache-read price in Cr / MTok
customer_cachewrite_mtokCustomer cache-write price in Cr / MTok

Select a Model

Chat Completions supports two main paths:

ModeRequestUse when
Fixed model"model": "GLM-5"You have evaluated a model and need stable routing
Auto routing"model": "auto"You want JoyToken to choose from policy, tier, request features, and model pool state
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}

Public docs should recommend auto first because JoyToken’s core value is routing, policy, and cost governance. Use concrete model_key values when you need repeatable evaluation, compliance pinning, or a fixed cost curve.

Selection Guidance

GoalRecommendation
Fast integrationUse model: "auto" with an appropriate tier
Cost firstRestrict policy to economy or use COST_FIRST
Quality firstUse QUALITY_FIRST or pin an evaluated model
Vision inputUse models with vision; the router also adds required_feature_tags from image input
CodingStart from feature_tag=code or the software_development_tools industry pack
Production stabilityUse separate API keys plus fixed model or controlled policy for gradual rollout

Relationship to API Key Policy

The model list shows the model pool. It does not mean every API key can call every model. Final availability is also constrained by:

  • API key tier.
  • Policy snapshot allowed_tiers / tiers.
  • model_blacklist.
  • API key fixed_model.
  • IP allowlist/blocklist.
  • Wallet balance, budget, and freeze amount.

If a model is visible in the catalog but the request is rejected, check the API key policy and tier first.