# TopxAI documentation

> The complete text of https://ai.topxea.com/docs in English. Each page names its canonical URL; the Chinese version is served at the same URL to Chinese readers.

## What TopxAI is

> One base URL, fourteen models on seven lines, prepaid USD credit, and nothing you send is stored.

Section: Getting started · URL: https://ai.topxea.com/docs/what-topxai-is · Updated: 2026-09-18

TopxAI is the model API service run by TopXEA, the team behind topxea.com. Point an OpenAI- or Anthropic-compatible client at one base URL, pay from a prepaid USD balance, and the relay forwards each request to the model you named.
One endpoint
The base URL is https://ai.topxea.com/v1. It serves OpenAI-style Chat Completions and Responses, Anthropic-style Messages, image generation and edits, video generation, and /v1/systemone for Jev. Keep your SDK; change the base URL and the key.
Fourteen models on seven lines
Claude: claude-fable-5-1, claude-sonnet-5-5, claude-opus-5-5
OpenAI: gpt-6-astra, gpt-6.1-sol, gpt-image-2.5-sunburst, gpt-image-2.5-flare
Grok: grok-4.7, grok-imagine-video-1.5
GLM: GLM-5.3-Abliterated
Kimi: kimi-k3
DeepSeek: deepseek-flash, deepseek-v4-pro
Jev: jev-1.14.0 (jev-latest and jev-preview are its aliases, billed and answered as it)
Claude, OpenAI, Grok, Kimi, DeepSeek and Jev are the providers' own models. GLM-5.3-Abliterated is a fine-tuned GLM 5.3 served from a private deployment, not the vendor's API: text only, priced above list.
Routes and prices
Every price is a fixed USD figure per model and route, listed under Models & pricing at https://ai.topxea.com/#models. The shared pool is 50% of the provider's list price, the official line 90%, Kimi's single official line 80%. DeepSeek's single official line is 80% of the DeepSeek list price in both of the provider's tiers: peak hours (01:00-04:00 and 06:00-10:00 UTC, Monday to Friday, except Chinese public holidays) cost twice the off-peak hours, and the tier is decided when a request is accepted. Jev is 107% of TypeSafe's list price: $0.04494 per million input tokens, output free. GLM runs on its private deployment above list.
A key is pinned to one route, such as claude-shared, or set to Auto route, which picks the lowest-priced line that serves each request's model.
Text bills per million tokens with separate input, output and cache lanes; images per picture by size (1K or 2K); video per second by resolution (480p, 720p or 1080p). Once the input reaches 272,001 tokens on gpt-6-astra or gpt-6.1-sol, or 200,000 tokens on grok-4.7, the whole request bills at long-context lanes: double the input price, higher output. Each request writes a usage-log row with model, route and charge.
Prepaid USD
Credit is added on the Wallet page under Add credit, by Card / local payment (checkout runs on topxea.com) or Crypto · USDT / USDC, between $10 and $10,000 per payment; an unpaid order expires after 60 minutes. Redeem a code takes a Redemption code; Gift cards sells one to keep or give away. Only your own requests spend the balance, and every deduction is listed.
Zero retention
Prompts, completions and uploaded files pass through TopxAI in memory and are never written to disk; bodies, headers and upstream error bodies are not stored. What is kept is metadata: token counts, model name, route, status, latency, timestamps, the API key identifier, request ids and the charge. The provider serving the request handles the content under its own terms and retention policy, which TopxAI does not control.
Support
The help button at the bottom right of the site, or support@topxea.com.

## Create an API key and choose a route

> The key drawer step by step, what each route means, and the three 403 refusals a key can hit.

Section: Getting started · URL: https://ai.topxea.com/docs/create-an-api-key-and-choose-a-route · Updated: 2026-09-18

Open API keys in the sidebar and click Create API key.
The form
Name: any label; the placeholder suggests production-backend.
Group: the route the key is billed on. Nothing is preselected; saving without one fails with Choose a group. An N models button on each row expands its price table (USD per 1M tokens, USD per image or USD per second), with a Long context row where that tier exists.
Quota: Unlimited quota on, or off with a Quota (USD) after which the key stops.
Expiry: an Expiration time, or a preset: Never, 1 Hour, 1 Day, 1 Month.
Quantity (creating only): up to 50 keys; the first keeps the name you typed, the rest get a random suffix.
Advanced settings, collapsed by default: Model limits and IP Whitelist (supports CIDR), both empty.
Click Save changes. The key starts with sk-.
The routes
Auto route is listed first and covers the whole catalogue with one key. Each request goes to the lowest-priced line that can serve its model right now, normally the shared pool; when the pool cannot, it goes to the official line at its higher price, so the billed route can differ per request. The usage log shows that route under Group.
Claude, OpenAI and Grok: a Shared pool (claude-shared, openai-shared, grok-shared) at 50% of list and an Official line (claude-official, openai-official, grok-official) at 90%. A text model is sold only on its own vendor's two routes. Grok's official line is also the only route for grok-imagine-video-1.5, per second.
OpenAI Image generation (image): the only route for gpt-image-2.5-sunburst and gpt-image-2.5-flare, per image by size.
GLM Private deployment (z-official): GLM-5.3-Abliterated, a fine-tuned GLM 5.3 on a private deployment, text only, above list.
Kimi Official line (kimi-official): kimi-k3 at 80% of list.
TypeSafe Official line (typesafe-official, marked Official key · 107% of list price): jev-1.14.0. Its Full API key popover adds One-command setup for Jev.
Official-line requests fall back to the shared pool when no dedicated line is configured; for a dedicated official-price line, write to support@topxea.com.
Three refusals
Three checks run before a provider is reached; each fails with HTTP 403:
Model is not offered by this service: the model id is not in the catalogue.
Model is not available on this API key route: the model is not on this key's route, such as a GPT model on a Claude key.
This token has no access to model <name>: the key's Model limits exclude it. Pick them under Select models (empty allows all); jev-latest and jev-preview count as jev-1.14.0 here.
IP Whitelist takes one IP or CIDR block per line; addresses can be spoofed, so pair it with a gateway such as nginx or a CDN.

## Connect your SDK

> The base URL, every endpoint with its auth header, working examples for the OpenAI and Anthropic SDKs, and what each error status means.

Section: Getting started · URL: https://ai.topxea.com/docs/connect-your-sdk · Updated: 2026-09-18

Use the SDK you already have; the key goes where the provider's key would go. The API endpoint panel at the top of the API keys page lists every path with a copy button. Copy base URL copies the origin https://ai.topxea.com without /v1: right for the Anthropic SDK; OpenAI-style SDKs need /v1 added, or copy the endpoint row.
Your first successful request
Open API keys and create a key for the model family you want to test. A key's route and model limits determine what it can call; choosing a model in a client does not expand those permissions.
Check Wallet. New accounts currently receive $0.50 of welcome credit. If your balance is positive, you can use it for a short test without first adding credit. A key's own quota must also cover the request reservation.
Copy the matching example below, replace the placeholder with your key locally, and run it once. Keep the output limit small. Never paste your key into a support message or a public issue.
Confirm that a response arrived, then open Usage to check the model, route and charge. A successful /v1/models response only confirms model discovery; it does not prove a generation succeeded.
For a desktop client, follow the Cherry Studio setup. Start with one model on one route, then add more after the first call succeeds.
Endpoints
POST /v1/chat/completions: OpenAI Chat Completions, Authorization: Bearer <key>, every text model except Jev
POST /v1/responses: OpenAI Responses, Bearer, GPT models and grok-4.7
POST /v1/messages: Anthropic Messages, x-api-key: <key>, every text model except Jev; Claude natively, the other models through a conversion whose differences the API reference lists. anthropic-version is optional, and without max_tokens Claude and DeepSeek get the model's output limit
POST /v1/images/generations and POST /v1/images/edits: OpenAI Images, Bearer, GPT Image 2.5 models
POST /v1/videos/generations, GET /v1/videos/{request_id} for status, GET /v1/videos/{request_id}/content for the video: Bearer, Grok Imagine Video
POST /v1/systemone (or /v1/system_one): TypeSafe System One, Bearer, Jev
GET /v1/models: the models your key can call
OpenAI Python SDK
Pass the base URL with /v1; the SDK appends /chat/completions.
from openai import OpenAI
client = OpenAI(base_url="https://ai.topxea.com/v1", api_key="sk-...")
reply = client.chat.completions.create(
model="claude-sonnet-5-5",
messages=[{"role": "user", "content": "Say hello in one sentence."}],
max_tokens=64,
)
print(reply.choices[0].message.content)
Anthropic SDK
The Anthropic SDK appends /v1/messages itself, so its base URL is the origin; the key travels as x-api-key.
from anthropic import Anthropic
client = Anthropic(base_url="https://ai.topxea.com", api_key="sk-...")
reply = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=256,
messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(reply.content[0].text)
Coding tools
Claude Code: Claude models work with Claude Code and any Anthropic-compatible client. CC Switch in a key's row menu opens a ccswitch:// import with the endpoint (https://ai.topxea.com for Claude, https://ai.topxea.com/v1 for Codex), the key and the Primary Model you pick, plus optional Haiku Model, Sonnet Model and Opus Model for Claude.
Codex CLI: GPT and Grok models, at https://ai.topxea.com/v1.
Trae and similar editors take the same two values. Trae's add-model test sends a small image, and GLM-5.3-Abliterated is text only; the relay swaps it for [Attachment omitted: this model accepts text only.], so the test passes but the model gets no attachments.
Jev: the TypeSafe SDKs read TYPESAFE_BASE_URL=https://ai.topxea.com and TYPESAFE_API_KEY. The one-command setup under a Jev key installs the TypeSafe agent skill, writes ~/.config/topxai/typesafe.env, a marked block in ~/.zshrc or ~/.bashrc and the env in ~/.claude/settings.json, then sends one ping; without --key it prompts for the key without echo.
If the first call fails
401: the key is missing or invalid.
402: the balance is empty.
403: the model id is not sold here, is not on this key's route, or is excluded by the key's model limits; the message says which.
404: the provider answered that the model does not exist.
429: rate limited; Retry-After gives the wait, at most 60 seconds.
503: no line can serve the model right now, or the provider is overloaded; retry.
Every error message ends with a request id you can send to support@topxea.com.

## API reference: every endpoint, with an OpenAPI specification

> Every endpoint TopxAI serves, what each accepts and returns, the two ways to send the key, and the OpenAPI 3.1 file at /openapi.json for API tools.

Section: Getting started · URL: https://ai.topxea.com/docs/api-reference · Updated: 2026-09-19

TopxAI forwards request bodies unchanged and returns responses unchanged, so the reference for a body is the provider's own documentation. The exceptions are listed in the comparison with the providers' own APIs: members the upstream adds to an answer are removed (several on /v1/responses, provider_specific_fields on /v1/chat/completions), and a GPT request without a system prompt is sent the one-line instruction "You are a helpful assistant." so that the provider does not add its own longer prompt. A request in a format other than the model's own, such as Messages to a GPT model, is converted on the way, and so is the answer; the section on Messages requests to other models below lists what that changes. This page lists what TopxAI itself defines: the endpoints, which models each serves, how the key travels, and the fields the relay validates or prices. The same information is machine-readable at /openapi.json (OpenAPI 3.1), which Postman, Insomnia, Bruno, Swagger UI, Redoc and code generators load directly.
Base URLs
https://ai.topxea.com/v1 for OpenAI-style SDKs and tools; they append /chat/completions, /responses, /images/…, /models.
https://ai.topxea.com for the Anthropic SDK; it appends /v1/messages.
Authentication
A TopxAI key (sk-…) from the API keys page, sent one of two ways:
Authorization: Bearer <key> on every endpoint.
x-api-key: <key> on /v1/messages, the way the Anthropic SDK sends it.
The key's route decides which models it can call; an Auto-route key can call every model.
Endpoints
Endpoint Format Models Notes
POST /v1/chat/completions OpenAI Chat Completions every text model except Jev stream: true for SSE
POST /v1/responses OpenAI Responses gpt-6-astra, gpt-6.1-sol, grok-4.7 what Codex CLI uses
POST /v1/messages Anthropic Messages every text model except Jev Claude natively, the other models through a conversion (below); anthropic-version optional
POST /v1/images/generations OpenAI Images gpt-image-2.5-sunburst, gpt-image-2.5-flare priced per image by the size tier; n 1 to 128
POST /v1/images/edits OpenAI Images (multipart) the same two priced like generation
POST /v1/videos/generations video job grok-imagine-video-1.5 duration 1 to 15 s, resolution 480p/720p/1080p; billed on acceptance
GET /v1/videos/{request_id} job status keep polling on pending, queued, processing, running, in_progress
GET /v1/videos/{request_id}/content the file after done
POST /v1/systemone TypeSafe System One jev-1.14.0, jev-latest, jev-preview model, state, questions; images in assets, as base64 or multipart parts; also /v1/system_one
GET /v1/models OpenAI model list filtered to the key's route
GET /api/pricing JSON price table no key needed; the data behind /pricing
Messages requests to other models
Claude models get a /v1/messages request in Anthropic's own format, cache_control breakpoints included; the few fields the relay changes on the way, such as a missing max_tokens set to the model's output limit, are listed in the comparison with the providers' APIs. Without anthropic-version the relay sends Claude 2023-06-01; the converted requests do not carry the header. For the other text models TopxAI converts the request: gpt-6.1-sol goes to the Responses API; gpt-6-astra, grok-4.7, kimi-k3, GLM-5.3-Abliterated, deepseek-flash and deepseek-v4-pro go to Chat Completions. The answer comes back as a Messages response or event stream either way. Where the converted models differ from Claude:
Without max_tokens, DeepSeek also gets the model's output limit, cut to what the context window leaves after the estimated prompt. The other models are sent no cap and write up to their provider's default.
The Chat Completions conversion keeps cache_control on the text, image and document blocks of the messages and drops it everywhere else: the system prompt, the tool definitions, tool_use and tool_result blocks. The Responses conversion for gpt-6.1-sol drops it everywhere.
A tool_result block that holds an image or a document is a 400 on the Chat Completions models. The Responses conversion passes it on to gpt-6.1-sol.
thinking blocks in the conversation history, including those gpt-6.1-sol's own earlier answers came back with, are dropped before the request reaches gpt-6.1-sol; the Chat Completions models take them as reasoning. redacted_thinking blocks are dropped on every converted model. The model continues without the reasoning that was dropped.
grok-4.7 reasons on every request and xAI refuses stop sequences on reasoning models, so stop_sequences on grok-4.7 is a 400 that names the parameter.
GLM-5.3-Abliterated takes text only. On /v1/chat/completions an attachment is replaced by a note (its page has the details); on /v1/messages an image or document block reaches the deployment and the request fails with a 400.
Status codes
400 the body failed validation, the message names the field; on System One it can also be TypeSafe's own rejection, passed through. 401 key missing or invalid. 402 balance empty. 403 model not sold here, not on this key's route, or excluded by the key's model limits. 404 the provider says the model does not exist, or an unknown video job. 413 a System One body or image over a size limit. 422 TypeSafe's validation detail (System One only). 429 rate limited, Retry-After in seconds. 503 no line can serve the model now; retry. Every error message ends with a request id; quote it to support@topxea.com.
Using the specification
curl -O https://ai.topxea.com/openapi.json
Import the file into Postman or Insomnia to get a request per endpoint with the examples filled in, or feed it to openapi-generator for a typed client. The file's servers entry is the production origin; nothing in it is specific to a key or an account.
Not served
Batch, fine-tuning, files, assistants, vector stores, realtime, audio and embeddings are not relayed; requests to those paths return 404. Keep them on the provider's own key. The comparison with the providers' APIs lists what else stays direct.

## Claude Code with TopxAI: ANTHROPIC_BASE_URL and the key

> Point Claude Code at https://ai.topxea.com with two environment variables and pick claude-sonnet-5-5, claude-opus-5-5 or claude-fable-5-1 as its model.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-claude-code · Updated: 2026-10-02

