Models

JoyToken model requests only accept model: "auto". JoyToken selects the concrete model during routing.

Recommended Choice

Auto Routing

{
  "model": "auto",
  "tier": "standard",
  "messages": [
    { "role": "user", "content": "Write a short onboarding message." }
  ]
}

auto lets JoyToken choose a model within API key policy, tier, wallet balance, and model-pool availability.

List Models

Set JOY_TOKEN_API_BASE_URL from Environments before calling the model catalog.

curl "$JOY_TOKEN_API_BASE_URL/api/v1/models?locale=en"

Set locale=en for English descriptions or locale=zh for Chinese descriptions. If locale is omitted, the API defaults to English.

Common filter:

curl "$JOY_TOKEN_API_BASE_URL/api/v1/models?locale=en&tier=standard&feature_tag=code"

GET /api/v1/models is public. The metadata and pricing endpoints require an API key. Send either Authorization: Bearer $JOY_TOKEN_API_KEY or X-API-Key: $JOY_TOKEN_API_KEY.

Catalog Metadata

Use catalog metadata to build filters without hard-coding provider names or capability tags.

curl "$JOY_TOKEN_API_BASE_URL/api/v1/models/meta" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY"

The response contains tiers, skus, featureTags, industryPacks, providers, and updatedAt.

Pricing

curl "$JOY_TOKEN_API_BASE_URL/api/v1/pricing" \
  -H "X-API-Key: $JOY_TOKEN_API_KEY"

The response lists customer-facing tier exchange-rate descriptions. This endpoint requires an API key.

Model Fields

Model Is Listed But Request Fails

The model catalog shows the models available to JoyToken routing. Applications still send model: "auto". Check: