API Docs

Quickstart

One chat completions call — pick your favorite client.

curl https://api.tokengp.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Authentication

All endpoints require an API key in the Authorization header:

Authorization: Bearer sk-tokengp-<your-key>

• • Keys are issued at /keys and shown to you ONCE — store them securely.
• • Optional per-key spend cap, RPM limit, allowed-models list, and source-IP allowlist can be set when creating a key. If an IP allowlist is set, only those IPv4/CIDR sources may call the key (403 otherwise); leaving it empty allows any IP.
• • Revoke compromised keys immediately from the same page; revocation is instant.

List models

Returns the catalog of models your account can call. Filters out coming-soon and disabled models.

Example

curl https://api.tokengp.com/v1/models \
  -H "Authorization: Bearer $TOKENGP_API_KEY"

• • Each entry has OpenAI-shape fields (id, object, created, owned_by) plus extras: display_name, input_price_per_1m, output_price_per_1m. Most OpenAI SDKs ignore unknown fields.

Retrieve a model

Lookup a single model by id. Used by some SDKs during client initialization to validate the model name.

Example

curl https://api.tokengp.com/v1/models/qwen3.8-max \
  -H "Authorization: Bearer $TOKENGP_API_KEY"

• • 404 model_not_found if the id is unknown or disabled.

Chat completions

OpenAI-compatible chat-completions endpoint. Supports streaming (SSE) and non-streaming. Token usage is tracked at the upstream and your balance is debited at the end of each request.

Request body

{
  "model": "qwen3.8-max",
  "messages": [
    {"role": "system", "content": "You are concise."},
    {"role": "user", "content": "Explain JWT in one sentence."}
  ],
  "max_tokens": 256,
  "temperature": 0.2,
  "stream": false
}

Example

curl https://api.tokengp.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [{"role":"user","content":"hi"}],
    "max_tokens": 32
  }'

• • For streaming, set "stream": true. Each SSE event is "data: {...}" carrying an OpenAI-shape chunk with "choices[0].delta.content" for partial text and "choices[0].finish_reason" on the final non-DONE chunk. Consume until you see "data: [DONE]".
• • Vision and tool / function calling are passed through to upstream models that support them (e.g. qwen-vl-*, qwen3-class). See the examples below.
• • Balance is pre-checked against worst-case cost (input + max_tokens × output_price). Insufficient balance returns 402.
• • Reasoning models (e.g. DeepSeek R1) bill the chain-of-thought as output_tokens — your usage.completion_tokens may exceed the visible message length. The chain itself is not exposed in the response.

{
  "model": "qwen3.8-max",
  "messages": [
    {"role": "user", "content": "What's the weather in Paris?"}
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather for a city.",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

{
  "model": "qwen3.8-max",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What is in this image?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
    ]
  }]
}

Anthropic Messages (compat)

Anthropic Messages API compatibility endpoint. Tools built on the Anthropic SDK — Claude Code, ZCode, and friends — work against TokenGP by pointing their base URL here. Requests are translated to chat-completions internally, so auth, model allowlists, rate limits, and billing behave identically.

Request body

{
  "model": "qwen3.8-max",
  "max_tokens": 1024,
  "system": "You are concise.",
  "messages": [
    {"role": "user", "content": "Explain JWT in one sentence."}
  ],
  "stream": false
}

Example

curl https://api.tokengp.com/v1/messages \
  -H "x-api-key: $TOKENGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "max_tokens": 256,
    "messages": [{"role":"user","content":"hi"}]
  }'

• • Auth accepts both the Anthropic-style "x-api-key: <key>" header and "Authorization: Bearer <key>" — same sk-tokengp-* keys as everywhere else.
• • Streaming emits standard Anthropic SSE events (message_start, content_block_delta, message_delta, message_stop). Tool use and image inputs are translated both ways.
• • The "thinking" request parameter is accepted but not forwarded — whether a model reasons is decided upstream. Models that emit reasoning (e.g. DeepSeek) return it as a standard Anthropic "thinking" content block.
• • POST /v1/messages/count_tokens returns a local estimate (~4 chars/token). It never hits the upstream and is free.

