IN ENGLISH · API DOCS

API documentation

Point any OpenAI SDK at https://1xai.ir/v1, authenticate with a 1xai-* key, and the models of OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot AI, Z.ai, Alibaba Qwen, MiniMax and Tencent Hunyuan are callable from an Iranian network, billed in Toman from a prepaid wallet. Each key may send 1,000 requests a minute by default. Every topic below has a page of its own.

Last updated:

[01]FIRST REQUEST

One request, any vendor

curl · POST /v1/chat/completionsbash
curl https://1xai.ir/v1/chat/completions \
  -H "Authorization: Bearer 1xai-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Hello from Tehran"}]
  }'
python · openai sdkpython
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Switching vendor is a string change: set model to gpt-5.5, claude-sonnet-5 or gemini-3.5-flash and the gateway routes by name. The steps from a new account to this request are in the quickstart.

[02]DOCUMENTATION

Getting started

  • Quickstart

    From a new account to a first answer from the 1xAi API: create a key, set the base URL https://1xai.ir/v1, and send one request with curl, Python or Node.

  • Authentication

    Every request to the 1xAi API carries a 1xai-* key in Authorization: Bearer, x-api-key or x-goog-api-key. A key in the URL is not accepted.

  • Models

    Models from 10 vendors behind one 1xAi key: counts from the live list, routing by model name, GET /v1/models, and what happens to retired ids.

  • SDKs

    The official OpenAI, Anthropic and Google GenAI SDKs work against https://1xai.ir by changing the base URL. Python and Node samples, Claude Code, and the open-source 1xai-sdk package.

[03]DOCUMENTATION

Core concepts

  • Rate limits

    Each 1xAi API key may send 1,000 requests a minute by default. The X-RateLimit headers, the 429 response, Retry-After, and how to get a higher limit.

  • Errors

    The error format of the 1xAi API, the request id header, and every error code with its cause and fix: 400, 401, 402, 403, 404, 409, 410, 413, 415, 429, 5xx.

  • Request id and cost

    The X-Request-Id header on every API response, the X-1xai-Cost-Toman header with that call's amount in Toman, and how to read the cost of a streamed call with GET /v1/usage?request_id=.

  • Billing and pricing

    How 1xAi prices API calls: the vendor's list price plus a 15–30% markup, times the day's dollar rate. 10% VAT on top-ups, holds, failed calls free, refunds.

  • Streaming

    With stream: true the answer arrives as Server-Sent Events and the last chunk carries the token counts. What a dropped connection costs, the time limit, and streaming on the Anthropic and Gemini routes.

[04]DOCUMENTATION

API endpoints

  • OpenAI-compatible endpoints

    The /v1 endpoints of 1xAi that work: chat/completions, responses with web search, embeddings, images, audio and videos; each with an example, its billing unit, and what the gateway changes in a request.

  • Function calling and structured output

    On the 1xAi API the fields tools, tool_choice, response_format with json_schema, and image input reach the model vendor unchanged. One example of each, and which server-side tools are allowed.

  • Anthropic (native)

    The route https://1xai.ir/anthropic/v1/messages is Anthropic's own Messages API: prompt caching with cache_control, extended thinking, citations, count_tokens, Message Batches, and Claude Code with the same 1xAi key.

  • Gemini (native)

    The route https://1xai.ir/gemini/v1beta is Google's own Generative Language API: generateContent, streamGenerateContent, countTokens, Google Search grounding, and video with Gemini Omni.

  • Realtime voice

    Connect your own app to two-way live voice through 1xAi: a 2-minute client secret, a WebSocket relay for gpt-realtime and Gemini Live, calls of up to 30 minutes, and how audio is billed.

[05]DOCUMENTATION

Account, keys and teams

  • Account API

    Read the usage log, one call by its id, a CSV export, daily roll-ups, the wallet and the keys with the same API key: GET /v1/usage, /v1/usage/export, /v1/usage/summary, /v1/wallet/*, /v1/keys and /v1/keys/current.

  • API keys and security

    A 1xAi key is shown once and only its hash is stored. Expiry (at least 12 hours), a spend cap that revokes the key by itself, alerts, and what is logged for how long.

  • Teams and budgets

    A 1xAi company account: one shared wallet, workspaces, 5 roles, workspace keys, and monthly limits per workspace and per member, in Toman and in requests.

[06]DOCUMENTATION

Reference

  • Unsupported endpoints

    The honest list of what the 1xAi API does not accept: OpenAI Assistants, Uploads and files for interactive use, Gemini cachedContents and files, unmetered hosted tools, and the answer each one gets.

  • Tool guides

    Step-by-step guides for Cursor, Claude Code, n8n, Cline, Open WebUI, LibreChat and Continue.

  • Changelog

    What changed in the API and the product, release by release.

[07]DOCUMENTATION

New features

  • Key controls

    For each API key: a list of allowed models (up to 100), allowed IP addresses (up to 50), a scope, the key's own rate limit, and rotation with a grace period.

  • Webhooks

    1xAi sends account events (low balance, a key near its cap, a key revoked or expired, a service credit paid) to your HTTPS address as a signed POST, with up to 7 attempts per event.

  • Service credit

    1xAi measures the success rate of each model vendor's calls per Persian-calendar month, counting only the failures that were ours; when a month is under 99.5%, part of what your wallet paid that vendor in it comes back as wallet credit after a review. Covered from Azar 1405.

  • OpenAI Batch

    Send OpenAI chat and embedding requests in one JSONL file and get the results within 24 hours at 50% of the usual price: the files and batches routes, the file rules, limits, the hold, settlement and errors.

FOR TOOLS AND LANGUAGE MODELS

The API is described in an OpenAPI 3.1 file. Every docs page has a markdown copy at /md plus its path (for example /md/en/docs/rate-limits), and llms.txt lists them all.

1xAi is an independent gateway. It is not affiliated with, endorsed by, or a reseller for OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot AI, Z.ai, Alibaba Qwen, MiniMax or Tencent Hunyuan. Requests are relayed upstream rather than answered by models of our own, 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.

MORE IN ENGLISH
  • Changelog

    What changed in the API and the product, release by release.

  • Terms of Service

    Billing, refunds, availability, liability and termination.

  • Privacy Policy

    What we collect, what never leaves, and what the model provider receives.

  • Contact

    Business enquiries, large top-ups, and anything the docs did not answer.

  • Models and prices

    Every callable model with live Toman rates, context windows and endpoints.

  • Overview

    What 1xAi is, who it is for, and what it costs — the English entry point.

  • ChatGPT API from Iran

    Whether the OpenAI API can be called from an Iranian network, and how.

  • Claude API from Iran

    Anthropic's Messages API from Iran, including the native passthrough route.

  • OpenAI-compatible endpoint

    The base URL, the auth header, every supported route, streaming and errors.

  • Pricing

    How billing works: list price plus a 15–30% markup by model, paid in Toman.

  • Service status

    Per-vendor success rates and latency from real traffic, with sample sizes, plus the raw dataset.

  • Benchmark

    The published latency figures, and an open script that times any OpenAI-compatible gateway with your own key.

  • Service credit

    The monthly success-rate commitment per vendor family, the credit tiers, and each closed month's measured rates.

  • AI tutor for the Konkur

    The learning panel for Iran's university entrance exam, compared with Zerang, Andarz, ChatGPT and Gemini, with sources.