مستندات 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 "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-..."| پارامتر | معنی |
|---|---|
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 | نام دقیق مدل |
provider | openai, anthropic, gemini, deepseek, xai, moonshot, zhipu, alibaba, minimax, tencent |
status | ok برای تماسهای موفق، error برای ناموفق |
key_id | شناسهٔ یک کلید |
q | جستوجو در نام مدل، مسیر، نام کلید، شناسهٔ تماس و متن ثبتشدهٔ درخواست و پاسخ. جستوجویی که بیش از ۸ ثانیه طول بکشد با 503 و کد usage_search_timeout متوقف میشود؛ بازه را با from و to کوتاه کن، و برای یافتن یک تماس request_id را به کار ببر. |
پاسخ
{
"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 "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 -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» در گزارش تماسها همین فایل را برای بازهٔ انتخابشده میدهد.
| ستون | محتوا |
|---|---|
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 "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 با کلید فضای کاری شرکت
{
"scope": "workspace",
"spendable_toman": 4820000
}API حساب · ۷
کلیدها: GET /v1/keys و /v1/keys/current
پاسخ GET /v1/keys
{
"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. برای اسکریپتی که باید بداند با کدام کلید کار میکند، سقف خرجش چقدر است و چقدر از آن مانده.- ساخت و ابطال کلید در داشبورد است (کلیدها و امنیت).