راهنمای اتصال به API

Batch API؛ اجرای انبوه درخواست‌های گفتگو با یک فایل JSONL

برای کارهای بزرگ، مثل دسته‌بندی حجم زیادی متن یا خلاصه کردن یک آرشیو، باز نگه داشتن اتصال‌ها و مدیریت هم‌زمانی و تلاش دوباره کار سختی است. مسیرهای POST /v1/files و POST /v1/batches در وان ای آی (1ai) همان روال آشنای OpenAI را دارند: فایل JSONL را بارگذاری می‌کنید، کار را می‌سازید، وضعیت را می‌پرسید و فایل نتیجه را برمی‌دارید. اجرا غیرهم‌زمان است و می‌تواند ساعت‌ها طول بکشد. قیمت هر مدل همان قیمت معمولی آن است و سطرهای ناموفق هزینه‌ای ندارند.

چرا با 1ai

بدون اتصال باز

درخواست‌ها را یک‌جا می‌فرستید؛ لازم نیست اتصال‌ها را باز نگه دارید یا هم‌زمانی و تلاش دوباره را خودتان مدیریت کنید.

روال آشنای OpenAI

بارگذاری فایل با purpose=batch، ساخت کار با POST /v1/batches و دریافت نتیجه با GET /v1/files/{id}/content.

فقط مصرف واقعی

بدترین حالت هر سطر هنگام ساخت کار رزرو می‌شود و بخش مصرف‌نشده در پایان برمی‌گردد. سطرهای ناموفق هزینه‌ای ندارند.

نتیجه با شناسه‌ی خودتان

هر سطر نتیجه custom_id شما را دارد، پس ترتیب مهم نیست و هر پاسخ را به رکورد خودش وصل می‌کنید.

در چند قدم

  1. ۱

    فایل JSONL را بسازید

    هر سطر یک درخواست است با custom_id، method، url و body؛ همه‌ی سطرها یک مدل، و max_tokens در هر سطر.

  2. ۲

    فایل را بارگذاری کنید

    فایل را با purpose=batch به POST /v1/files بفرستید و id آن را بردارید.

  3. ۳

    کار را بسازید

    POST /v1/batches را با input_file_id، endpoint و completion_window صدا بزنید؛ اعتبار همین‌جا رزرو می‌شود.

  4. ۴

    نتیجه را بردارید

    با GET /v1/batches/{id} وضعیت را بپرسید و بعد output_file_id و error_file_id را دانلود کنید.

مدل‌های گفتگو در API

همه‌ی مدل‌ها

GPT-6 Luna

اوپن‌ای‌آی
گفتگو

سریع و بسیار ارزان؛ مدل پیش‌فرض و در نسخه‌ی رایگان

شروع پاسخ ۲٫۶ ثانیه و سرعت ۷۴ توکن در ثانیه

در نسخه‌ی رایگان
رایگانAPI

GPT-6.1 Sol

اوپن‌ای‌آی
گفتگو

پرچم‌دار اوپن‌ای‌آی برای کارهای دقیق، تحلیلی و چندمرحله‌ای

شروع پاسخ ۵٫۶ ثانیه و سرعت ۵۷ توکن در ثانیه

با اشتراک
API

Claude Sonnet 5.5

آنتروپیک
گفتگو

نویسندگی روان و برنامه‌نویسی دقیق

با اشتراک
API
گفتگو

سریع، چندوجهی و با حافظه‌ی متنی بسیار بلند

با اشتراک
API

Claude Haiku 5.5

آنتروپیک
گفتگو

سریع‌ترین کلود؛ در نسخه‌ی رایگان

شروع پاسخ ۴٫۶ ثانیه و سرعت ۲۹۸ توکن در ثانیه

در نسخه‌ی رایگان
رایگانAPI
گفتگو

سبک و ارزان؛ در نسخه‌ی رایگان

در نسخه‌ی رایگان
رایگانAPI

۱. ساختن فایل JSONL

هر سطر فایل requests.jsonl یک درخواست کامل است:

json
{"custom_id": "q-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-6.1-sol", "max_tokens": 300, "messages": [{"role": "user", "content": "این نظر مثبت است یا منفی؟ خیلی راضی بودم."}]}}
{"custom_id": "q-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-6.1-sol", "max_tokens": 300, "messages": [{"role": "user", "content": "این نظر مثبت است یا منفی؟ بسته دیر رسید."}]}}
  • custom_id در هر فایل باید یکتا باشد و تا ۶۴ نویسه.
  • model در همه‌ی سطرها یکی است: هر فایل یک مدل.
  • max_tokens را در همه‌ی سطرها بگذارید؛ بخش رزرو اعتبار را ببینید.
  • شناسه‌ی مدل بالا فقط نمونه است و همه‌ی مدل‌ها به صورت Batch اجرا نمی‌شوند؛ بخش «محدودیت‌ها» را ببینید.

۲. بارگذاری فایل و ساختن کار

bash
curl https://1ai.ir/v1/files \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -F purpose=batch \
  -F file=@requests.jsonl