Claude Code talks to the Anthropic Messages API, which TopxAI serves at https://ai.topxea.com/v1/messages. Two environment variables set the endpoint and key; the model variables select a catalogue model.
Setup
export ANTHROPIC_BASE_URL=https://ai.topxea.com
export ANTHROPIC_AUTH_TOKEN=sk-... # a TopxAI key on the Claude or Auto route
export ANTHROPIC_MODEL=claude-sonnet-5-5 # optional: the default model
claude
ANTHROPIC_AUTH_TOKEN sends the key as a Bearer token; ANTHROPIC_API_KEY sends it as x-api-key. TopxAI accepts both, so use whichever your shell already has. The base URL is the origin without /v1: Claude Code adds /v1/messages itself.
To make it permanent, put the same values under env in ~/.claude/settings.json:
{
"env": {
"ANTHROPIC_BASE_URL": "https://ai.topxea.com",
"ANTHROPIC_AUTH_TOKEN": "sk-...",
"ANTHROPIC_MODEL": "claude-sonnet-5-5"
}
}
Claude Code also reads ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL for the models it switches between; set them to catalogue ids (claude-opus-5-5, claude-sonnet-5-5) so a switch never asks for a model TopxAI does not sell.
Moving from Sonnet 5
Change any saved ANTHROPIC_MODEL or ANTHROPIC_DEFAULT_SONNET_MODEL value from claude-sonnet-5 to claude-sonnet-5-5. The old ID is retired without a forwarding alias. Keep the same endpoint and unrestricted key; if the key has an allowed-model list, edit it to include the new ID. Start a fresh conversation so old model-bound thinking blocks are not replayed into Sonnet 5.5.
Token and cache prices stay the same. Adaptive thinking defaults to high effort; TopxAI translates legacy disabled-thinking requests to between_tools at low effort. Custom clients that force a tool must switch to automatic tool selection, and Anthropic-native computer-use clients must adopt the new toolset format. The Sonnet 5.5 migration post covers these settings and links to Anthropic's migration guide.
Which key
A key on the Auto route sends each request to the lowest-priced route that serves the model, the shared pool first. A key on the Claude official line pins the provider's own line at 90% of list. Both are created on the API keys page; the routes page explains the difference.
CC Switch
If you keep several endpoints, the CC Switch entry in a key's row menu on the keys page opens a ccswitch:// import with the endpoint, the key and the model already filled in.
What Claude Code sends
Claude Code sends its own system prompt and tool definitions with every request; those tokens are billed as input like any other. Prompt caching applies at the cache-read and cache-write prices on the model's page, and the usage log shows the cached and uncached counts separately.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.
During the October 2 supplier checks, some between_tools requests returned 502, including medium on both routes and OpenAI none on the official route. Adaptive mode with explicit low effort passed on both routes: use thinking: {"type":"adaptive"} with output_config: {"effort":"low"} for Messages, or reasoning_effort: "low" for Chat Completions, when it fits your task. Adaptive mode can still think before answering, and those tokens are billed as output. TopxAI preserves the requested mode rather than silently substituting another one.

## Codex CLI custom model provider: model_providers in config.toml for TopxAI

> Point Codex CLI at TopxAI with a [model_providers.topxai] table in ~/.codex/config.toml and run gpt-6.1-sol, gpt-6-astra or grok-4.7. An npm mirror is included.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-codex-cli · Updated: 2026-09-22

Codex CLI is OpenAI's coding agent for the terminal. It speaks the OpenAI Responses API, which TopxAI serves at https://ai.topxea.com/v1/responses for the GPT models and grok-4.7. This page covers the whole path: where to get Codex when GitHub and npm are out of reach, the one command that installs and connects it, what that command changes, and how to do the same by hand.
Where to get Codex
Codex is published in three places: the GitHub releases (one archive per system), npm (npm install -g @openai/codex) and Homebrew (brew install codex). The downloads page now provides the TopxAI desktop app. To install Codex CLI when GitHub or npm is slow or blocked, use the npm mirror or the installation scripts described below. If you choose a GitHub release archive, check your system:
macOS: Apple menu, About This Mac. An Apple M-series chip means Apple silicon; "Intel" means Intel.
Windows: Settings, System, About; "System type" names x64 or ARM64.
Linux: uname -m prints x86_64 or aarch64.
A package is a .tgz with the codex binary under package/vendor/<target>/bin/ and its helper programs beside it. The installer below does the unpacking and the PATH work for you; with Node.js installed, npm install -g @openai/codex --registry=https://registry.npmmirror.com is the other way through the mirror.
Install in one command
macOS and Linux, in a terminal:
curl -fsSL https://ai.topxea.com/install/codex.sh | sh -s -- --key sk-...
Windows, in PowerShell:
$env:TOPXAI_API_KEY = "sk-..."; irm https://ai.topxea.com/install/codex.ps1 | iex
sk-... is a TopxAI key on the OpenAI, Grok or Auto route from the API keys page. Leave the key out and the script asks for it without echo, so it never lands in your shell history.
Then open a new terminal and run codex.
What the script changes
The script only touches these places, and running it again is safe: it replaces the binary and rewrites only its own lines.
It downloads the current Codex package for your system through the npm mirror (the newest release the mirror has for that system) and checks npm's integrity value before anything is installed. --version 0.155.1 picks another version.
It unpacks the package into ~/.local/lib/codex and links ~/.local/bin/codex to the binary, putting that folder on PATH through a marked block in ~/.zshrc and ~/.bashrc (Windows: the package goes to %LOCALAPPDATA%\Programs\codex and the folder holding codex.exe goes on the user PATH). Pass --config-only to keep a Codex you installed from npm or Homebrew and only write the configuration.
It writes ~/.codex/config.toml: model = "gpt-6.1-sol", model_provider = "topxai" and a [model_providers.topxai] table. Anything else already in the file is kept, and the previous file is saved as config.toml.bak.<timestamp>.
It stores the key in ~/.codex/topxai.env (mode 0600), exported by the same shell block as TOPXAI_API_KEY; on Windows it becomes a user environment variable.
It calls GET /v1/models with the key and reports whether gpt-6.1-sol is on the key's route.
Options: --model gpt-6-astra for another default model, --no-verify to skip the last request, --base-url for a self-hosted relay, --bin-dir for another install folder. sh -s -- --help prints them all.
Set up by hand
If Codex is already installed, the whole configuration is one provider block in ~/.codex/config.toml. It must be the user-level file: Codex ignores model_provider in a project's .codex/config.toml.
model = "gpt-6.1-sol"
model_provider = "topxai"
[model_providers.topxai]
name = "TopxAI"
base_url = "https://ai.topxea.com/v1"
env_key = "TOPXAI_API_KEY"
wire_api = "responses"
Then export the key and start Codex:
export TOPXAI_API_KEY=sk-... # a TopxAI key on the OpenAI, Grok or Auto route
codex
wire_api = "responses" is the default and the only value current Codex releases accept; it is written out so nobody wonders. base_url is the origin with /v1; Codex appends /responses. env_key names the environment variable Codex reads the key from, so the variable has to be set in the shell that starts Codex: put the export line in ~/.zshrc or ~/.bashrc, or on Windows set TOPXAI_API_KEY as a user environment variable. If Codex is started by an application that does not inherit your shell, Codex also accepts the key in the file itself as experimental_bearer_token = "sk-..." in the same table, instead of env_key.
The IDE extension for VS Code reads the same ~/.codex/config.toml, so the provider applies there too as long as the editor sees the variable.
Models
gpt-6.1-sol and gpt-6-astra: the OpenAI line, on the shared pool (50% of list) or the official line (90%).
grok-4.7: the only non-OpenAI model on the Responses endpoint.
Claude, GLM, Kimi, DeepSeek and Jev are not reachable through Codex, because Codex only speaks Responses.
Switch models with codex -m gpt-6-astra or by editing model. Reasoning effort is set with model_reasoning_effort. GPT-6.1 Sol supports low, medium (default), high, xhigh and max. The model cannot disable reasoning; TopxAI normalizes legacy none and minimal to low. Replace any saved gpt-6-sol model ID with gpt-6.1-sol; the old ID is retired and does not forward.
Update and uninstall
Run the install command again: it fetches the current package and keeps your configuration and key. To remove Codex, delete ~/.local/bin/codex and ~/.local/lib/codex (Windows: the %LOCALAPPDATA%\Programs\codex folder and its PATH entry), the block between # >>> topxai codex >>> and # <<< topxai codex <<< in your shell file, and ~/.codex if you want the configuration and the key gone too.
Long context
Once the input of a GPT-6.1 Sol request passes 272K tokens (cached tokens included), the whole request bills at the long-context rates: input and cache prices double and output rises by half. GPT-6 Astra has the same 272K tier. See the model page for both tiers. Codex compacts long sessions automatically.
If it fails
codex: command not found right after installing: the shell has not read the new PATH yet. Open a new terminal, or run . ~/.zshrc (or . ~/.bashrc).
Codex says TOPXAI_API_KEY is not set: same cause, the new shell block has not been read; or the key was skipped. Run the install command again with --key.
The download fails or the integrity value does not match: the connection dropped. Run the command again; each run starts the download over.
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## Cursor with TopxAI: override the OpenAI base URL

> In Cursor, paste a TopxAI key as the OpenAI key, turn on the base URL override with https://ai.topxea.com/v1 and add the model ids you want to chat with.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-cursor · Updated: 2026-09-19

Cursor lets you bring your own OpenAI-compatible endpoint for chat. The override applies to the models you add by name; Cursor's own features that run on its servers keep using Cursor's models.
Setup
Open Cursor Settings → Models.
Under OpenAI API Key, paste a TopxAI key (Auto route covers every model).
Turn on Override OpenAI Base URL and enter https://ai.topxea.com/v1.
Click Verify. Cursor sends one small request; the usage log at TopxAI shows it.
Under the model list, Add model and type the catalogue id exactly: claude-sonnet-5-5, gpt-6.1-sol, grok-4.7, kimi-k3, GLM-5.3-Abliterated. Enable the ones you want in the picker.
Cursor sends every added model to /v1/chat/completions, which serves every text model except Jev, so Claude models work here through the OpenAI format without a separate Anthropic key.
What to expect
Chat and inline edits with an added model go through TopxAI and are billed at the model's price on the route the key uses.
Turning the override on disables Cursor's built-in OpenAI models in the picker; turn it off to get them back.
Cursor sends its own system prompt and, in agent mode, tool definitions; those are input tokens like any other.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## Cline and Roo Code with TopxAI: the OpenAI-compatible provider

> Set the provider to OpenAI Compatible with base URL https://ai.topxea.com/v1, a TopxAI key and a model id; or the Anthropic provider with a custom base URL.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-cline-and-roo-code · Updated: 2026-09-19

Cline, Roo Code and Kilo Code share the same provider settings. Two of their providers reach TopxAI: OpenAI Compatible for every text model, and Anthropic with a custom base URL for the Claude models.
OpenAI Compatible
In the extension's settings:
API Provider: OpenAI Compatible
Base URL: https://ai.topxea.com/v1
API Key: a TopxAI key (Auto route covers every model)
Model ID: claude-sonnet-5-5, gpt-6.1-sol, grok-4.7, kimi-k3 or GLM-5.3-Abliterated
Leave the "Azure" and "legacy format" switches off. The model id must match the catalogue exactly; the picker cannot list TopxAI's models by itself, so type it.
Anthropic with a custom base URL
For Claude models the Anthropic provider keeps prompt caching and the Messages-specific features:
API Provider: Anthropic
Use custom base URL: on, https://ai.topxea.com
API Key: the TopxAI key
Model: claude-sonnet-5-5 or claude-opus-5-5
The base URL here is the origin without /v1; the extension appends /v1/messages.
Agent mode and cost
These tools send the whole conversation, tool definitions and file contents with each turn. Prompt caching on the Claude line is where the savings are: cache reads bill at one tenth of the input price. The usage log separates cached from uncached tokens per request.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## Continue with TopxAI: models in config.yaml

> Add TopxAI models to ~/.continue/config.yaml with provider openai or anthropic and apiBase, then use them for chat, edit and agent mode in VS Code or JetBrains.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-continue · Updated: 2026-09-19

Continue reads its models from ~/.continue/config.yaml. A model entry names the provider, the model id, the base URL and the key; TopxAI fits the openai provider for every text model and the anthropic provider for Claude.
config.yaml
name: TopxAI
version: 0.0.1
schema: v1
models:
- name: Claude Sonnet 5.5 (TopxAI)
provider: anthropic
model: claude-sonnet-5-5
apiBase: https://ai.topxea.com
apiKey: sk-...
roles: [chat, edit, apply]
- name: GPT-6.1 Sol (TopxAI)
provider: openai
model: gpt-6.1-sol
apiBase: https://ai.topxea.com/v1
apiKey: sk-...
roles: [chat, edit, apply]
- name: Kimi K3 (TopxAI)
provider: openai
model: kimi-k3
apiBase: https://ai.topxea.com/v1
apiKey: sk-...
Two details:
The anthropic provider takes the origin without /v1 and adds /v1/messages; the openai provider takes the origin with /v1 and adds /chat/completions.
apiKey may also be ${{ secrets.TOPXAI_API_KEY }} with the key stored in Continue's secrets, so the file can be committed.
Roles
chat, edit and apply all work with the chat models above. Autocomplete (roles: [autocomplete]) needs a fill-in-the-middle model; none of the catalogue models is one, so leave autocomplete on whatever you use today.
Agent mode
Agent mode needs tool calling. Add capabilities: [tool_use] to a model entry if Continue does not detect it for a catalogue id it has not seen before.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## Zed with TopxAI: OpenAI- and Anthropic-compatible providers

> Add TopxAI to Zed as an openai_compatible provider for GPT, Grok, Kimi and GLM, and as an anthropic_compatible provider for Claude, in settings.json.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-zed · Updated: 2026-09-19

Zed's agent takes custom providers under language_models in settings.json. TopxAI is one openai_compatible provider for the text models on Chat Completions and one anthropic_compatible provider for Claude.
settings.json
{
"language_models": {
"openai_compatible": {
"TopxAI": {
"api_url": "https://ai.topxea.com/v1",
"available_models": [
{
"name": "gpt-6.1-sol",
"display_name": "GPT-6.1 Sol",
"max_tokens": 1000000
},
{
"name": "grok-4.7",
"display_name": "Grok 4.7",
"max_tokens": 500000
},
{
"name": "kimi-k3",
"display_name": "Kimi K3",
"max_tokens": 1000000
}
]
}
},
"anthropic_compatible": {
"TopxAI Claude": {
"api_url": "https://ai.topxea.com",
"available_models": [
{
"name": "claude-sonnet-5-5",
"display_name": "Claude Sonnet 5.5",
"max_tokens": 1000000,
"max_output_tokens": 128000,
"capabilities": {
"tools": true,
"images": true,
"prompt_caching": true
}
},
{
"name": "claude-opus-5-5",
"display_name": "Claude Opus 5.5",
"max_tokens": 1000000,
"max_output_tokens": 128000,
"capabilities": {
"tools": true,
"images": true,
"prompt_caching": true
}
}
]
}
}
}
}
The key does not go in settings.json. Enter it in the provider's row in the agent settings, or export the variable Zed derives from the provider name: TOPXAI_API_KEY and TOPXAI_CLAUDE_API_KEY for the two providers above.
Notes
max_tokens is the context window Zed assumes for its "context left" meter; use the model's real window.
Enable prompt_caching on the Claude provider: TopxAI forwards cache_control breakpoints and bills cache reads at one tenth of the input price.
Zed's Edit Prediction has its own provider setting and is not covered by these entries.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## Aider with TopxAI: OPENAI_API_BASE and the model name

> Run aider against TopxAI with OPENAI_API_BASE=https://ai.topxea.com/v1 and --model openai/claude-sonnet-5-5, or the Anthropic variables for the Claude line.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-aider · Updated: 2026-09-19

