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.

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).