Connect LibreChat to an AI API from Iran
LibreChat is an open-source, multi-user chat interface like ChatGPT, with accounts, history and several endpoints side by side, that runs with Docker on your own server. You define 1xAi once as a custom endpoint in librechat.yaml, and the models of all ten vendors are available in the same interface with one key billed in Toman.
Setting up LibreChat
- [01]
Create an account and a 1xAi key. Register at 1xai.ir (the app is in Persian) and confirm your email or mobile number. You spin the sign-up gift wheel (from 100,000 to 1,000,000 Toman of gift credit) once, which is enough to test the connection. Then create a 1xai-* key in the dashboard and copy it at once: a key is shown only once.
- [02]
Create librechat.yaml with a custom endpoint. In the root of the LibreChat project (beside docker-compose.yml) create librechat.yaml and define an endpoint under endpoints → custom: name 1xAi, baseURL https://1xai.ir/v1 and apiKey ${ONEXAI_API_KEY}. With fetch: true the model list is read from /v1/models, and default is the fallback list.
- [03]
Put the key in .env. Add the line ONEXAI_API_KEY=1xai-* to the .env file of the same folder. When it starts, LibreChat replaces ${ONEXAI_API_KEY} with that variable's value, so the key is never written inside librechat.yaml.
- [04]
Mount the file into the container and restart. With Docker, librechat.yaml has to be mounted into the api container through docker-compose.override.yml. The first time, build the container with the new mount using docker compose up -d; after that, docker compose restart is enough after any change to librechat.yaml or .env.
- [05]
Choose 1xAi and start a conversation. In the selector at the top of the chat page pick the 1xAi endpoint and then the model, and send a message. The title of each new conversation is written by titleModel, which is a small separate call; the Toman cost of every call is recorded in the usage report of the 1xAi dashboard.
Ready to copy
version: 1.2.1
cache: true
endpoints:
custom:
- name: "1xAi"
apiKey: "${ONEXAI_API_KEY}"
baseURL: "https://1xai.ir/v1"
models:
default: ["gpt-5", "claude-sonnet-4-6", "gemini-2.5-flash", "gpt-4o-mini"]
fetch: true
titleConvo: true
titleModel: "gpt-4o-mini"
modelDisplayLabel: "1xAi"services:
api:
volumes:
- type: bind
source: ./librechat.yaml
target: /app/librechat.yamlONEXAI_API_KEY=1xai-XXXXXXXXXXXXXXXX docker compose up -d docker compose restart
Recommended model
Recommended: gpt-5. A cheaper alternative: gpt-4o-mini. Use a strong model for the main conversation and keep a light one beside it in default for everyday work. Set titleModel to a small model so that writing each conversation's title costs almost nothing. Every model and its Toman price is on the models page.
Common errors
- 1xAi is not in the list of endpoints
- That means librechat.yaml was not read: either it is not mounted into the container or the YAML has an error. The file has to be at /app/librechat.yaml in the container, and after adding the mount docker compose up -d is needed, not only a restart. A configuration error is printed in docker compose logs api; YAML is sensitive to indentation and does not accept tabs.
- Only the default models are shown
- When /v1/models does not answer, usually because ONEXAI_API_KEY is wrong or empty, LibreChat falls back to the default list. Check the key's value in .env, make sure fetch: true is under models, and restart the container.
- 401: invalid key
- The key is wrong, has expired, or you revoked it. Copy it again from the dashboard or create a new one, with no space before or after it.
- 402: insufficient balance
- The account's Toman credit is used up. A top-up starts at 100,000 Toman, by the Zarinpal gateway or the Digipay gateway or card-to-card transfer with a receipt; calls work again as soon as a payment succeeds.
- Model name or routing error
- 1xAi routes by model name: claude-* to Anthropic, gemini-* to Google, deepseek-* to DeepSeek; grok-*, kimi-*, glm-*, qwen*, MiniMax-* and hy* reach the Grok, Kimi, GLM, Qwen, MiniMax and Hunyuan models; every other name goes to OpenAI. Write a model id exactly as the model list shows it.
Every error code is in the error reference.
Why is apiKey written as ${ONEXAI_API_KEY}?
LibreChat replaces environment variables in librechat.yaml with that syntax. The key stays in .env, and the yaml file itself can safely be kept in git or shared with teammates. If you want each user to enter a 1xai-* key of their own, set apiKey to "user_provided" instead.
Is the text of my conversations stored anywhere?
The chat history stays in the database of that LibreChat server (MongoDB). 1xAi passes the request to the vendor of that model. Next to each usage record, the start of the request and of the response (up to 64 KB each) and, when it is longer, its last 16 KB are kept so that you can read them in your own usage report. That text is erased after 30 days. The numbers (model, tokens, cost, status and time) stay for accounting.
Other guides: Cursor, Claude Code, n8n, Cline, Open WebUI, Continue.
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.