API Reference

Overview

The tokencoup gateway is a thin, OpenAI-compatible proxy in front of Baidu Qianfan. It adds gateway-level authentication, rate limiting, usage metering and billing without rewriting your request body.

The edition and the mode are encoded in the URL path, not in headers. That makes the data-residency boundary explicit and prevents a domestic key from ever being used to serve an overseas request (C2/S3 guard).

Quickstart

• Create a gateway API key (rf_…). Its plan sets your RPM and token quota.
• Choose Mode A (bring your own Qianfan key) — available on both editions.
• POST an OpenAI-style chat payload to /intl/a/….

BASE=https://api.tokencoup.com

curl -s "$BASE/intl/a/v1/chat/completions" \
  -H "X-Gateway-Key: rf_YOUR_GATEWAY_KEY" \
  -H "Authorization: Bearer YOUR_QIANFAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ernie-4.0-8k",
    "messages": [{"role": "user", "content": "Say hi in one sentence."}]
  }'

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "ernie-4.0-8k",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hi there!"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 12, "completion_tokens": 5, "total_tokens": 17}
}

Authentication

There are two distinct keys. Confusing them is the most common integration error.

Endpoints

POST is used for inference: the first two path segments select edition and mode, and the remainder is forwarded verbatim to the Qianfan upstream. GET covers two read-only endpoints: /v1/usage (local ledger) and /v1/models (upstream passthrough). GET calls are authenticated and rate-limited, but never consume tokens or incur billing.

{
  "model": "ernie-4.0-8k",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Summarize this in two lines: …"}
  ],
  "temperature": 0.7,
  "stream": false
}

Usage (GET, local truth)

GET /intl/{a|b}/v1/usage returns measured values from the gateway's own subscriptions and usage_ledger tables. It makes no upstream call, is not metered and is not billed. Quota and RPM come from gateway/plans.py — the same source injected into the pricing page at build time.

curl -s http://127.0.0.1:8081/intl/a/v1/usage \
  -H 'X-Gateway-Key: rf_...'

Model list (GET, passthrough)

GET /intl/{a|b}/v1/models is relayed to the Qianfan upstream under the same edition/key checks (C2 S3) as inference. Verified 2026-11-12: the public endpoint https://api.baiduqianfan.ai/v1/models returned HTTP 200 with 17 models, 14 carrying published per-token prices, with no authentication required. tokencoup does not rewrite that catalogue — the homepage model price table is a dated snapshot produced by site/fetch_models.py. Mock mode makes no network call and returns an empty list.

curl -s http://127.0.0.1:8081/intl/a/v1/models \
  -H 'X-Gateway-Key: rf_...' -H 'Authorization: Bearer <your-qianfan-key>'

Streaming (SSE)

Set stream: true in the request body. The response uses Content-Type: text/event-stream with OpenAI-style data: chunks terminated by data: [DONE]. v0.3 uses buffered passthrough: the upstream SSE body is read in full and written once. Chunk-by-chunk flushing is not implemented yet, so clients must not assume token-by-token latency.

curl -N http://127.0.0.1:8081/intl/a/v1/chat/completions \
  -H 'X-Gateway-Key: rf_...' -H 'Authorization: Bearer <your-qianfan-key>' \
  -H 'Content-Type: application/json' \
  -d '{"model":"ernie-4.0-8k","messages":[{"role":"user","content":"hi"}],"stream":true}'

data: {"id":"mock-chunk-1","object":"chat.completion.chunk","mock":true,"choices":[...]}

data: [DONE]

Modes: BYOK vs metered

Mode B quickstart (international only)

Mode B needs no provider key. You pay for tokens from tokencoup's international Qianfan pool, and the gateway injects the pool key upstream after authenticating your gateway key.

curl -s "https://api.tokencoup.com/intl/b/v1/chat/completions" \
  -H "X-Gateway-Key: rf_YOUR_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "ernie-4.0-8k", "messages": [{"role": "user", "content": "Hello"}]}'

const res = await fetch('https://api.tokencoup.com/intl/b/v1/chat/completions', {
  method: 'POST',
  headers: {
    'X-Gateway-Key': process.env.TOKENCOUP_GATEWAY_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'ernie-4.0-8k',
    messages: [{ role: 'user', content: 'Hello' }],
  }),
});
console.log(res.status, await res.json());

Billing & quotas

Only Mode B is billed. Usage is metered on successful (200) responses, written to a usage ledger and charged against the subscription's token quota. The prototype estimates tokens as len(body)/4; production must read the upstream usage field instead.

Overage is $0.002 per 1,000 tokens (placeholder). Exhausting the quota returns 402 quota_exceeded. USD→CNY FX (7.2) and the tax rate are placeholders; EU customers require VAT handling before launch.

Errors

Errors are JSON objects with an error machine code; some also carry detail. Upstream Qianfan errors are passed through with their original status and body.

{
  "error": "quota_exceeded",
  "detail": "subscription token quota exhausted; upgrade plan or wait for reset"
}

Rate limits

Limits are per gateway key, enforced with a 60-second sliding window (Redis when REDIS_URL is configured, in-memory fallback otherwise). The check happens before the upstream call, so a 429 never consumes tokens.

Recommended: exponential backoff with jitter on 429 and 5xx; never retry 401, 402 or 403 without fixing the request first.

Data residency & privacy (international)

The international edition implements the C2 / S1 design target: requests are routed to the Qianfan International upstream and tagged X-Data-Region: overseas, with log_prompt set to false — prompts are not persisted. Audit records contain only edition, mode, key id and token counts. The X-Data-Region header is an internal routing tag only; it does not control where the upstream processes data and is not evidence of residency. Overseas residency is a target, pending written confirmation from Baidu.

Cloudflare AI Gateway fronts the international path only: 300 s edge cache, 600 req / 60 s rate limiting, 3 retries, collect_logs=false (no request or response bodies stored) and gateway authentication enabled. The domestic edition stays direct.

Machine-readable spec

An OpenAPI 3.1 description of the three path families is published at openapi.json. Import it into Postman, Insomnia or an SDK generator to scaffold a client.

FAQ

Do I need my own Qianfan account?

Mode A: yes. Mode B: no — tokencoup supplies the international pool key.

Is my prompt stored?

On the international edition, no (log_prompt=false, collect_logs=false). On the domestic edition, prompt logging is enabled for domestic compliance.

Can I use a domestic Qianfan key on the international endpoint?

No. That is the permanently blocked C2/S3 path; the gateway returns 403 key_edition_mismatch.

When am I charged?

Only for Mode B, only on successful (200) responses. Failed requests write a zero-billed ledger row but consume no quota.

Is streaming supported?

Not in v0.2 — the reference server reads and forwards a single JSON response. Set stream: false.