مستندات API زیرفارسی

با API زیرفارسی می‌توانید ترجمه زیرنویس را مستقیم از برنامه‌ها و اسکریپت‌های خود انجام دهید.

شروع سریع

کلید API خود را از داشبورد ← تنظیمات ← کلید API بسازید و آن را در هدر درخواست‌ها بفرستید:

احراز هویت

Authorization: Bearer zf_live_YOUR_API_KEY
# یا
X-API-Key: zf_live_YOUR_API_KEY

نمونه سریع (curl)

curl -X POST https://zirfarsi.ir/api/v1/translate \
  -H "Authorization: Bearer zf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subtitleContent": "1\n00:00:01,000 --> 00:00:02,500\nHello world\n", "filename": "movie.srt"}'

محدودیت ها

محدودیت کل درخواست ها: ۶۰ درخواست در دقیقه به‌ازای هر کلید API.
درخواست‌های ترجمه وارد صف می‌شوند و به ترتیب تکمیل و ترجمه می‌شوند.
پاسخ 429 با فیلد error: rate_limited نشان‌دهنده عبور از محدودیت است.

نقاط انتهایی (Endpoints)

POST/api/v1/estimate

برآورد تخمینی هزینه اعتبار قبل از ارسال درخواست ترجمه.

request

{
  "subtitleContent": "1
00:00:01,000 --> 00:00:02,500
Hello world
"
}

200 OK

{ "estimatedCredits": 0.03 }

POST/api/v1/translate

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

request

{
  "subtitleContent": "1\n00:00:01,000 --> 00:00:02,500\nHello world\n",
  "filename": "movie.srt",     // اختیاری — برای تشخیص فرمت (SRT/VTT/SBV/ASS)

  // اختیاری — تنظیمات ترجمه:
  "translationGoal": "movieSeries",  // general | movieSeries | anime | educational | documentary | kids | news | gaming
  "tone": "polite",                   // neutral | polite | vulgar | formal | casual

  // اختیاری — گزینه‌های ویرایش:
  "cleanFormatting": true,           // حذف تگ‌ها و کدهای قالب‌بندی متن قبل از ترجمه
  "clearAds": true,                   // حذف تبلیغات و لینک‌ها از ترجمه
  "replacements": [                   // حداکثر ۲۰ مورد — جایگزینی دقیق کلمه، قبل از ترجمه روی متن اصلی
    { "from": "phone", "to": "mobile" },
    { "from": "word", "to": "" }      // "to" خالی = حذف کلمه
  ],
  "inserts": [                        // حداکثر ۵ مورد — درج متن زمان‌دار در فضای خالی
    { "position": "middle", "text": "کانال دیجی موویز", "minSeconds": 10, "maxSeconds": 20 },
    { "position": "end", "text": "t.me/DigiMoviez", "minSeconds": 5 }
  ]
}

202 Accepted

{
  "id": "tr_Ab3xK9mQ2z",       // شناسه عمومی ترجمه — در همه فراخوانی‌ها از همین استفاده کنید
  "status": "queued",
  "estimatedCredits": 1.4
}

پس از درخواست ترجمه اعتبار نمایش داده شده در پاسخ «رزرو» می‌شود؛ اگر موجودی اعتبار حساب کافی نباشد پاسخ 402 با error: insufficient_credits برمی‌گردد. مصرف واقعی پس از پایان ترجمه تسویه و مازاد برگشت داده می‌شود.

گزینه‌های ویرایش:cleanFormatting تگ‌های قالب‌بندی (مثل <i> و {\\i1} و کدهای زمانی) را قبل از ارسال به مدل از متن پاک می‌کند (باعث کاهش مصرف اعتبار نیز می‌شود)؛ clearAds به‌صورت یک قانون روی همان درخواست ترجمه اعمال می‌شود (خط‌های تمام‌تبلیغاتی به‌کلی از فایل نهایی حذف می‌شوند) و replacements قبل از ترجمه دقیقاً روی متن اصلی زیرنویس اجرا می‌شود (کلمه from به زبان فایل اصلی است و هوش مصنوعی نسخه جایگزین‌شده را ترجمه می‌کند). inserts به‌صورت قطعی و بدون دخالت هوش مصنوعی، متن شما را در فضای خالی بین دیالوگ‌ها (نزدیک به position درخواستی) به‌صورت خط زیرنویس جدید درج می‌کند — زمان‌بندی هیچ دیالوگی تغییر نمی‌کند. اگر فضای خالی با حداقل زمان درخواستی وجود نداشته باشد، درخواست با خطای دقیق رد می‌شود (مثلاً «بزرگ‌ترین فضای موجود در آن محدوده ۷ ثانیه است») و چیزی از اعتبار شما کم نمی‌شود.

GET/api/v1/translations/:id

پیگیری وضعیت و پیشرفت یک ترجمه — :id همان translateId است (tr_...).

200 OK

{
  "id": "tr_Ab3xK9mQ2z",
  "filename": "movie.srt",
  "status": "in_progress",       // queued | in_progress | completed | failed | cancelled
  "progress": 66,                // درصد پیشرفت (۰ تا ۱۰۰)
  "creditsUsed": 0,
  "errorMessage": "",
  "createdAt": "2026-08-19T10:00:00.000Z",
  "downloadUrl": null             // پس از تکمیل: /api/v1/translations/:id/download
}

GET/api/v1/translations/:id/download

دانلود فایل زیرنویس ترجمه‌شده (فقط پس از تکمیل و قبل از انقضای ۱۵ روزه).

200 OK — text/plain

1
00:00:01,000 --> 00:00:02,500
سلام دنیا
...

GET/api/v1/translations?page=1&pageSize=10

فهرست ترجمه‌های شما (جدیدترین اول).

200 OK

{
  "translations": [
    { "id": "...", "filename": "movie.srt", "status": "completed",
      "creditsUsed": 1.38, "progress": 100, "createdAt": "..." }
  ],
  "total": 12, "page": 1, "pageSize": 10, "pageCount": 2
}

GET/api/v1/credits

موجودی اعتبار حساب.

200 OK

{
"free": 1.5, 
"bought": 10, 
"total": 11.5
}

کدهای خطا

کد	فیلد error	توضیح
400	`invalid_request`	ورودی نامعتبر (مثلاً SRT خالی یا ساختار خراب)
401	`missing_api_key / invalid_api_key`	کلید ارسال نشده، نامعتبر است یا لغو شده
402	`insufficient_credits`	موجودی اعتبار برای این ترجمه کافی نیست
404	`not_found / not_available`	ترجمه یافت نشد یا خروجی آن هنوز آماده/منقضی است
429	`rate_limited`	عبور از محدودیت نرخ
500	`internal_error`	خطای داخلی سرور

نکات مهم

کلید API را مثل رمز عبور محرمانه نگه دارید؛ در صورت لو رفتن، از داخل داشبورد حساب کاربری کلید API خود را «تعویض» یا «لغو» کنید.
فایل‌های ترجمه‌شده ۱۵ روز نگهداری می‌شوند و پس از آن متن اصلی زیرنویس و متن ترجمه شده آن‌ها حذف می‌شود و دیگر قابل دانلود نمی‌باشند به همین دلیل خروجی را دانلود و ذخیره کنید.
همه پاسخ‌ها JSON هستند (به‌جز دانلود که text/plain است) و تاریخ‌ها در قالب ISO 8601 برگردانده می‌شوند.