Aider uses LiteLLM underneath, so any OpenAI-compatible endpoint works through the openai/ prefix, and the Anthropic endpoint through anthropic/.
OpenAI-compatible (every text model)
export OPENAI_API_BASE=https://ai.topxea.com/v1
export OPENAI_API_KEY=sk-... # a TopxAI key on the Auto route
aider --model openai/claude-sonnet-5-5
Any catalogue id except Jev goes after openai/: openai/gpt-6.1-sol, openai/grok-4.7, openai/kimi-k3, openai/GLM-5.3-Abliterated.
Anthropic (Claude, with prompt caching)
export ANTHROPIC_API_BASE=https://ai.topxea.com
export ANTHROPIC_API_KEY=sk-...
aider --model anthropic/claude-sonnet-5-5 --cache-prompts
--cache-prompts turns on Aider's cache breakpoints; TopxAI forwards them and bills cache reads at one tenth of the input price.
Model metadata
Aider warns when it has no context-window or price data for a model name. Add a .aider.model.metadata.json next to your project so the warnings stop and the token meter is right:
{
"openai/claude-sonnet-5-5": {
"max_input_tokens": 1000000,
"max_output_tokens": 128000,
"input_cost_per_token": 0.000001,
"output_cost_per_token": 0.000005,
"litellm_provider": "openai",
"mode": "chat"
}
}
The costs above are the shared-pool prices from the model's page; Aider uses them only for its running total, the actual charge is in the TopxAI usage log.
Persisting it
Put the same values in ~/.aider.conf.yml (model: openai/claude-sonnet-5-5, openai-api-base: https://ai.topxea.com/v1) and the key in ~/.aider/oai.env or your shell profile.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## opencode with TopxAI: a custom provider in opencode.json

> Declare TopxAI in opencode.json with @ai-sdk/openai-compatible, the base URL and the model ids, then pick them with /models.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-opencode · Updated: 2026-09-19

opencode takes custom providers in opencode.json (in the project or in ~/.config/opencode/). One block with the @ai-sdk/openai-compatible package covers every TopxAI text model; a second with @ai-sdk/anthropic keeps Claude on the Messages API.
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"topxai": {
"npm": "@ai-sdk/openai-compatible",
"name": "TopxAI",
"options": {
"baseURL": "https://ai.topxea.com/v1",
"apiKey": "{env:TOPXAI_API_KEY}"
},
"models": {
"claude-sonnet-5-5": {
"name": "Claude Sonnet 5.5",
"limit": { "context": 1000000, "output": 128000 }
},
"gpt-6.1-sol": {
"name": "GPT-6.1 Sol",
"limit": { "context": 1000000, "output": 128000 }
},
"grok-4.7": {
"name": "Grok 4.7",
"limit": { "context": 500000, "output": 128000 }
},
"kimi-k3": {
"name": "Kimi K3",
"limit": { "context": 1000000, "output": 128000 }
}
}
},
"topxai-claude": {
"npm": "@ai-sdk/anthropic",
"name": "TopxAI (Anthropic API)",
"options": {
"baseURL": "https://ai.topxea.com/v1",
"apiKey": "{env:TOPXAI_API_KEY}"
},
"models": {
"claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
"claude-opus-5-5": { "name": "Claude Opus 5.5" }
}
}
}
}
Then:
export TOPXAI_API_KEY=sk-...
opencode
and choose a model with /models; the provider names appear as headings.
Notes
{env:TOPXAI_API_KEY} reads the key from the environment; {file:~/.secrets/topxai} reads it from a file. Either keeps the key out of the config.
The @ai-sdk/anthropic package expects a base URL ending in /v1 and appends /messages; the @ai-sdk/openai-compatible package appends /chat/completions.
limit is what opencode uses for its context meter; the values above are the models' windows, not a TopxAI limit.
Model ids must match the catalogue exactly; GET https://ai.topxea.com/v1/models with your key lists them.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## Open WebUI with TopxAI: one OpenAI connection, every model

> Add https://ai.topxea.com/v1 as an OpenAI API connection in Open WebUI; the model list fills from /v1/models and every text model is ready to chat.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-open-webui · Updated: 2026-09-19

Open WebUI treats any OpenAI-compatible endpoint as an "OpenAI API connection" and lists its models from /v1/models. One connection brings in every TopxAI text model.
In the admin panel
Admin Panel → Settings → Connections.
Under OpenAI API, add a connection: URL https://ai.topxea.com/v1, key sk-... (a TopxAI key on the Auto route).
Save. The model picker now lists the models your key can call.
With environment variables
For a Docker deployment, the same two values as variables:
docker run -d -p 3000:8080 \
-e OPENAI_API_BASE_URL=https://ai.topxea.com/v1 \
-e OPENAI_API_KEY=sk-... \
-v open-webui:/app/backend/data \
--name open-webui ghcr.io/open-webui/open-webui:main
What is listed
/v1/models returns the models the key's route can serve: on the Auto route, every text model and the image models. Jev is listed only for keys on the TypeSafe route and is not usable from a chat window, since it answers typed questions through /v1/systemone, not chat.
Images
Open WebUI's image generation setting also takes an OpenAI-compatible endpoint. Use the same URL and key and set the model to gpt-image-2.5-sunburst or gpt-image-2.5-flare; images bill per picture by size, as on the image generation page.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## LobeChat with TopxAI: the OpenAI proxy address

> Set OpenAI’s API proxy address to https://ai.topxea.com/v1 in LobeChat, or OPENAI_PROXY_URL for a deployment, and fetch the model list.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-lobechat · Updated: 2026-09-19

LobeChat's OpenAI provider accepts a proxy address, which is all TopxAI needs. The Anthropic provider takes one too, for Claude on the Messages API.
In the app
Settings → AI Service Provider → OpenAI.
API Key: a TopxAI key. API Proxy Address: https://ai.topxea.com/v1.
Click Get model list; the models your key can call appear. Enable the ones you want.
Check sends one request and shows the reply.
For Claude on the Anthropic provider: API key the same, proxy address https://ai.topxea.com (no /v1), models claude-sonnet-5-5 and claude-opus-5-5.
Self-hosted, with variables
OPENAI_API_KEY=sk-...
OPENAI_PROXY_URL=https://ai.topxea.com/v1
OPENAI_MODEL_LIST=-all,+claude-sonnet-5-5,+gpt-6.1-sol,+grok-4.7,+kimi-k3
ANTHROPIC_API_KEY=sk-...
ANTHROPIC_PROXY_URL=https://ai.topxea.com
OPENAI_MODEL_LIST starts with -all to drop LobeChat's built-in OpenAI names, then adds the catalogue ids; without it the picker shows models TopxAI does not sell and every one of them returns 403.
Images
LobeChat's image generation with the OpenAI provider works with gpt-image-2.5-sunburst and gpt-image-2.5-flare through the same proxy address.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## Cherry Studio with TopxAI: first chat and endpoint setup

> Connect a route-scoped TopxAI key to Cherry Studio, choose the right endpoint, and diagnose the first request without guessing URL suffixes.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-cherry-studio · Updated: 2026-09-19

Start with one model and a key whose route includes it. For example, create a Claude-route key for claude-sonnet-5-5. A single OpenAI-compatible connection does not make every model available to every key.
Choose the endpoint your version exposes
Cherry Studio has changed its provider settings between versions. Older releases show a single API Address field and add a version suffix. The current v2 source stores a separate base URL for each endpoint. Follow the field in your installed version and inspect the resulting request path if setup fails.
Endpoint Base URL for a v2 endpoint configuration Example model
OpenAI Chat Completions https://ai.topxea.com/v1 claude-sonnet-5-5 on a Claude key; gpt-6.1-sol on a GPT key
OpenAI Responses https://ai.topxea.com/v1 gpt-6.1-sol, grok-4.7 on their matching routes
Anthropic Messages https://ai.topxea.com claude-sonnet-5-5, claude-opus-5-5
The resulting POST paths must be /v1/chat/completions, /v1/responses, or /v1/messages, respectively. Select Chat Completions for Kimi and GLM; they do not use TopxAI's Responses endpoint. Jev uses a separate protocol and is outside this setup.
In older versions that explicitly append /v1, start with https://ai.topxea.com in the single API Address field. Do not apply that rule blindly to v2 endpoint fields. An address containing /v1 is not inherently wrong: the final request path is what matters. Avoid the advanced # endpoint override for this first setup.
Complete the first chat
Open Settings → Model Provider, add a custom provider and name it TopxAI. Choose an OpenAI-compatible Chat Completions connection, or Anthropic for a native Claude connection. Labels vary by version.
Set the matching address above and enter your TopxAI key locally. Keep screenshots and exported settings free of credentials.
Fetch the model list or manually add a model permitted by that key. Fetching /v1/models checks discovery, not generation.
Select that provider and model in a new chat. Send Say hello in one sentence. Set a small output limit if the client exposes one. A connectivity check that generates text also consumes balance.
Confirm a response, then open TopxAI Usage to verify the model, route and charge. Add other models only after this works.
New TopxAI accounts currently receive $0.50 welcome credit. Check Wallet before adding credit; the key's own quota must also cover the request reservation.
Diagnose the boundary that failed
Symptom Check next
401 Correct key, no surrounding whitespace, correct authentication type
402 with positive balance Key quota and requested output limit; the initial reservation can exceed the available balance
403 The key's route and model limits; choosing a model in Cherry does not expand them
404 or duplicated /v1/v1 Final request path and the version-specific address field
Models load but chat fails Selected endpoint, model permissions and response format
Curl works but the client fails Extra tools, attachments, reasoning options and automatic retries; start with plain text
Timeout after submission Check Usage and the request ID before repeating; do not assume the first request never ran
Image generation is a separate configuration and route. A working text-model key does not establish that image requests are enabled.
Verification scope and sources
This guide was checked against Cherry Studio's endpoint resolver, base URL selection and provider registry on September 19, 2026. It is a source-reviewed custom-provider recipe, not a claim that TopxAI is an official built-in preset or that every desktop version was tested end to end.
See Connect your SDK for a minimal comparison request and Common error responses for error details.

## ChatBox with TopxAI: a custom provider

> In ChatBox, add a custom provider in OpenAI API compatible mode with host https://ai.topxea.com and path /v1/chat/completions, then add the model ids.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-chatbox · Updated: 2026-09-19

ChatBox reaches any OpenAI-compatible endpoint through a custom provider.
Setup
Settings → Model Provider → Add Custom Provider.
Name: TopxAI. API Mode: OpenAI API Compatible.
API Host: https://ai.topxea.com. API Path: /v1/chat/completions.
API Key: a TopxAI key on the Auto route.
Model: add claude-sonnet-5-5, gpt-6.1-sol, grok-4.7, kimi-k3 or GLM-5.3-Abliterated; or fetch the list, which reads /v1/models.
Save and pick the provider in a chat.
Notes
Every text model except Jev is on /v1/chat/completions, including Claude, so one provider is enough. Jev answers typed questions through /v1/systemone and is not a chat model.
If ChatBox offers a separate Anthropic provider with a custom host, https://ai.topxea.com and the same key work there for claude-sonnet-5-5 and claude-opus-5-5.
Image generation in ChatBox with this provider uses gpt-image-2.5-sunburst or gpt-image-2.5-flare, billed per image.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## LangChain with TopxAI: ChatTopxAI from the langchain-topxai package

> Call TopxAI chat models from LangChain in Python with ChatTopxAI from langchain-topxai. ChatOpenAI with a base URL still works, also for the Responses API.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-langchain · Updated: 2026-10-16

langchain-topxai is the LangChain package for TopxAI. Its ChatTopxAI class calls TopxAI's text models through Chat Completions and reads your key from TOPXAI_API_KEY. TopXEA, the operator of TopxAI, maintains it; the source is on GitHub and releases are on PyPI.
Install
pip install -U langchain-topxai
export TOPXAI_API_KEY="sk-..."
Create the key on the API keys page; Create an API key and choose a route explains the route each key is tied to.
Python
from langchain_topxai import ChatTopxAI
llm = ChatTopxAI(model="claude-sonnet-5-5")
print(llm.invoke("Say hello in one sentence.").content)
model takes the id of any text model on the price list except Jev, for example claude-sonnet-5-5, gpt-6.1-sol, grok-4.7, kimi-k3, deepseek-v4-pro, deepseek-flash or GLM-5.3-Abliterated. ChatTopxAI builds on BaseChatOpenAI from langchain-openai, so you write streaming, async calls, tool calling, structured output and token usage the same way as with ChatOpenAI.
Argument Environment variable Default
api_key TOPXAI_API_KEY none; required. OPENAI_API_KEY is never read.
base_url TOPXAI_API_BASE https://ai.topxea.com/v1
Because OPENAI_API_KEY is never read, an OpenAI key in the same environment is not sent to TopxAI by mistake.
Reasoning text
ChatTopxAI puts the reasoning of models that return it, for example deepseek-flash and GLM-5.3-Abliterated, in additional_kwargs["reasoning_content"], also when streaming. GLM sends the field as reasoning (see its page); ChatTopxAI reads both names.
msg = ChatTopxAI(model="deepseek-flash").invoke("What is 17 * 3?")
print(msg.additional_kwargs.get("reasoning_content"))
ChatOpenAI does not extract this field, so with it the reasoning text is lost.
Structured output
with_structured_output sends a JSON Schema by default (method="json_schema"), as ChatOpenAI does. Keep the default for the Claude models (claude-sonnet-5-5, claude-opus-5-5, claude-fable-5-1): they do not accept a forced tool call, so method="function_calling" fails for them, and TopxAI answers it with a 400.
For Claude, TopxAI turns the json_schema response format into Anthropic's structured outputs, which accept a subset of JSON Schema. Number bounds such as ge and le and list lengths reach Claude as a hint in the field description instead of being enforced; LangChain still checks the answer against your Pydantic model. dict and Any fields, recursive models and tuples get a 400 that says which part of the schema Claude cannot take. With method="json_mode" there is no schema, so TopxAI asks Claude for a single JSON object in the system prompt.
ChatOpenAI and ChatAnthropic
ChatOpenAI from langchain-openai still works with a base URL. It is also the class for TopxAI's Responses API: ChatTopxAI calls Chat Completions only and refuses use_responses_api=True. The API reference lists the models /v1/responses serves.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="gpt-6.1-sol",
base_url="https://ai.topxea.com/v1",
api_key=os.environ["TOPXAI_API_KEY"],
)
responses_llm = ChatOpenAI(
model="gpt-6.1-sol",
base_url="https://ai.topxea.com/v1",
api_key=os.environ["TOPXAI_API_KEY"],
use_responses_api=True,
)
ChatAnthropic from langchain-anthropic reaches Claude through the Messages API, with prompt caching. For structured output, pass method="json_schema" to its with_structured_output. Its default, function_calling, cannot force the tool call on the three Claude models; langchain-anthropic 1.7.6 warns and raises OutputParserException whenever Claude answers without calling the tool.
import os
from langchain_anthropic import ChatAnthropic
claude = ChatAnthropic(
model="claude-sonnet-5-5",
base_url="https://ai.topxea.com",
api_key=os.environ["TOPXAI_API_KEY"],
max_tokens=1024,
)
Without base_url and api_key arguments, these two classes read OPENAI_BASE_URL / OPENAI_API_KEY and ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY (OPENAI_API_BASE and ANTHROPIC_API_URL take precedence when set), so a deployment can switch endpoints without a code change.
JavaScript
langchain-topxai is a Python package. In LangChain.js, pass the base URL to ChatOpenAI or ChatAnthropic:
import { ChatOpenAI } from '@langchain/openai'
import { ChatAnthropic } from '@langchain/anthropic'
const llm = new ChatOpenAI({
model: 'gpt-6.1-sol',
apiKey: process.env.TOPXAI_API_KEY,
configuration: { baseURL: 'https://ai.topxea.com/v1' },
})
const claude = new ChatAnthropic({
model: 'claude-sonnet-5-5',
apiKey: process.env.TOPXAI_API_KEY,
anthropicApiUrl: 'https://ai.topxea.com',
})
Embeddings
The catalogue has no embedding model; keep OpenAIEmbeddings on the provider you use today.
If it fails
TOPXAI_API_KEY must be set, or pass api_key: the variable is missing in the process that runs LangChain. ChatTopxAI does not fall back to OPENAI_API_KEY.
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in your code: that page lists the seven usual differences between the curl request and a tool's.

## Vercel AI SDK with TopxAI: createOpenAI, createAnthropic and openai-compatible

> Create an AI SDK provider with baseURL https://ai.topxea.com/v1 and a TopxAI key, then use generateText or streamText with any catalogue model.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-vercel-ai-sdk · Updated: 2026-09-19

