Developer APIToken Relay public API reference
Token Relay exposes multi-protocol inference APIs and customer management OpenAPI endpoints. All protected endpoints use Authorization: Bearer <api_key>.
Inference APIs
One API key, model-selected calls
The same TOKEN_RELAY_API_KEY works across OpenAI-compatible, Anthropic-compatible, and DashScope-compatible endpoints. Use the request body model field to choose any entitled model returned by GET /openapi/v1/models or GET /v1/models. API key allowed_model_ids controls which model values a key may call; if a key is scoped away from the requested model, the gateway returns model_not_allowed.
API key model scope examples
| Mode | Request | Meaning |
|---|---|---|
automatic | POST /openapi/v1/api-keys {"allowed_model_ids":[]} | Use all currently entitled customer-visible models. On PATCH, "allowed_model_ids":[] will clear an existing key back to automatic matching. |
single | {"allowed_model_ids":["qwen-plus"]} | Pin the key to one runtime model value. |
selected | {"allowed_model_ids":["qwen-plus","qwen-max"]} | Restrict the key to a selected model set. |
unchanged | PATCH /openapi/v1/api-keys/{api_key_id} | Omit allowed_model_ids on PATCH to keep the current scope unchanged. Responses include model_scope so clients can render automatic, single, or selected state directly. |
| Method | Path | Description |
|---|---|---|
| GET | GET /v1/models | List models callable by the current API key. |
| POST | POST /v1/chat/completions | OpenAI Chat Completions-compatible endpoint with non-streaming and streaming support. |
| POST | POST /v1/messages | Anthropic Messages-compatible endpoint that reuses the same authentication, routing, billing, content safety, and context-cache pipeline. |
| POST | POST /api/v1/services/aigc/text-generation/generation | DashScope Text Generation-compatible endpoint for customers using DashScope request bodies. |
Customer Management OpenAPI v1
| Method | Path | Description |
|---|---|---|
| GET | GET /openapi/v1/client | Get the unified customer identity for the current API key. |
| GET | GET /openapi/v1/client/profile | Get the current customer profile. |
| PATCH | PATCH /openapi/v1/client/profile | Update the current customer profile. |
| POST | POST /openapi/v1/conversations | Create customer conversation metadata. |
| GET | GET /openapi/v1/conversations | List customer conversation metadata. |
| GET | GET /openapi/v1/conversations/{conversation_id} | Get one conversation metadata record. |
| PATCH | PATCH /openapi/v1/conversations/{conversation_id} | Update conversation title, model, and custom metadata. |
| DELETE | DELETE /openapi/v1/conversations/{conversation_id} | Archive a conversation metadata record. |
| GET | GET /openapi/v1/context/config | Get context window, memory retention, and cache configuration. |
| PATCH | PATCH /openapi/v1/context/config | Update context window, memory retention, and cache configuration. |
| GET | GET /openapi/v1/security/policy | Get content safety, masking, logging, data retention, and model-scope policy. |
| PATCH | PATCH /openapi/v1/security/policy | Update content safety, masking, logging, data retention, and model-scope policy. |
| GET | GET /openapi/v1/routing/policy | Get multi-region, fallback, retry, rollout, and model-scope policy. |
| PATCH | PATCH /openapi/v1/routing/policy | Update multi-region, fallback, retry, rollout, and model-scope policy. |
| GET | GET /openapi/v1/resources | List model, MCP, Skills, and Agents resource catalog entries. |
| GET | GET /openapi/v1/resources/{resource_id} | Get one resource catalog entry. |
| GET | GET /openapi/v1/resource-types | List resource type values. |
| GET | GET /openapi/v1/models | List models, capabilities, and price summaries visible to the current customer. |
| GET | GET /openapi/v1/models/{model} | Get one model detail record. |
| GET | GET /openapi/v1/models/{model}/preflight | Check one model before sending inference traffic with one Bearer API key. Returns protocol URLs, blocking reasons, and billing reconciliation links. |
| GET | GET /openapi/v1/model-tags | List tags for models visible to the current customer. |
| GET | GET /openapi/v1/balance | Get available and reserved balance. |
| GET | GET /openapi/v1/balance/config | Get customer balance and quota alert configuration. |
| PATCH | PATCH /openapi/v1/balance/config | Update customer balance and quota alert configuration. |
| POST | POST /openapi/v1/balance/check | Check whether a specified charge can be covered by available balance. |
| GET | GET /openapi/v1/balance-transactions | List balance transactions for the current customer. |
| GET | GET /openapi/v1/balance-transactions.csv | Download balance transactions as CSV for recharge, charge, reservation, release, and correction ledger movement. |
| GET | GET /openapi/v1/balance-transactions/{transaction_id} | Get one balance transaction. |
| GET | GET /openapi/v1/api-keys | List API keys without returning plaintext tokens. |
| POST | POST /openapi/v1/api-keys | Create an API key. The plaintext token is returned once. |
| GET | GET /openapi/v1/api-keys/{api_key_id} | Get one API key. |
| GET | GET /openapi/v1/api-keys/{api_key_id}/model-access | Check whether one API key can call each customer-visible model. |
| PATCH | PATCH /openapi/v1/api-keys/{api_key_id} | Update API key name, quota, and model scope. |
| DELETE | DELETE /openapi/v1/api-keys/{api_key_id} | Delete an API key by safely disabling it. |
| POST | POST /openapi/v1/api-keys/{api_key_id}/disable | Disable an API key. |
| POST | POST /openapi/v1/api-keys/{api_key_id}/copy | Copy quota and model scope into a new key. The new plaintext token is returned once. |
| POST | POST /openapi/v1/api-keys/{api_key_id}/rotate | Rotate an API key. The old key is disabled and the new plaintext token is returned once. |
| GET | GET /openapi/v1/usage/breakdown | Get recent usage and daily breakdowns. |
| GET | GET /openapi/v1/billing/cost-breakdown | Get customer billing charge breakdown rows. This endpoint reports customer charges, not supplier cost. |
| GET | GET /openapi/v1/billing/detail | Get customer-safe billing detail rows. Supports from, to, model, status, key_id, and request_id filters. |
| GET | GET /openapi/v1/billing/detail.csv | Download billing detail as CSV for finance reconciliation jobs using the same Bearer API key. |
| GET | GET /openapi/v1/billing/monthly-statement | Get a customer monthly billing statement with month=YYYY-MM. |
| GET | GET /openapi/v1/billing/monthly-statement.csv | Download monthly statement as CSV for accounting import and offline reconciliation. |
| GET | GET /openapi/v1/billing/rules | List customer-visible billing rules. |
| GET | GET /openapi/v1/billing/rules/{model} | Get one customer-visible billing rule. |
| GET | GET /openapi/v1/cost/overview | Get customer spend overview metrics. |
| GET | GET /openapi/v1/cost/trend | Get daily customer spend trend metrics. |
| GET | GET /openapi/v1/cost/models | Get model-level customer spend metrics. |
| GET | GET /openapi/v1/cost/models/{model} | Get customer spend details for one model. |
| GET | GET /openapi/v1/observation/metrics | Get success rate, latency, error, and request metrics. |
| GET | GET /openapi/v1/observation/charts | Get chart-ready observation data. |
| GET | GET /openapi/v1/observation/logs | List customer-safe request observation logs. |
| GET | GET /openapi/v1/traces/{request_id} | Get a diagnostic trace summary for the current customer's request. |
Customer-safe billing APIs
The billing APIs expose customer charges only: usage, tokens, request IDs, balance changes, visible model names, and customer prices. They never expose supplier cost, margin, operator-side secrets, or internal price-rule identifiers.
Response envelope
{
"request_id": "req_xxx",
"success": true,
"data": {},
"code": null,
"message": null
}
Quick start: OpenAI Chat Completions compatible
Optional preflight for one-key model calls and billing: GET /openapi/v1/models/auto-chat-balanced/preflight. The response includes POST https://xbingo.xin/v1/chat/completions, billing_detail_url, and monthly_statement_url so clients can check model availability before inference and reconcile charges afterwards.
curl https://xbingo.xin/v1/chat/completions \
-H "Authorization: Bearer $TOKEN_RELAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"auto-chat-balanced","messages":[{"role":"user","content":"hello"}]}'
Quick start: Anthropic Messages compatible
curl https://xbingo.xin/v1/messages \
-H "Authorization: Bearer $TOKEN_RELAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"auto-chat-balanced","max_tokens":512,"messages":[{"role":"user","content":"hello"}]}'
Quick start: DashScope Text Generation compatible
curl https://xbingo.xin/api/v1/services/aigc/text-generation/generation \
-H "Authorization: Bearer $TOKEN_RELAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"auto-chat-balanced","input":{"messages":[{"role":"user","content":"hello"}]},"parameters":{"max_tokens":512}}'