پردازش دستهای OpenAI: نیمبها با Batch API
درخواستهایی را که لازم نیست همان لحظه جواب بگیرند در یک فایل JSONL بارگذاری میکنی و از آن یک دسته (batch) میسازی؛ OpenAI آنها را تا ۲۴ ساعت بعد اجرا میکند و ورودی و خروجی با ۵۰٪ قیمت عادی همان مدل حساب میشوند، با همان کارمزد همیشگی. کتابخانهٔ رسمی OpenAI با آدرس پایهٔ https://1xai.ir/v1 و کلید 1xAi کار میکند. هنگام ساختن دسته بیشترین هزینهٔ ممکنش از کیف پول رزرو میشود و وقتی تمام شد فقط درخواستهای انجامشده حساب میشوند.
آخرین بهروزرسانی:
فهرست مستندات
مسیرهای API
حساب، کلید و تیم
پردازش دستهای OpenAI · ۱
پردازش دستهای به چه کار میآید
هر کاری که میتواند چند ساعت صبر کند و تعداد زیادی درخواست دارد: دستهبندی و برچسبزدن هزاران متن، خلاصهسازی و ترجمهٔ انبوه، ساختن بردار (امبدینگ) برای یک پایگاه متن، یا اجرای یک مجموعهٔ ارزیابی. همان کار با ۵۰٪ هزینهٔ ورودی و خروجی انجام میشود و سقف نرخ کلیدت را هم مصرف نمیکند، چون هر دسته فقط چند درخواست به API است.
- فقط مدلهای OpenAI، روی دو مسیر:
/v1/chat/completionsو/v1/embeddings. - نتیجه حداکثر تا ۲۴ ساعت بعد آماده است (
completion_windowفقط24h). دستهای که تا آن زمان تمام نشود وضعیتexpiredمیگیرد: درخواستهای انجامشدهاش در فایل خروجی هستند و بقیه هزینهای ندارند. - هزینه فقط از کیف پول پرداخت میشود؛ اعتبار پلن و اعتبار هدیه هزینهٔ دسته را نمیپردازند.
- هر فایل و دسته فقط با کلیدهای همان حسابی در دسترس است که آن را ساخته، و اگر با کلید فضای کاری شرکت ساخته شده باشد فقط با کلیدهای همان فضای کاری. هر کلید دیگری همان پاسخ شناسهٔ ناشناخته را میگیرد:
404با کدnot_found. فهرستها هم فقط فایلها و دستههای خود تو را نشان میدهند.
پردازش دستهای OpenAI · ۲
مسیرها
| مسیر | کار |
|---|---|
POST /v1/files | بارگذاری فایل ورودی: فرم multipart/form-data با purpose=batch و file (فایل JSONL). فایل هنگام بارگذاری سطر به سطر بررسی میشود. پاسخ شیء فایل OpenAI است (id به شکل file-…). |
GET /v1/files | فایلهای دستهای خودت (ورودی و خروجی)، تازهترین اول. پارامترها: purpose (batch یا batch_output)، limit (پیشفرض و بیشینه ۱۰٬۰۰۰)، order (desc یا asc) و after (شناسهٔ یک فایل). |
GET /v1/files/{id} | یکی از فایلهایت؛ expires_at زمان پاک شدن آن است. |
GET /v1/files/{id}/content | محتوای فایل خروجی یا فایل خطای یک دسته، مستقیم از OpenAI. انتقالی که وسط کار قطع شود با قطع اتصال تمام میشود، نه با یک فایل کوتاهتر. |
DELETE /v1/files/{id} | پاک کردن فایل همین حالا (نگهداری و حذف). |
POST /v1/batches | ساختن دسته: input_file_id، endpoint (همان url سطرهای فایل)، completion_window برابر 24h و در صورت نیاز metadata. پاسخ شیء دستهٔ OpenAI است (id به شکل batch_…). |
GET /v1/batches | دستههای خودت، تازهترین اول، همانطور که OpenAI آخرین بار گزارش داده. limit تا ۱۰۰ (پیشفرض ۲۰) و after (شناسهٔ یک دسته). |
GET /v1/batches/{id} | وضعیت یک دسته: status، request_counts، output_file_id و error_file_id. |
POST /v1/batches/{id}/cancel | لغو دسته (لغو). |
- هر مسیر دیگری زیر
/v1/files،/v1/uploadsو/v1/batches، و بارگذاری با هرpurposeدیگری جزbatch، خطای402با کدpath_unmeteredمیگیرد. فهرست سراسری اشیای OpenAI هیچوقت داده نمیشود؛ فهرستهای بالا از سابقهٔ خود 1xAi خوانده میشوند. - فایل یک دسته (ورودی، خروجی یا خطا) فقط به کار دسته میآید: اگر
file_idآن را در بدنهٔ/v1/responsesیا/v1/chat/completionsبیاوری، حتی با کلید صاحبش، پاسخ404با کدnot_foundاست و چیزی رزرو یا حساب نمیشود. expires_afterدر بارگذاری وoutput_expires_afterدر ساخت دسته نادیده گرفته میشوند؛ مدت نگهداری را 1xAi تعیین میکند (نگهداری و حذف).
پردازش دستهای OpenAI · ۳
نمونهٔ کامل: از فایل تا نتیجه
هر سطر فایل ورودی یک درخواست است، با یک custom_id یکتا که در نتیجه هم برمیگردد:
requests.jsonl
{"custom_id": "review-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5-mini", "messages": [{"role": "user", "content": "این نظر را مثبت یا منفی دستهبندی کن: ارسال سریع بود."}], "max_completion_tokens": 1000}}
{"custom_id": "review-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5-mini", "messages": [{"role": "user", "content": "این نظر را مثبت یا منفی دستهبندی کن: بستهبندی خراب رسید."}], "max_completion_tokens": 1000}}کتابخانهٔ رسمی OpenAI
import time
from openai import OpenAI
client = OpenAI(
base_url="https://1xai.ir/v1",
api_key="1xai-...",
)
# ۱. بارگذاری فایل
batch_file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
# ۲. ساختن دسته
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
# ۳. صبر تا پایان دسته
while batch.status not in ("completed", "failed", "expired", "cancelled"):
time.sleep(60)
batch = client.batches.retrieve(batch.id)
# ۴. دانلود نتیجهها
print(batch.status, batch.request_counts)
if batch.output_file_id:
client.files.content(batch.output_file_id).write_to_file("results.jsonl")# ۱. بارگذاری فایل
curl https://1xai.ir/v1/files \
-H "Authorization: Bearer 1xai-..." \
-F purpose=batch \
-F file=@requests.jsonl
# ۲. ساختن دسته، با id پاسخ بالا
curl https://1xai.ir/v1/batches \
-H "Authorization: Bearer 1xai-..." \
-H "Content-Type: application/json" \
-d '{"input_file_id": "file-...", "endpoint": "/v1/chat/completions", "completion_window": "24h"}'
# ۳. وضعیت دسته
curl https://1xai.ir/v1/batches/batch_... \
-H "Authorization: Bearer 1xai-..."
# ۴. نتیجهها، با output_file_id دسته
curl https://1xai.ir/v1/files/file-.../content \
-H "Authorization: Bearer 1xai-..." \
-o results.jsonl- وضعیت دسته اول
validating، بعدin_progressوfinalizingاست و در پایان یکی ازcompleted،failed،expired،cancelled. هر چند دقیقه یک بار پرسیدن کافی است. - فایل خروجی (
output_file_id) برای هر درخواست انجامشده یک سطر دارد، با همانcustom_idو پاسخ کامل درresponse.body. ترتیب سطرهای خروجی لزوماً ترتیب فایل ورودی نیست؛ باcustom_idجفتشان کن. - درخواستهایی که شکست خوردهاند یا منقضی شدهاند در فایل خطا (
error_file_id) هستند و هزینهای ندارند. - دروازه سطرها را تغییر نمیدهد: تغییرهایی که روی مسیرهای تعاملی انجام میشود (آنچه دروازه تغییر میدهد)، مثل تبدیل
max_tokensبهmax_completion_tokensیا حذفtemperatureبرای مدلهای استدلالی، در دسته انجام نمیشود. هر سطر را همانطور بنویس که OpenAI میپذیرد؛ سطری که OpenAI رد کند در فایل خطا میآید و هزینهای ندارد.
پردازش دستهای OpenAI · ۴
قواعد فایل ورودی
- هر سطر یک شیء JSON است؛ سطر خالی نادیده گرفته میشود.
custom_id: رشتهٔ غیرخالی تا ۵۱۲ نویسه، یکتا در همان فایل.methodبرابرPOST، وurlبرابر/v1/chat/completionsیا/v1/embeddings، در همهٔ سطرهای یک فایل یکسان.body.model: مدلی از OpenAI که در دسته فروخته میشود و در 1xAi قیمت دارد. روی چت: خانوادههایgpt-6،gpt-5،gpt-4.1،gpt-4o،gpt-4-turbo،gpt-4،gpt-3.5-turbo،o1،o3وo4-mini. روی امبدینگ:text-embedding-3-*وtext-embedding-ada-002. پذیرفته نمیشوند: مدلهای صدا، Realtime، جستوجو، تصویر، رونویسی و گفتار، Codex، مدلهای-pro، deep-research و computer-use، و*-chat-latest. یک فایل میتواند چند مدل داشته باشد.max_tokensیاmax_completion_tokens: اختیاری؛ اگر بفرستی، عدد صحیحی از یک تا بیشینهٔ خروجی مدل (از فهرست مدلهای ما؛ ۱۲۸٬۰۰۰ برای مدلی که بیشینهاش آنجا نیست). سطری که سقف ندارد با بیشینهٔ خروجی مدل رزرو میشود؛ برای رزرو کمتر سقف خودت را بگذار.n: تا ۸؛ خروجیnبرابر رزرو میشود.
آنچه در یک سطر پذیرفته نمیشود
"stream": true.- صدا:
modalitiesباaudio، فیلدaudio، یا بخشinput_audio. - بخش فایل (
file: PDF یاfile_id). web_search_optionsوprediction.- هر ابزاری جز
functionوcustom. service_tierبا مقداری جزautoوdefault.
کل فایل هنگام بارگذاری بررسی میشود و اولین سطر نادرست کل فایل را رد میکند: 400 با کد batch_file_invalid، شمارهٔ سطر در line (همان شمارهای که ویرایشگر نشان میدهد، سطرهای خالی هم شمرده میشوند) و علت در reason. پیام به زبان هدر Accept-Language است. از فایل ردشده هیچ چیز جایی نگه داشته نمیشود و هزینهای ندارد.
{
"error": {
"message": "سطر 3: n باید بین ۱ و 8 باشد.",
"type": "api_error",
"code": "batch_file_invalid",
"line": 3,
"reason": "n"
}
}reason | معنی |
|---|---|
invalid_json | سطر یک شیء JSON معتبر نیست |
custom_id | custom_id خالی، غیررشته یا بلندتر از حد است |
duplicate_custom_id | custom_id تکراری است |
method | method برابر POST نیست |
url | url یکی از دو مسیر پذیرفتهشده نیست |
mixed_url | url با سطرهای قبلی فرق دارد |
body | body شیء JSON نیست یا خوانده نمیشود |
model | body.model نیست |
model_not_batch | مدل در دسته یا روی این url ارائه نمیشود |
model_not_priced | مدل در 1xAi قیمت ندارد |
stream | "stream": true |
max_tokens | سقف خروجی بیرون از بازهٔ مجاز است |
n | n بیرون از بازهٔ یک تا ۸ است |
unsupported_field | فیلد، بخش یا ابزاری که در دسته پذیرفته نمیشود (فهرست بالا) |
too_many_lines | بیش از ۵۰٬۰۰۰ درخواست |
line_too_long | سطری بزرگتر از ۸ مگابایت |
empty_file | فایل هیچ درخواستی ندارد (line برابر 0) |
پردازش دستهای OpenAI · ۵
سقفها
| چه چیزی | سقف | بیشتر از آن |
|---|---|---|
| حجم یک فایل | ۲۵ مگابایت | 413 batch_file_too_large |
| درخواستهای یک فایل | ۵۰٬۰۰۰ | 400 batch_file_invalid (too_many_lines) |
| یک سطر فایل ورودی | ۸ مگابایت | 400 batch_file_invalid (line_too_long) |
| بارگذاری همزمان | ۲ | 429 batch_limit |
| فایل ورودی نگهداشتهشده نزد OpenAI | ۱۰۰ | 429 batch_limit |
| حجم همهٔ فایلهای نگهداشتهشده (ورودی، خروجی و خطا) | ۲٬۰۴۸ مگابایت | 429 batch_limit |
| دستهٔ تسویهنشده در یک زمان | ۱۰ | 429 batch_limit |
| جمع تخمین دستههای تسویهنشده | ۱۰۰٬۰۰۰٬۰۰۰ تومان | 429 batch_limit |
| درخواستهای فرستادهشده در ۲۴ ساعت گذشته | ۲۰۰٬۰۰۰ | 429 batch_limit |
- پاسخ
429با کدbatch_limitدر سقف دستهها و درخواستها فیلدهایlimitوcurrentرا دارد؛ در سقف فایلها و حجم،filesوstored_bytesرا؛ و وقتی یک فایل در فضای باقیمانده جا نشود،reasonبرابرstored_bytes. فایلهایی را که لازم نداری باDELETE /v1/files/{id}پاک کن. - فایلی بزرگتر از سقف
413با کدbatch_file_too_largeمیگیرد. بارگذاری خیلی بزرگتر ممکن است پیش از رسیدن به دروازه رد شود:413بدون بدنهٔ JSON؛ آن را با وضعیت HTTP بشناس. - صف دستهای ما نزد OpenAI میان همهٔ حسابها مشترک است. وقتی پر باشد، ساخت دسته
429با کدupstream_capacityمیگیرد و چیزی رزرو نمیماند؛ کمی بعد دوباره بفرست یا دستهٔ کوچکتری بساز. - سقف نرخ کلید (محدودیت نرخ) فقط درخواستهای خود این مسیرها را میشمارد، نه سطرهای فایل را.
پردازش دستهای OpenAI · ۶
قیمت
cost_toman = tokens × vendor_list_price_usd × 0.5 × (1 + markup) × toman_per_usd0.5نیمبهای خود OpenAI برای دسته است: ورودی بدون کش و خروجی با ۵۰٪ نرخ عادی همان مدل. توکنهای ورودی کششده با نرخ عادی کش همان مدل حساب میشوند، بدون تخفیف دسته.- کارمزد همان کارمزد همیشگی همان مدل برای حساب توست و برای دسته عوض نمیشود (کارمزد بر اساس مدل)؛ نرخ تومان، نرخ روز هنگام تسویه است.
- فقط درخواستهای انجامشده حساب میشوند؛ درخواست ناموفق، منقضی یا لغوشده هزینهای ندارد.
- هزینهٔ هر مدل در هر دسته به تومان کامل به بالا گرد میشود.
- هزینهٔ دسته فقط از کیف پول پرداخت میشود: اعتبار پلن و اعتبار هدیه نه هزینهٔ دسته را میپردازند و نه پشتوانهٔ رزرو آن حساب میشوند (پلن چت و اعتبار هدیه).
- نرخ هر مدل در صفحهٔ قیمتها است.
پردازش دستهای OpenAI · ۷
رزرو مبلغ هنگام ساختن دسته
- با
POST /v1/batchesبیشترین هزینهٔ ممکن فایل تخمین زده میشود: پرامپت هر سطر از روی اندازهاش، هر تصویر با بیشترین توکنی که خانوادهٔ مدل برای یک تصویر میگیرد، و خروجی هر سطر با سقفش (یا اگر سقفی نداشت با بیشینهٔ خروجی مدل) ضرب درn؛ همه با قیمت دستهای و کارمزد حساب تو. - رزرو هر تصویر: ۴۸٬۲۰۰ توکن روی
gpt-4o-mini، ۳٬۸۰۰ روی مدلهای*-nano، ۲٬۷۰۰ روی بقیهٔ مدلهای*-miniو ۱٬۵۰۰ روی بقیه. فقط آنچه OpenAI گزارش کند حساب میشود. - این تخمین بهعلاوهٔ ۱۰٪ حاشیه (برای تغییر نرخ تومان تا پایان دسته) از کیف پول رزرو میشود. رزرو هزینه نیست: وقتی دسته تمام شد هزینهٔ واقعی کم و رزرو آزاد میشود. اگر OpenAI دسته را نپذیرد، رزرو همان لحظه آزاد میشود.
- اگر اعتبار قابل خرج (موجودی منهای رزروهای دیگر) کافی نباشد، پاسخ
402با کدinsufficient_balanceاست، با فیلدهایestimate_toman،required_tomanوavailable_toman، و چیزی فرستاده نمیشود. سقف خروجی سطرها را کمتر کن یا کیف پول را شارژ کن. - پیش از رزرو، همان بررسیهای هر تماس API برای مبلغ رزرو: حساب بدهکار
402با کدinsufficient_balanceمیگیرد؛ کلیدی که سقف خرج دارد باید برای آن مبلغ جا داشته باشد (402با کدkey_cappedو فیلدهایcap_toman،spent_tomanوrequired_toman)؛ و کلید فضای کاری شرکت باید زیر سقف ماهانهٔ فضای کاری و عضو جا داشته باشد (402با کدworkspace_limit). - اگر مدلی از فایل پس از بارگذاری قیمتش را از دست داده باشد، ساخت دسته
402با کدmodel_not_pricedمیگیرد. - اگر کلید فهرست مدل داشته باشد، همهٔ مدلهای فایل باید در آن باشند؛ وگرنه ساخت دسته با
403و کدkey_model_not_allowedرد میشود. بارگذاری فایل این بررسی را ندارد.
پردازش دستهای OpenAI · ۸
تسویه و گزارش مصرف
- وقتی OpenAI دسته را تمامشده گزارش کند (
completed،failed،expired،cancelled)، 1xAi معمولاً ظرف چند دقیقه فایل خروجی را میخواند، مصرف درخواستهای انجامشده را جمع میزند، هزینه را از کیف پول کم میکند و رزرو را آزاد میکند. لازم نیست چیزی دانلود کنی تا تسویه شود. - هزینه در گزارش مصرف (
GET /v1/usage، خروجی CSV و «لاگ درخواستها» در داشبورد) یک ردیف برای هر مدلِ هر دسته است:endpointبرابر/v1/batches، مدل با همان نامی که در فایل نوشتهای، توکنهای آن مدل در کل دسته، و مبلغ درcost_toman. request_idاین ردیفobatch_<batch id>_<model>است (مثلاًobatch_batch_abc123_gpt-5-mini)، پسGET /v1/usage?request_id=…ردیف یک مدل را دقیق پیدا میکند و جستوجویqبا شناسهٔ دسته همهٔ ردیفهایش را (API حساب).- ساختن و لغو دسته هم هر کدام یک ردیف بیهزینه در گزارش مصرف میگذارند (
/v1/batchesو/v1/batches/cancel). - پاسخ
POST /v1/batchesهدرX-1xai-Cost-Tomanندارد، چون هزینه هنگام تسویه معلوم میشود؛X-Request-Idرا مثل هر پاسخ دیگری دارد (متادیتای پاسخ). - در داشبورد، پردازش دستهای دستههایی را که با کلیدهای شخصی ساختهای نشان میدهد: وضعیت، درخواستهای انجامشده و ناموفق، مبلغ رزروشده یا هزینهٔ نهایی به تومان، و دانلود خروجی تا وقتی نگه داشته میشود.
پردازش دستهای OpenAI · ۹
نگهداری و حذف فایلها
- پس از تسویهٔ دسته، فایل ورودی، خروجی و خطای آن ۱ روز نزد OpenAI میمانند و بعد پاک میشوند.
expires_atدر شیء فایل زمان پاک شدن را میگوید. خروجی را در همین مدت دانلود کن. - فایل ورودی تا وقتی دستهاش باز است نگه داشته میشود. فایل ورودیای که در هیچ دستهای به کار نرود ۱ روز پس از بارگذاری پاک میشود.
- خواندن فایلی که دورهٔ نگهداریاش تمام شده:
404با کدfile_expired. DELETE /v1/files/{id}فایل را همان لحظه از OpenAI پاک میکند و پس از آن پاسخ404با کدnot_foundاست. فایل خروجی یا خطای یک دسته را پیش از تسویهٔ هزینهاش نمیشود پاک کرد:409با کدbatch_not_settled؛ چند دقیقه بعد دوباره امتحان کن.- حسابی که دستهٔ باز دارد حذف نمیشود: اول دسته را لغو کن و صبر کن تا تسویه شود. با حذف حساب، همهٔ فایلهای باقیمانده همان لحظه از OpenAI پاک میشوند.
پردازش دستهای OpenAI · ۱۰
لغو دسته
POST /v1/batches/{id}/cancelدسته را لغو میکند. وضعیت اولcancellingو بعدcancelledمیشود، که ممکن است چند دقیقه طول بکشد.- درخواستهایی که پیش از لغو انجام شدهاند در فایل خروجی هستند و حساب میشوند؛ بقیه هزینهای ندارند. دستهٔ لغوشده هم مثل بقیه تسویه میشود و رزروش آزاد میشود.
- پاسخهای خود OpenAI (مثلاً برای لغو دستهای که تمام شده) همانطور که OpenAI فرستاده برمیگردند.
پردازش دستهای OpenAI · ۱۱
خطاها
| وضعیت | کد | کِی |
|---|---|---|
400 | batch_file_invalid | سطری از فایل نادرست است (line، reason) |
400 | invalid_request | بارگذاری بدون multipart/form-data، بدون file یا بدون purpose؛ بدنهٔ ساخت دسته بدون input_file_id یا endpoint؛ completion_window جز 24h؛ input_file_id که فایل ورودی بررسیشدهٔ تو نیست یا پاک شده؛ endpoint که با url فایل نمیخواند |
402 | path_unmetered | purpose جز batch، یا مسیر دیگری زیر /v1/files، /v1/uploads یا /v1/batches |
402 | insufficient_balance | حساب بدهکار است یا کیف پول کفاف رزرو را نمیدهد |
402 | key_capped | سقف خرج کلید برای رزرو جا ندارد |
402 | workspace_limit | سقف ماهانهٔ فضای کاری یا عضو برای رزرو جا ندارد |
402 | model_not_priced | مدلی از فایل پس از بارگذاری قیمتش را از دست داده |
403 | key_model_not_allowed | مدلی از فایل در فهرست مدلهای کلید نیست |
404 | not_found | فایل یا دستهای که مال تو نیست، وجود ندارد یا پاکش کردهای؛ یا file_id یک فایل دسته در بدنهٔ یک تماس تعاملی |
404 | file_expired | دورهٔ نگهداری فایل تمام شده و پاک شده است |
409 | batch_not_settled | پاک کردن فایل خروجی یا خطا پیش از تسویهٔ دسته |
413 | batch_file_too_large | فایل بزرگتر از ۲۵ مگابایت |
429 | batch_limit | یکی از سقفهای حساب (بالا) |
429 | upstream_capacity | صف دستهای ما نزد OpenAI پر است |
500 | internal | فایل یا دسته ثبت نشد؛ پاک یا لغو شد و هزینهای ندارد. دوباره بفرست. |
502 | upstream_error | ارتباط با OpenAI برقرار نشد |
503 | upstream_unavailable | پردازش دستهای الان از راه ما در دسترس نیست |
همهٔ این خطاها قالب همیشگی را دارند: {"error": {"message", "type": "api_error", "code", …}}. خطاهای خود OpenAI (مثلاً 400 برای دستهای که OpenAI نمیتواند اجرا کند) همانطور که OpenAI فرستاده برمیگردند. همهٔ کدها در مرجع خطاها هستند.