۱۰۰ هزار تومان هدیهٔ ثبت‌نام، تا ۱ میلیونبا ثبت‌نام گردونهٔ هدیه را بچرخان: دست‌کم ۱۰۰٬۰۰۰ تومان و تا ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه، بدون کارت بانکیگردونهٔ هدیه۱ میلیون برای تو، ۱ میلیون برای دوستتدوستانت را دعوت کن: برای هر دوستی که فعال شود ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه می‌گیری و خودش هم ۱٬۰۰۰٬۰۰۰ تومانجوایز
1xAi
مستندات API

API حساب: مصرف، خروجی CSV، کیف پول و کلیدها

هر چه داشبورد دربارهٔ مصرف و کیف پول نشان می‌دهد، با همان کلید 1xai-* از API هم خوانده می‌شود: فهرست تماس‌ها با هزینهٔ هر کدام، یک تماس با شناسه‌اش، خروجی CSV یک بازه، خلاصهٔ روزانه، کیف پول و کلیدها. این مسیرها فقط‌خواندنی و رایگان‌اند و در سقف نرخ همان کلید شمرده می‌شوند. کلید شخصی و کلید فضای کاری شرکت هر کدام فقط دادهٔ خودشان را می‌خوانند.

آخرین به‌روزرسانی:

فهرست مستندات

API حساب · ۱

مسیرها

مسیرهای API حساب
مسیرچه برمی‌گرداند
GET /v1/usageفهرست تماس‌ها، تازه‌ترین اول؛ با request_id= یک تماس
GET /v1/usage/exportتماس‌های یک بازه به‌صورت فایل CSV
GET /v1/usage/summaryخلاصهٔ یک بازه: جمع‌ها و سری روزانه، به تفکیک مدل، سازنده و کلید
GET /v1/wallet/transactionsتراکنش‌های کیف پول: شارژ، کسر، برگشت
GET /v1/wallet/summaryخلاصهٔ کیف پول و اعتبار قابل خرج همین لحظه
GET /v1/keysکلیدها
GET /v1/keys/{id}یک کلید و آمار مصرفش
GET /v1/keys/currentهمان کلیدی که درخواست با آن فرستاده شده
  • فقط GET. هر روش یا مسیر دیگری زیر /v1/usage، /v1/wallet و /v1/keys خطای 404 با کد path_not_found می‌گیرد و هرگز به سازندهٔ مدل نمی‌رسد.
  • در مسیرهای مصرف (/v1/usage، /v1/usage/summary و /v1/usage/export) و در /v1/wallet/transactions مقدار from یا to (و در مسیرهای مصرف request_id) که خوانده نشود خطای 400 با کد invalid_request می‌گیرد و نام همان پارامتر در param می‌آید. پارامتر نادرست دیگر نادیده گرفته می‌شود و مقدار پیش‌فرض به کار می‌رود.
  • پاسخ‌ها هدر Cache-Control: no-store دارند.
  • هر کلید چه چیزی را می‌خواند در بخش بعد آمده است.

API حساب · ۲

هر کلید چه چیزی را می‌خواند

دسترسی کلید شخصی و کلید فضای کاری شرکت
مسیرکلید شخصیکلید فضای کاری شرکت
GET /v1/usage, /v1/usage/summary, /v1/usage/exportتماس‌های حساب، بیرون از فضاهای کاری شرکتتماس‌های همان فضای کاری (همهٔ اعضا، از API و از محصول چت)
GET /v1/keys, /v1/keys/{id}, /v1/keys/currentکلیدهای حساب، بیرون از فضاهای کاری شرکتکلیدهای همان فضای کاری
GET /v1/wallet/summaryکل خلاصهفقط scope و spendable_toman
GET /v1/wallet/transactionsریز تراکنش‌های کیف پول403 با کد forbidden
GET /v1/sla/creditsاعتبارهای جبرانی حساب403 با کد forbidden
  • از راه کلید API، متن ثبت‌شدهٔ درخواست و پاسخ (request_body و response_body) فقط برای تماس‌هایی برگردانده می‌شود که با یک کلید API فرستاده شده‌اند. برای آنچه در محصول چت نوشته شده این دو فیلد null هستند. داشبورد مثل قبل متن خود هر کس را نشان می‌دهد.
  • کیف پول شرکت مال کل شرکت است: کلید فضای کاری فقط اعتبار قابل خرج را می‌خواند و ریز تراکنش‌ها در داشبورد شرکت است.
  • تماس‌هایی که یک نفر در فضای کاری شرکت فرستاده با کلید همان فضا یا در داشبورد شرکت خوانده می‌شوند، نه با کلید شخصی او (تیم‌ها و بودجه‌ها).
  • هیچ کلیدی داده‌ای از حساب یا شرکت دیگری نمی‌خواند.

