کار ماندگار و فایل‌ها

شروع مستقیم Work

POST /v1/work برای شروع یک کار بدون تعریف عامل است. kind، input و یک title کوتاه بفرستید. input بین ۱۰ تا ۱۲٬۰۰۰ نویسه است. درخواست پذیرفته‌شده HTTP 202 و شناسهٔ کار می‌دهد.

import json, os, urllib.request, urllib.error

payload = {
    "kind": "document",
    "title": "راهنمای شروع فروشگاه",
    "input": "یک راهنمای عملی فارسی برای شروع یک فروشگاه کوچک اینترنتی بنویس. چک‌لیست مراحل و جدول هزینه‌های نمونه داشته باشد."
}

request = urllib.request.Request(
    "https://api.sarovi.ir/v1/work",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["SAROVI_API_KEY"],
        "Content-Type": "application/json"
    },
    method="POST"
)
try:
    with urllib.request.urlopen(request, timeout=300) as response:
        result = json.load(response)
        print(result)
except urllib.error.HTTPError as error:
    detail = json.load(error)
    raise RuntimeError(f"{error.code}: {detail['error'].get('code', detail['error'].get('type', 'HTTP_ERROR'))}") from error

بودجهٔ اولیه

رزرو اولیهٔ research برابر ۶۰۰، document برابر ۴۰۰، code برابر ۵۰۰ و data برابر ۴۰۰ اعتبار است. این اعداد بودجهٔ شروع‌اند و قیمت ثابت تمام کارها نیستند. کار توسط صف و worker فعلی ساروی اجرا می‌شود؛ زمان تکمیل به نوع کار و ظرفیت سرویس وابسته است.

وضعیت

GET /v1/work/{id} وضعیت پروژه، کارها، خروجی‌ها و اطلاعات قابل نمایش را برمی‌گرداند. وجود شناسه یا queued به معنی کامل شدن نیست. completed، failed و cancelled را به‌عنوان وضعیت پایانی مدیریت کنید. اگر fail شد، پیام خطای قابل نمایش را حفظ کنید.

فایل و بستهٔ خروجی

GET /v1/work/{id}/files?bundle=1 بستهٔ فایل‌ها را می‌گیرد. برای یک فایل خاص پارامتر path را URL-encode کنید. اسم فایل و نوع محتوا از هدرهای پاسخ می‌آید. پیش از آماده شدن خروجی ممکن است 404 دریافت کنید؛ این حالت را از شناسهٔ غیرمجاز با بررسی وضعیت همان کار تفکیک کنید.

توقف

POST /v1/work/{id}/cancel درخواست توقف کار را می‌فرستد. نتیجهٔ توقف را در وضعیت بعدی بررسی کنید. لغو کلید به‌تنهایی جایگزین توقف کار نیست. برای ارسال مجدد همان کار از Idempotency-Key قبلی استفاده کنید؛ برای اجرای آگاهانهٔ یک نسخهٔ تازه، کلید تازه بدهید.

خروجی وب‌سایت و قابلیت‌های دیگر

این قرارداد نسخهٔ اول Work شامل research/document/code/data است. انتشار سایت، اتصال دامنه، تغییر زیرساخت، پرداخت و مدیریت حساب از endpoint عمومی Work انجام نمی‌شوند. قابلیت‌های جدید با مسیر و مجوز مشخص در مرجع API اضافه می‌شوند.