Skip to navigation

Models

Use model: "auto" to let JoyToken select the concrete model during routing, or send a modelName from the catalog to pin a specific model.

A modelName from the catalog can be sent as the request model to pin that model. See Routing for how a pinned model behaves.

ScenarioRequest
New integrationmodel: "auto"
Cost-firstmodel: "auto" + tier: "economy"
Balanced defaultmodel: "auto" + tier: "standard"
Quality-firstmodel: "auto" + tier: "premium"
Pin one modelmodel: "<modelName from the catalog>"

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

FieldMeaning
modelNameCatalog model name; send it as the request model to pin this model
displayName / aliasAlways auto in the current response
tierBilling and routing tier
tagsProduct tags
descriptionLocalized description selected by locale
providerAlways auto in the current response
featureTagsCapability tags
scenarioTagsScenario tags
mciScoreCatalog score
customerInputMtokInput price in Cr / MTok
customerOutputMtokOutput price in Cr / MTok
customerCachereadMtokCache-read price in Cr / MTok
customerCachewriteMtokCache-write price in Cr / MTok
customerImageInputMtokImage-input price as a decimal string; empty when unavailable
customerImageCachedInputMtokCached image-input price as a decimal string; empty when unavailable
customerImageOutputMtokImage-output price as a decimal string; empty when unavailable

Model Is Listed But Request Fails

The model catalog shows the models available to JoyToken routing. Send model: "auto" to let JoyToken choose, or send a catalog modelName to pin one. Check:

CheckDescription
API key policytier and model restrictions
Source IPwhether the key policy allows it
Wallet and budgetmain wallet has balance