API حساب · ۳

گزارش مصرف: GET /v1/usage

GET /v1/usage
curl
curl "https://1xai.ir/v1/usage?limit=50&status=ok&from=2026-11-01&to=2026-11-18" \
  -H "Authorization: Bearer 1xai-..."

# یک تماس با شناسه‌اش (هدر X-Request-Id پاسخ)
curl "https://1xai.ir/v1/usage?request_id=gw_01JD3Z5T8Q0V6W4M2K9R7N1PXA" \
  -H "Authorization: Bearer 1xai-..."
پارامترهای /v1/usage
پارامترمعنی
limitشمار ردیف‌ها؛ پیش‌فرض ۵۰، حداکثر ۵۰۰
offsetردیف‌هایی که باید رد شوند، برای صفحه‌بندی
from, toبازهٔ زمانی: زمان RFC-3339 با منطقهٔ زمانی (2026-11-01T00:00:00Z یا 2026-11-01T08:30:00+03:30)، یا تاریخ ساده YYYY-MM-DD که روز تهران خوانده می‌شود: در from آغاز آن روز و در to پایانش. پس from=2026-06-01&to=2026-06-01 دقیقاً همان روز تهران است. قالب دیگر خطای 400 می‌گیرد.
request_idتطبیق دقیق با شناسهٔ یک تماس (X-Request-Id پاسخش)؛ حداکثر ۱۲۸ نویسه از حروف، رقم‌ها و _ - . :. ردیف‌های همان تماس را برمی‌گرداند (معمولاً یکی) اگر این کلید اجازهٔ خواندنش را داشته باشد؛ شناسهٔ حساب دیگر، شناسهٔ ناشناخته یا شناسهٔ سازنده فهرست خالی می‌دهد. با فیلترهای دیگر هم ترکیب می‌شود.
modelنام دقیق مدل
provideropenai, anthropic, gemini, deepseek, xai, moonshot, zhipu, alibaba, minimax, tencent
statusok برای تماس‌های موفق، error برای ناموفق
key_idشناسهٔ یک کلید
qجست‌وجو در نام مدل، مسیر، نام کلید، شناسهٔ تماس و متن ثبت‌شدهٔ درخواست و پاسخ. جست‌وجویی که بیش از ۸ ثانیه طول بکشد با 503 و کد usage_search_timeout متوقف می‌شود؛ بازه را با from و to کوتاه کن، و برای یافتن یک تماس request_id را به کار ببر.

پاسخ

json
{
  "usage": [
    {
      "created_at": "2026-11-18T08:12:45Z",
      "model": "gpt-5.5",
      "provider": "openai",
      "endpoint": "/v1/chat/completions",
      "prompt_tokens": 812,
      "completion_tokens": 240,
      "total_tokens": 1052,
      "cached_tokens": 0,
      "base_cost_usd": 0.004432,
      "cost_toman": 1375,
      "status_code": 200,
      "request_id": "gw_01JD3Z5T8Q0V6W4M2K9R7N1PXA",
      "request_body": "{…}",
      "response_body": "{…}",
      "request_body_truncated": false,
      "response_body_truncated": false,
      "key_name": "production",
      "workspace": null
    }
  ],
  "total": 18234,
  "filtered_total": 412
}
  • cost_toman مبلغ کامل همان تماس است، با کارمزد؛ base_cost_usd قیمت رسمی سازنده به دلار، پیش از کارمزد.
  • cached_tokens بخشی از prompt_tokens است که از کش خوانده شده.
  • request_id شناسهٔ 1xAi برای همان تماس است، همان X-Request-Id پاسخش (متادیتای پاسخ). فقط برای ردیف‌های قدیمی‌ای که شناسه ندارند null است.
  • request_body و response_body متن ثبت‌شدهٔ تماس‌اند و پس از ۳۰ روز null می‌شوند (چه چیزی ثبت می‌شود). از راه کلید API فقط برای تماس‌هایی برمی‌گردند که با کلید API فرستاده شده‌اند.
  • در مسیرهای غیرتوکنی total_tokens واحد همان مسیر است: ثانیهٔ صدا در رونویسی، نویسه در متن به گفتار و شمار تصویر در ساخت تصویر.
  • total شمار همهٔ ردیف‌هایی است که این کلید می‌خواند و filtered_total شمار ردیف‌های همین فیلتر. با request_id هر دو برابر شمار ردیف‌های برگشتی‌اند.
  • ردیف برگشت وجه endpoint: "refund" و مبلغ منفی دارد.

