TokenFlyTokenFly API
TokenFly is wire-compatible with the OpenAI and Anthropic APIs. If your code already uses one of those SDKs, switching means changing the base URL and the key.
Quickstart
- Create an account and add credit under Billing.
- Create a key under API keys. It starts with
tf_live_and is only shown once. - Point your client at the base URL below.
{{origin}}/v1
{{origin}} # Anthropic SDKs append /v1/messages themselves
from openai import OpenAI client = OpenAI(base_url="{{origin}}/v1", api_key="tf_live_...") r = client.chat.completions.create( model="deepseek-v4.1-flash", messages=[{"role": "user", "content": "Say hi"}], ) print(r.choices[0].message.content, r.usage.cost)
import OpenAI from "openai"; const client = new OpenAI({ baseURL: "{{origin}}/v1", apiKey: process.env.TOKENFLY_API_KEY }); const r = await client.chat.completions.create({ model: "deepseek-v4.1-flash", messages: [{ role: "user", content: "Say hi" }], });
curl {{origin}}/v1/chat/completions \
-H "Authorization: Bearer $TOKENFLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-v4.1-flash","messages":[{"role":"user","content":"Say hi"}]}'
Authentication
Send your key as Authorization: Bearer tf_live_…. On the Messages endpoints, x-api-key is accepted as well, the way Anthropic SDKs send it. Keys are stored hashed. Revoking a key in the dashboard takes effect on the next request.
Endpoints
| Method & path | Purpose |
|---|---|
POST /v1/chat/completions | OpenAI Chat Completions, including tools, vision and streaming |
POST /v1/responses | OpenAI Responses API (stateless) |
POST /v1/completions | Legacy text completions |
POST /v1/messages | Anthropic Messages |
POST /v1/messages/count_tokens | Token count estimate (free) |
POST /v1/embeddings | Text embeddings |
POST /v1/rerank, /v2/rerank | Document reranking |
POST /v1/images/generations, /v1/images/edits | Image generation and editing |
POST /v1/videos/generations | Video generation (blocks until complete) |
POST /v1/audio/speech, /transcriptions, /translations | Text-to-speech and speech-to-text |
POST /v1/uploads, DELETE /v1/uploads/{id} | Temporary image uploads for vision prompts |
GET /v1/models | Catalog with TokenFly prices (no key needed) |
Choosing a model
Pass any id from the catalog as model. Vendor-prefixed aliases such as anthropic/claude-opus-5 also resolve. Each catalog entry lists the endpoints it supports in supported_endpoints.
Streaming
Set "stream": true. Events are relayed as they arrive: chat.completion.chunk for Chat Completions, Anthropic's message_start … message_stop for Messages. Pass stream_options.include_usage to get a final usage chunk. Streams are metered whether or not you ask for it.
Billing & usage
Requests are paid from your prepaid wallet at the rates in the catalog. Input and output token rates are never above the model maker's own list price. Non-streamed responses include the exact charge, in US dollars:
{
"usage": { "prompt_tokens": 21, "completion_tokens": 9, "cost": 0.000012 },
"request_id": "req_…",
"billing": { "status": "settled", "billed_cost_usd": "0.000012", "currency": "USD" }
}Each response also carries an x-tokenfly-request-id header that matches the entry under Usage in the dashboard. Streamed Chat Completions are charged from their token counts first, then corrected to the final settled figure a few seconds later.
Errors
Errors use the OpenAI envelope, {"error": {"message", "type", "code"}}, or the Anthropic one on /v1/messages.
| Status | Meaning |
|---|---|
| 400 / 422 | Invalid request, such as an unknown model or a malformed body |
| 401 | Missing, invalid or revoked API key |
| 402 | Wallet is empty. Add credit to continue. |
| 429 | Rate or concurrency limit. Honour Retry-After. |
| 502 / 503 | Provider capacity issue. Retry with exponential backoff. |
Limits
- Request bodies: up to 4.5 MB, or 20 MB inflated when sent with
Content-Encoding: gzip. - Default rate limit of 600 requests per minute per key, and 16 concurrent requests per account. Contact us to raise either.
- Realtime (WebSocket) endpoints are not available yet.
Data handling
TokenFly stores request metadata needed for billing: time, endpoint, model, token counts, cost, latency and status. Prompts and completions are relayed in memory and never written to our database or logs.