Documentation
APIEX.CLOUD gives you one OpenAI-compatible API for GPT, Claude, Gemini and more, plus live chat with every model, with a single wallet, keys you can limit and a report for every request. This guide covers the API, live chat, billing, keys, limits and the user panel.
How it works
- You send a standard OpenAI-style request to the gateway with your API key.
- The gateway checks the key, its limits, your model access and your balance, and holds the maximum possible cost of the request.
- The request is forwarded to an upstream service. If it fails, the next service for that model is tried automatically.
- You receive the response, are charged the real cost, and the rest of the hold is released. The request appears in your usage logs.
The API is compatible with the OpenAI SDKs. Point an existing OpenAI client at the base URL below, use your gateway key, and it works without other code changes, whether the model is GPT, Claude, Gemini or another one.
Authentication
Every request except GET /ping and GET /models must include your API key in the Authorization header, using the Bearer scheme. Keys begin with apx-.
Authorization: Bearer YOUR_API_KEY
Never expose your API key in client-side code such as browser JavaScript or mobile apps. Always call the gateway from your own backend.
- The full secret is displayed only once, when the key is created. Only a hash is stored, so a lost key cannot be recovered; create a new one instead.
- A key can be revoked, can expire, and can be restricted to certain IP addresses. A restricted key refuses requests from any other address.
- Keys never need to be sent in the URL or the request body.
Create and manage keys in your panel: API Keys section
Quick start
- Create an account and sign in to your panel.
- Use a free model right away, or top up your wallet for the rest.
- Create an API key in the API Keys tab and copy the secret.
- Send a request in the language of your choice. Replace YOUR_API_KEY with your key.
curl https://apiex.cloud/api/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.6-terra-pro",
"messages": [
{ "role": "user", "content": "Hello!" }
]
}'
from openai import OpenAI
client = OpenAI(
base_url="https://apiex.cloud/api/v1/",
api_key="YOUR_API_KEY",
)
response = client.chat.completions.create(
model="openai/gpt-5.6-terra-pro",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://apiex.cloud/api/v1/",
apiKey: "YOUR_API_KEY",
});
const response = await client.chat.completions.create({
model: "openai/gpt-5.6-terra-pro",
messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);
$ch = curl_init( "https://apiex.cloud/api/v1/chat/completions" );
curl_setopt_array( $ch, array(
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer YOUR_API_KEY',
'Content-Type: application/json',
),
CURLOPT_POSTFIELDS => json_encode( array(
'model' => 'openai/gpt-5.6-terra-pro',
'messages' => array(
array( 'role' => 'user', 'content' => 'Hello!' ),
),
) ),
) );
$response = json_decode( curl_exec( $ch ), true );
echo $response['choices'][0]['message']['content'];
Prefer not to write code? Open the Live chat tab in your panel, pick any model and start talking. It uses the same wallet and the same billing as the API.
Errors
The API uses conventional HTTP status codes: 2xx means success, 4xx means a problem with the request or your account, 5xx means a problem on our side or with an upstream service. Errors use the OpenAI error envelope, so official SDKs read them without extra code.
{
"error": {
"message": "Insufficient wallet balance for this request. ...",
"type": "insufficient_quota",
"param": null,
"code": "insufficient_balance"
}
}
Error types
| Status | type | Meaning |
|---|---|---|
| 400 | invalid_request_error | A required parameter is missing or a value is malformed. |
| 401 | authentication_error | The API key is missing, invalid, revoked or expired. |
| 402 | insufficient_quota | Your balance, key spend limit, plan or free allowance cannot cover this request. |
| 403 | permission_error | The key may not use this model, the address is not allowed, or the account is suspended. |
| 404 | not_found_error | The model does not exist or is not active. |
| 429 | rate_limit_error | A rate, concurrency or daily spending limit was reached. Back off and retry. |
| 5xx | api_error | Something went wrong on our side or upstream. Retrying is safe, especially with an Idempotency-Key. |
Error codes
The code field tells you exactly what happened, so your application can react to it.
| Status | code | Meaning |
|---|---|---|
| 400 | missing_model |
The "model" field is required. |
| 400 | invalid_request |
A parameter is invalid, "messages" or "input" is missing, or "n" is not 1. |
| 400 | invalid_idempotency_key |
The Idempotency-Key header is not 1 to 255 printable characters. |
| 401 | invalid_key |
The key is missing or does not start with apx-. |
| 401 | unknown_key |
The key was not recognised. |
| 401 | key_revoked |
The key has been revoked. |
| 401 | key_expired |
The key has passed its expiry date. |
| 402 | insufficient_balance |
The worst-case cost of the request is higher than your available balance. Lower max_tokens or top up. |
| 402 | spend_limit |
The key has used up its own spend limit. |
| 402 | plan_budget_exhausted |
The payment source is "plan" and its credit cannot cover the request (used up, or too low for the worst case of this request). Switch to the wallet, buy a new plan, or lower max_tokens. Nothing is taken from the wallet. |
| 402 | model_not_in_plan |
The payment source is "plan" and the plan does not include this model. Switch to the wallet to use it. |
| 402 | request_limit_reached |
Your plan's request limit has been reached. |
| 402 | free_tier_quota_exhausted |
Your free allowance for this period is used up. It renews automatically, or you can top up. |
| 403 | model_not_allowed |
This key, or your account, may not use this model. |
| 403 | ip_not_allowed |
The key is restricted to other IP addresses. |
| 403 | ip_blocked |
The request address is blocked. |
| 403 | account_suspended |
API access for this account is suspended. Contact support. |
| 404 | unknown_model |
The model is unknown or inactive. |
| 409 | idempotency_in_progress |
A request with this Idempotency-Key is still running. Retry in a few seconds. |
| 422 | idempotency_key_reused |
The Idempotency-Key was already used with a different request body. |
| 429 | rate_limited |
The key exceeded its requests-per-minute limit. |
| 429 | too_many_concurrent |
Too many requests are already running for your account. |
| 429 | daily_cap |
You reached the daily spending limit for your account. |
| 429 | model_daily_cap |
You reached the daily spending limit for this model. |
| 429 | free_tier_rate_limited |
The free-tier request rate was reached. Slow down and retry. |
| 502 | upstream_error |
The upstream service failed and no backup could answer. |
| 503 | service_unavailable |
No service is currently available for this model. |
| 503 | billing_unavailable |
Billing is temporarily unavailable. Retry shortly. |
| 503 | api_paused |
The API is temporarily paused by the administrator. |
| 503 | maintenance |
The service is being updated. Retry after the Retry-After delay. |
Base URL & endpoints
All requests are made against this base URL:
https://apiex.cloud/api/v1/
| Method | Endpoint | Description | Key required |
|---|---|---|---|
| POST | /chat/completions |
Create a chat completion. Streaming, tools and vision input are supported. | Yes |
| POST | /embeddings |
Create vector embeddings for text. | Yes |
| POST | /audio/speech |
Turn text into speech. The answer is the audio file. | Yes |
| POST | /audio/transcriptions |
Turn an audio file into text. | Yes |
| POST | /videos |
Start generating a video. Returns a job you can follow. | Yes |
| GET | /videos/{id} |
The status of a video job. Once finished it also gives the download link. | Yes |
| GET | /videos/{id}/content |
Download the finished video file. | Yes |
| DELETE | /videos/{id} |
Cancel a video that has not finished yet. | Yes |
| POST | /cost/estimate |
Get the maximum cost of a request without sending it. | Yes |
| GET | /usage/me |
Your balance, held amount, key spend state and usage statistics. | Yes |
| GET | /models |
The model catalog with prices. With a key, only the models that key may use. | Optional |
| GET | /models/count |
How many models match the output_modalities filter. | Optional |
| GET | /models/user |
The same catalog, limited to the models your key may use. A key is required. | Yes |
| GET | /embeddings/models |
Embedding models only, in the same shape as /models. | Optional |
| GET | /images/models |
Image-generating models only, in the same shape as /models. | Optional |
| GET | /videos/models |
Video models only, with their price list (per second or per video token) and supported durations, resolutions and aspect ratios. | Optional |
| GET | /ping |
A health check that returns the gateway status and version. | No |
Speech, transcription and video generation work through the API as well as in the panel's Live chat tab, with the same prices and the same wallet. Image generation is available in the Live chat tab.
Chat completions
Creates a model response for a conversation. Request and response shapes match the OpenAI Chat Completions API.
Request parameters
| Parameter | Type | Description |
|---|---|---|
model
required
|
string | ID of the model to use. See Models & providers for how to list the available values. |
messages
required
|
array | The conversation so far. Each item needs a role and content. Content can include image, audio, video and file parts for models that accept them. |
temperature
|
number | Sampling temperature. Higher values make output more random. |
top_p
|
number | Nucleus sampling threshold. Usually left at its default. |
max_tokens
|
integer | Maximum tokens to generate. Optional: a site default applies when omitted, and larger values are lowered to the site maximum. A lower value also lowers the amount held on your wallet. |
max_completion_tokens
|
integer | Alternative to max_tokens with the same limits, for models that use this name. |
stop
|
string | array | Up to 4 sequences where generation stops. |
presence_penalty
|
number | Penalises tokens that have already appeared. |
frequency_penalty
|
number | Penalises tokens by how often they have appeared. |
logit_bias
|
object | Adjusts the likelihood of specific tokens. |
seed
|
integer | Requests more repeatable output where the model supports it. |
response_format
|
object | Ask for JSON or structured output where the model supports it. |
tools
|
array | Functions the model may call. Up to 128 tools. |
tool_choice
|
string | object | Controls whether and which tool is called. |
parallel_tool_calls
|
boolean | Allow several tool calls in one turn. |
functions / function_call
|
array / mixed | The older function-calling parameters, still accepted. |
logprobs / top_logprobs
|
boolean / integer | Return log probabilities where the model supports it. |
reasoning_effort
|
string | Reasoning effort for models that support it. |
user
|
string | An identifier for your end user, up to 256 characters. |
n
|
integer | Must be 1 or omitted. Only one completion per request is supported, because every extra choice would be billed output. |
stream
|
boolean | If true, the answer is sent as server-sent events. See Streaming responses. |
stream_options.include_usage
|
boolean | When streaming, add a final event with token usage. |
Only the parameters above are forwarded. Anything else, such as provider routing or web-search options, is ignored, so a request can never add costs you did not expect.
Example response
{
"id": "chatcmpl-...",
"object": "chat.completion",
"model": "openai/gpt-5.6-terra-pro",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 10,
"total_tokens": 19
}
}
Streaming responses
Set "stream": true to receive the response as server-sent events in the OpenAI format, ending with [DONE]. Every official OpenAI SDK reads this automatically.
data: {"choices":[{"delta":{"role":"assistant","content":"Hello"}}]}
data: {"choices":[{"delta":{"content":"!"}}]}
data: [DONE]
- Where live streaming is enabled, tokens are forwarded as they are generated and your wallet is settled when the stream ends.
- Otherwise the gateway completes and bills the generation first, then delivers it in the same event format. The text then arrives at once instead of word by word.
- Nothing is sent to you until the upstream has produced a valid first event, so a failing upstream is still replaced by the next one before you see anything.
- Add "stream_options": { "include_usage": true } to receive a final event with token usage, as with OpenAI.
If your reverse proxy buffers responses, disable buffering for the API path so tokens reach clients immediately.
Embeddings
Creates vector representations of text for search, clustering and retrieval. Use an embedding model from the model catalog.
| Parameter | Type | Description |
|---|---|---|
model required | string | ID of the embedding model. |
input required | string | array | The text to embed: a non-empty string or an array of up to 2,048 items. |
encoding_format | string | The format of the returned vectors, for example float or base64. |
dimensions | integer | Number of dimensions, for models that support shortening. |
user | string | An identifier for your end user. |
curl https://apiex.cloud/api/v1/embeddings \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "EMBEDDING_MODEL_ID",
"input": "The quick brown fox"
}'
List embedding models
Every model filed as Embedding is listed by GET /embeddings/models and reports embeddings as its output. GET /models leaves them out by default; add ?output_modalities=embeddings to list them there too.
curl https://apiex.cloud/api/v1/embeddings/models \ -H "Authorization: Bearer YOUR_API_KEY"
{
"data": [
{
"id": "EMBEDDING_MODEL_ID",
"name": "...",
"architecture": {
"input_modalities": ["text"],
"output_modalities": ["embeddings"]
}
}
]
}
Speech & transcription
Turn text into spoken audio, or turn an audio recording into text. Pick a speech or transcription model from the model catalog. Both are charged to your wallet like any other request.
POST /audio/speech
| Parameter | Type | Description |
|---|---|---|
model required | string | ID of a speech model from the model catalog. |
input required | string | The text to speak. Up to 4,000 characters. |
voice | string | The voice to use. Which voices exist depends on the model. |
The answer is the audio file itself, not JSON. You are charged by the number of characters.
curl https://apiex.cloud/api/v1/audio/speech \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "SPEECH_MODEL_ID",
"input": "Hello! This is a test of the text-to-speech API.",
"voice": "alloy"
}' \
--output speech.mp3
POST /audio/transcriptions
| Parameter | Type | Description |
|---|---|---|
model required | string | ID of a transcription model from the model catalog. |
file required | file | The audio to transcribe, sent as a multipart upload. Up to 25 MB; mp3, mp4, mpeg, mpga, m4a, wav, webm, ogg, flac, aac or opus. |
language | string | The spoken language as a short code such as en or fa. It is detected automatically when left out. |
Instead of a file upload you can send JSON with input_audio: an object holding the base64 data and the format. You are charged by the length of the audio.
curl https://apiex.cloud/api/v1/audio/transcriptions \ -H "Authorization: Bearer YOUR_API_KEY" \ -F model=TRANSCRIPTION_MODEL_ID \ -F file=@recording.mp3
{
"text": "The transcribed text appears here.",
"usage": { "type": "duration", "seconds": 12.4 }
}
Video generation
Video takes a while to make, so it works in three steps: start a video, check its progress, then download the file. Start a video with POST /videos, check it with GET /videos/{id}, and download it from the content_url once the status is completed.
| Parameter | Type | Description |
|---|---|---|
model required | string | ID of a video model from the model catalog. |
prompt required | string | Describe the video you want. Up to 4,000 characters. |
duration | integer | Clip length in seconds. Leave it out to let the model choose. |
aspect_ratio | string | One of 16:9, 9:16, 1:1, 4:3, 3:4 or 21:9. The default is 16:9. |
resolution | string | For example 720p or 1080p. Only the resolutions this model supports are accepted. |
generate_audio | boolean | Ask the model to generate audio together with the video, when it can. |
image | string | A first frame to start the clip from: a PNG, JPEG or WebP data URL, or an https link. |
You are charged only when the finished video is delivered. DELETE the video's polling URL to cancel it before it finishes. Finished videos are kept for two days.
# 1. Start the video
curl https://apiex.cloud/api/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "VIDEO_MODEL_ID",
"prompt": "A calm sunrise over snowy mountains, slow aerial shot.",
"duration": 5
}'
# 2. Check until "status" is "completed"
curl https://apiex.cloud/api/v1/videos/vid_123 \
-H "Authorization: Bearer YOUR_API_KEY"
# 3. Download the file
curl https://apiex.cloud/api/v1/videos/vid_123/content \
-H "Authorization: Bearer YOUR_API_KEY" \
-o video.mp4
{
"id": "vid_123",
"object": "video",
"model": "VIDEO_MODEL_ID",
"status": "queued",
"created_at": 1767225600,
"polling_url": "https://apiex.cloud/api/v1/videos/vid_123"
}
Cost estimate & usage
Estimate a request
POST /cost/estimate accepts the same body as the request you plan to send and returns the most it could cost, without sending anything upstream and without charging you. Add "endpoint": "embeddings" to estimate an embeddings request.
{
"object": "cost_estimate",
"model": "openai/gpt-5.6-terra-pro",
"endpoint": "chat/completions",
"input_tokens": 24,
"max_output_tokens": 4096,
"max_cost": 0.0,
"currency": "IRT",
"free": false,
"available_balance": 0.0,
"sufficient_balance": true
}
max_cost is the amount held while the request runs. The final charge is the real cost and is usually lower. The values above are placeholders; the response contains your real figures in the wallet currency.
Check your balance and usage
GET /usage/me returns your wallet balance, the part currently held by running requests, the available amount, usage statistics, and the calling key's own spend state (limit, period, spent, remaining and when it resets, in UTC).
curl https://apiex.cloud/api/v1/usage/me \ -H "Authorization: Bearer YOUR_API_KEY"
Idempotent requests
Network errors happen. Add an Idempotency-Key header to a chat or embeddings request so that retrying it can never charge you twice.
Idempotency-Key: 5e7d3f8a-order-1042
- The key can be 1 to 255 printable characters. Use something unique per logical operation, such as a UUID.
- Repeating the same key with the same body within 24 hours returns the stored response and does not charge again.
- Reusing the key with a different body returns 422 idempotency_key_reused.
- If the first request is still running, the retry returns 409 idempotency_in_progress with a Retry-After of 2 seconds.
- Streaming requests are not covered by idempotency.
Rate limits
Limits keep the gateway stable for everyone and protect your balance. Several limits can apply to a request; each one has its own error code.
| Limit | Scope | When exceeded |
|---|---|---|
| Requests per minute | Per API key. Each key has its own value, within the site maximum. | 429 rate_limited |
| Concurrent requests | Per account. | 429 too_many_concurrent |
| Daily spending cap | Per account, and optionally per model. | 429 daily_cap / 429 model_daily_cap |
| Key spend limit | Per API key, total, daily or monthly. | 402 spend_limit |
| Plan request limit | Per active subscription. | 402 request_limit_reached |
| Free-tier allowance and rate | Per account, for free models only. | 429 free_tier_rate_limited / 402 free_tier_quota_exhausted |
Authenticated responses include headers that describe your per-key request limit:
| Header | Description |
|---|---|
X-RateLimit-Limit-Requests | Maximum requests allowed in the current window. |
X-RateLimit-Remaining-Requests | Requests remaining in the current window. |
X-RateLimit-Reset-Requests | Time until the window resets, for example 12s. |
Retry-After | Sent with a 429 response: seconds to wait before retrying. |
When you exceed a limit the API returns 429. Wait for the Retry-After time, or use exponential backoff, before retrying.
Reliability on our side
A model can be served by several upstream services. If one fails, the identical request is retried on the next. A circuit breaker skips a service that fails 5 times within 60 seconds for 30 seconds, then lets one request through to test it, so a single outage does not slow every request.
Wallet & billing
Every account has a prepaid wallet that works across all models. Prices are per token, shown per 1,000 tokens in the catalog, and a request is charged from the real usage reported for it.
How a request is charged
- Before a request is forwarded, the gateway holds its worst-case cost: the input size plus the maximum output tokens, at the model's price.
- If your available balance cannot cover the hold, the request is refused with 402 insufficient_balance and nothing is charged. Lower max_tokens or top up.
- When the answer arrives you are charged the real cost and the rest of the hold is released immediately. A failed request releases the whole hold.
- Available balance is your balance minus the amount held by requests that are still running.
Ways to add credit
Pay through the Zarinpal gateway; the wallet is credited when the payment is confirmed. This method needs an Iranian IP address, so turn off a VPN first.
Transfer to the card shown in your panel, attach the receipt, and the wallet is credited once an administrator approves it.
Send a supported coin to the address shown, optionally add the transaction hash, and the wallet is credited after approval.
A valid code credits your wallet immediately. A code can have its own usage limit and expiry.
A paid plan gives you credit equal to its price. It is spent only from the plan, separate from your wallet, and expires with the plan. See Plans & subscriptions.
Check in from your profile once a day to earn credit. Longer streaks reach milestones with a higher multiplier.
Share your referral link and earn 10% of every top-up made by people who join through it, credited to your wallet. Some rewards may be held until the referred person has used the API.
Every request is logged with its tokens, cost, duration and status. Open any row in your usage logs for a full report.
Currency
The wallet works in the site's currency. The panel can show the same balance in Toman or in Dollars, using the exchange rate set by the administrator. This changes only how amounts are displayed.
Free tier
Models marked as free can be used without wallet balance or a plan, within an allowance that renews automatically.
| Allowance | Value |
|---|---|
| Free models available | 6 |
| Tokens | 10,000,000 per day |
| Requests | 500 per day |
| Speed | 6 requests per minute, 100 per hour |
- Free usage is counted separately from your wallet. When the allowance is used up you receive 402 free_tier_quota_exhausted until it renews, or you can top up to continue.
- You are notified once when your usage passes the warning threshold for the period.
Live chat
Besides the API, every account includes live chat. Instead of paying a separate platform for each model, you can chat with all paid and free models in one place and switch between them whenever you like.
Pick any paid or free model from a single list and switch to another whenever you like. Prices are shown next to each model when the site enables it.
Every conversation is saved with its full history. Search, pin, rename and continue any of them at any time.
Generate pictures, turn text into speech, transcribe audio and create videos with the models that support them.
Attach files to a message, set custom instructions per conversation and use the thinking setting of reasoning models, when the site enables them.
Live chat is charged to the same wallet and at the same model prices as the API, and free models stay free within the free-tier allowance.
While a plan with credit is running, the live chat has its own Plan | Wallet switch above the chat input. It works independently of the API: what you choose there does not change what your API keys pay from, and the other way round.
API keys
Keys authenticate your requests, and each one can carry its own limits. Use one key per application or environment so you can limit, rotate or revoke it without affecting the others.
What you can set on a key
| Setting | What it does |
|---|---|
| Name | A label to recognise the key in lists and in your usage logs. |
| Spend limit | The most the key may spend: in total, per day or per month. A request is accepted only if its worst-case cost still fits in what is left. Or leave it unlimited. |
| Expiry | A date and time after which the key stops working. |
| IP restriction | Allowed IPv4 or IPv6 addresses or CIDR ranges, one per line. Requests from any other address are refused. |
| Allowed models | Leave empty to let the key use everything you have access to, or select models to restrict it to only those. |
| Rate limit | Requests per minute for this key, up to the maximum the site allows. |
- Create several keys at once; a numbered suffix is added to the name.
- Edit a key's limits, regenerate its secret, or revoke it at any time. Changes apply immediately.
- An account can hold up to 20 keys.
- A key can only use models your account is entitled to. If a plan or code changes your access, every key follows immediately with nothing to re-save.
Plans & subscriptions
A plan is a fixed-duration subscription. Depending on how it is set up, it can unlock specific models, include a request limit, and give you plan credit equal to its price. You can also skip plans and simply pay as you go from the wallet.
| Plan | Price | Duration | Request limit | Plan credit | Usage discount | Real usage covered |
|---|---|---|---|---|---|---|
| Gemini | 1,600,000 Toman | 30 days | Unlimited | 1,600,000 Toman | 5% | 1,684,211 Toman |
| Gemini | 4,700,000 Toman | 90 days | Unlimited | 4,700,000 Toman | 6,50% | 5,026,738 Toman |
| Gemini | 9,150,000 Toman | 180 days | Unlimited | 9,150,000 Toman | 9% | 10,054,945 Toman |
| Chat GPT | 4,400,000 Toman | 30 days | Unlimited | 4,400,000 Toman | 5% | 4,631,579 Toman |
| Chat GPT | 13,000,000 Toman | 90 days | Unlimited | 13,000,000 Toman | 6,50% | 13,903,743 Toman |
| Chat GPT | 25,200,000 Toman | 180 days | Unlimited | 25,200,000 Toman | 9% | 27,692,308 Toman |
How plan credit works
- Each purchase of a paid plan gives credit equal to the plan price. The credit belongs to that purchase.
- Wallet and plan are separate balances.
- Unused credit expires with the plan and cannot be refunded or moved to the wallet.
- When the credit ends, requests on this plan stop; switch to your wallet or buy a new plan.
- A usage discount, when a plan has one, lowers what each request takes from the credit. With 10%, every 100 of real usage takes 90 from the credit.
- The discount makes the credit cover more real usage than you paid for: with 20%, every 100 of usage takes 80 from the credit, so 1,000,000 paid covers 1,250,000 of usage. See the "Real usage covered" column above.
- Longer plans have a bigger discount, so their price per month is lower. A plan for one provider usually has a bigger discount than a plan for all models.
- Only one plan runs at a time; a plan bought while another is running waits and starts when the first ends. If you use several providers, choose the plan for all models, or pay the other models from your wallet.
- A plan for chosen models can only pay for those models. A free plan has no credit: it only sets the duration, model access and request limit.
- On a plan with credit, the request limit counts only requests paid from the plan. Requests paid from your wallet do not use it.
Choosing what pays
While a plan with credit is running, you choose where requests are paid from: Plan or Wallet. The default is Plan. For your API keys the choice is called "API requests pay from" and you can change it on the Overview tab and on the Wallet tab of your panel. The live chat has its own choice, "Live chat pays from", above the chat input, and it works independently of the API: your chats can be paid from your plan while your API keys use your wallet, or the other way round. Until you change it in the chat, the live chat follows your API choice. Nothing is ever moved from the wallet to the plan on its own, and the other way round.
Warnings
You are told once for each of these, in the panel and by email or Telegram when you use them: the credit is running low, almost empty, used up, the plan expires soon (with the amount that will burn) and the plan expired (with the amount that burned).
API errors for plan credit
| Status | code | Meaning |
|---|---|---|
| 402 | plan_budget_exhausted | The payment source is "plan" and its credit cannot cover the request (used up, or too low for the worst case of this request). Switch to the wallet, buy a new plan, or lower max_tokens. Nothing is taken from the wallet. |
| 402 | model_not_in_plan | The payment source is "plan" and the plan does not include this model. Switch to the wallet to use it. |
Response headers
| Header | Meaning |
|---|---|
X-Plan-Remaining | Plan credit left, in Toman, with 2 decimals. |
X-Plan-Expires-At | When the plan ends, ISO 8601 in UTC. |
They are added to successful answers while the plan pays and is near its end: the credit is at or below the warning share, or the plan ends within the warning days. Streamed answers carry the values from before the request.
Questions about plans
How is a plan different from the wallet?
The wallet holds money you top up; it never expires and works for every model you may use. A plan gives you credit equal to its price for a fixed period, and that credit is spent only on requests paid from the plan. The two balances are separate and are never added together.
What happens when the plan credit is used up?
Requests paid from the plan stop. Nothing is taken from your wallet on its own. Switch the payment source to your wallet, or buy a new plan, to continue.
What happens to unused credit when the plan ends?
Unused credit expires with the plan and cannot be refunded or moved to the wallet.
What if I buy again before the plan ends?
The new plan is queued and starts when the current one ends. Each purchase has its own credit and its own end date, and only the running plan's credit is spent.
How do I choose what pays for my requests?
While a plan is running you can choose what pays for your API requests with the Plan | Wallet switch on the Overview tab and on the Wallet tab. The live chat has its own Plan | Wallet switch above the chat input, so the live chat and your API keys work independently of each other.
How much more usage does the discount give me?
A plan with a 20% usage discount makes every 100 of real usage take 80 from your credit, so the credit covers 25% more usage than you paid for. For example, paying 1,000,000 Toman covers 1,250,000 Toman of usage. Longer plans have a bigger discount, so the price per month is lower.
Which plan should I choose?
If you mostly use one provider (for example only Gemini), choose that provider's plan: it usually has the bigger discount. If you use several providers, choose the plan for all models. Pick the duration by how much you really use: unused credit expires with the plan.
Which models can I use with the plan credit?
A plan for all models can pay for any model you may use. A plan for specific models can only pay for those; for any other model, switch to your wallet.
Your panel & live chat
Everything about your account is in the user panel.
Balance, spending, requests and tokens over the period you pick, from the last 12 hours up to a year.
A workspace with saved, searchable and pinnable conversations, file attachments, custom instructions, a thinking setting for reasoning models, image generation, text-to-speech, transcription and video generation. Everything is billed to the same wallet.
Search the catalog, filter by capability and open a page for each model with its pricing, context length and recent performance.
Insights on how each model and key is used, plus every request with filters, search and a full report for each row.
Open a support ticket, follow the replies and get notified when we answer.
Link your Telegram account from your profile. The link is verified through Telegram itself, and you then receive alerts such as credit received, low balance and announcements, in your own language.
Models & providers
The catalog currently contains 474 active models. Use the model name exactly as it appears in the catalog as the "model" value of your request.
List models
curl https://apiex.cloud/api/v1/models \ -H "Authorization: Bearer YOUR_API_KEY"
{
"data": [
{
"id": "openai/gpt-5.6-terra-pro",
"name": "...",
"architecture": {
"input_modalities": ["text", "image"],
"output_modalities": ["text"]
},
"context_length": 128000,
"pricing": { "prompt": "0.0000010", "completion": "0.0000040" }
}
]
}
Model ids use the form vendor/model, for example openai/gpt-5. Send either that form or the bare model name. GET /models lists text models by default; add ?output_modalities=all, or a comma list such as image,video, to include the others.
Without a key you get the full public catalog. With a key you get only the models that key may use, matching what the chat endpoint will accept. The pricing block is in USD per token (the selling price, margin included); price_input_per_1k and price_output_per_1k are per 1,000 tokens in the wallet currency.
Query parameters
GET /models accepts these optional query parameters, the same ones OpenRouter uses. Filters can be combined.
| Parameter | Type | Description |
|---|---|---|
output_modalities | string | Comma-separated output types to list: text, image, video, audio, speech, transcription, embeddings, or all. Defaults to text. |
input_modalities | string | Comma-separated input types a model must accept: text, image, audio, file. |
supported_parameters | string | Comma-separated request parameters a model must support, for example tools. |
endpoints | string | Comma-separated request paths a model must serve, for example /api/v1/embeddings. |
q | string | Search by model id, name or description. |
arch | string | Only models of this family, for example GPT, Claude or Gemini. |
model_authors | string | Comma-separated vendor names, for example openai,anthropic. |
context | integer | Minimum context length, in tokens. |
min_price, max_price | number | Lowest or highest prompt (input) price, in USD per million tokens. Use min_price and max_price. |
min_output_price, max_output_price | number | Lowest or highest completion (output) price, in USD per million tokens. Use min_output_price and max_output_price. |
min_age_days, max_age_days | integer | Youngest or oldest model, in days since it was added. Use min_age_days and max_age_days. |
sort | string | Order of the list: pricing-low-to-high, pricing-high-to-low, context-high-to-low or newest. Models without a value come last. |
offset | integer | Number of models to skip. |
limit | integer | Most models to return, from 1 to 1,000. With neither offset nor limit the whole list is returned. |
The answer holds data (the models), total_count (every model that matches, before offset and limit) and links.next (the path of the next page, or null on the last one). GET /embeddings/models, /images/models and /videos/models accept offset and limit and answer in the same shape.
Each model also carries endpoints (the request paths that serve it, such as /api/v1/embeddings), supported_voices, knowledge_cutoff and hugging_face_id, which are null when not known.
Providers
Models from these providers are available in the catalog right now.
Best practices
- Create a separate key per application and environment (production, staging, local).
- Store keys in environment variables or a secrets manager, never in source control or client-side code.
- Give each key a spend limit and, where possible, an IP allow-list and a model allow-list.
- Set max_tokens deliberately. It bounds both the cost of a request and the amount held on your wallet.
- Send an Idempotency-Key and retry only 429 and 5xx responses, with exponential backoff and the Retry-After delay.
- Use /cost/estimate before expensive requests, and /usage/me to watch your balance from code.
- Revoke a key immediately if you suspect it was exposed, then create a new one.
Frequently asked questions
Can I chat with the models without writing code?
Yes. Open the live chat in your panel to talk to all paid and free models in one place and switch between them. Your conversations and their history are saved, and it is billed to the same wallet.
Is the API compatible with the official OpenAI SDKs?
Yes. Set the SDK's base URL to the gateway address and use your gateway API key. No other code changes are needed.
What happens if my balance is too low?
Before forwarding a request, the gateway holds the most it could cost. If your available balance does not cover that, the request is refused with 402 insufficient_balance and nothing is charged. Lower max_tokens or top up your wallet. Otherwise only the real cost is charged and the rest of the hold is released.
Why was my request charged less than the estimate?
The estimate is the worst case: the whole input plus the full max_tokens of output. You are charged the real usage, which is normally lower.
Which request parameters are forwarded?
Only the standard chat parameters listed in the Chat completions section. Any other parameter is ignored.
Can I restrict a key to specific models?
Yes. Select the allowed models when you create or edit the key. Leave the list empty to allow every model your account can use.
Can I cap how much a key can spend?
Yes. Set a spend limit on the key, in total, per day or per month. Once it is used up, requests return 402 spend_limit.
Do unused wallet credits expire?
Money added to the wallet by a top-up does not expire. Plan credit is different: it lasts as long as the plan and then burns. It cannot be refunded or moved to the wallet.
Are my prompts stored?
The usage log records metadata about each request, such as the model, token counts, cost, status, duration, IP address and request ID. See the Privacy Policy for how data is handled.
Open a ticket from your panel or send us a message. Our team is happy to help.