API حساب · ۴

خلاصهٔ مصرف: GET /v1/usage/summary

GET /v1/usage/summary
curl
curl "https://1xai.ir/v1/usage/summary?days=30" \
  -H "Authorization: Bearer 1xai-..."
  • days: شمار روزهای گذشته؛ پیش‌فرض ۳۰، حداکثر ۳۶۵. from و to اگر فرستاده شوند مقدم‌اند و همان قاعدهٔ /v1/usage را دارند. فیلترهای /v1/usage این‌جا هم کار می‌کنند، جز request_id که نادیده گرفته می‌شود.
  • جمع‌ها: total_calls، ok_calls، error_calls، total_tokens، prompt_tokens، completion_tokens، total_cost_toman، total_cost_usd، average_cost_toman.
  • daily: یک ردیف برای هر روز (به وقت تهران) با day، calls، tokens، cost_toman و سهم هر سازنده.
  • by_model، by_provider، by_key و by_status: همان بازه به تفکیک مدل، سازنده، کلید و وضعیت HTTP.

API حساب · ۵

خروجی CSV: GET /v1/usage/export

GET /v1/usage/export
curl
curl -o usage.csv "https://1xai.ir/v1/usage/export?from=2026-11-01&to=2026-11-30" \
  -H "Authorization: Bearer 1xai-..."
پارامترهای خروجی
پارامترمعنی
fromآغاز، با خودش. زمان RFC-3339 یا تاریخ ساده (روز تهران). پیش‌فرض: ۳۱ روز پیش از to.
toپایان، با خودش. زمان RFC-3339 یا تاریخ ساده (پایان همان روز تهران). پیش‌فرض: همین حالا.
cursorادامهٔ خروجی بریده‌شده: خانهٔ دوم خط #truncated فایل قبلی، با همان from و to.
  • بازهٔ from تا to حداکثر ۳۱ روز است. بازهٔ بلندتر، from بعد از to، مقدار خوانده‌نشده یا cursor نادرست خطای 400 با کد invalid_request و param می‌گیرد. بازه هرگز بی‌صدا کوتاه نمی‌شود.
  • پاسخ 200 با Content-Type: text/csv; charset=utf-8، Content-Disposition: attachment; filename="1xai-usage-<from>-<to>.csv" (تاریخ‌ها به وقت تهران)، Cache-Control: no-store و X-1xai-Export-Row-Limit (سقف ردیف‌های یک فایل) است.
  • فایل UTF-8 با نشانهٔ ترتیب بایت (BOM) است تا Excel نام‌های فارسی را درست نشان دهد؛ خط‌ها با CRLF تمام می‌شوند و خانه‌ها به قاعدهٔ RFC-4180 در گیومه می‌آیند. ردیف‌ها تازه‌ترین اول‌اند.
  • خانهٔ متنی‌ای که با =، +، -، @، تب یا CR شروع شود (حتی پس از فاصله) با یک ' در ابتدا نوشته می‌شود تا صفحه‌گسترده آن را فرمول نخواند.
  • هر فایل حداکثر ۱۰۰٬۰۰۰ ردیف دارد. اگر ردیف بیشتری باشد، خط آخر #truncated,<cursor> است: با cursor=<cursor> و همان from و to دوباره بخواه تا بقیه بیاید، بی‌تکرار و بی‌جاافتادگی. فایلی که این خط را ندارد کامل است.
  • اگر خروجی پس از نوشتن چند ردیف با خطا قطع شود، یا پس از ۱۰ دقیقه هنوز تمام نشده باشد، خط آخر #error,<cursor> است: فایل ناقص است و از همان cursor ادامه بده.
  • برای هر حساب (و برای کلید فضای کاری شرکت، برای هر فضا) یک خروجی در یک زمان: دومی 429 با کد export_in_progress و Retry-After: 5 می‌گیرد. حداکثر ۶ خروجی در دقیقه: بیشتر از آن 429 با کد rate_limited و Retry-After. سقف نرخ خود کلید هم مثل هر مسیر دیگر برقرار است.
  • فایل همان ردیف‌هایی را دارد که GET /v1/usage به همان کلید نشان می‌دهد و هرگز متن درخواست یا پاسخ را ندارد. در داشبورد، دکمهٔ «دانلود CSV» در گزارش تماس‌ها همین فایل را برای بازهٔ انتخاب‌شده می‌دهد.