پاسخ یک id به شکل fil_… دارد. با آن کار را بسازید:

bash
curl https://1ai.ir/v1/batches \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "fil_...",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

completion_window باید 24h باشد تا با قالب OpenAI یکی بماند، ولی پایان کار را در این زمان تضمین نمی‌کند. موعد نهایی کار در expires_at می‌آید.

۳. پیگیری وضعیت و دریافت نتیجه

bash
curl https://1ai.ir/v1/batches/bat_... -H "Authorization: Bearer $ONEAI_API_KEY"
json
{
  "id": "bat_…",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "model": "openai/gpt-6.1-sol",
  "status": "completed",
  "input_file_id": "fil_…",
  "output_file_id": "fil_…",
  "error_file_id": null,
  "request_counts": { "total": 2, "completed": 2, "failed": 0 },
  "estimated_credits": …,
  "credits": …
}
statusمعنی
validatingدر حال ارسال برای اجرا
in_progressدر حال اجرا
completedتمام شده؛ فایل‌های نتیجه آماده‌اند
failedاجرا نشد؛ علت در errors است
expiredتا موعد تمام نشد و اعتبار رزروشده برگشت

وقتی کار تمام شد، فایل‌ها را بردارید:

bash
curl -L -o output.jsonl https://1ai.ir/v1/files/fil_.../content -H "Authorization: Bearer $ONEAI_API_KEY"

این مسیر به یک لینک امضاشده هدایت می‌کند که یک ساعت اعتبار دارد. سطرهای موفق در output_file_id و سطرهای ناموفق در error_file_id هستند:

json
{"id": "batch_req_…", "custom_id": "q-1", "response": {"status_code": 200, "request_id": "…", "body": {"object": "chat.completion", "choices": […], "usage": {…}}}, "error": null}
{"id": "batch_req_…", "custom_id": "q-2", "response": null, "error": {"code": "request_failed", "message": "This request failed, and no credits were charged."}}

نتیجه‌ها را با custom_id به رکوردهای خودتان وصل کنید.

نمونه کامل با Python

python
# pip install requests
import os, time, requests

API = "https://1ai.ir/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['ONEAI_API_KEY']}"}

with open("requests.jsonl", "rb") as f:
    file = requests.post(f"{API}/files", headers=HEADERS, data={"purpose": "batch"}, files={"file": f}, timeout=120).json()

batch = requests.post(f"{API}/batches", headers=HEADERS, json={
    "input_file_id": file["id"],
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
}, timeout=120).json()

while batch["status"] in ("validating", "in_progress"):
    time.sleep(300)
    batch = requests.get(f"{API}/batches/{batch['id']}", headers=HEADERS, timeout=60).json()

for name in ("output_file_id", "error_file_id"):
    if batch[name]:
        res = requests.get(f"{API}/files/{batch[name]}/content", headers=HEADERS, timeout=600)
        open(f"{name}.jsonl", "wb").write(res.content)

چون کار ممکن است ساعت‌ها طول بکشد، به جای یک حلقه‌ی بلند می‌توانید id کار را ذخیره کنید و وضعیت را با یک زمان‌بند بپرسید.

رزرو اعتبار و هزینه

هنگام ساختن کار، اعتبارِ بدترین حالت همه‌ی سطرها یک‌جا رزرو می‌شود و بخش مصرف‌نشده وقتی کار تمام شد برمی‌گردد. پس موجودی شما باید برای کل فایل کافی باشد؛ وگرنه ساختن کار با 402 insufficient_credits رد می‌شود.

در هر سطر max_tokens بگذارید. سطری که آن را ندارد، به اندازه‌ی کل سقف خروجی مدل رزرو می‌کند و در یک فایل بزرگ رزرو خیلی بالا می‌رود.

هر سطر به قیمت معمولی مدل حساب می‌شود و Batch تخفیف جداگانه‌ای ندارد؛ مزیتش این است که اتصال و هم‌زمانی را شما مدیریت نمی‌کنید. سطرهای ناموفق هزینه‌ای ندارند و به فایل خطا می‌روند. تخمین رزرو در estimated_credits و مبلغ نهایی در credits می‌آید.

محدودیت‌ها

  • فقط گفتگو: تنها مسیر مجاز /v1/chat/completions است.
  • یک مدل در هر فایل. همه‌ی مدل‌ها به صورت Batch اجرا نمی‌شوند و بقیه خطای 400 batch_not_available می‌گیرند. کلیدی که گاردریل دارد هم همین خطا را می‌گیرد.
  • بدون استریم: stream پذیرفته نمی‌شود و n باید ۱ باشد.
  • فیلدهای مجاز body: model، messages، max_tokens، max_completion_tokens، temperature، top_p، stop، seed، presence_penalty، frequency_penalty، tools، tool_choice، parallel_tool_calls، response_format و reasoning_effort.
  • فقط ابزارهای function: ابزارهای دیگر پذیرفته نمی‌شوند.
  • فقط متن و تصویر در پیام‌ها؛ فایل‌های دیگر پذیرفته نمی‌شوند.
  • یک سطر بد، کل فایل را رد می‌کند. خطای 400 invalid_batch_file شماره‌ی همان سطر را می‌گوید؛ سطر را درست کنید و فایل را دوباره بفرستید.
  • حجم فایل: تا ۲۵ مگابایت. تعداد سطرها و حجم کل فایل‌های هر حساب هم سقف دارد و فایل‌ها پس از مدتی حذف می‌شوند.
  • بدون لغو: کاری که شروع شده لغو نمی‌شود و POST /v1/batches/{id}/cancel خطای 409 batch_not_cancellable می‌دهد.

