Adaptive API guide
Enable adaptive routing in your console and choose an enabled strategy. Keep using the same PikToken API endpoint and key. Explicit model IDs continue to work independently.
Choose a routing strategy
Economy minimizes the estimated selling cost among verified candidates above the quality floor. Quality first prioritizes the operator task-quality score. Balanced combines quality, estimated selling cost and observed latency once there are at least 20 observations.
{
"model": "piktoken/auto-economy",
"messages": [
{
"role": "user",
"content": "Summarize this paragraph."
}
],
"max_tokens": 256,
"routing": {
"task": "writing",
"max_cost_usd": 0.02
}
}Use piktoken/auto to follow your saved default, or choose piktoken/auto-economy, piktoken/auto-balanced or piktoken/auto-quality. A task hint is optional; supported hints are general, writing, coding, reasoning and translation.
Capabilities, uncertainty and budgets
The router checks your model permissions, current capability evidence, compatible verified upstream routes, assigned VPS, context/output limits, quality floors and selling-price freshness. Unknown capability is not treated as support, and missing prices are not treated as free.
Local task classification uses lexical similarity to built-in Chinese and English examples. It is experimental, runs without another model call and is not a calibrated prediction of difficulty or quality. Low similarity or ambiguous matches start with the verified conservative fallback.
The effective budget is the lowest of the platform strategy ceiling, your saved ceiling and routing.max_cost_usd. A single reservation covers the maximum context plus requested output cost of every allowed fallback candidate. Cost estimates only rank candidates; settlement uses valid provider usage and the actual selected model rates.
Operator quality scores require evaluation evidence. They do not guarantee that every task succeeds, and this release does not claim proven savings or equal quality across models.
Session stability and tools
For a tool chain or conversation that must keep one model, use the same opaque routing.session_key of 16–120 letters, digits, underscores or hyphens. The key is hashed with your user ID and is not stored in plaintext. A pin lasts 24 hours; different users never share pins.
{
"model": "piktoken/auto",
"messages": [
{
"role": "user",
"content": "Help me debug a function."
}
],
"max_tokens": 512,
"routing": {
"task": "coding",
"complexity": "advanced",
"session_key": "conversation_001_example",
"max_cost_usd": 0.05
}
}A pinned request can fail over among compatible upstreams for the same model, but cannot switch models. If its model loses eligibility, the request fails clearly. Review the configuration and start a new session key; tool continuations without a key are rejected.
Fallback and billing
All upstream attempts share a four-attempt maximum and one 120-second deadline. The model routing settings determine which HTTP failures allow fallback. No retry follows a partial response, invalid usage, ambiguous connection failure or timeout. There is one client reservation and one settlement.
The response model field and x-piktoken-model header show the actual public model used. x-piktoken-strategy and x-piktoken-policy-version identify the decision. x-piktoken-reservation-usd shows the maximum reserved amount. The JSON piktoken field identifies the requested auto alias and local task source.
Preview, shadow reports and feedback
The console route preview does not contact an inference provider. Shadow mode records a proposal for an explicit-model request while that original model still answers and settles its normal bill. It does not generate a second answer or measure the alternative model quality.
Routing history retains numeric request features, candidate decisions, recorded retail rates, token usage and outcomes. It excludes prompts, completions, credentials and raw session keys. Reference-cost differences are modeled from the same token counts, not measured savings. Outcome ratings belong to your own completed requests and inform administrator review.