1xAi SDK — cookbook
Open-source Python and Node SDKs for 1xAi, an OpenAI-compatible AI gateway for Iran: one key and one base URL for OpenAI, Anthropic Claude, Google Gemini and DeepSeek — no VPN, no foreign card, billed in Toman.
pip install 1xai-sdk # Python
npm install 1xai-sdk # Node / TypeScriptThe packages are deliberately thin. This README is the actual product: every recipe below is copy-paste runnable, and every model name and endpoint in it was verified against the live gateway.
---
The 10-second version
1xAi is the OpenAI API at a different base URL. You do not need any of this to use it:
from openai import OpenAI
client = OpenAI(api_key="1xai-...", base_url="https://1xai.ir/v1")import OpenAI from "openai";
const client = new OpenAI({ apiKey: "1xai-...", baseURL: "https://1xai.ir/v1" });That is the whole integration. Three env vars cover most tools:
export OPENAI_API_KEY="1xai-..."
export OPENAI_BASE_URL="https://1xai.ir/v1" # some tools call it OPENAI_API_BASESo why does this package exist?
Because there are exactly four things a generic OpenAI SDK cannot know about a gateway in Iran, and all four cost you an afternoon the first time you hit them:
| | | |---|---| | Toman cost | estimateCost() / costOfResponse(), priced from 1xAi's public catalogue. Your bill is in Toman; your SDK thinks in dollars it never shows you. | | Persian errors | The gateway answers {"error":{"message":"کلید API نامعتبر است"}}. explain() turns that into one actionable English sentence. | | 402 means something else | On api.openai.com you would never see a 402. Here it means your wallet is empty, not your code is broken. That is a top-up, not a debugging session. | | Wrong-key confusion | Pasting an sk-... key fails at construction with an explanation, instead of a mystery 401 twenty lines later. |
We depend on the official openai package and pre-configure it. That is a deliberate design choice: re-implementing HTTP, streaming, retries, tool calls and file uploads would ship a worse copy of a client OpenAI already maintains, and it would drift every time the API gains a field. You get the real SDK, with the base URL, key discovery and validation already correct. If our wrapper were large, it would be doing something wrong.
---
Point your existing tools at 1xAi
No code — just a base URL and a key. Get a key from the dashboard; new accounts get free credit from the signup wheel.