// %USERPROFILE%\.zcode\cli\config.json  (macOS/Linux: ~/.zcode/cli/config.json)
{
  "provider": {
    "tokengp": {
      "kind": "openai-compatible",
      "name": "TokenGP",
      "options": {
        "baseURL": "https://api.tokengp.com/v1",
        "apiKey": "sk-tokengp-...",
        "apiKeyRequired": true,
        "includeUsage": true
      },
      "models": {
        "qwen3.8-max": { "name": "Qwen3.8 Max" },
        "deepseek-v4-pro":   { "name": "DeepSeek V4 Pro" }
      }
    }
  },
  "model": { "main": "tokengp/qwen3.8-max", "lite": "tokengp/deepseek-v4-pro" }
}

Embeddings

Generate vector embeddings for one or more strings. Only models with modality=embedding are accepted here (chat models return 400 wrong_endpoint).

Request body

{
  "model": "text-embedding-v3",
  "input": "Hello, world."
}

Example

curl https://api.tokengp.com/v1/embeddings \
  -H "Authorization: Bearer $TOKENGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v3",
    "input": ["hello", "world"]
  }'

• • input accepts a single string or an array of strings.
• • Billing is by input tokens only (output_tokens = 0).

Image generation

Generate images from a text prompt. We wrap Aliyun’s async task API so the client sees a synchronous response — typical latency is 3-10s. Charged per image regardless of resolution.

Request body

{
  "model": "qwen-image-plus",
  "prompt": "a red apple on a wooden table",
  "n": 1,
  "size": "1024x1024"
}

Example

curl https://api.tokengp.com/v1/images/generations \
  -H "Authorization: Bearer $TOKENGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-plus",
    "prompt": "a red apple on a wooden table",
    "n": 1,
    "size": "1024x1024"
  }'

• • Response shape: {"created":<ts>,"data":[{"url":"<signed-oss-url>","revised_prompt":"..."}]}.
• • n is capped at 4. Sizes supported depend on the model; 1024x1024 works everywhere.
• • URLs are temporary signed OSS links — download and re-host within ~1 hour.
• • Internal polling deadline is 90s; long jobs return 504 upstream_timeout.

Billing

Usage is billed per request in CNY and debited from your balance when the request completes. Prices are listed per 1M tokens on the pricing page.

• • Settled on actual usage: you are charged on the token counts the upstream reports for the request (input + output), not on estimates. Failed requests are not charged.
• • Pre-flight balance check: before a call is forwarded we check your balance against a worst-case estimate (input + max_tokens at the most expensive tier the request could land in). Insufficient balance returns 402 before any upstream call is made.
• • Tiered pricing: some models are priced in tiers rather than at one flat rate — the rate depends on how long the input is, whether the model reasoned, and on some models the time of day. Tiers can differ by 10x between the cheapest and priciest band, and each request is billed at the tier it actually lands in, based on its real input token count. Every model with tiers is marked on the pricing page with a “Tiered” badge — expand it to see the rate for each band. The headline price for such a model is its cheapest band.
• • How the thinking tier is decided: a request is billed at the thinking rate if it asked for thinking (enable_thinking, reasoning_effort, or thinking.type) OR if the response actually contains reasoning content. Some models reason by default without being asked, and the upstream charges the thinking rate whenever they do.
• • Cache hits: when the upstream reports a prompt-cache hit, the cached portion of the input is billed at that model’s cache-hit rate instead of the full input rate; the rest of the input is billed normally. On tiered models the cache-hit rate is tiered too, and follows the same band as the request.
• • Checking a charge: the tier each call was billed at is shown next to that call on your dashboard. If a charge still looks wrong, send us the request id and we will reconcile it against the upstream bill.

Error codes

All errors return JSON of shape {"error":{"code":"...","message":"...","type":"..."}}. HTTP status maps to error.code as follows.

The type field groups codes into families so you can branch on it without pattern-matching every name: auth_error (key issues), invalid_request_error (your input), rate_limit (RPM caps), billing_error (balance / cap), upstream_error (provider side), server_error (rare — our side).