ستون‌های فایل CSV، به ترتیب
ستونمحتوا
timeزمان تماس به UTC، مثل 2026-11-18T09:30:15.123Z
request_idشناسهٔ 1xAi برای همان تماس (X-Request-Id پاسخش)
key_nameنام کلید؛ __chat__ برای تماس‌های خود محصول چت، خالی وقتی کلید حذف شده
modelمدلی که هزینه‌اش حساب شد
providerسازندهٔ مدل، مثل گزارش مصرف
endpointمسیر، مثل /v1/chat/completions
statusوضعیت HTTP پاسخ
prompt_tokensمثل گزارش مصرف
completion_tokensمثل گزارش مصرف
cached_tokensمثل گزارش مصرف
total_tokensمثل گزارش مصرف (در صدا و تصویر، واحد همان مسیر)
base_cost_usdقیمت رسمی سازنده برای همان تماس به دلار، تا هشت رقم اعشار
markup_percentدرصد کارمزدی که اعمال شد
toman_per_usdنرخ دلاری که اعمال شد
cost_tomanمبلغی که حساب شد، به تومان

API حساب · ۶

کیف پول: GET /v1/wallet/summary و /v1/wallet/transactions

curl
curl "https://1xai.ir/v1/wallet/summary?days=30" \
  -H "Authorization: Bearer 1xai-..."

curl "https://1xai.ir/v1/wallet/transactions?limit=20&kind=topup,refund" \
  -H "Authorization: Bearer 1xai-..."
  • /v1/wallet/summary: balance_toman (موجودی فعلی)، spendable_toman (اعتبار قابل خرج همین لحظه: موجودی منهای مبلغ رزروشدهٔ درخواست‌های در جریان، به‌علاوهٔ اعتبار هدیه‌ای که روی هر مدلی خرج می‌شود)، و جمع شارژ، مصرف، برگشت و تغییر خالص بازه، با سری روزانه.
  • spendable_toman همان عددی است که هشدار کم شدن اعتبار با آن سنجیده می‌شود.
  • /v1/wallet/transactions: limit (پیش‌فرض ۵۰، حداکثر ۵۰۰)، offset، from، to و kind (فهرستی از topup، charge، refund، adjustment، gift). from و to همان‌طور خوانده می‌شوند که در مسیرهای مصرف: زمان RFC-3339 با منطقهٔ زمانی، یا تاریخ ساده YYYY-MM-DD که روز تهران خوانده می‌شود (در from آغاز آن روز و در to پایانش)؛ قالب دیگر خطای 400 با کد invalid_request و param می‌گیرد.
  • هر تراکنش id، created_at، kind، amount_toman (کسرها منفی) و reference دارد. reference یک کسر همان شناسهٔ تماس (X-Request-Id) است.
  • بخشی از هزینهٔ یک تماس که از اعتبار پلن پرداخت شده در تراکنش‌های کیف پول نیست؛ مبلغ کامل در cost_toman گزارش مصرف است.

GET /v1/wallet/summary با کلید فضای کاری شرکت

json
{
  "scope": "workspace",
  "spendable_toman": 4820000
}

API حساب · ۷

کلیدها: GET /v1/keys و /v1/keys/current

پاسخ GET /v1/keys

json
{
  "keys": [
    {
      "id": 4821,
      "prefix": "1xai-AbCdEfGh",
      "name": "production",
      "last_used_at": "2026-11-18T08:12:45Z",
      "revoked_at": null,
      "expires_at": null,
      "cap_toman": 5000000,
      "spent_toman": 1284350,
      "created_at": "2026-10-02T11:30:00Z"
    }
  ]
}
  • خود کلید هرگز برگردانده نمی‌شود؛ فقط پیشوندش.
  • کلیدهای باطل‌شده و منقضی هم در فهرست‌اند.
  • GET /v1/keys/{id} همان کلید را با stats برمی‌گرداند: total_calls، ok_calls، total_tokens، total_cost_toman، first_used_at، last_used_at و most_used_model.
  • GET /v1/keys/current کلیدی را برمی‌گرداند که همین درخواست با آن فرستاده شده: {"key":{…}} با همان فیلدهای یک کلید در GET /v1/keys، بدون stats. برای اسکریپتی که باید بداند با کدام کلید کار می‌کند، سقف خرجش چقدر است و چقدر از آن مانده.
  • ساخت و ابطال کلید در داشبورد است (کلیدها و امنیت).