کلاینت‌های رسمی OpenAI به‌صورت پیش‌فرض به api.openai.com وصل می‌شوند. اما همه‌ی آن‌ها پارامتر base_url (یا baseURL) دارند که آدرس ریشه را عوض می‌کند. اگر سرویس مقصد همان قالب درخواست و پاسخ را پیاده کرده باشد، بقیه‌ی کد بدون تغییر کار می‌کند.
خطاهای رایج: فراموش کردن /v1 در انتها (که 404 می‌دهد) یا برعکس، اضافه کردن مسیر کامل /chat/completions به base URL که باعث تکرار مسیر می‌شود. بعضی ابزارها خودشان /v1 را اضافه می‌کنند و باید آدرس را بدون آن بدهید، مثل Claude Code که مسیر /v1/messages را به آدرس پایه اضافه می‌کند.
همیشه با یک درخواست ساده به /models اتصال را بسنجید.
client = OpenAI(base_url="https://api.picoai.ir/v1", api_key="YOUR_API_KEY")مثال کاربردی
تیم شما از SDK پایتون OpenAI استفاده می‌کند و می‌خواهد سرویس را عوض کند. فقط base_url و کلید را در یک فایل پیکربندی عوض می‌کنید و تست‌های موجود را اجرا می‌کنید؛ اگر همه سبز بود، مهاجرت تمام است.
چطور در عمل بررسی کنیم؟
بهترین راه یادگرفتن این مفهوم، دیدن آن در یک درخواست واقعی است. یک کلید بسازید، فهرست مدل‌ها را با /v1/models بگیرید، یک درخواست کوچک بفرستید و فیلدهای پاسخ (از جمله usage و finish_reason) را بخوانید. سپس همان درخواست را با پارامتر یا مدل دیگر تکرار و در داشبورد مصرف و هزینه را مقایسه کنید. نمونه‌های آماده در راهنمای cURL و راهنمای پایتون هست.
اصطلاحات نزدیک
- API سازگار با OpenAI: API سازگار با OpenAI سرویسی است که همان مسیرها، قالب درخواست و پاسخ API رسمی OpenAI را پیاده کرده تا کلاینت‌ها و ابزارهای موجود بدون تغییر با آن کار کنند.
- کلید API: کلید API رشته‌ی محرمانه‌ای است که هویت شما را در برابر یک API ثابت می‌کند و مصرف را به حساب شما نسبت می‌دهد.
- جایگزینی خودکار مسیر: Failover یعنی وقتی مسیر یا ارائه‌دهنده‌ی اصلی خطا می‌دهد یا کند است، درخواست به‌طور خودکار به مسیر پشتیبان فرستاده شود.
- استریم: استریم یعنی مدل پاسخ را تکه‌تکه و هم‌زمان با تولید ارسال کند و نیاز نباشد تا پایان تولید منتظر بمانید.
در پیکو هوش
آدرس پایهی نقطهی سازگار با OpenAI در پیکو هوش https://api.picoai.ir/v1 است. برای ابزارهای Anthropic از https://api.picoai.ir استفاده کنید (در برخی ابزارها بدون /v1).
اشتباهات رایج
- آدرس پایه با اسلش اضافه یا بدون https.
- گذاشتن مسیر کامل endpoint به‌جای آدرس ریشه.
پرسش‌های متداول
اگر 404 گرفتم؟
مسیر تکراری یا /v1 جاافتاده را بررسی کنید.
آیا برای Anthropic هم همین است؟
نه؛ بسیاری از ابزارهای Anthropic آدرس را بدون /v1 میخواهند.
آدرس پایه (Base URL) در پیکو هوش چه نقشی دارد؟
آدرس پایهی نقطهی سازگار با OpenAI در پیکو هوش https://api.picoai.ir/v1 است. برای ابزارهای Anthropic از https://api.picoai.ir استفاده کنید (در برخی ابزارها بدون /v1).
از تعریف تا عمل
ثبت‌نام کنید، یک کلید بسازید و مفهوم را روی مدل واقعی امتحان کنید.