مدیریت فایل‌ها و خطاها

فهرست فایل‌ها و کارها با GET /v1/files و GET /v1/batches می‌آید و با after و limit صفحه‌بندی می‌شود. DELETE /v1/files/{id} فایل را حذف می‌کند.

کدمعنی
400 invalid_batch_fileسطری از فایل نادرست است؛ پیام شماره‌ی سطر را می‌گوید
400 batch_not_availableاین مدل یا این کلید به صورت Batch اجرا نمی‌شود
402 insufficient_creditsموجودی برای رزرو کل فایل کافی نیست
404 file_not_found و 404 batch_not_foundفایل یا کاری با این شناسه برای این حساب نیست
409 file_in_useکاری در حال اجرا این فایل را می‌خواند و حذف نمی‌شود
409 batch_not_cancellableکاری که شروع شده لغو نمی‌شود
413 file_quota_exceededحجم فایل‌های حساب از سقف گذشته؛ چند فایل را حذف کنید

سوالات متداول

Batch از درخواست معمولی ارزان‌تر است؟

خیر. هر سطر به قیمت معمولی همان مدل حساب می‌شود. فایده‌ی Batch این است که برای کارهای بزرگ لازم نیست اتصال‌ها را باز نگه دارید یا هم‌زمانی و تلاش دوباره را خودتان مدیریت کنید.

یک کار Batch چقدر طول می‌کشد؟

اجرا غیرهم‌زمان است و می‌تواند ساعت‌ها طول بکشد؛ زمان مشخصی را قول نمی‌دهیم. برای کاری که پاسخ فوری می‌خواهد، همان POST /v1/chat/completions مناسب‌تر است.

کدام مدل‌ها به صورت Batch اجرا می‌شوند؟

همه‌ی مدل‌ها این امکان را ندارند و فهرست آن ممکن است تغییر کند. اگر مدلی نشود، ساختن کار با 400 batch_not_available رد می‌شود و اعتباری رزرو نمی‌شود؛ مدل دیگری را امتحان کنید.

چرا باید در هر سطر max_tokens بگذارم؟

چون اعتبارِ بدترین حالت هر سطر هنگام ساختن کار رزرو می‌شود. سطر بدون max_tokens کل سقف خروجی مدل را رزرو می‌کند و ممکن است موجودی کافی نباشد. بخش مصرف‌نشده در پایان برمی‌گردد.

اگر بعضی سطرها شکست بخورند چه می‌شود؟

هزینه‌ای برایشان حساب نمی‌شود و با همان custom_id به فایل error_file_id می‌روند. می‌توانید همان سطرها را در یک فایل تازه دوباره بفرستید.

می‌توانم کار را وسط اجرا لغو کنم؟

خیر. کاری که شروع شده لغو نمی‌شود، پس پیش از ساختن کار فایل را با چند سطر امتحان کنید.

چه فرقی با POST /v1/batch دارد؟

POST /v1/batch چند درخواست را در یک فراخوانی و همان لحظه اجرا می‌کند و پاسخ را همان‌جا می‌دهد. POST /v1/batches برای فایل‌های بزرگ است، غیرهم‌زمان اجرا می‌شود و نتیجه را در فایل می‌دهد.

مطالب مرتبط

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL
توسعه‌دهندگان

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL

چطور پروژه‌ای را که با کتابخانه‌ی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدل‌ها و مدیریت خطا.

۴ دقیقه مطالعه
کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه
توسعه‌دهندگان

کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه

چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدل‌های مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.

۴ دقیقه مطالعه
همه‌ی امکانات

OpenAI SDK

کتابخانه‌ی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.

Rerank API

یک پرسش و فهرستی از متن‌ها بفرستید و همان متن‌ها را مرتب‌شده بر اساس ارتباط با پرسش، همراه با امتیاز هر کدام، پس بگیرید.

Extraction API

فیلدهایی را که لازم دارید با نوعشان تعریف کنید و از متن یا تصویر، مقدار هر فیلد را با اطمینان آن بگیرید؛ فیلدی که در متن نیست null برمی‌گردد.

Batch API؛ اجرای انبوه درخواست‌های گفتگو با یک فایل JSONL

حجم زیادی از درخواست‌های گفتگو را لازم نیست یکی‌یکی بفرستید: آن‌ها را در یک فایل JSONL بگذارید، کار را بسازید و وقتی تمام شد فایل نتیجه را بردارید.

ساخت کلید API