API Reference

All API requests use the base URL https://tokenpass.cloud/v1.

Authentication

Send the TokenPass API key as a Bearer token:

Authorization: Bearer <TOKENPASS_API_KEY>

List models

GET /v1/models returns the model IDs available to the current API key.

curl https://tokenpass.cloud/v1/models \
  -H "Authorization: Bearer $TOKENPASS_API_KEY"

Chat Completions

POST /v1/chat/completions accepts an OpenAI-compatible message list.

{
  "model": "gpt-5-mini",
  "messages": [
    { "role": "system", "content": "You are a concise assistant." },
    { "role": "user", "content": "Explain token caching." }
  ],
  "stream": false
}

Common fields include model, messages, stream, tools, tool_choice, response_format, and model-supported sampling or reasoning controls.

Responses

POST /v1/responses is required for Responses-only models such as gpt-5.4-pro and supports stateful response items and compatible tools.

curl https://tokenpass.cloud/v1/responses \
  -H "Authorization: Bearer $TOKENPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-pro",
    "input": "Review this architecture for failure modes."
  }'

Messages

POST /v1/messages accepts an Anthropic-compatible request.

curl https://tokenpass.cloud/v1/messages \
  -H "Authorization: Bearer $TOKENPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Streaming

Set stream to true on an interface and model that support streaming. Clients must process Server-Sent Events incrementally and stop when the interface-specific completion event is received.

curl -N https://tokenpass.cloud/v1/chat/completions \
  -H "Authorization: Bearer $TOKENPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [{"role": "user", "content": "Count to five."}],
    "stream": true
  }'

Errors

HTTP status	Meaning	Action
400	Invalid JSON or request parameter	Check the request schema and model-specific fields.
401	Missing or invalid API key	Check the Bearer token and key status.
402/403	Balance, quota, or access condition	Check the Console and model access.
404	Unknown model or endpoint	Refresh IDs with GET /v1/models.
429	Rate limit reached	Retry with exponential backoff and jitter.
502/503	Temporary upstream unavailability	Retry idempotent requests with bounded backoff.

Oversized input may also fail when the request exceeds the effective context limit for the selected model and interface.