درک URL پایه
آدرس پایه جایی را تعریف می‌کند که کلاینت شما درخواست‌ها را ارسال می‌کند. عدم تطابق در اینجا باعث شکست فوری اتصال یا پاسخ‌های مدل غیرمنتظره می‌شود. بسیاری از توسعه‌دهندگان فرض می‌کنند که URL استاندارد OpenAI به طور جهانی کار می‌کند، اما ارائه‌دهندگان بدون سانسور اغلب از اندپوینت‌های متمایز برای مسیریابی ترافیک به گروه‌های مدل خاص استفاده می‌کنند.
بررسی کنید که پیکربندی شما به https://api.openrouterabliteratedmodels.com/v1 برای خدمات ما. اگر از یک تجمیع‌کننده شخص ثالث استفاده می‌کنید، اطمینان حاصل کنید که URL پایه دقیقاً با مستندات آن مطابقت دارد. URLهای نادرست اغلب منجر به خطاهای 404 یا پاسخ‌هایی از مدل‌های پیش‌فرض به جای نسخه بدون سانسور مورد نظر می‌شوند.
- متغیرهای محیطی خود را برای ... بررسی کنید
BASE_URLیاAPI_HOST. - اطمینان حاصل کنید که مسیر شامل
/v1برای سازگاری استاندارد. - اتصال را با یک درخواست ساده لیست مدل‌ها قبل از استفاده سنگین تست کنید.
مدیریت محدودیت نرخ
محدودیت نرخ درخواست‌ها، تعداد درخواست‌هایی را که می‌توانید در یک بازه زمانی مشخص ارسال کنید، محدود می‌کند. API ما محدودیت ۳۰۰ درخواست در دقیقه به ازای هر کلید را اعمال می‌کند. عبور از این آستانه منجر به خطاهای HTTP 429 می‌شود و به طور موقت ارسال درخواست‌های بیشتر را تا زمان بازنشانی پنجره زمانی مسدود می‌کند.
علاوه بر این، محدودیت درخواست همزمان ۸ درخواست در یک زمان برای هر کلید وجود دارد. اگر بیش از ۸ درخواست همزمان ارسال کنید، مازاد بسته به کتابخانه کلاینت شما صف‌بندی یا شکست می‌خورد. همزمانی برنامه خود را مانیتور کنید تا از برخورد با این محدودیت‌های سخت جلوگیری کنید. از استراتژی‌های بازگشت نمایی (exponential backoff) در کد خود برای مدیریت خطاهای 429 بدون شلوغ کردن سرور استفاده کنید.
به یاد داشته باشید که هر کلید منحصر به فرد برای حساب شما است. اشتراک‌گذاری کلیدها در چندین سرویس می‌تواند رسیدن به این محدودیت‌ها را تسریع کند. اگر برای بخش‌های مختلف برنامه خود به مخازن محدودیت نرخ جداگانه نیاز دارید، یک کلید جدید تولید کنید.
پاسخ‌های استریم در مقابل غیر استریم
بازگشت جریان‌دار داده‌ها را به صورت تدریجی همان‌طور که توکن‌ها تولید می‌شوند برمی‌گرداند، در حالی که بازگشت غیرجریان‌دار منتظر پاسخ کامل می‌ماند. جریان‌دار بودن برای تجربه‌های کاربری بلادرنگ ضروری است اما نیازمند مدیریت دقیق رویدادهای ارسال‌شده سرور (SSE) است.
هنگام Streaming، آخرین Chunk شامل آمار مصرف توکن است. اگر پردازش را زودتر متوقف کنید، ممکن است این داده‌ها را از دست بدهید. اطمینان حاصل کنید که کلاینت شما پیام نهایی SSE را Parse می‌کند تا تعداد توکن‌های ورودی و خروجی را به دقت دریافت کند. پاسخ‌های Non-streaming ساده‌تر هستند اما می‌توانند برای خروجی‌های طولانی باعث تأخیر بالا شوند.
برای رابط‌های چت که کاربران متن را کاراکتر به کاراکتر می‌بینند، از استریمینگ استفاده کنید. برای پردازش دسته‌ای یا زمانی که نیاز دارید پاسخ کامل قبل از ادامه پردازش دریافت شود، از حالت غیر استریمینگ استفاده کنید. API ما از هر دو حالت از طریق stream پارامتر در بدنه درخواست.
خطاهای حالت JSON
حالت JSON تضمین می‌کند که مدل JSON معتبر خروجی می‌دهد که برای یکپارچه‌سازی برنامه‌نویسی حیاتی است. خطاها اغلب ناشی از هدرهای نادرست یا عدم تطابق طرحواره هستند. API نیازمند response_format: {"type": "json_object"} برای اجبار به خروجی JSON سخت‌گیرانه.
اگر JSON نامعتبر دریافت کردید، تعریف طرحواره (Schema) خود را بررسی کنید. مدل ممکن است بلوک‌های کد مارک‌داون یا متن توضیحی را خارج از ساختار JSON شامل شود. از یک تجزیه‌گر قوی که می‌تواند حصارهای مارک‌داون را حذف کند یا خروجی را با طرحواره مورد انتظار شما اعتبارسنجی کند، استفاده کنید. از طرحواره‌های بسیار پیچیده که مدل را گیج می‌کند، پرهیز کنید.
ابتدا با ساختارهای ساده شروع کنید. به‌تدریج پیچیدگی را اضافه کنید تا مشخص شود مدل در کجا با مشکل مواجه می‌شود. مطمئن شوید که دمای شما به‌درستی تنظیم شده است، زیرا دماهای بالاتر می‌توانند تصادفی بودن را افزایش داده و اعتبار JSON را کاهش دهند.
خطاهای محاسبه تعداد توکن
تعداد توکن‌ها صورتحساب و مصرف پنجره زمینه شما را تعیین می‌کند. محاسبات نادرست می‌تواند منجر به هزینه‌های غیرمنتظره یا پاسخ‌های قطع شده شود. API ما بابت هر 1M توکن ورودی $0.15 و بابت هر 1M توکن خروجی $0.50 هزینه دریافت می‌کند.
از یک کتابخانه توکن‌پرداز قابل اعتماد که با طرح توکن‌پردازی مدل مطابقت دارد استفاده کنید. مدل‌های مختلف ممکن است فاصله‌ها یا علائم نگارشی را به‌طور متفاوتی توکن‌پردازی کنند که منجر به تفاوت بین شمارش محلی شما و شمارش API می‌شود. همیشه برای صورتحساب دقیق به مصرف توکن بازگردانده شده در پاسخ اعتماد کنید.
به پنجره زمینه خود توجه کنید که مجموعاً ۱۰۰,۰۰۰ توکن است. تجاوز از این حد باعث خطا می‌شود. پیام‌ها یا خلاصه‌های قدیمی‌تر را کوتاه کنید تا در محدوده بمانید. مصرف توکن خود را در طول زمان پایش کنید تا ساختار پرامپت خود را بهینه‌سازی کرده و هزینه‌ها را کاهش دهید.
تأخیرهای پرداخت رمزارز
شارژهای کریپتو از طریق USDT (TRC20) یا USDC (Base) در سمت ما به صورت آنی پردازش می‌شوند. با این حال، شلوخی شبکه گاهی اوقات می‌تواند باعث تأخیرهای جزئی در تأیید شود. برای جلوگیری از از دست رفتن وجه، مطمئن شوید که مبلغ و شبکه صحیح را ارسال می‌کنید.
شارژها از ۲۰ تا ۵۰۰ دلار در مبالغ صحیح هستند. اعتبارات پاداش به طور خودکار اعمال می‌شوند: +۵٪ از ۵۰ دلار، +۱۰٪ از ۱۰۰ دلار و +۱۵٪ از ۲۰۰ دلار. هش تراکنش را برای تأیید پرداخت بررسی کنید. اگر اعتبارات ظرف چند دقیقه ظاهر نشدند، وضعیت تراکنش را در اکسپلورر بلاکچین بررسی کنید.
اعتبار شما منقضی نمی‌شود، بنابراین عجله‌ای برای استفاده فوری وجود ندارد. خطاهایی مانند شارژهای دوتایی از طریق صفحه پشتیبانی حل می‌شوند. سوابق تراکنش خود را برای ارجاع آسان در صورت بروز مشکل نگه دارید.
پیکربندی شناسه مدل
شناسه مدل مشخص می‌کند که از کدام نسخه از مدل بدون سانسور استفاده می‌کنید. برای سرویس ما، شناسه مدل است uncensored. استفاده از شناسه نادرست می‌تواند منجر به خطاها یا رفتارهای غیرمنتظره شود.
اطمینان حاصل کنید که درخواست‌های شما مشخص می‌کنند model: "uncensored" در بدنه درخواست. این شناسه به مدل وزن‌باز خاص ما اشاره دارد که برای پاسخ‌های بدون محدودیت بهینه‌سازی شده است. این یک شناسه عمومی نیست، بلکه یک اشاره‌گر خاص به نمونه میزبانی شده ما است.
مستندات کتابخانه کلاینت خود را برای نحوه تنظیم شناسه مدل بررسی کنید. برخی از کتابخانه‌ها از یک model فیلد، در حالی که برخی ممکن است از پارامتر متفاوتی استفاده کنند. ثبات در استفاده از شناسه مدل در سراسر برنامه شما از سردرگمی جلوگیری کرده و تضمین می‌کند که همیشه به مدل uncensored مورد نظر متصل می‌شوید.
اعمال پنجره زمینه
پنجره زمینه تعداد کل توکن‌هایی که می‌توانید در یک درخواست ارسال کنید را محدود می‌کند. API ما از پنجره‌ای به اندازه ۱۰۰,۰۰۰ توکن پشتیبانی می‌کند که شامل پرامپت و تکمیل است. فراتر رفتن از این حد منجر به خطا می‌شود.
برای مدیریت زمینه، یک استراتژی پنجره لغزان پیاده‌سازی کنید. پیام‌های قدیمی‌تر را حذف یا خلاصه کنید تا فضا آزاد شود. تعداد توکن‌های ورودی خود را پایش کنید تا اطمینان حاصل کنید که در محدودیت 100,000 توکن باقی می‌ماند. اگر از این محدودیت تجاوز کنید، API درخواست را رد خواهد کرد.
از max_tokens پارامتری برای کنترل طول خروجی. حداکثر خروجی در هر درخواست ۱۶,۰۰۰ توکن است. تنظیم این پارامتر به جلوگیری از مصرف بیش‌ازحد توکن کمک کرده و پاسخ‌ها را در محدوده‌های قابل مدیریت برای برنامه شما نگه می‌دارد.
سیاست پشتیبانی و بازپرداخت
اعتبار پس از مصرف مسترد نمی‌شود، اما منقضی نمی‌گردد. اگر با مشکلات پرداخت یا سرویس مواجه شدید، از طریق صفحه مشخص‌شده با پشتیبانی تماس بگیرید. اشتباهاتی مانند شارژهای دوبل توسط تیم پشتیبانی حل می‌شوند.
برای مشکلات فنی، ابتدا مستندات را بررسی کنید. API ما ساده است، اما ممکن است موارد حاشیه‌ای پیش بیاید. هنگام درخواست کمک، کلید API و جزئیات درخواست خود را ارائه دهید. زمان‌های پاسخ متفاوت است، اما ما تلاش می‌کنیم مشکلات را به سرعت حل کنیم.
به یاد داشته باشید که اعتبار از پیش پرداخت می‌شود. شما بابت آنچه مصرف می‌کنید پرداخت می‌کنید، و خطاها و رد شدن‌ها رایگان هستند. این مدل شفافیت در صورتحساب را تضمین می‌کند. برای هرگونه مغایرت یا سوال درباره حساب خود از صفحه پشتیبانی استفاده کنید.
