API documentation

1. [01]

   Register and complete the identity profile. Sign up with an email, confirm it, then fill the short identity profile (full name, national ID, mobile number) at /onboarding. Verified identity is an Iranian legal requirement for Rial payments — until the profile is complete, key, wallet and chat endpoints answer 428.

2. [02]

   Spin the gift wheel. Every new account gets one server-drawn spin worth 100,000 to 1,000,000 Toman of wallet credit. It never expires and spends on API calls, so you can benchmark the endpoint against your own workload before paying anything.

3. [03]

   Create a key. Issue a 1xai-* key from the dashboard and copy it immediately — the full key is shown once.

4. [04]

   Send the first request. Any of the three below. Switching provider is a string change: set model to gpt-5, claude-sonnet-4-6 or gemini-2.5-pro and the gateway routes by name.

curl https://1xai.ir/v1/chat/completions \
  -H "Authorization: Bearer 1xai-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Hello from Tehran"}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://1xai.ir/v1",
    api_key="1xai-...",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",  # any provider's model, same client
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://1xai.ir/v1",
  apiKey: "1xai-...",
});

const resp = await client.chat.completions.create({
  model: "gemini-2.5-flash",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);

Every request must carry your 1xai-* key. The canonical header is Authorization: Bearer, but the gateway also accepts the key as x-api-key and x-goog-api-key — which is what lets the official Anthropic and Google SDKs work unmodified in the native sections below.

# canonical form — every OpenAI-style client sends this for you
Authorization: Bearer 1xai-XXXXXXXXXXXXXXXXXXXXXXXX

# the same key is also accepted under the provider-style names,
# so native Anthropic / Google SDKs need no header rewriting:
x-api-key: 1xai-...
x-goog-api-key: 1xai-...

Each key may send up to 300 requests per minute; the burst allowance is also 300, so the whole budget can be spent in one instant. Beyond that the answer is 429 with a Retry-After header saying when to try again. The limit shapes speed only — it never costs money.

GET /v1/models returns the merged catalogue — OpenAI, Anthropic, Google and DeepSeek in one list, every entry callable with the same key from the same base URL. Routing is by model name: claude-* to Anthropic, gemini-* / gemma-* to Google, the rest to their own providers. Live Toman rates per model are on the models page.

curl https://1xai.ir/v1/models \
  -H "Authorization: Bearer 1xai-..."

Retired model ids stay callable: when a provider kills an id, the gateway aliases it to its living successor instead of failing your pinned config. When that happens the response carries an X-1xai-Model-Alias header naming the model that actually served — watch for it if exact model identity matters to your evals.

The compatibility layer on /v1silently drops what the OpenAI schema cannot express — Anthropic's cache_control, extended thinking and citations, Google's cachedContentsand grounding. Two passthrough routes expose each provider's official API unchanged, with the same 1xai-* key and the same wallet.

Anthropic — https://1xai.ir/anthropic

The exact Messages API: key in x-api-key, plus the required anthropic-version header. count_tokens is available for sizing a prompt before sending it, and /v1/messages on the main base URL routes to this same passthrough — the gateway recognises the Anthropic wire shape wherever it arrives. Claude Code needs nothing but two environment variables and no Anthropic account:

export ANTHROPIC_BASE_URL="https://1xai.ir/anthropic"
export ANTHROPIC_AUTH_TOKEN="1xai-..."
claude

from anthropic import Anthropic

client = Anthropic(
    base_url="https://1xai.ir/anthropic",
    api_key="1xai-...",
)

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.content[0].text)

Gemini — https://1xai.ir/gemini/v1beta

The exact Generative Language API (generateContent, streamGenerateContent, cachedContents). The key must travel in the x-goog-api-key header — the ?key= query parameter is not accepted and answers 401, so configure Google SDKs with a header, never a URL.

curl https://1xai.ir/gemini/v1beta/models/gemini-2.5-flash:generateContent \
  -H "x-goog-api-key: 1xai-..." \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Summarise this text."}]}
    ]
  }'

Set "stream": true and the response arrives as standard Server-Sent Events — every OpenAI-compatible streaming client works as-is. The gateway adds stream_options.include_usage for you, so the final chunk always carries the token counts; those counts are the input to your Toman bill, which means a streamed call is as auditable as a buffered one.

Balance is held in Toman. Each successful call costs the provider's own USD list price for the tokens used, converted at the daily USD rate, plus a flat 20% markup — deducted from the wallet as you go. Failed requests are logged but never charged.

Low balance degrades gracefully instead of refusing: if your max_tokens asks for more output than the wallet can fund, the gateway lowers the cap to what the balance affords and makes the call. The response may then end with finish_reason: "length" — the model wrote until the money ran out. A 402 is reserved for the case where the wallet cannot fund even the prompt plus one output token.

402 · payment required

The wallet truly cannot fund prompt + 1 token. Top up; calls work immediately after a successful payment.

428 · profile incomplete

The identity profile is not finished — a legal prerequisite for Rial payments, not a billing state. Complete it at 1xai.ir/onboarding.

503 · provider incident

The upstream provider is failing on our side of the relay — never your balance or your key. We retry automatically; if it persists, check the status page and try again in a few minutes.

Everything the dashboard shows is readable over the API with the same 1xai-* key — no second credential, no session token. That is what you want when attributing spend to a tenant or wiring a budget alarm.

GET /v1/usage

The call log. Filters: limit, from, to, q, model, provider, status.

GET /v1/usage/summary

Daily roll-ups for the last N days (days=N) — chart-ready.

GET /v1/wallet/summary

Wallet over the last N days: total top-ups, total spend, net change.

GET /v1/wallet/transactions

Every credit and debit, paginated with limit and offset — for reconciliation scripts.

GET /v1/keys

Your keys with prefix, name and last use; /v1/keys/{id} adds per-key usage aggregates.

# the key that makes your API calls also reads its owner's account
curl "https://1xai.ir/v1/usage/summary?days=30" \
  -H "Authorization: Bearer 1xai-..."

1xAi is an independent gateway. It is not affiliated with, endorsed by, or a reseller for OpenAI, Anthropic, Google or DeepSeek. Requests are relayed to those providers' official APIs, so each provider's own usage policies apply to what their models will and will not do, and their model availability is theirs to change. Current reachability is published on the status page.