مستندات API
APIKit دو سرویس زبان انگلیسی را با یک کلید ارائه می‌کند: تصحیح رایتینگ با توضیح فارسی برای خطاهای رایج فارسی‌زبان‌ها، و گفتار به متن. هر دو روی HTTPS ساده کار می‌کنند و با هر زبان برنامه‌نویسی قابل استفاده‌اند.
آدرس پایه‌ی همه‌ی درخواست‌ها:
شروع سریع
- حساب بسازید (توکن رایگان برای امتحان می‌گیرید).
- در داشبورد، بخش API، یک کلید بسازید و جایی امن نگهش دارید.
- اولین درخواست را بفرستید:
احراز هویت
کلید را در هدر Authorization بفرستید:
Authorization: Bearer ak_xxxxxxxxxxxxxxxxxxxxxxxx
برای سازگاری با کتابخانه‌های موجود، این روش‌ها هم پذیرفته می‌شوند: هدر X-API-Key، پارامتر api_key در آدرس، یا فیلد فرم apiKey (مثل API خود LanguageTool).
تصحیح رایتینگ
متن انگلیسی را بررسی می‌کند و فهرست اشتباه‌ها را با توضیح و پیشنهاد برمی‌گرداند. همان قالب API نسخه‌ی ۲ LanguageTool است، پس کتابخانه‌های آماده‌ی LanguageTool با تغییر آدرس کار می‌کنند. بدنه به‌صورت application/x-www-form-urlencoded (یا multipart) فرستاده می‌شود.
پارامترها
| نام | الزامی | توضیح |
|---|---|---|
text | بله | متن انگلیسی، حداکثر ۲۰٬۰۰۰ نویسه. |
language | بله | en-US یا en-GB (یا auto). |
motherTongue | خیر | مثلاً fa؛ برای تشخیص بهتر خطاهای ناشی از زبان مادری. |
level | خیر | picky برای بررسی سخت‌گیرانه‌تر (سبک نگارش). |
enabledRules / disabledRules | خیر | شناسه‌ی قانون‌ها با کاما؛ برای روشن یا خاموش کردن قانون خاص. |
explain | خیر | پیش‌فرض: توضیح همه‌ی اشتباه‌ها فارسی است. با explain=en توضیح‌های انگلیسی اصلی LanguageTool برمی‌گردد. |
enabledCategories + enabledOnly=true | خیر | مثلاً فقط FA_LEARNER برای دیدن تنها خطاهای مخصوص فارسی‌زبان‌ها. |
نمونه
پاسخ
| فیلد | توضیح |
|---|---|
offset / length | جای اشتباه در متن (بر حسب نویسه، از صفر). |
message | توضیح اشتباه به فارسی (راست‌به‌چپ، حتی داخل پنجره‌ی چپ‌به‌راست). با explain=en انگلیسی. |
replacements | پیشنهادهای درست به ترتیب اولویت؛ برای جایگزینی با یک کلیک. |
rule.id / rule.category.id | شناسه‌ی قانون. خطاهای مخصوص فارسی‌زبان‌ها در دسته‌ی FA_LEARNER هستند. |
message را در عنصری با dir="auto" (یا dir="rtl") نشان دهید تا راست‌چین شود.گفتار به متن
فایل صوتی را به‌صورت multipart/form-data در فیلد file بفرستید. فرمت‌های رایج (mp3، m4a/aac، ogg/opus، webm، wav، flac) پذیرفته می‌شوند.
| نام | الزامی | توضیح |
|---|---|---|
file | بله | فایل صوتی؛ حداکثر ۵ دقیقه و ۲۵ مگابایت. |
response_format | خیر | json (پیش‌فرض)، text، srt، vtt یا verbose_json (با زمان‌بندی جمله‌ها). |
language | خیر | زبان گفتار؛ پیش‌فرض en. |
prompt | خیر | متن راهنما (مثلاً کلمه‌های تخصصی درس) برای دقت بیشتر. |
temperature | خیر | عدد بین ۰ و ۱؛ پیش‌فرض ۰. |
پاسخ: {"text": "..."}. مدت صدا (ثانیه‌ی محاسبه‌شده برای هزینه) در هدر X-Audio-Seconds برمی‌گردد.
سازگاری با OpenAI
همان سرویس گفتار به متن با آدرس و قالب OpenAI. اگر از کتابخانه‌ی رسمی OpenAI استفاده می‌کنید، فقط base_url و کلید را عوض کنید (فیلد model نادیده گرفته می‌شود):
توکن و هزینه
هر حساب یک کیف پول توکنی دارد که از داشبورد، آنلاین شارژ می‌شود (همان کیف پولی که ابزارهای داشبورد از آن استفاده می‌کنند). هر درخواست موفق به‌اندازه‌ی مصرفش توکن کم می‌کند:
| سرویس | واحد | توکن |
|---|---|---|
| گفتار به متن | هر دقیقه صدا (محاسبه‌ی ثانیه‌ای) | — |
| تصحیح رایتینگ | هر ۱۰۰۰ نویسه‌ی متن ارسالی | — |
درخواست‌های ناموفق (خطای سرور، صدای ناخوانا و…) توکن کم نمی‌کنند. اگر توکن کافی نباشد، پاسخ 402 با پیام insufficient tokens برمی‌گردد.
مشاهده‌ی مصرف
مصرف این ماه همان کلید را برمی‌گرداند. گزارش کامل‌تر (روزانه، هر کلید، تاریخچه‌ی درخواست‌ها) در داشبورد است.
محدودیت‌ها
| مورد | مقدار |
|---|---|
| طول متن در هر درخواست تصحیح | ۲۰٬۰۰۰ نویسه |
| طول و حجم صدا در هر درخواست | ۵ دقیقه، ۲۵ مگابایت |
| تعداد درخواست هر کلید | ۱۲۰ در دقیقه (برای بیشتر تماس بگیرید) |
| تعداد کلید هر حساب | ۲۰ |
کدهای خطا
خطاها با کد HTTP و بدنه‌ی {"error": "..."} برمی‌گردند.
| کد | معنی | چه کنید |
|---|---|---|
| 400 | درخواست نادرست (مثلاً فایل صوتی خوانده نشد) | پارامترها و فایل را بررسی کنید. |
| 401 | کلید نیست، اشتباه است یا غیرفعال شده | کلید را در داشبورد بررسی کنید. |
| 402 | توکن کافی نیست | کیف پول را از داشبورد شارژ کنید. |
| 403 | کلید برای این سرویس فعال نیست، یا حساب غیرفعال است | کلیدی با دسترسی این سرویس بسازید. |
| 413 | متن یا صدا بیش از حد بزرگ است | متن یا صدا را کوتاه‌تر کنید یا چند تکه بفرستید. |
| 429 | درخواست بیش از حد در دقیقه | بعد از ثانیه‌های هدر Retry-After دوباره بفرستید. |
| 503 / 504 | سرویس موقتاً شلوغ است یا جواب نداد | چند ثانیه بعد دوباره امتحان کنید (با فاصله‌ی افزایشی). |
توصیه‌ها
- صدا را فشرده بفرستید: opus یا aac تک‌کانال با ۱۶ تا ۳۲ کیلوبیت کافی است و آپلود را چند برابر سریع‌تر می‌کند.
- کلید جدا برای هر محیط (آزمایشی، اصلی، هر اپ) بسازید تا مصرف هر کدام جدا دیده شود و در صورت لو رفتن فقط همان را عوض کنید.
- تلاش دوباره: برای 429، 503 و 504 با فاصله‌ی افزایشی (۱، ۲، ۴ ثانیه) دوباره بفرستید.
- متن‌های طولانی را بر اساس پاراگراف تکه کنید؛
offsetها نسبت به همان تکه است.