The AI SDK's provider packages accept a baseURL, so TopxAI is one create… call away.
@ai-sdk/openai
import { createOpenAI } from '@ai-sdk/openai'
import { generateText } from 'ai'
const topxai = createOpenAI({
baseURL: 'https://ai.topxea.com/v1',
apiKey: process.env.TOPXAI_API_KEY,
})
const { text } = await generateText({
model: topxai.chat('claude-sonnet-5-5'),
prompt: 'Say hello in one sentence.',
})
topxai.chat(id) uses Chat Completions and serves every text model except Jev. topxai.responses("gpt-6.1-sol") uses the Responses API, which TopxAI serves for the GPT models and grok-4.7. topxai.image("gpt-image-2.5-sunburst") generates images, billed per picture.
@ai-sdk/anthropic
import { createAnthropic } from '@ai-sdk/anthropic'
const claude = createAnthropic({
baseURL: 'https://ai.topxea.com/v1',
apiKey: process.env.TOPXAI_API_KEY,
})
const { text } = await generateText({
model: claude('claude-opus-5-5'),
prompt: 'Say hello in one sentence.',
})
This package's base URL ends in /v1 (it appends /messages), unlike the Anthropic Python SDK, which takes the origin.
@ai-sdk/openai-compatible
For a provider object without OpenAI-specific options:
import { createOpenAICompatible } from '@ai-sdk/openai-compatible'
const topxai = createOpenAICompatible({
name: 'topxai',
baseURL: 'https://ai.topxea.com/v1',
apiKey: process.env.TOPXAI_API_KEY,
})
const model = topxai('kimi-k3')
Notes
streamText, tool calling and Output.object structured output work as with the provider's own endpoint. For Claude, TopxAI passes the schema to Anthropic's structured outputs: number bounds and array lengths in a Zod schema reach Claude as a hint in the description instead of being enforced (the SDK still validates the result), and z.record, z.any, recursive schemas and tuples get a 400 that says which part of the schema Claude cannot take.
With @ai-sdk/openai-compatible, set supportsStructuredOutputs: true for Output.object. Without it the SDK sends json_object and no schema, whatever the model.
usage on the result carries the token counts TopxAI returns; the charge itself is in the usage log.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## LiteLLM with TopxAI: proxy config and the Python SDK

> Route LiteLLM to TopxAI with model openai/<id> and api_base https://ai.topxea.com/v1, in the proxy’s model_list or a completion() call.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-litellm · Updated: 2026-09-19

