
مستندات 1xAi و API
هر موضوع صفحهٔ خودش را دارد: شروع سریع، احراز هویت، محدودیت نرخ، خطاها، صورتحساب، مدلها و مسیرهای API. از راهنمای کاربر شروع کن یا مستقیم سراغ صفحهای برو که لازم داری.
https://1xai.ir/v1آخرین بهروزرسانی:
- سازگار با OpenAI
- بدون ویپیان
- صورتحساب تومانی
- ۱٬۰۰۰ درخواست در دقیقه
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": "سلام"}]
}'فهرست مستندات
در همین صفحه
مسیرهای API
حساب، کلید و تیم
راهنمای کاربر · ۱
شروع سریع در ۵ دقیقه
از ثبتنام تا دیدن مصرف در داشبورد، در شش گام.
گام ۱
ثبتنام و تأیید
از صفحهٔ ثبتنام با ایمیل یا شمارهٔ موبایل حساب بساز و آن را تأیید کن.
گام ۲
تکمیل پروفایل هویتی
در /onboarding نام کامل، کد ملی و شمارهٔ موبایلت را ثبت کن. تا این پروفایل کامل نشده، داشبورد کلید صادر نمیکند و شارژ ممکن نیست.
گام ۳
گردونهٔ هدیه یا شارژ
حساب تازه یک بار گردونهٔ هدیه را میچرخاند. برای ادامه، از صفحهٔ شارژ کیف پول را شارژ کن.
گام ۴
ساخت کلید API
در کلیدهای API یک کلید
1xai-*صادر و همان لحظه کپی کن؛ دوباره نشان داده نمیشود.گام ۵
یک تماس با curl
یک درخواست به
/v1/chat/completionsبفرست و مدل را رویgpt-5.5،claude-sonnet-5یاgemini-3.5-flashبگذار.گام ۶
دیدن مصرف
در داشبورد همان تماس را با هزینهٔ تومانی، توکنها و زمانش میبینی.
اولین تماس
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": "سلام"}]
}'نسخهٔ کامل، با نمونهٔ Python و Node: شروع سریع API.
راهنمای کاربر · ۲
شروع به کار
استفاده از 1xAi به نصب چیزی نیاز ندارد: حساب میسازی، کلید API میگیری و آدرس پایهٔ کلاینتت را عوض میکنی. اگر نمیخواهی کد بنویسی، از آزمایشگاه یک پیام بفرست تا اولین پاسخ را بگیری.
راهنمای کاربر · ۳
آشنایی با داشبورد
- موجودی فعلی
- مبلغی که با هر تماس موفق کم میشود.
- کلیدهای API
- فهرست کلیدها، با پیشوند، نام و آخرین استفاده.
- گزارش مصرف
- تماسهای اخیر، با مدل، توکن و هزینهٔ تومانی هر تماس.
راهنمای کاربر · ۴
راهنمای داشبورد
- خلاصهٔ موجودی
- موجودی فعلی، مصرف یک روز گذشته، شمار تماسهای موفق و ناموفق.
- نمودارها
- تماسهای روزانه، توکنها و سهم هر سازنده، به وقت تهران.
- جستوجو در گزارش
- فیلتر روی متن، مدل، سازنده، وضعیت و بازهٔ زمانی، در سمت سرور.
- صفحهٔ هر کلید
- نمودار، آخرین تماسها، مدلهای پرمصرف، سقف خرج و دکمهٔ ابطال همان کلید.
- تنظیمات و امنیت
- تغییر رمز، تأیید دومرحلهای و فهرست نشستهای فعال.
راهنمای کاربر · ۵
شارژ موجودی
در صفحهٔ شارژ مبلغ و روش پرداخت را انتخاب میکنی: درگاه زرینپال، درگاه دیجیپی و کارتبهکارت با ثبت رسید. هر شارژ از ۱٬۰۰۰ تومان تا ۲۵٬۰۰۰٬۰۰۰ تومان است و ۱۰٪ مالیات بر ارزش افزوده روی مبلغ اضافه میشود. پرداخت با درگاه بلافاصله به کیف پول مینشیند؛ کارتبهکارت پس از بررسی رسید تأیید میشود.
جزئیات قیمت، کارمزد و برگشت وجه: صورتحساب و قیمتگذاری.
راهنمای کاربر · ۶
آزمایشگاه
آزمایشگاه برای فرستادن یک پیام به مدل بدون نوشتن کد است: مدل را انتخاب میکنی، پیامت را مینویسی و پاسخ، همراه با هزینهٔ تومانی همان تماس، نمایش داده میشود.
راهنمای کاربر · ۷
انتخاب مدل مناسب
با یک کلید و یک آدرس به مدلهای ۱۰ سازنده میرسی و نام مدل تعیین میکند درخواست به کدام سازنده برود. مدلهای کوچک (mini، flash، haiku) سبک و ارزاناند و برای بیشتر کارهای روزمره کافی هستند؛ مدلهای پرچمدار برای کارهای پیچیدهتر مناسبترند. فهرست زنده با قیمت تومانی در صفحهٔ مدلها است و جدول مسیریابی در مستند مدلها.
راهنمای کاربر · ۸
اتصال ابزارها به 1xAi
هر ابزاری که آدرس پایهٔ سفارشی بپذیرد با همین کلید کار میکند. نقطهٔ شروع: راهنمای اتصال ابزارها، یا مستقیم راهنمای ابزار خودت:
راهنمای کاربر · ۹
پرسشهای پرتکرار
آیا برای استفاده از 1xAi نیاز به VPN دارم؟
آیا متن درخواستهای من ذخیره میشود؟
چطور بفهمم هر تماس چقدر هزینه داشت؟
آیا کلید 1xAi با SDKهای OpenAI کار میکند؟
آیا 1xAi به مدلهای Claude دسترسی دارد؟
آیا میتوانم از مدلهای Gemini گوگل استفاده کنم؟
هر کلید چند درخواست در دقیقه میتواند بفرستد؟
مرجع API: هر موضوع، یک صفحه
همهٔ مسیرها روی همین آدرس پایه، با هدر Authorization: Bearer 1xai-*:
https://1xai.ir/v1شروع
- شروع سریع API: اولین درخواست در چند دقیقهاز ساخت حساب تا اولین پاسخ از API هوش مصنوعی 1xAi: ساخت کلید، آدرس پایهٔ https://1xai.ir/v1 و یک درخواست با curl، Python و Node.
- احراز هویت در API: کلید و هدرهاهر درخواست به API 1xAi کلید 1xai-* را در هدر Authorization: Bearer، x-api-key یا x-goog-api-key میفرستد. کلید در نشانی پذیرفته نمیشود.
- مدلهای API: شمار، سازندهها و مسیر هر مدلمدلهای ۱۰ سازنده با یک کلید در 1xAi: شمار مدلها از فهرست زنده، مسیریابی با نام مدل، GET /v1/models و رفتار مدلهای بازنشسته.
- استفاده با SDK: کتابخانههای OpenAI، Anthropic و Googleکتابخانههای رسمی OpenAI، Anthropic و Google GenAI با عوض کردن آدرس پایه به https://1xai.ir کار میکنند. نمونهٔ Python و Node، Claude Code و بستهٔ متنباز 1xai-sdk.
مفاهیم پایه
- محدودیت نرخ درخواست در APIهر کلید API در 1xAi بهطور پیشفرض ۱٬۰۰۰ درخواست در دقیقه میفرستد. هدرهای X-RateLimit، پاسخ 429، Retry-After و راه گرفتن سقف بالاتر.
- مرجع خطاهای API: قالب پاسخ و همهٔ کدهاقالب پاسخ خطا در API 1xAi، هدر شناسهٔ درخواست، و همهٔ کدهای خطا با علت و راهحل: 400، 401، 402، 403، 404، 409، 410، 413، 415، 429، 5xx.
- متادیتای پاسخ: شناسهٔ درخواست و هزینهٔ هر تماسهدر X-Request-Id روی هر پاسخ API، هدر X-1xai-Cost-Toman با مبلغ تومانی همان تماس، و راه خواندن هزینهٔ یک تماس استریم با GET /v1/usage?request_id=.
- صورتحساب و قیمتگذاری APIفرمول قیمت API در 1xAi: قیمت رسمی سازنده بهعلاوهٔ کارمزد ۱۵ تا ۳۰٪، ضرب در نرخ روز دلار. مالیات ۱۰٪ روی شارژ، رزرو مبلغ، درخواست ناموفق رایگان، برگشت وجه.
- پاسخ استریم (SSE) در APIبا stream: true پاسخ بهصورت Server-Sent Events میرسد و آخرین تکه شمار توکنها را دارد. رفتار قطع اتصال، مهلت پاسخ و استریم در مسیرهای Anthropic و Gemini.
مسیرهای API
- مسیرهای سازگار با OpenAI: چت، Responses، امبدینگ، تصویر، صدا و ویدیومسیرهای /v1 در 1xAi که کار میکنند: chat/completions، responses با جستوجوی وب، embeddings، images، audio و videos؛ هر کدام با نمونه، واحد محاسبهٔ هزینه و آنچه دروازه در درخواست تغییر میدهد.
- فراخوانی تابع، خروجی ساختاریافته و ورودی تصویردر API 1xAi فیلدهای tools، tool_choice، response_format با json_schema و ورودی تصویر بدون تغییر به سازندهٔ مدل میرسند. یک نمونه از هر کدام، و ابزارهای سمت سروری که مجازند.
- مسیر نیتیو Anthropic: Messages API، کش پرامپت و Claude Codeمسیر https://1xai.ir/anthropic/v1/messages همان Messages API رسمی Anthropic است: کش پرامپت با cache_control، فکر گسترده، استنادها، count_tokens، دستههای پیام (Message Batches) و Claude Code با همان کلید 1xAi.
- مسیر نیتیو Gemini: generateContent، استریم و ساخت ویدیومسیر https://1xai.ir/gemini/v1beta همان Generative Language API رسمی Google است: generateContent، streamGenerateContent، countTokens، grounding با Google Search و ساخت ویدیو با Gemini Omni.
- صوت زنده (Realtime)
حساب، کلید و تیم
- API حساب: مصرف، خروجی CSV، کیف پول و کلیدهابا همان کلید API، گزارش مصرف، یک تماس با شناسهاش، خروجی CSV، خلاصهٔ روزانه، کیف پول و کلیدها را بخوان: GET /v1/usage، /v1/usage/export، /v1/usage/summary، /v1/wallet/*، /v1/keys و /v1/keys/current.
- کلیدهای API و امنیتکلید 1xAi یک بار نمایش داده میشود و فقط هش آن نگه داشته میشود. تاریخ انقضا (دستکم ۱۲ ساعت)، سقف خرج که کلید را خودش باطل میکند، هشدارها، و آنچه ثبت میشود.
- تیمها و بودجهها: حساب شرکتی، نقشها و سقف ماهانهحساب شرکتی 1xAi: کیف پول مشترک، فضاهای کاری، ۵ نقش، کلید فضای کاری و سقف ماهانه برای هر فضا و هر عضو، به تومان و به تعداد درخواست.
مرجع
امکانات تازه
- محدودیتهای کلید: فهرست مدل، نشانی IP، دامنهٔ دسترسی و چرخش کلیدبرای هر کلید API: فهرست مدلهای مجاز (تا ۱۰۰)، نشانیهای IP مجاز (تا ۵۰)، دامنهٔ دسترسی، سقف نرخ خود کلید و چرخش کلید با مهلت.
- وبهوکها: خبر کم شدن اعتبار و وضعیت کلید1xAi رویدادهای حساب (کم شدن اعتبار، نزدیک شدن کلید به سقف، ابطال و انقضای کلید، پرداخت اعتبار جبرانی) را با POST امضاشده به نشانی HTTPS تو میفرستد؛ تا ۷ تلاش برای هر رویداد.
- اعتبار جبرانی: تعهد نرخ موفقیت API1xAi نرخ موفقیت تماسها با هر سازندهٔ مدل را در هر ماه شمسی میسنجد و در آن فقط شکستهایی را میشمارد که از طرف ما بوده؛ اگر ماهی زیر ۹۹.۵٪ باشد، بخشی از آنچه کیف پولت آن ماه به آن سازنده پرداخته، پس از بررسی، بهصورت اعتبار برمیگردد. از آذر ۱۴۰۵.
- پردازش دستهای OpenAI: نیمبها با Batch APIدرخواستهای چت و امبدینگ OpenAI را در یک فایل JSONL بفرست و تا ۲۴ ساعت بعد نتیجه بگیر، با ۵۰٪ قیمت عادی: مسیرهای files و batches، قواعد فایل، سقفها، رزرو، تسویه و خطاها.
برای ابزارها و مدلهای زبانی: مشخصات OpenAPI، و نسخهٔ متنی هر صفحه با افزودن /md به ابتدای مسیر آن (مثل /md/docs/rate-limits).
کلید بساز و اولین درخواست را همین حالا بزن.