پرسش‌های متداول
عیب‌یابی
مشکلات احراز هویت، مدل، استریم، کار و محدودیت نرخ را با چک‌لیستی که از نشانه شروع می‌شود برطرف کنید.
با نشانه شروع کنید، سپس راه‌حل را دنبال کنید. بیشتر شکست‌ها از base URL، کلید، شناسه مدل یا مانده می‌آیند.
جدول نشانه‌محور
| نشانه | علت احتمال | راه‌حل |
|---|---|---|
401 UNAUTHORIZED | کلید گم‌شده، اشتباه، لغوشده یا ارسال‌نشده | Authorization: Bearer $FELO_API_KEY بفرستید؛ اگر لغو شده کلید تازه بسازید |
402 INSUFFICIENT_CREDITS | مانده هزینه فراخوانی را پوشش نمی‌دهد | در Console Billing شارژ کنید |
| 404 در هر درخواست | base URL مسیری دارد که endpoint خودش اضافه می‌کند | برای کلاینت‌های OpenAI از https://openapi.felo.ai/api/v1 و برای کلاینت‌های Anthropic از https://openapi.felo.ai/api استفاده کنید |
| 404 در یک مدل | شناسه مدل عمومی نیست یا endpoint آن را سرو نمی‌کند | شناسه مدل را در صفحه مدل‌ها و مستندات endpoint بررسی کنید |
خطای model یا max_tokens با 400 | فیلد الزامی گم شده یا مدل شکل درخواست را نمی‌پذیرد | برای Messages فیلد max_tokens را اضافه کنید؛ فیلدهای پشتیبانی‌نشده را بردارید |
| 429 | محدودیت نرخ یا محدودیت ارائه‌دهنده بالادستی | Retry-After را بخوانید؛ خطاها، محدودیت‌ها و تلاش دوباره را ببینید |
| 5xx | شکست بالادستی یا سرویس | با عقب‌نشینی دوباره تلاش کنید؛ اگر ادامه یافت request_id را بگنجانید |
| جریان وصل می‌شود اما چیزی نمی‌فرستد | یک پروکسی پاسخ را بافر می‌کند یا تجزیه‌گر رویداد قالب اشتباه را انتظار دارد | جریان را تدریجی بخوانید؛ بافر پاسخ را در پروکسی خود غیرفعال کنید |
| وظیفه هرگز تمام نمی‌شود | endpoint پیگیری اشتباه، یا وضعیت پایانی مدیریت نشده | endpoint وضعیت خود وظیفه را پیگیری کنید و در مقدارهای پایانی متوقف شوید |
| فراخوانی ابزار نادیده گرفته می‌شود | مدل آن توانمندی را اعلام نمی‌کند | supported_parameters را در کاتالوگ بررسی کنید |
| Data API 404 برمی‌گرداند | پیشوند /v1/beta دو بار اضافه شده | مسیر را دقیقاً همان‌طور که در مرجع نوشته شده به کار ببرید |
احراز هویت
کلید لغوشده پیامی برمی‌گرداند که پیشوند کلید را نام می‌برد:
{
"status": 401,
"code": "UNAUTHORIZED",
"message": "API Key has been revoked (keyPrefix=...)"
}فهرست بررسی:
- برای Model API و Felo APIها سرآیند
Authorization: Bearer <key>است. - Data API همچنین
X-API-Key: <key>را می‌پذیرد. - کلید در گیومه پیچیده نشده و یک خط جدید انتهایی از متغیر محیطی کپی‌شده ندارد.
- محیط مستقر واقعاً متغیر را تنظیم کرده است؛ کلیدی که محلی کار می‌کند ممکن است در تولید گم شده باشد.
- کلید حذف یا چرخانده نشده است. کلید حذف‌شده یا چرخانده‌شده نمی‌تواند دوباره نشان داده شود؛ کلید تازه بسازید.
برای ساخت کلید و محدودیت‌ها احراز هویت را ببینید.
تله‌های base URL
| کلاینت | base URL درست |
|---|---|
| OpenAI SDK | https://openapi.felo.ai/api/v1 |
| Anthropic SDK | https://openapi.felo.ai/api |
| endpoint خام مدل | https://openapi.felo.ai/api/v1/chat/completions، /responses یا /messages |
| Data API | https://openapi.felo.ai/v1/beta |
Felo APIهای /v2 | https://openapi.felo.ai/v2 |
دو اشتباه رایج:
- افزودن
/chat/completionsبه base URLی که SDK از قبل آن را گسترش می‌دهد. - تنظیم base URL سازگار با Anthropic روی
https://openapi.felo.ai/api/v1. SDK مسیر/v1/messagesرا می‌افزاید، پس درخواست به/api/v1/v1/messagesتبدیل می‌شود.
مشکلات شناسه مدل
شناسه‌های مدل همان شناسه‌های عمومی کاتالوگ‌اند، نه نام‌های داخلی ارائه‌دهنده بالادستی یا نام نمایشی.
- شناسه را در صفحه مدل‌ها یا در
GET /api/v1/modelsپیدا کنید. - تأیید کنید مدل پروتکلی را که صدا می‌زنید پشتیبانی می‌کند (
supported_protocols). - اگر کانالی پین کرده‌اید، تأیید کنید آن کانال برای آن مدل منتشرشده و قابل اجراست. کانال در دسترس نبودن، جایگزین نیست.
کانال‌ها و مسیریابی ارائه‌دهنده را ببینید.
مشکلات جریان‌دهی
stream: trueرا در بدنه درخواست تنظیم کنید، نه به‌عنوان پارامتر پرس‌وجو.- بدنه پاسخ را به‌صورت جریان بخوانید. انتظار برای پاسخ کامل، جریان‌دهی را بی‌اثر می‌کند.
- برخی پروکسی‌ها و پلتفرم‌های serverless پاسخ‌ها را بافر می‌کنند. بافر را برای مسیری که درخواست را پروکسی می‌کند غیرفعال کنید.
- Chat Completions جریان
choices[0].deltaرا می‌فرستد، نهchoices[0].message. محتوای نهایی در بسیاری از تکه‌ها می‌رسد. - اگر اتصال قطع شود، جریان می‌تواند بدون رویداد پایانی تمیز تمام شود. اتصال قطع‌شده را پاسخ ناقص بدانید.
مشکلات وظیفه ناهمگام
- endpoint وضعیتی را پیگیری کنید که به همان خانواده وظیفه تعلق دارد. گردش‌کارهای Felo از
GET /v2/tasks/{task_id}/statusاستفاده می‌کنند؛ وظایف ویدیو و تصویر مدل از endpointهای تولید خودشان. - در هر وضعیت پایانی متوقف شوید، از جمله شکست‌ها و انقضاها، نه فقط موفقیت.
- callbackهای ویدیو و تصویر در حال حاضر نادیده گرفته می‌شوند. برای webhook صبر نکنید.
- URL نتیجه می‌تواند کوتاه‌عمر باشد. اگر دانلود منقضی شد، از endpoint وضعیت URL تازه بخواهید.
- پیش از ارسال دوباره وظیفه را بررسی کنید. ارسال دوباره یک وظیفه در حال اجرا نسخه تکراری می‌سازد و هر دو صورت‌حساب می‌شوند.
وظایف ناهمگام را ببینید.
مشکلات Data API
- مسیر متد دقیق را از مرجع Data API نگه دارید.
- بدنه‌های درخواست مخصوص تأمین‌کننده‌اند. فیلدی که برای یک تأمین‌کننده کار می‌کند برای دیگری تضمین نشده است.
- خطای ارائه‌دهنده می‌تواند درون پاسخ 4xx با پیام مخصوص ارائه‌دهنده برسد.
request_idو بدنه پاسخ را ثبت کنید.
یادآوری‌های امنیتی
- هرگز کلید API را در کد مرورگر، بسته برنامه موبایل یا مخزن عمومی نگذارید. آن را روی سرور نگه دارید و درخواست‌ها را پروکسی کنید.
- کلید کامل را ثبت نکنید. اگر برای شناسایی لازم است پیشوند را ثبت کنید.
- اگر احتمال نشت کلید هست، بی‌درنگ آن را بچرخانید.
پیش از تماس با پشتیبانی
این‌ها را جمع کنید:
- endpoint و متد HTTP.
- وضعیت HTTP،
codeوrequest_id. - شناسه مدل یا شناسه وظیفه.
- برچسب زمانی همراه با منطقه زمانی.
- یک بدنه درخواست کمینه با حذف اطلاعات محرمانه.
آن را همراه ایمیل حساب برای پشتیبانی بفرستید. کلید API کامل را نگنجانید.