LiteLLM reaches any OpenAI-compatible endpoint with the openai/ prefix and an api_base, and the Anthropic endpoint with anthropic/. That covers every TopxAI text model.
Python SDK
import litellm
reply = litellm.completion(
model="openai/claude-sonnet-5-5",
api_base="https://ai.topxea.com/v1",
api_key="sk-...",
messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(reply.choices[0].message.content)
For Claude with prompt caching through the Messages API:
reply = litellm.completion(
model="anthropic/claude-sonnet-5-5",
api_base="https://ai.topxea.com",
api_key="sk-...",
messages=[...],
)
Proxy config.yaml
model_list:
- model_name: claude-sonnet-5-5
litellm_params:
model: openai/claude-sonnet-5-5
api_base: https://ai.topxea.com/v1
api_key: os.environ/TOPXAI_API_KEY
- model_name: gpt-6.1-sol
litellm_params:
model: openai/gpt-6.1-sol
api_base: https://ai.topxea.com/v1
api_key: os.environ/TOPXAI_API_KEY
- model_name: kimi-k3
litellm_params:
model: openai/kimi-k3
api_base: https://ai.topxea.com/v1
api_key: os.environ/TOPXAI_API_KEY
Start it with litellm --config config.yaml; clients then call the proxy with the model_name values.
Cost tracking
LiteLLM prices by model name and knows nothing about TopxAI's routes. To make its cost column match the usage log, set input_cost_per_token and output_cost_per_token in litellm_params from the model's page (for example 0.000001 and 0.000005 for claude-sonnet-5-5 on the shared pool).
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## Dify with TopxAI: the OpenAI-API-compatible provider

> Add each TopxAI model to Dify through the OpenAI-API-compatible provider with endpoint https://ai.topxea.com/v1, your key and the model id.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-dify · Updated: 2026-09-19

Dify's OpenAI-API-compatible model provider takes an endpoint URL, a key and a model name per model. Each TopxAI model you want in Dify is one entry.
Add a model
Settings → Model Provider → OpenAI-API-compatible → Add model.
Model Type: LLM. Model Name: claude-sonnet-5-5 (exactly as in the catalogue).
API Key: a TopxAI key on the Auto route. API endpoint URL: https://ai.topxea.com/v1.
Completion mode: Chat. Model context size: the model's window (1050000 for GPT-6.1 Sol, 1000000 for Claude Sonnet 5.5 and Kimi K3, 500000 for Grok 4.7). Upper bound for max tokens: the model's output limit.
Function calling: Tool Call, for agent nodes. Vision: on for the Claude and GPT models, off for GLM-5.3-Abliterated (text only).
Save; the model appears in the picker of every app.
Repeat for gpt-6.1-sol, grok-4.7, kimi-k3 and GLM-5.3-Abliterated.
Images
Add gpt-image-2.5-sunburst with Model Type: Text to Image if your Dify version lists that type for the compatible provider; otherwise call /v1/images/generations from an HTTP Request node with the same key.
Workflows and cost
Dify sends the prompt template, the knowledge-base chunks and the conversation with each LLM node. All of it is input tokens at the model's price on the route the key uses; the usage log lists each request with its route and charge.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## n8n with TopxAI: an OpenAI credential with a base URL

> Create an OpenAI credential in n8n with base URL https://ai.topxea.com/v1 and a TopxAI key, then use any catalogue model in the Chat Model and AI Agent nodes.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-n8n · Updated: 2026-09-19

n8n's OpenAI credential has a Base URL field, which is all TopxAI needs. The Anthropic credential has one too.
Credential
Credentials → Add credential → OpenAI.
API Key: a TopxAI key on the Auto route. Base URL: https://ai.topxea.com/v1.
Save. n8n tests the credential by listing /v1/models.
For Claude through the Messages API: Anthropic credential, key the same, base URL https://ai.topxea.com.
Nodes
OpenAI Chat Model (for AI Agent, Basic LLM Chain and the other LangChain nodes): choose the credential, then pick the model from the list n8n fetched or type the id (claude-sonnet-5-5, gpt-6.1-sol, grok-4.7, kimi-k3, GLM-5.3-Abliterated).
OpenAI node, Message a model operation: the same credential and ids; Generate an image with gpt-image-2.5-sunburst or gpt-image-2.5-flare.
Anthropic Chat Model: the Anthropic credential and claude-sonnet-5-5 or claude-opus-5-5.
Notes
Operations that call endpoints TopxAI does not serve (audio transcription, assistants, files) fail with 404; keep those on the provider's own credential.
The AI Agent node sends tool definitions and memory with each turn; all of it is input at the model's price. The usage log at TopxAI shows every call the workflow made.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## llm CLI with TopxAI: extra-openai-models.yaml

> Register TopxAI models in llm’s extra-openai-models.yaml with api_base https://ai.topxea.com/v1, store the key with llm keys set, and prompt from the shell.

Section: Integrations · URL: https://ai.topxea.com/docs/use-topxai-with-llm-cli · Updated: 2026-09-19

Simon Willison's llm reads extra OpenAI-compatible models from a YAML file in its config directory. Each TopxAI model is one entry.
Register the models
llm keys set topxai # paste a TopxAI key on the Auto route
cat > "$(dirname "$(llm keys path)")/extra-openai-models.yaml" <<'EOF'
- model_id: claude-sonnet-5-5
model_name: claude-sonnet-5-5
api_base: https://ai.topxea.com/v1
api_key_name: topxai
supports_tools: true
vision: true
- model_id: gpt-6.1-sol
model_name: gpt-6.1-sol
api_base: https://ai.topxea.com/v1
api_key_name: topxai
supports_tools: true
vision: true
- model_id: kimi-k3
model_name: kimi-k3
api_base: https://ai.topxea.com/v1
api_key_name: topxai
supports_tools: true
EOF
llm models | grep -i topxea
api_key_name points at the key stored with llm keys set, so the YAML holds no secret. model_id is the name you use on the command line; model_name is what is sent to TopxAI. They can differ (model_id: sonnet) if you want a short alias.
Prompt
llm -m claude-sonnet-5-5 "Say hello in one sentence."
llm -m gpt-6.1-sol -s "Answer in JSON" "List three ports of Portugal"
cat main.go | llm -m kimi-k3 "Explain this file"
llm logs -n 1 shows the last request and response; the charge is in the TopxAI usage log.
Responses API
Add responses: true to a GPT entry to send it through /v1/responses instead of Chat Completions; TopxAI serves both for the GPT models.
If it fails
401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
The model works in curl but not in the tool: that page lists the usual causes, one per tool.

## Shared pool, official line and auto route

> Same models, different routing and price: what each API-key route means and how Auto route picks one for you.

Section: Routes and pricing · URL: https://ai.topxea.com/docs/shared-pool-official-line-and-auto-route · Updated: 2026-09-18

Every API key belongs to one route, the Group field when you create a key (Edit changes it later). The route decides how traffic reaches the provider and which fixed USD price applies; the models are the same.
The routes
Claude, OpenAI and Grok each have two routes:
Shared pool (claude-shared, openai-shared, grok-shared): 50% of list price.
Official line (claude-official, openai-official, grok-official): 90% of list price. If the official line has no dedicated channel for a model, the shared pool serves it at the official price and the log records fallback_group.
Claude routes sell claude-opus-5-5, claude-sonnet-5-5 and claude-fable-5-1; OpenAI routes sell gpt-6-astra and gpt-6.1-sol; Grok routes sell grok-4.7, plus grok-imagine-video-1.5 on the official line only, billed per second.
Three lines have one route and no shared pool:
Kimi: kimi-official, kimi-k3 at 80% of list price.
Jev (TypeSafe's System One model): typesafe-official, 107% of TypeSafe's list price, via POST /v1/systemone. Model jev-1.14.0 (aliases jev-latest, jev-preview bill the same): $0.04494 per million input tokens, output $0.
GLM: z-official, a private deployment of a fine-tuned GLM 5.3, text only, priced above the base model's list price.
Image models (gpt-image-2.5-sunburst, gpt-image-2.5-flare) sit on the image route, priced per image.
Prices differ per lane (input, output, cache read, cache write), and OpenAI and Grok add a long-context tier from 272,001 and 200,000 input tokens. Expand a route's model-count button in the Group list for its USD per 1M tokens table.
Two refusals happen before anything is forwarded or charged, both HTTP 403 permission_denied: a model outside the catalogue gets "Model is not offered by this service"; a model your route does not sell gets "Model is not available on this API key route".
Auto route
Pick Auto route and one key covers the catalogue. Per request the relay lists the routes that sell the model (shared pool, official line, then single-route lines) and takes the cheapest one that can serve it now, by input price then output; image and video compare their cheapest size or resolution. Ties keep shared first. Only Claude, OpenAI and Grok text models have a real choice.
A route with no configured price is skipped; if none is left, the request gets the same 403 as above. If no priced route has an enabled channel, the first priced candidate is tried and fails with HTTP 503 upstream_unavailable, "The model provider is temporarily unavailable. Please retry." Nothing is charged either way.
Today every Claude, OpenAI and Grok text model resolves to its shared pool. The usage log shows the concrete route next to the key name; auto_route: true appears only in the API's log record, never auto as a route.
For a dedicated official-price line, write to support@topxea.com.

## How requests are billed

> Billing units, long-context tiers, the up-front reservation and what happens to it when a request fails.

Section: Routes and pricing · URL: https://ai.topxea.com/docs/how-requests-are-billed · Updated: 2026-09-24

Every request is priced from one fixed USD tariff: the model on your key's route, as on the Models page (Auto route keys pay the route picked per request). The tariff is captured before forwarding; later price edits never touch a request in flight. A model with no price on your route is refused with HTTP 400 invalid_request, "model ... has no configured USD price for this API key route".
Units
Text models bill per million tokens, one price per lane: input, output, cache read and cache write (Claude also prices a 1-hour cache write). Cached tokens are not regular input; a lane with no price of its own bills as input. Jev bills input only, output $0.
Image models bill per image: 1k (up to 1024x1024) or 2k (up to 2048x2048). An omitted or auto size is pinned to 1024x1024; a larger output than requested settles at its class. Both gpt-image-2.5-* models cost $0.03 per 1K image and $0.05 per 2K, times n.
grok-imagine-video-1.5 bills per second: $0.05 at 480p (default), $0.10 at 720p, $0.20 at 1080p, for 1 to 15 seconds (default 8).
Long-context tiers
OpenAI and Grok models carry a long-prompt tariff: once total input context (prompt plus cache tokens) reaches 272,001 tokens (gpt-6-astra, gpt-6.1-sol) or 200,000 tokens (grok-4.7), the whole request settles at the long lanes, not just the excess. Claude, Kimi, GLM and Jev have no tier; the tier is decided at settlement.
Peak hours
DeepSeek models (deepseek-flash, deepseek-v4-pro) carry two complete tariffs. The peak tariff applies to a request accepted during the provider's peak hours: 09:00-12:00 and 14:00-18:00 Beijing time (01:00-04:00 and 06:00-10:00 UTC; the pricing pages show these windows in your own time zone), Monday to Friday, except Chinese public holidays; every other hour, weekends and public holidays are off-peak, at half the peak rates. The tier is frozen when the relay accepts the request, so a long stream that crosses the boundary keeps the tier it was quoted. The usage-log row says which tier applied and the billing details show the lanes that were charged.
Reservation and settlement
Each request first reserves an estimate at that tariff: prompt tokens plus your output cap (max_tokens, max_completion_tokens on Chat Completions, max_output_tokens on the Responses API; 8,192 when unset). Without a cap the model may still write up to its output limit; the reserve stays at 8,192 and settlement charges what it wrote. Image and video reserve the whole job: per-image fee times n, or per-second fee times duration. If balance or key quota cannot cover the estimate, the request is refused with HTTP 402 before forwarding:
{
"error": {
"message": "Insufficient quota. Top up your balance and try again. (request id: ...)",
"type": "insufficient_quota",
"code": "insufficient_quota",
"param": null
}
}
On /v1/messages the body is {"type":"error","error":{"type":"billing_error","message":"..."}}.
At the end, actual usage is priced and the difference credited back, or the extra charged if usage exceeded the estimate. An abandoned reservation is refunded when its 5-minute lease expires.
An upstream failure releases the whole reservation and logs an error row with no charge; the relay retries once on another channel, charging only the final attempt. A stream that has already produced output is different: if it breaks off, or the provider sends an error partway through, the output produced so far is charged once, on the provider's reported usage or the counted text plus the estimated prompt, and the rest of the reservation is released (what your client receives). Other exceptions: image, video and Jev (/v1/systemone) requests keep running up to 4 minutes after your client disconnects and are settled, not refunded, because the provider bills an accepted job. A video that fails, expires or comes back shorter is refunded afterwards (in full, or the missing seconds) as a Refund row. A request Grok rejects on its child-safety check is refunded, then charged a separate $0.05 fee in its own row marked Violation Fee, also when the rejection arrives partway through a stream.

## Reading your usage log

> What each row of the usage log shows, how to filter it, and what is never recorded.

Section: Routes and pricing · URL: https://ai.topxea.com/docs/reading-your-usage-log · Updated: 2026-09-18

Usage logs opens on today's Consume rows, one per successful request. Pick All types or another type (Top-up, Manage, System, Error, Refund, Login) in the type selector for the rest.
What a row shows
Time and Type.
Token: the key name, then the billed route (for example claude-shared). An Auto route key shows its concrete route, with no auto flag.
Model: what you requested.
Stream: Stream or Sync, plus output speed in tokens per second.
Tokens: input / output, plus Cache Read, Cache Write (5m), Cache Write (1h) or Cache Creation lines when cached.
Cost: the USD actually charged.
Latency: first token and duration.
Details: the route and its input / output price per million tokens, plus +N for further notes (long context, cache prices) that open in Details.
The Details panel starts with Request ID (quote it to support), Upstream Request ID, Token, Group and Response Time (with FRT for streams). Billing Details names the route, model and unit (USD per 1M tokens, image or second), splits Total input into Uncached input, Cache Read and Cache Write, then lists Item, Quantity, Unit price and Amount, a Billing precision adjustment line when rounding moved the total, and Wallet charged. A long-context request also states the threshold and its input tokens. Stream Status appears only when a stream ended abnormally, with End Reason, Soft Errors and End Error (stream_terminated).
A Refund row reads Billing refund; its Refund Details give the amount, original request, task id and reason. Failed, expired or shorter videos refund this way.
An Error row carries no tokens and no charge, only the HTTP status and a fixed error category. A retried request leaves an Error row beside its final Consume row; only that attempt is charged.
Login rows record the login method, IP address and user agent under Login Info.
Filters
The bar has quick ranges (24h, 7d, 14d, 30d), a date picker, Model Name, Group (a route id such as openai-official) and the type selector. More adds Token Name, Request ID and Upstream Request ID. Search or Enter applies; Reset returns to today's Consume rows. Hide masks key names, routes, the totals and the Group and Token Name boxes.
Below the filters, Net consumption sums the selected range next to RPM and TPM; Gross charges and Billing refunds appear when the range contains a refund.
What is never in the log
Rows hold metadata only: model, route, token counts, charge, latency, request ids, status. Prompts, completions, system prompts, tool calls, images, files and upstream error bodies are never written, and the relay keeps them nowhere else. Rows are pruned after the retention window (30 days by default), and there is no export button.

## Jev (TypeSafe System One)

> What Jev 1.14 returns, how to call POST /v1/systemone with text or images, Box questions, the one-line setup for a TypeSafe key, and the price.

Section: Models · URL: https://ai.topxea.com/docs/jev-typesafe-system-one · Updated: 2026-10-16

Jev is TypeSafe's System One model. It does not write text: you send a state and a map of typed questions, it returns typed answers with probabilities. The catalogue id is jev-1.14.0, which replaced jev-1.13.0 on 2026-10-16 at the same price. jev-latest and jev-preview are accepted as aliases; TopxAI bills them as jev-1.14.0 and sends jev-1.14.0 to TypeSafe, so the response's model field always reads jev-1.14.0. On TypeSafe's own API jev-latest still pointed at 1.13 that day; through TopxAI every name reaches the same model. jev-1.13.0 is no longer served here: a request for it gets a 403, and if you tuned thresholds on 1.13, check them again on 1.14. A key whose allowed-model list names jev-1.13.0 needs jev-1.14.0 added to it; jev-latest and jev-preview count as jev-1.14.0 there.
The four question types
noul: a yes/no question. The answer is the probability of yes: near 1 yes, near 0 no, near 0.5 undecided. There is no separate confidence.
choice: one option from a map you define, up to 255. The answer carries choice, confidence and probabilities over every option.
score: a position on an ordered scale of 2 to 10 levels you describe in words; probability-weighted, so it can fall between levels. The answer carries score, confidence, legend and probabilities.
box: where something is in an image. instructions names the target and the image ("the coffee mug in photo"), there are no criteria, and the answer is box with top, bottom, left and right as fractions of the image's height and width, plus confidence. Box needs an image in the request and Jev 1.14.
Questions in one request are independent and run in parallel, so put every question you might need into one call. The question id is never sent to the model; write the whole question in instructions.
Request and response
curl -X POST https://ai.topxea.com/v1/systemone \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"state": "I have asked three times now. Can I please just talk to a real person?",
"model": "jev-1.14.0",
"questions": {
"is_human_escalation": {
"type": "noul",
"instructions": "Is the customer asking for a human agent?"
}
}
}'
{
"model": "jev-1.14.0",
"answers": {
"is_human_escalation": { "type": "noul", "noul": 0.99 }
},
"usage": { "input_tokens": 296, "output_tokens": 20 }
}
The body is identical to TypeSafe's own API; only the base URL and key are TopxAI's. POST /v1/system_one is accepted as a second spelling of the same endpoint. Another catalogue model on this endpoint gets a 400.
Images and Box
Images can go anywhere text can: in the state, in a question's instructions, or in its criteria. List each image once in a top-level assets map under a reference string, then write that reference where the image belongs. This request finds a mug in a photo and asks whether one is there at all, because a Box answer is always a box, even when the target is missing:
{
"model": "jev-1.14.0",
"state": { "photo": "3f9c2e1a-kitchen" },
"assets": {
"3f9c2e1a-kitchen": { "type": "image", "format": "jpg", "data_base64": "/9j/4AAQSkZJRg..." }
},
"questions": {
"mug_visible": { "type": "noul", "instructions": "Is there a coffee mug in `photo`?" },
"mug": { "type": "box", "instructions": "the coffee mug in `photo`" }
}
}
{
"model": "jev-1.14.0",
"answers": {
"mug_visible": { "type": "noul", "noul": 0.94 },
"mug": { "type": "box", "box": { "top": 0.25, "bottom": 0.82, "left": 0.44, "right": 0.84 }, "confidence": 0.92 }
},
"usage": { "input_tokens": 1618, "output_tokens": 52 }
}
To crop or draw the box, multiply left and right by the image width in pixels, top and bottom by its height.
Images can also travel as file parts of a multipart/form-data request, which is what TypeSafe's SDKs send: the first part is named request and holds the JSON body, each image is its own part, and the asset names its part with "part": "<part name>" instead of data_base64. Multipart skips base64's extra third. Both forms work through TopxAI, and so does the SDKs' zstd body compression.
TypeSafe calls images and Box "Dreamer-ready": fine for prototypes, not yet up to its production standard, and the format, answers and limits can change between releases. On its own API every such request needs the header TypeSafe-Danger-Zone-Images: true. TopxAI adds that header whenever a request carries assets or a Box question, so you can leave it out; sending it does no harm.
TypeSafe's image limits apply unchanged: PNG or JPEG stills only, at most 1568 pixels on each side, between 78,400 and 2,458,624 pixels in total, at most 16 MiB per file. Its docs give 256 pixels as the smallest side, but in our tests on 2026-10-16 any side under 280 pixels was rejected (279 × 400 failed, 280 × 400 passed), so keep both sides at 280 or more. An image outside the limits is rejected, never resized, and one bad image fails the whole request. Scale images so the longest side is at most 1568 pixels and rotate the pixels upright before sending; the API strips EXIF and ignores its orientation. Each place a reference appears adds the image again, so when several questions look at the same picture, put it in the state once and point to it by path.
Limits and errors
Before any quota is reserved, the relay checks the body itself: model, state and a non-empty questions object, state and questions together at most 1 MiB, the whole body (base64 images included) at most 32 MiB, and assets, when present, an object of at most 1,024 images whose reference strings are non-empty, at most 1,024 bytes each and 64 KiB together. A body over 32 MiB gets a 413; anything else that fails these checks is a 400. A malformed multipart body (the first part not named request, a repeated part name, a file part that is not PNG, JPEG or untyped bytes) is a 400 too.
When TypeSafe rejects a request with a 400, 413 or 422 (an unreadable image, an asset nobody references, a request over the context length), you get its detail as written and the reservation is released. A 429 is passed on with its Retry-After; back off and retry. A provider outage or a rejected upstream key comes back as a 503.
The context limits are TypeSafe's defaults: 64k tokens per request and 32k for the state plus any one question, image tokens included. TypeSafe's long-context header is not forwarded.
One-line setup
Create a key on the API keys page. Under Group, pick Official line in the TypeSafe section (its note reads Official key · 107% of list price). An Auto route key can call Jev too, since Jev has only one line, but the setup command below is shown only for keys on the TypeSafe line. Open the full-key popover in the key's row, or the key detail drawer, and look for One-command setup for Jev:
curl -fsSL https://ai.topxea.com/install/typesafe.sh | sh -s -- --key sk-xxxx
The script installs the typesafe-ai agent skill, writes TYPESAFE_BASE_URL=https://ai.topxea.com and TYPESAFE_API_KEY=<your key> to ~/.config/topxai/typesafe.env, adds a block to ~/.zshrc and ~/.bashrc (whichever exist) that sources that file, and merges the same two variables into the env of ~/.claude/settings.json when that file exists. Then it sends one test request: a real, billed call to jev-latest with one noul question. A 401 means the key was rejected.
Leave out --key and the script takes TOPXAI_API_KEY from the environment, then the key saved by an earlier run, and only then asks for the key in the terminal without echo. With no key at all it still installs the skill and writes the config, and skips the test. --no-skill and --no-verify skip those two steps, --base-url points at another relay origin, -h prints the help. Running it again is safe: every file it touches is rewritten in place, and settings.json gets a timestamped .bak copy first.
The official SDKs (pip install typesafe-sdk, npm install @typesafe-ai/sdk) read TYPESAFE_BASE_URL and TYPESAFE_API_KEY and call /v1/systemone themselves; TYPESAFE_DEFAULT_MODEL picks the model. Images and Box need Python SDK 0.7.5 or JavaScript SDK 0.7.0 (Node.js 22 or newer).
Price
$0.04494 per 1M input tokens, 107% of TypeSafe's list price of $0.042. Output tokens are free. Images have no separate charge: their tokens are input tokens at the same price, and usage.input_tokens includes them. TypeSafe has not published how it counts image tokens yet; in our measurements on 2026-10-16 an image cost ceil(width / 28) × ceil(height / 28) × 2 tokens for each place its reference appears, so an 800 × 600 photo is 1,276 tokens and a full 1568 × 1568 image 6,272, about $0.00028. The charge is settled from the provider's usage.input_tokens; if a response carries no usage, the estimate reserved before the call (text plus that image arithmetic) is charged.
Known weak spots
From TypeSafe's own docs:
It answers the question you wrote, not the one you meant.
It is not a calculator, and it reads dates as text.
Double negatives, multi-hop questions and irrelevant state cost accuracy.
Contradictory criteria make answers unreliable.
It is not trained to generate text.
English is its main language; CJK input is handled "but not equally well".
Images and Box are experimental, and there is no recommended Box confidence threshold yet. A target a few dozen pixels wide in a large image can be missed; crop to the region first.
Do not reuse a threshold across question types.
Questions? Use the help button at the bottom right of the site or write to support@topxea.com.

## GLM-5.3-Abliterated

> A fine-tuned GLM 5.3 on a private deployment: text only, 1M-token context, three reasoning modes, priced above list, and covered by a compliance notice.

Section: Models · URL: https://ai.topxea.com/docs/glm-5-3-abliterated · Updated: 2026-09-18

GLM-5.3-Abliterated is a commercially fine-tuned variant of Z.ai's GLM-5.3, served from a private deployment rather than the provider's official API. The tuning adds vertical business skills and removes the built-in refusal alignment (that is what "abliterated" means). It is the one catalogue model that is not the provider's own line, and it is labelled as a private deployment everywhere it appears.
The model id is case-sensitive. Send it exactly as GLM-5.3-Abliterated. An id in the wrong case is not in the catalogue, and the relay answers 403 with the message "Model is not offered by this service".
Route and endpoint
The model is sold on one route only, shown on the API keys page as GLM with the line name private deployment (route id z-official). There is no shared pool behind it, so a request on this route goes only to its dedicated upstream. An Auto route key dispatches the model to the same place.
Send requests to POST /v1/chat/completions:
curl https://ai.topxea.com/v1/chat/completions \
-H "content-type: application/json" \
-H "Authorization: Bearer sk-xxxx" \
-d '{"model":"GLM-5.3-Abliterated","messages":[{"role":"user","content":"Say hello in one sentence."}]}'
The model field of the response says GLM-5.3-Abliterated, not the upstream's internal id. The same holds when you stream: every chunk, and the final chunk that carries usage, names the catalogue model.
/v1/messages also answers for this model: the relay converts the request to Chat Completions, but without the attachment rewrite described below.
Text only
This deployment takes text and tool calls only. If a message carries an image, audio, file or video part, the relay does not fail the request with a 400. It replaces each such part with one text part that reads:
[Attachment omitted: this model accepts text only.]
The rest of the message is forwarded as sent, and the model sees the note in its context. Some clients send a small test image with their "add model" probe; with this rewrite the probe still passes. The rewrite is wired into /v1/chat/completions only, one more reason to send this model through that endpoint. On /v1/messages an image or document block reaches the deployment and the request fails with a 400.
The relay also drops, for every model but relevant here because this upstream rejects them, a tool_choice with no tools and empty containers such as "tools": [], "logit_bias": {} or "stop": []. Real tools, biases and stop sequences are forwarded untouched.
Context and output
The context window is 1,000,000 tokens, prompt and output together. /api/pricing publishes it as context_window and gives 131,072 as max_output, the output limit of Z.ai's own GLM-5.3. That figure is for clients that reserve room for the answer inside the window; the relay does not cap requests with it. The deployment accepts max_tokens or max_completion_tokens up to 999,990, though an answer that long only fits after a short prompt, and rejects 1,000,000 or more with a 400. A request without a cap is forwarded without one.
Reasoning
The model reasons before every answer. Set the depth with reasoning_effort. The deployment has three modes, low, high and max, and maps the standard values onto them: none, minimal and low run as low, medium and high as high, xhigh and max as max. A request that sets no effort runs as max. The nested form "reasoning": {"effort": "low"} works the same way.
Reasoning cannot be switched off. none runs as low and leaves the reasoning text out of the response; the tokens are still spent.
Z.ai's own API switches reasoning with "thinking": {"type": "enabled"} or {"type": "disabled"}, and this deployment rejects that object with a 400. The relay rewrites it before forwarding: disabled, and the boolean "thinking": false, become reasoning_effort: "none"; enabled is dropped because reasoning is on anyway. If the request also sets reasoning_effort or a reasoning object, that setting decides and the switch is dropped.
The reasoning text arrives in choices[].message.reasoning, or choices[].delta.reasoning when you stream, not in reasoning_content. Its tokens are counted in usage.completion_tokens, listed on their own as usage.completion_tokens_details.reasoning_tokens, and billed at the output price. To leave the text out of the response, send "reasoning": {"effort": "high", "exclude": true}: the model still reasons and the tokens are still billed. include_reasoning is not forwarded.
Structured output
A response_format of type json_schema works, with strict true or false: the deployment holds the answer to the schema while it writes it. That enforcement goes wrong for some string formats. In our tests (2026-10-16, reasoning_effort low), when the prompt did not say what a field should contain, a field with "format": "uri" filled up with run-together letters until the answer hit max_tokens, so the JSON came back cut off and every token up to the cap was billed; this happened in 9 of 12 tries, and "format": "email" did the same in 1 of 10. Fields with "format": "date" or "date-time" came back in the right shape with the wrong date: asked for Ada Lovelace's birth date, the model wrote 1046-10-14 instead of 1815-12-10, and 7 of 10 tries went wrong this way.
So before forwarding, the relay takes uri, email, date and date-time out of the schema and writes each into its field's description as {format: "uri"}. The deployment then only holds the field to a string. Prompts that asked for the value got a correct URL, address or ISO date 16 times out of 16, with or without the format. Prompts that left the field open often got a sentence of prose there instead; 2 of 40 such answers still ran to max_tokens and 1 had a wrong ISO date, while the same prompts with no format at all ran to max_tokens in 1 of 16. Other formats are forwarded as written. The two we also tried with open prompts, hostname and uri-reference, came back in the right shape with meaningless content (a hostname of 8, a uri-reference of Ada_Lovelace). Say in the prompt what each field should hold, and check the values in your own code after parsing.
Price
Per 1M tokens on the private deployment: input $4.00, output $7.00, cache read $0.40. That is above the Z.ai list price of the base GLM-5.3 (input $1.40, output $4.40, cache read $0.26, verified 2026-09-18). On the home page price list that reference row is labelled Provider list price · GLM-5.3, with the percentage above list next to each lane; the source is https://docs.z.ai/guides/overview/pricing.
Compliance notice
This notice appears in small print wherever the model is described, and it applies to every request:
Because fine-tuning may affect safety alignment, the model may produce biased, offensive or locally unlawful content. Users bear full responsibility for compliance and legal consequences.
The AI Acceptable Use Policy covers this line exactly as it covers Claude, OpenAI, Grok, Kimi, DeepSeek and Jev. Removing the refusal alignment does not remove the policy. If you are unsure whether a use case is allowed, ask through the help button at the bottom right or support@topxea.com before building on it.

## Image generation

> gpt-image-2.5-sunburst and -flare: the two endpoints, the 1K and 2K per-image prices, how the size tier is chosen, and where the image link comes from.

Section: Models · URL: https://ai.topxea.com/docs/image-generation · Updated: 2026-09-18

Two image models are in the catalogue, both from OpenAI's GPT Image 2.5 family and both sold per image:
gpt-image-2.5-sunburst: the highest-fidelity model for generation and editing.
gpt-image-2.5-flare: the faster one, same endpoints and same prices.
gpt-image-2 was retired on 2026-09-18 in favour of these two.
Route and endpoints
Image models are sold on one route, shown on the API keys page as OpenAI with the line name Image generation (route id image). An Auto route key sends them there as well.
Two endpoints, both with Authorization: Bearer <key>:
POST /v1/images/generations (JSON body)
POST /v1/images/edits (multipart form with the source image)
POST /v1/images/variations is not implemented and answers 501 with "This API is not implemented".
curl https://ai.topxea.com/v1/images/generations \
-H "content-type: application/json" \
-H "Authorization: Bearer sk-xxxx" \
-d '{"model":"gpt-image-2.5-flare","prompt":"A lighthouse at dawn, watercolour","size":"1024x1024","n":1}'
Price and size tiers
Both models: $0.03 per 1K image, $0.05 per 2K image. The tier is chosen from the pixel count of the size you request, written as WIDTHxHEIGHT with a plain x:
up to 1024x1024 pixels (1,048,576) is 1K;
up to 2048x2048 pixels (4,194,304) is 2K;
anything larger, or an edge above 4096, is refused before the request is forwarded.
An omitted size or "size": "auto" is pinned to 1024x1024 before pricing and forwarding, so the provider cannot render a larger image than the one you are billed for. If the provider still reports an output size of a higher tier, the fee is raised to that tier; a smaller output keeps the quoted fee. quality is validated but does not change the fee; only the size tier does.
n may be 1 to 128 and multiplies the fee. The full amount (fee times n) is reserved from your wallet before the request is forwarded, so a large n needs that balance up front. On settlement the count is taken from the number of images actually returned, with one exception: a stream: true request whose client disconnects before the stream ends is billed for the requested n, so dropping after the first completed image does not buy one image.
The priced fields model, size, n and quality are accepted once each, in their exact spelling; Size is refused, and a multipart form that repeats one of them is refused. The messages you will meet:
n must be an integer between 1 and 128
field "Size" is not accepted; use "size"
field "size" must be provided once
unsupported image size "<size>"
image size "<size>" exceeds the largest sold class (2K)
A size written with the multiplication sign × is refused with a message asking for a plain x.
An accepted image request is settled even if your client disconnects while waiting, because the provider bills the job whatever the client does.
Where the image link comes from
Every url in the response is replaced by a link on this relay:
{
"data": [{ "url": "https://ai.topxea.com/v1/images/content/<token>" }]
}
The token is an encrypted, signed claim that hides the supplier's storage address and credentials. You can put the link straight into an <img> tag: fetching it needs no API key. It expires one hour after the response was issued; after that the link answers 404 with the code image_unavailable and the message "Generated image is unavailable or the link has expired". Download the file within the hour if you need to keep it. Base64 payloads (b64_json) are passed through unchanged.
Three limits on fetching the link. The relay fetches at most 4 generated images at a time across the whole site; a fifth simultaneous fetch gets the same 404 image_unavailable and should be retried, which a page with many <img> tags can trigger. Only image/png, image/jpeg, image/webp and image/gif are served (sniffed from the bytes; anything else is a 404), with Cache-Control: private, max-age=300. A single fetched image is limited to 32 MiB.

## Video generation

> grok-imagine-video-1.5: submit a job, poll it, per-second prices by resolution, refunds on failure, and how forgotten jobs are refunded after 24 hours.

Section: Models · URL: https://ai.topxea.com/docs/video-generation · Updated: 2026-09-18

grok-imagine-video-1.5 is xAI's text-to-video and image-to-video model, the only video model in the catalogue. It is billed per second of video, by resolution.
Route and endpoints
Sold only on the Grok official line, shown on the API keys page as Grok, line official line (route id grok-official). An Auto route key sends it there too. All calls use Authorization: Bearer <key>.
POST /v1/videos/generations submits a job.
GET /v1/videos/{request_id} returns the job's status.
GET /v1/videos/{request_id}/content streams the finished clip.
Both GET endpoints go straight to the channel that accepted the job, so any valid key of the same account can poll; it need not be on the grok-official route.
Submitting a job
curl https://ai.topxea.com/v1/videos/generations \
-H "content-type: application/json" \
-H "Authorization: Bearer sk-xxxx" \
-d '{"model":"grok-imagine-video-1.5","prompt":"A paper boat drifting down a rain gutter","duration":8,"resolution":"720p"}'
duration is 1 to 15 seconds (default 8). resolution is 480p, 720p or 1080p (default 480p). model, duration and resolution decide the price, so each is accepted once, in that exact spelling, and the validated values are written into the forwarded body. Other fields (image and reference_images for image-to-video, generate_audio, aspect_ratio) pass through as sent; their shape is xAI's request schema.
A failed validation is a 400 with one of these messages:
duration must be between 1 and 15 seconds
resolution must be one of 480p, 720p or 1080p
field "Duration" is not accepted; use "duration"
field "duration" must be provided once
The reply carries the provider's request_id and the model name. Keep the id: both GET endpoints need it, and only the account that created the job can use it. An unknown id, or another account's id, answers 404 with "video job not found".
Price
Per second of requested video:
$0.05 at 480p
$0.10 at 720p
$0.20 at 1080p
The 8-second request above costs 8 x $0.10 = $0.80. The home page price list shows xAI's published $0.08 per second beside these in a row labelled Provider list price, with the difference per resolution.
The whole fee (requested seconds times the per-second price) is charged the moment the provider accepts the job. The provider bills an accepted job whether or not your client stays connected, so disconnecting does not cancel the charge. The charge appears on the Usage logs page with the resolution and the seconds.
Polling and refunds
Poll GET /v1/videos/{request_id}. The status document comes back as the provider sent it. pending, queued, processing, running and in_progress mean keep polling; done, failed and expired are final. The relay reads video.url and video.duration from a done document when they are present.
The first poll that sees a final status settles the job; later polls do not settle it again:
failed or expired: the whole fee is refunded.
done with a video.duration shorter than requested: each whole undelivered second is refunded at the same per-second price. A fraction of a second counts as a full second, and a done document without video.duration is treated as fully delivered. The credit never exceeds the fee that was actually charged.
A refund is a row of type Refund on the Usage logs page, and the Billing refunds stat at the top sums them.
If you stop polling, a background reconciler checks pending jobs for you, from ten minutes after submission and at least five minutes apart. When the provider no longer knows a job (it answers 404) and the job is over 24 hours old, the reconciler refunds it as expired. A 404 that you meet while polling yourself only returns a normalized error and refunds nothing; leave that job to the reconciler instead of retrying.
Polls count like any other request against the request rate limit when one is enabled, so a tight loop can get 429 rate_limited. Leave a gap between polls.
Fetching the clip
When the finished clip is served as a path under /v1/videos, fetch it through GET /v1/videos/{request_id}/content with your key. The relay fetches it from the channel that ran the job and forwards it to you, passes Range through, and returns the provider's 206 with its Content-Range and Accept-Ranges. The response carries Content-Disposition: inline; filename="<request_id>.mp4" and Cache-Control: private, max-age=600. One file is capped at 512 MB; a larger one answers 502 with "The video file is larger than this relay serves". It arrives as video/mp4 unless the provider says otherwise. If the channel that took the job has been disabled, both GET endpoints answer 503 with "The channel that created this video job is unavailable".

## Top up with a card

> Add USD credit with a card, Apple Pay, Google Pay or a local e-wallet; the checkout runs on topxea.com through Waffo.

Section: Payments and credit · URL: https://ai.topxea.com/docs/top-up-with-a-card · Updated: 2026-09-18

Where you pay
TopxAI does not take card details. When you pick Card / local payment on the Wallet page and click Continue to secure checkout, TopxAI creates an order and sends you to a payment page on topxea.com, TopXEA's main site. That page opens Waffo, the merchant of record, which handles tax and takes cards, Apple Pay, Google Pay and local e-wallets. No TopXEA account is needed; the link carries an access key.
Steps
On Wallet, in the Add credit panel, pick Card / local payment under Payment method.
Enter Amount (USD) or use a preset ($10, $25, $50, $100); one payment is $10.00 to $10,000.00.
Click Continue to secure checkout. On topxea.com, click Pay $25.00 with Waffo (showing your amount).
Pay, then click Return to TopxAI. Payment details opens for this order by itself and refreshes every 10 seconds while Pending.
How the balance arrives
Your credit is exactly the USD amount you entered; where tax applies, Waffo's total is higher, but tax is not added to your credit.
Returning from checkout credits nothing by itself. After Waffo confirms the payment, topxea.com sends TopxAI a signed notice; TopxAI credits only when the provider, the main-site order number, the exact cent amount and the currency (USD) all match. Cards usually confirm in seconds. TopxAI also polls the main site every minute, so a late notice still lands. When done, the dialog reads "Payment verified. Credit added." and the order is listed under Statement.
Pending and expired orders
An order stays Pending until the Checkout expires time in Payment details, 60 minutes by default. Continue payment reopens the same page in a new tab. Do not start another order after paying; at five unexpired pending orders, a new checkout is refused and the page shows "Could not create checkout. Try again or contact support."
After the deadline the order turns Expired, Continue payment disappears, and the dialog reads "Checkout expired. If you already paid, we will keep checking the provider." A last-minute payment is still credited once the verified payment arrives; the status then changes to Success and the message to "Payment verified. Credit added." Expired orders are swept only every six hours, so click Check payment: it queries the main site at once, every 30 seconds at most.
If Waffo reports a refund or dispute after crediting, the order shows Review required in the statement (the payment details say Payment requires review, reason Refund reported) and support reviews it by hand. For that, for refunds, or if money left your account without credit, contact support with the Order ID: the help button at the bottom right of the site, or support@topxea.com. Per the User Agreement, applicable law and the verified payment status govern refunds.

## Pay with crypto

> Top up with USDT or USDC through a NOWPayments invoice: what to send, how long confirmation takes, and what happens if you send too little.

Section: Payments and credit · URL: https://ai.topxea.com/docs/pay-with-crypto · Updated: 2026-09-18

What you pay with
Crypto top-ups run through a NOWPayments hosted invoice for the USD amount only; you pick the coin and network on the NOWPayments page. The invoice uses a fixed rate, the NOWPayments service fee is not added, and your balance is credited in USD.
Steps
On Wallet, under Payment method, pick Crypto · USDT / USDC and enter Amount (USD), from $10.00 to $10,000.00.
Click Continue to secure checkout. It opens nowpayments.io.
Pick the asset and network, then send exactly the amount shown to the address shown, on that network.
Return through the NOWPayments link: Payment details opens by itself and refreshes every 10 seconds while Pending. Otherwise, open it from Statement with Details.
Confirmation timing
Credit is added only when NOWPayments reports Payment complete (finished) and received at least the amount requested. Until then, Provider status moves through Waiting for payment, Confirming payment, Payment confirmed and Processing payment. TopxAI never credits on confirmed or sending. Timing depends on the network and NOWPayments.
NOWPayments sends TopxAI a signed callback; TopxAI re-reads the payment from the NOWPayments API before crediting and rechecks pending orders every minute. Until the first callback, the dialog reads "Waiting for verified payment. You can safely leave this page." and Payment ID and Provider status read Not available yet. Check payment checks now, at most every 30 seconds; before a payment ID exists it may answer "Verification is delayed. Your order is saved and will be checked again." That is normal.
Underpaid, overpaid, expired
Underpaid: partially_paid, or finished with less received than requested, keeps the order Pending with "The payment amount is incomplete. Follow the provider instructions or contact support." No tolerance, no partial credit. Follow the NOWPayments page, or contact support with the Order ID. Continue payment reopens the same invoice while the order is pending and unexpired; there is never a second invoice for one order.
Overpaid: you are credited the USD amount ordered, not more.
Expired: the order turns Expired at the Checkout expires time (60 minutes by default); the NOWPayments invoice and rate quote have their own deadlines. A transfer that confirms later is still credited once NOWPayments reports it. Send only the coin, network, address and amount the invoice shows; under the User Agreement, any other transfer may not be credited and recovery is not guaranteed.
Failed or cancelled: the order shows Failed. If funds left your own wallet, contact support.
Refunded after crediting: the order shows Review required in the statement and Payment requires review (Refund reported) in the payment details; nothing is deducted automatically; support reviews it by hand.
Support: the help button at the bottom right of the site, or support@topxea.com.

## Gift cards and credit codes

> Buy a single-use credit code, redeem one on any account, and what the User Agreement says about refunds.

Section: Payments and credit · URL: https://ai.topxea.com/docs/gift-cards-and-credit-codes · Updated: 2026-09-18

What a gift card is
A gift card is a single-use redemption code worth the USD amount you pay. It is not added to the buyer's balance. Whoever holds the code redeems it on any TopxAI account, which gains the card's value. A purchased card has no expiry date; codes issued by an administrator may carry one.
Buy a gift card
On Wallet, in the Gift cards panel, click Buy a gift card.
Enter Card value (USD), from $10.00 to $10,000.00, or use a preset.
Under Gift card payment method, pick Card / local payment (on topxea.com through Waffo) or Crypto · USDT / USDC (NOWPayments).
Click Buy gift card · $25.00 and pay as for a top-up.
The code is issued only after the payment is verified. It then appears under My gift cards as Unused, with a copy button, and under Gift card code in the order's Payment details. A Redeemed, Disabled or Expired card shows only its first 8 characters.
Redeem a code
On Wallet, in the Add credit panel, scroll to Redeem a code under the checkout form.
Paste the 32-character code into Enter your code and click Redeem credit.
You see "$25.00 added to your balance." (your amount). The entry is listed in Statement as Redemption code.
Each code adds its value once. Submitting it again from the same account shows "This code already added $25.00 to your balance." and adds nothing. An expired, disabled, already used or mistyped code fails with one message: "Could not redeem this code. Check the code and try again. Retrying cannot add credit twice." TopxAI does not say which happened. Redemption is rate-limited per account and IP.
TopXEA also sells TopxAI credit codes on topxea.com. A code bought there shows on the order page after payment and is emailed to you; redeem it the same way.
Refunds
The User Agreement, section "Payments, credits and refunds", sets the position:
A top-up is credited only after TopxAI verifies the payment with the payment provider. Returning from checkout does not confirm receipt.
Underpaid, failed or refunded payments are not treated as successful top-ups.
For payment corrections or refund requests, contact support with the order identifier; applicable law and the verified payment status govern the outcome.
Unused credits do not expire while the account remains in good standing. They are forfeited if the account is terminated for a material breach of the User Agreement, or for wilful or repeated abuse under the Acceptable Use Policy.
Credit codes sold on topxea.com carry one more line: once redeemed, the credit stays in the account and cannot be refunded.
Support: the help button at the bottom right of the site, or support@topxea.com.

## Common error responses

> What each HTTP status and error code from the gateway means, and what to change before you retry.

Section: Troubleshooting · URL: https://ai.topxea.com/docs/common-error-responses · Updated: 2026-09-24

Errors share one shape. OpenAI-style endpoints return {"error":{"message":"...","type":"...","code":"...","param":null}}; /v1/messages returns {"type":"error","error":{"type":"...","message":"..."}}. The message ends with (request id: ...); the x-request-id response header carries the same id. Mid-stream, the status is already 200: the error is one data: {"error":...} event (event: error first on /v1/messages) and the stream ends without [DONE]. A /v1/responses stream that has started ends with response.failed instead when it breaks off or fails (see the last two sections). Support needs that id; prompts and responses are not stored.
401 authentication_error
Message: Invalid token. The key is missing, in the wrong header, disabled, expired, or its own Quota (USD) is spent to zero (a key with some quota left, but less than the request's estimate, gets a 402 instead). A 401 is about your key; failed upstream credentials surface as upstream_unavailable. Send it as Authorization: Bearer sk-....
403 permission_denied
The message names the check:
Model is not offered by this service: unknown id or wrong case (GLM-5.3-Abliterated, not glm-5.3-abliterated).
Model is not available on this API key route: the key's Group does not sell this model; create a key on Auto route.
This token has no access to model ...: the key's Model limits exclude it.
The service is not available in your region. or Your service region could not be verified. Please contact support.: regional access controls (code region_unavailable, no request id).
Requests from this account to models from this provider are paused until 2026-10-17 09:20 UTC because the provider rejected a request from this account for its content. Contact support if this is a mistake.: the provider behind Claude, GPT, Grok, Kimi, DeepSeek and the image and video models rejected one of the account's requests for its content, so for 24 hours the gateway refuses the account's requests to these models. Other models stay available. Email support@topxea.com if the rejection was a mistake.
402 insufficient_quota
Message: Insufficient quota. Top up your balance and try again. The gateway first reserves the prompt plus the output you allow (max_tokens, max_completion_tokens or max_output_tokens; 8192 when unset) against your balance and the key's Quota (USD), then settles on real usage. A positive balance means the reserve exceeded one of them: lower max_tokens, raise the key's quota, or use Add credit on Wallet.
429 rate_limited
The gateway's per-account limit (all your keys together) answers Request limit reached: successful requests are limited to M per N-minute window, or, counting failures too, Total request limit reached: requests are limited to M per N-minute window, failed requests included. Check that your requests are correct. The message follows your Accept-Language header (English, Chinese, Japanese, Russian or Spanish); without the header it uses the language saved on your account, and English when none is saved. A provider limit returns Rate limit exceeded. Please retry after a short delay. Wait the Retry-After seconds when present.
400 invalid_request
A provider rejection is returned as The request was rejected. Check the parameters and try again., never the provider's text. Gateway checks keep their message, such as duration must be between 1 and 15 seconds. A safety refusal is content_filtered and is not retried on another channel. Before forwarding a request to Claude, GPT, Grok, Kimi, DeepSeek or the image and video models, the gateway also checks it for jailbreak phrases and for terms that name prohibited content. A match is refused with content_filtered and a message naming the term: The request contains a term that is not allowed for this model: "<term>". Remove it and try again. Nothing is sent to the provider and nothing is charged. On /v1/chat/completions, GLM-5.3-Abliterated does not reject images: each attachment becomes [Attachment omitted: this model accepts text only.] and the text is forwarded.
404 and 5xx
An upstream 404 is model_not_found; internal_error is 500. upstream_unavailable is 502, or 503 for provider overload or no channel able to serve the model; upstream_timeout is 504. The gateway retried another channel where it could. A failed request is refunded to your balance (a stream that broke off or failed after producing output is charged for that output, see below); Billing refunds lists only later corrections, not this. Video differs: the fee is taken when the provider accepts the job; polling a failed, expired or shorter clip refunds it in full or pro rata, and that refund is listed there.
stream_interrupted
The provider's stream broke off or went silent before the answer was complete. You get the text that arrived, then one error instead of the normal end ([DONE], message_stop or response.completed): code stream_interrupted with type upstream_error on OpenAI-style endpoints, type api_error on /v1/messages. A /v1/responses stream ends with response.failed, whose error.code is server_error with the same message. The OpenAI and Anthropic SDKs raise an exception on this event. The text you already have is incomplete: retry the request. If the break came before anything reached you, the gateway first tries another attempt and, failing that, answers HTTP 502 with this code. A connection lost after the provider had finished its answer is a normal end.
Output produced before the break is charged once, on the provider's reported usage or, without one, on the counted text. A stream that produced no output is refunded and listed as a failed request, and so is a request you cancel before the first token. Cancel mid-answer and the output generated so far is charged.
An error partway through an answer
When the provider reports an error after part of the answer has streamed, you get the text that arrived, then the error as one event in the shape above, with its usual code (for example upstream_unavailable) and no normal end. A /v1/responses stream ends with response.failed, error.code server_error, carrying that message, also when the error comes before any text. Retry the request: the answer is incomplete.
Billing is the same as for a stream that broke off: the output produced before the error is charged once, and an error before any output is refunded and listed as a failed request. A retry never adds a second charge. One exception: a request Grok rejects on its child-safety check is refunded and charged the separate violation fee, even when the rejection arrives partway through the answer.

## The model works in curl but not in my tool

> Seven places where a tool differs from the working curl: base URL, auth header, model id, key route and limits, IP whitelist, GLM and Jev endpoints, timeouts.

Section: Troubleshooting · URL: https://ai.topxea.com/docs/the-model-works-in-curl-but-not-in-my-tool · Updated: 2026-09-18

The First API request curl in the Get started panel on the Dashboard sends the exact path, header and model id. A tool failing with the same key usually differs in one of seven ways.
1. The base URL
The API endpoint panel on API keys gives https://ai.topxea.com and leaves the path to the client. OpenAI-style tools append /chat/completions, so their base URL must end with /v1:
https://ai.topxea.com/v1
Without /v1 the tool posts to https://ai.topxea.com/chat/completions, the console's web page: 200 with HTML, and the tool reports a JSON parse error. /v1 twice gives 404 Invalid URL (POST /v1/v1/chat/completions). Anthropic-style tools and TypeSafe's SDKs append /v1/messages and /v1/systemone themselves, so they take https://ai.topxea.com without /v1.
2. The auth header
OpenAI-style endpoints read Authorization: Bearer sk-.... x-api-key is accepted only on /v1/messages and /v1/models, so an Anthropic tool pointed at /v1/chat/completions gets 401 Invalid token.
3. The model id
Ids are case-sensitive: GLM-5.3-Abliterated, claude-sonnet-5-5. A tool that lowercases the name gets 403 Model is not offered by this service. List what the key can call:
curl https://ai.topxea.com/v1/models -H "Authorization: Bearer sk-..."
4. The key's route and limits
A key belongs to one Group; one on claude-shared cannot call gpt-6-astra and gets 403 Model is not available on this API key route. Tools that switch vendors need a key on Auto route, which routes each model to its lowest-priced line. A model outside the key's Model limits answers 403 This token has no access to model ....
5. The key's IP whitelist
A key with an IP Whitelist (supports CIDR) works from your laptop's curl and answers 403 from a server not on the list.
6. GLM, Kimi and Jev
The API reference lists /v1/responses for the GPT and Grok models. For GLM-5.3-Abliterated and kimi-k3, point the tool at /v1/chat/completions, or at /v1/messages, which answers for every text model except Jev. GLM accepts text only: on /v1/chat/completions an editor's image probe is replaced by [Attachment omitted: this model accepts text only.], so the probe passes but the model never sees pictures. jev-1.14.0 is TypeSafe's System One model on POST /v1/systemone. It returns typed judgments, not chat: set TYPESAFE_BASE_URL=https://ai.topxea.com in TypeSafe's SDK, not in a chat client.
7. Timeouts, streaming and video
The gateway waits up to 30 minutes for the provider's first byte and as long again between stream chunks; a shorter timeout is your tool's. For long generations use stream: true; a mid-stream error is one data: {"error":...} event (event: error first on /v1/messages) and the stream ends without [DONE]. Video is asynchronous: POST /v1/videos/generations returns the job document with a request_id at once. Poll GET /v1/videos/{request_id}, then fetch GET /v1/videos/{request_id}/content; a tool expecting the clip in the POST gets JSON, not a file.

## Sign-in and account

> How sign-in is shared with topxea.com, how sessions, devices and TopxAI Desktop sign-ins work, the regional service notice, and how to reach support.

Section: Troubleshooting · URL: https://ai.topxea.com/docs/sign-in-and-account · Updated: 2026-09-24

One sign-in for topxea.com and TopxAI
Sign-in goes through Clerk with a verified primary email; TopxAI and topxea.com share one Clerk identity. If already signed in on topxea.com, you are signed in here too; otherwise you browse as a visitor and meet the sign-in page only on console pages such as Dashboard. Balance, keys and usage are bound to that Clerk user id. Accounts are not merged by email; a second Clerk id on the same email answers This email belongs to an existing account. Contact support.
Name, email, password and sign-in methods live in Clerk's panels: Manage Clerk profile and Manage password and security on Profile. Account closure goes through support.
Sign-in page stuck
Sign-in is taking too long. Please try again. with Reload sign-in: the page waited 30 seconds for configuration or the Clerk script.
The same message with Try again and Sign out: the TopxAI exchange timed out.
Retry loading sign-in: the Clerk script failed to load.
Unable to load sign-in configuration. Please try again.: press Try again.
A bare Sign in button after signing out here: it ends the leftover Clerk session, then shows the form.
Sessions and devices
A console session lasts up to 30 days and is re-verified against Clerk on every visit; a revoked or expired Clerk session fails the next request. A briefly unreachable Clerk answers 503; retry.
Login sessions on Profile is Clerk's device list, including devices that only signed in on topxea.com; Expires shows each Clerk session's expiry. TopxAI Desktop sign-ins are listed there as well, as TopxAI Desktop · computer name with the system and app version underneath and Desktop app as the method. They are not Clerk sessions: each one stays signed in while the app is used at least once a month.
Sign out ends this device.
Revoke ends one other device. Revoking a TopxAI Desktop sign-in also disables the API key the app created on that computer.
Sign out other sessions revokes every other Clerk session, topxea.com included, and every TopxAI Desktop sign-in with its key. The desktop sign-ins end first, so if the Clerk step then fails they are already signed out; try again for the Clerk devices.
If Clerk's device list cannot be loaded, the card says so and lists only this device and the TopxAI Desktop sign-ins, which you can still revoke.
Signing out does not touch the API keys you created; they work until Disable or Delete on the API keys page. The exception is the key TopxAI Desktop creates for a computer, which stops working when that sign-in ends; signing in from the app again creates a new one. Sign-ins made before keys were tied to a sign-in are different: their key keeps working after the sign-in ends. The confirmation says so; disable or delete that key on the API keys page. A disabled account blocks sign-in and every key.
Regional service notice
With regional access controls on, the console API and every /v1/ endpoint answer 403 with The service is not available in your region. or Your service region could not be verified. Please contact support. The decision uses our infrastructure's location headers, not browser settings; public pages and sign-out still work.
Reaching support
Use the help button at the bottom right of any page (the footer's Support link opens it too) or write to support@topxea.com. For an API error, copy the (request id: ...) at the end of the message or the x-request-id response header. For a block in the browser (no request id there) give the time with time zone, the page and your account email. Never paste an API key. Prompts and responses are not stored; support sees only metadata (model, token counts, status, latency, key id).

## TopxAI vs OpenRouter: what is the same and what differs

> Compare current model and route prices: TopxAI shared routes cost 37.5% to 50% less than OpenRouter standard routes, and Kimi hosts can cost less.

Section: Comparisons · URL: https://ai.topxea.com/docs/topxai-vs-openrouter · Updated: 2026-10-02

Both services put many providers' models behind one endpoint and one balance. The differences are in how many models, what a token costs, and what else is on offer. This page states what each side publishes; OpenRouter's numbers are from their documentation on 2026-09-24, with GPT-6.1 Sol rechecked on 2026-09-30 and Sonnet 5.5 on 2026-10-02, and may change.
Side by side
TopxAI OpenRouter
Models 14, seven lines: Claude, GPT, Grok, GLM (private deployment), Kimi, DeepSeek, Jev Hundreds, from most providers
Token price Claude/GPT/Grok shared routes at 50% of the listed provider reference, their official routes at 90%; Kimi 80%; DeepSeek 80% with off-peak and peak hours; Jev 107%; GLM is a different private fine-tune Varies by provider, route and promotion; not always the model vendor's list price
Fee on top-up None: the amount credited is the amount you enter (regional tax may be added at checkout) Standard lists a 5.5% platform fee; payment conditions and other plans differ (pricing)
API formats OpenAI Chat Completions and Responses, Anthropic Messages, Images, video, /v1/systemone OpenAI-style API; see their docs for what else is supported
Routing Auto route picks the lowest-priced of TopxAI's own routes for the model; per-route keys pin a line Routes across providers, with fallbacks and provider preferences
Prompts and completions Relayed in memory, never stored Their privacy page describes logging options and zero-retention routes
Extras Usage log per request with route and charge; gift cards; shared sign-in with topxea.com Web search plugin, presets, app attribution, provider analytics
Free start $0.50 credit at sign-up Free-tier models
Current price examples
Checked on September 24, 2026 against the TopxAI price API, OpenRouter model API and the linked provider pages. The GPT-6.1 Sol comparison was updated on September 30 against its OpenRouter model page. Sonnet 5.5 was rechecked on October 2 against Anthropic's model page and OpenRouter's Sonnet 5.5 standard routes; both list $2 input / $10 output, and Anthropic lists no long-context premium. Prices below are USD per million tokens, shown as input / output, for standard online requests below any applicable long-context threshold. They exclude platform fees, taxes, cache tokens and tool charges; Batch, Flex and priority processing are separate service tiers.
Model TopxAI route TopxAI input / output OpenRouter standard input / output Comparison
Claude Sonnet 5.5 Shared $1 / $5 $2 / $10 TopxAI 50% lower
Claude Opus 5.5 Shared $2 / $10 $4 / $20 TopxAI 50% lower
Claude Fable 5.1 Shared $5 / $25 $10 / $50 TopxAI 50% lower
GPT-6 Astra Shared $5 / $25 $10 / $50 TopxAI 50% lower
GPT-6.1 Sol Shared $1 / $5 $2 / $10 TopxAI 50% lower
Grok 4.7 Shared $1 / $3 $1.60 / $4.80 TopxAI 37.5% lower
Kimi K3 Official $2.40 / $12 $3 / $15 (Moonshot AI) TopxAI 20% lower; some FP4 hosts are cheaper
The official routes sell at 90% of the provider list price. Sonnet 5.5's official route is $1.80 input / $9 output, 10% below the standard $2 / $10 comparison above. For the other Claude and GPT models above that is also 10% below OpenRouter's standard routes; for Grok 4.7 the official route ($1.80 / $5.40) is 12.5% above it, because OpenRouter sells Grok 4.7 below xAI's $2 / $6 list price. OpenRouter's GPT-6.1 Sol and GPT-6 Astra pages also list OpenAI Flex endpoints at half price; Flex is not standard routing. Its Kimi K3 page lists 20 routes: Moonshot AI at $3 / $15, and FP4-quantised hosts such as Sail Research at $1.50 / $10.76 and Relace at $1.95 / $9.75. A lower advertised rate does not establish equal throughput, availability, quantisation or hosting conditions.
These savings apply to the shared routes and comparison prices listed above, not to every TopxAI model or route. Auto routing can select a different-priced route; inspect the billed route in the usage log. Provider Batch/Flex discounts, cache hit rates, long-context tiers and retries can change an actual workload's bill. These are public price comparisons, not a paid performance or billing benchmark. Recheck the live ledgers before purchasing.
Where TopxAI is the better fit
You use a handful of the big models and the price per token matters: on the shared pool, claude-sonnet-5-5 is $1 input / $5 output per 1M tokens against a $2 / $10 list price (model page).
You want the Anthropic Messages format, not only an OpenAI-style one, for Claude Code, the Anthropic SDK or any tool that speaks it.
You want a fixed, published price per route and a log row per request that shows which route it took.
You want nothing stored: no prompt, no completion, no file.
Where OpenRouter is the better fit
You need a model TopxAI does not sell: an open-weight model, a small vendor, or the latest release before it reaches the catalogue.
You want cross-provider fallbacks or a preference for a particular hosting provider.
You rely on their extras: web search in the request, presets, or per-app analytics.
Your chosen provider has a lower current price for the model you need, such as the Kimi K3 routes above; compare the actual route, not only the vendor's reference price.
Using both
Nothing prevents it. Both are OpenAI-compatible, so a client that takes a base URL and a model id switches with two values. A LiteLLM or opencode configuration can list TopxAI models next to OpenRouter models under separate provider names (LiteLLM page, opencode page).

## TopxAI vs the providers' own APIs: price, retention and what stays direct

> What changes when Claude, GPT, Grok or Kimi go through TopxAI: the price per token, one key and one balance, zero retention, and what stays with the provider.

Section: Comparisons · URL: https://ai.topxea.com/docs/topxai-vs-the-providers-own-apis · Updated: 2026-09-19

Calling a provider directly is the baseline every relay is measured against. This page lists what changes when the same request goes through TopxAI, including what you give up.
What changes
Direct Through TopxAI
Price per token The provider's list price Shared pool 50% of list, official line 90%; Kimi 80%; Jev 107%; GLM-5.3-Abliterated above list, on a private deployment
Accounts and keys One account, one key, one invoice per provider One account, one Auto-route key for every model, one prepaid USD balance
Payment The provider's billing: card, monthly invoice, prepaid, in the provider's currency and terms Prepaid USD by card on topxea.com, crypto invoice or gift card; $0.50 credit at sign-up
Request path Client → provider Client → TopxAI → provider; the extra hop adds the round trip between TopxAI and the provider
Prompts and completions The provider's retention policy Relayed in memory, never stored; the usage log keeps token counts, model, route and identifiers
Rate limits The provider's per-account limits Per-key request limits and the shared pool's capacity; the official line calls the provider under TopxAI's own account
Usage records The provider's dashboard One usage-log row per request with the route and the charge, filterable by key, model and route
Model versions Every model and snapshot the provider offers The models in TopxAI's catalogue; new releases arrive when they are added
What stays with the provider
TopxAI serves Chat Completions, Responses, Messages, image generation and edits, video generation, /v1/systemone and /v1/models. Anything else stays on the provider's own key:
Batch APIs and their discounts
Fine-tuning, files, assistants, vector stores
Realtime and audio endpoints
Embeddings (no embedding model in the catalogue)
Provider-side features that need account-level settings, such as organisation-wide data controls
The same either way
The request body is forwarded unchanged and the response is returned unchanged, apart from the upstream members described below: tool calling, structured output, streaming, vision inputs, prompt caching and reasoning settings behave as they do at the provider. TopxAI adds no headers of its own, and it adds a system prompt in two cases. Claude has no JSON mode, so a Chat Completions request to Claude with response_format set to json_object gets one sentence in the system prompt asking for a single JSON object. A GPT request without a system prompt that reaches the provider's Responses API (GPT-6.1 Sol on every endpoint, GPT-6 Astra through /v1/responses) is sent the one-line instruction "You are a helpful assistant.", so that the provider does not add its own longer prompt (next paragraph); a request with its own system prompt or instructions is forwarded unchanged. The relay's test suite checks that a Claude Messages request reaches the provider with the fields the client sent. Three things change on the way: a missing max_tokens is set to the model's output limit, service_tier, inference_geo and speed are not passed on, and the deprecated output_format, which the upstream ignores, is sent as output_config.format. GLM-5.3-Abliterated has one change of its own: its deployment decodes some string formats badly, so the uri, email, date and date-time formats of a json_schema move into the field description before forwarding, as its page explains.
Some upstream capacity puts a system prompt of its own in front of the request. The upstream counts those tokens as input, so they are billed with the rest of the input. The GPT provider adds about 4,300 tokens of instructions to a Responses request that has no instructions: on 2026-10-16 a short GPT-6.1 Sol request counted 4,353 input tokens without them and 107 with them. TopxAI's one line keeps that prompt out. On /v1/responses, a system prompt sent only as a system or developer item of input leaves instructions empty and TopxAI adds nothing, so such a request can still carry the provider's prompt; send the system prompt in instructions to avoid it. Some Claude requests can carry several thousand such tokens, reported mostly as cache writes and cache reads. On /v1/responses the upstream also returns the instructions it ran with and members of its own: TopxAI sets instructions, metadata, safety_identifier and prompt_cache_key back to what your request sent, so TopxAI's line never shows in an answer, and removes the members of its own that it is known to add, in the body and in every stream event. Some capacity also adds a provider_specific_fields member to Chat Completions answers, and TopxAI removes it too. The usage log lists the input and cache counts each request was billed for.
Deciding
Go direct when you need an endpoint TopxAI does not serve, the provider's own billing terms, or a model outside the catalogue. Go through TopxAI when the models you use are in the catalogue, the price per token matters, and one key with one balance is simpler than several accounts. The two are not exclusive: most tools take a base URL per model, so the catalogue models can run through TopxAI while the rest stay direct.

## TopxAI vs Vercel AI Gateway: list price with no markup, or half of it

> Vercel AI Gateway charges the provider list price with no markup; TopxAI shared routes charge 50% of it for Claude, GPT and Grok. What else differs.

Section: Comparisons · URL: https://ai.topxea.com/docs/topxai-vs-vercel-ai-gateway · Updated: 2026-10-06

Both services put several providers' models behind one key and one balance, and both work with the Vercel AI SDK. They price tokens differently. Vercel AI Gateway charges the provider's list price with no markup. TopxAI's shared routes charge half of that list price for Claude, GPT and Grok. This page states what each side publishes. Vercel's figures come from its pricing page and its public model API, both read on October 6, 2026, and may change.
Side by side
TopxAI Vercel AI Gateway
Models 14, seven lines: Claude, GPT, Grok, GLM (private deployment), Kimi, DeepSeek, Jev About 400 entries in its model API, from most providers, including embeddings, reranking and speech
Token price Claude, GPT and Grok shared routes at 50% of the provider list price, their official routes at 90%; Kimi 80%; DeepSeek 80% with off-peak and peak hours; Jev 107% The provider's list price with no markup and no platform fee; some models discounted for everyone; volume discounts by agreement
Free start $0.50 credit at sign-up $5 of credit a month on a free tier that covers a subset of models at lower rate limits; it stops once you buy credits
Your own provider keys Not supported Supported on the paid tier with no markup; a failed request is retried with Vercel's credentials and charged to your credits
Fees None on top-up: the amount credited is the amount you enter (regional tax may be added at checkout) Payment processing fees may apply; optional paid add-ons such as Custom Reporting and a team-wide provider allowlist
API formats OpenAI Chat Completions and Responses, Anthropic Messages, images, video, /v1/systemone AI SDK provider, OpenAI Chat Completions and Responses, Anthropic Messages, OpenResponses, a REST API
Routing Auto route picks the lowest-priced of TopxAI's own routes for the model; per-route keys pin a line Provider ordering and filtering, model fallbacks, budgets per team, project, key or member
Prompts and completions Relayed in memory, never stored Optional Zero Data Retention routing to providers that have agreed not to retain or train on prompt data
Current price examples
Checked on October 6, 2026 against the TopxAI price API and the Vercel AI Gateway model API. Prices are USD per million tokens, shown as input / output, for standard requests below any long-context threshold. They exclude cache tokens, fees and taxes.
Model TopxAI route TopxAI input / output Vercel AI Gateway input / output Comparison
Claude Sonnet 5.5 Shared $1 / $5 $2 / $10 TopxAI 50% lower
Claude Opus 5.5 Shared $2 / $10 $4 / $20 TopxAI 50% lower
Claude Fable 5.1 Shared $5 / $25 $10 / $50 TopxAI 50% lower
GPT-6.1 Sol Shared $1 / $5 $2 / $10 TopxAI 50% lower
GPT-6 Astra Shared $5 / $25 $10 / $50 TopxAI 50% lower
Grok 4.7 Shared $1 / $3 $2 / $6 TopxAI 50% lower
Kimi K3 Official $2.40 / $12 $3 / $15 TopxAI 20% lower
DeepSeek V4.1 Flash Official $0.12 / $0.48 off-peak, $0.24 / $0.96 peak $0.30 / $1.20 TopxAI 60% lower off-peak, 20% lower peak
DeepSeek V4 Pro Official $0.528 / $1.584 off-peak, $1.056 / $3.168 peak $0.66 / $1.98 TopxAI 20% lower off-peak, 60% higher peak
Jev Official $0.04494 input $0.042 input TopxAI 7% higher
Cache prices follow the same ratio on the shared routes. For Sonnet 5.5, a cache read costs $0.10 per million tokens on TopxAI and $0.20 on Vercel, and a 5-minute cache write $1.25 against $2.50. Long-context rates keep the ratio too: Grok 4.7 requests from 200K input tokens cost $2 / $6 on TopxAI's shared route and $4 / $12 on Vercel.
DeepSeek is where the comparison turns. TopxAI follows DeepSeek's own off-peak and peak hours and bills each at 80% of DeepSeek's price for that period. Vercel's model API lists one rate per model. During DeepSeek's peak hours, V4 Pro costs more on TopxAI than Vercel's listed rate. Every TopxAI usage-log row names the period it was billed at, see how requests are billed.
The official routes sell at 90% of the provider list price, so they are 10% below Vercel's rate for the Claude, GPT and Grok models above. GLM-5.3-Abliterated is a different private fine-tune and has no Vercel counterpart; Vercel lists Z.ai's GLM-5.3 at $1.40 / $4.40. These savings apply to the routes and prices listed above, not to every TopxAI model or route. Auto routing can select a different-priced route; the billed route is in the usage log. These are public price comparisons, not a performance or reliability benchmark. Recheck both price lists before buying.
Where TopxAI is the better fit
Most of your tokens go to Claude, GPT or Grok: the shared pool costs half the list price Vercel charges. claude-sonnet-5-5 is $1 input / $5 output per million tokens (model page).
You want a fixed, published price per route and a log row per request that shows which route it took and what it cost.
You want nothing stored: no prompt, no completion, no file.
Where Vercel AI Gateway is the better fit
You need a model TopxAI does not sell, or embeddings, reranking or speech.
You want to use your own provider keys or credits you already hold with a provider.
You deploy on Vercel and want spend budgets, fallbacks and observability in the same dashboard.
You run DeepSeek V4 Pro during DeepSeek's peak hours, or you call Jev in volume.
You want to try models on a free monthly credit before paying.
Using both
Both work with the AI SDK through @ai-sdk/openai-compatible. Vercel's base URL is https://ai-gateway.vercel.sh/v1 and TopxAI's is https://ai.topxea.com/v1 (setup). Model ids differ: Vercel uses provider/model, such as anthropic/claude-sonnet-5.5, and TopxAI uses the bare id, such as claude-sonnet-5-5. Two provider objects in one application let each request go where it costs least.

## What TopxAI stores and what it never stores

> Request and response content passes through memory only; here is what the usage log, account and payment records keep, and for how long.

Section: Privacy and policies · URL: https://ai.topxea.com/docs/what-topxai-stores-and-what-it-never-stores · Updated: 2026-10-16

Content is relayed, not kept
Request and response bodies sent to https://ai.topxea.com/v1 live in memory only for the relay attempt. Prompts, messages, system instructions, tool definitions and arguments, images, audio and files, completions, streamed deltas, tool calls, headers and upstream error bodies are never written to disk or a database. They are not used to train models, build profiles or serve advertising, and TopxAI does not sell data about you.
The upstream provider serving your model, and on some routes an intermediary API provider, does process the content under retention terms TopxAI does not control.
What the usage log keeps
Each request leaves a metadata row; a request retried upstream leaves one error row per failed attempt plus one row for the final attempt. Usage logs in the console shows Time, Type, Token (the key name), Model, Stream, Tokens, Cost and Latency. The row also holds user id, username, key id, routing group, channel and request ids, and an IP only if the per-user record_ip_log setting is on.
A failed request leaves an error row with zero tokens and zero charge: the HTTP status and a fixed public category such as rate_limited, never the provider's message, which may echo your prompt.
Account, payment and browser records
To run your account TopxAI processes your Clerk user id and verified primary email, session identifiers, network metadata (IP address, user agent, and location data where regional access controls are on) and payment records (order id, USD amount, payment method, provider transaction reference).
When an account is created, TopxAI also records its sign-up source once: the first page of this site that was opened, the domain of the site that linked there (never its path or query) and the campaign tags of that link. It shows which pages and channels bring new users, and it is deleted with the account. Until the account exists, this information waits in your browser's storage; it is cleared once reported.
Card numbers and wallet private keys never pass through TopxAI; Waffo handles card checkout on topxea.com, NOWPayments handles USDT and USDC. A crypto top-up's transaction hash and addresses are public on chain and cannot be deleted.
API keys are kept in recoverable form (you can view and copy them in the console), so revoke any key that leaks; personal access tokens are kept as digests. The only cookies are an HttpOnly session cookie, a topxai_session hint and Clerk's own; none serve advertising.
Retention
Account and payment records stay while your account is active and as long as accounting and legal obligations require; network metadata is kept briefly. Usage records have no promised period: by default, diagnostic rows and settled per-request detail older than 30 days are pruned, so Usage logs shows roughly the last 30 days, while settlement records, daily totals, balances and top-ups are kept permanently.
What you can do
Delete or Disable a key from its detail drawer. To access, export or delete other data, or close your account, use the help button at the bottom right or write to support@topxea.com; requests are verified through your signed-in account and answered within 30 days.

## Acceptable use and abuse reports

> The six prohibited content categories, how enforcement works, why GLM's private deployment is no exception, and how to report abuse.

Section: Privacy and policies · URL: https://ai.topxea.com/docs/acceptable-use-and-abuse-reports · Updated: 2026-09-18

Scope
The policy covers every request relayed through TopxAI on any line, route or API key, including end-user traffic of a product you build on it, which is your responsibility; a stricter upstream policy takes precedence. TopxAI does not provide any services to users located in mainland China.
Prohibited content
Six categories are prohibited:
Sexual and pornographic content, including "nudifying" a photo. Informative medical, scientific, educational and legal material is permitted.
Violence, gore and incitement: weapon or attack instructions, threats, extremist recruitment, gratuitous gore. Journalism, history, fiction and safety research without operational detail are permitted.
Hate speech and discrimination against protected groups.
Child sexual abuse material and the sexualisation or endangerment of minors; claimed age, art style or consent make no difference.
Deepfakes and impersonation: synthetic media of a real person without consent, phishing, forged documents, bots that deny being automated when sincerely asked. Clearly labelled parody of public figures that no reasonable viewer would mistake for real is permitted.
Copyright and trademark infringement, including reproducing paid content in substantial part and DRM bypass tools.
Malware, fraud, spam, illegal activity and bypassing safety systems (jailbreaks, prompt injection, evading filters or limits) are also prohibited.
GLM's private deployment
GLM-5.3-Abliterated is a fine-tuned GLM 5.3 with its refusal behaviour removed, served from a private deployment, not the vendor API. The same policy applies; its notice adds that it may produce biased, offensive or locally unlawful content and that you bear full responsibility for compliance and legal consequences.
Enforcement
Automated checks run before forwarding and keep no content. Requests to the Claude, GPT, Grok, Kimi, DeepSeek, image and video models that carry a known jailbreak template (persona prompts such as DAN, "developer mode" templates, Chinese role-play presets such as 破限, instruction-override phrases) are refused before forwarding with content_filtered, and one rejection by the provider for content pauses your account's requests to those models for 24 hours. Measures match severity, frequency and intent, one or more in any order: warning, request blocking, rate limiting, key suspension, account termination (prepaid balance forfeited for wilful or repeated abuse, or for a material breach of the User Agreement) and referral to law enforcement. Child-safety violations end the account on the first request, without refund, and are reported to the authorities. Repeated upstream refusals count as an abuse signal; your keys are your responsibility until revoked.
To appeal, email support@topxea.com within 7 days of the notice with your account email, the key identifier and your reasons; a person reviews it while the measure stays in force. Child-safety decisions are final.
Reporting abuse
Use the help button at the bottom right of any page or email support@topxea.com. Include what happened and which category applies, when (with time zone), any key or request identifier, evidence, and how to reach you. Reports are acknowledged within 2 business days; those concerning the sexual abuse of a minor are handled first. A good-faith report never affects your own account, and your identity stays confidential unless the law requires otherwise. If someone is in immediate danger, contact local emergency services first.
The full policy is at https://ai.topxea.com/acceptable-use-policy (effective 2026-09-18).