نقطهی اتصال سفارشی API: وصل کردن API سازگار با OpenAI
نقطهی اتصال سفارشی API و Base URL چیست و چطور یک API سازگار با OpenAI، سرویس واسط، پروکسی یا gateway را فقط با یک نشانی و یک کلید وصل کنید.
- نقطهی اتصال سفارشی API (custom API endpoint) نشانی وب یا Base URL یک سرویس هوش مصنوعی است که در برنامهی شما از پیش تعریف نشده؛ مثل یک API سازگار با OpenAI، سرویس واسط (relay)، پروکسی (proxy) یا درگاه (gateway). در Oriveo معمولاً برای وصل کردنش دو چیز لازم دارید: همان نشانی و یک کلید API.
- Oriveo پروتکل را خودش تشخیص میدهد (OpenAI Chat Completions، OpenAI Responses، Anthropic Messages یا Gemini) و وقتی فقط نشانی ریشه را وارد کنید، مسیر نسخه مثل /v1 را خودش اضافه میکند.
- نشانیهای عمومی باید HTTPS باشند. سرویس شخص ثالث میتواند هر چیزی را که از آن عبور میدهید ببیند؛ پس به آن یک کلید جداگانه با سقف هزینه بدهید و هرگز کلید رسمی ارائهدهندهتان را در اختیارش نگذارید.

Base URL یا API endpoint چیست؟
هر سرویس هوش مصنوعی یک نشانی وب دارد که برنامهها درخواستهایشان را به آن میفرستند. برنامهنویسها به آن Base URL، API endpoint یا نشانی درخواست (request URL) میگویند؛ اینجا همهی اینها یک معنی دارند. ظاهرش مثل یک نشانی وب معمولی است؛ مثلاً نشانی OpenAI این است: https://api.openai.com/v1.
در Oriveo، نشانی 15 ارائهدهندهی داخلی از قبل پر شده است و شما فقط کلید را جایگذاری میکنید. نقطهی اتصال سفارشی برای هر چیز دیگری است: سرویسی که API سازگار با OpenAI ارائه میدهد، یک سرویس واسط یا gateway که شرکتی آن را اداره میکند، یا یک gateway که خودتان روی سرور خودتان اجرا میکنید.
«سازگار با OpenAI» (OpenAI-compatible) یعنی سرویس، درخواستها را در همان قالب API شرکت OpenAI میپذیرد؛ پس برنامههایی که برای OpenAI ساخته شدهاند میتوانند با آن کار کنند. بسیاری از ارائهدهندگان و gatewayها این قالب را ارائه میدهند.
سرویس واسط، پروکسی و gateway چه فرقی دارند؟
این واژهها را معمولاً بیدقت به کار میبرند و برای وصل کردن یک برنامه همه یکجور کار میکنند: سرویسی میان برنامهی شما و ارائهدهندگان مدل قرار میگیرد، درخواست را میگیرد و آن را به مقصد میفرستد. بعضی چند ارائهدهنده را پشت یک کلید و یک صورتحساب میگذارند؛ بعضی برای تیمها کنترل مصرف اضافه میکنند؛ بعضی هم نرمافزاریاند که روی سرور خودتان اجرا میکنید.
Oriveo هیچکدام را توصیه یا رتبهبندی نمیکند. هرکدام را به کار ببرید، مراحل زیر یکی است.
برای وصل کردن نقطهی اتصال سفارشی چه لازم دارم؟
معمولاً دو چیز، که هر دو را در داشبورد یا مستندات خود سرویس پیدا میکنید:
- نشانی درخواست (Base URL)، مثلاً https://api.example.com/v1. اگر سرویس روی اینترنت عمومی است، باید با https:// شروع شود.
- یک کلید API که همان سرویس برای شما صادر کرده است. با «افزودن کلید دیگر» میتوانید کلیدهای بیشتری اضافه کنید.
- اختیاری: یک نام برای اتصال، تا آن را از اتصالهای دیگر تشخیص دهید.
چطور در Oriveo نقطهی اتصال سفارشی اضافه کنم؟
مراحل در iPhone، Android و وب یکسان است.
- «ارائهدهندگان» را باز کنید و دکمهی + («افزودن ارائهدهنده») را بزنید.
- دکمهی «سفارشی» و بعد «سرویس واسط سفارشی» («سرویس مدل خودتان را متصل کنید») را انتخاب کنید.
- در صفحهی «اتصال سرویس واسط سفارشی»، نشانی درخواست و کلید API را جایگذاری کنید. سطر «درخواست خواهد کرد: …» نشانی کاملی را که Oriveo به کار میبرد نشان میدهد. «بعدی» را بزنید.
- Oriveo اتصال را بررسی میکند، فهرست مدلها را میخواند و پروتکل هر مدل را تشخیص میدهد. در این مرحله فقط فهرست خوانده میشود و هیچ پیام چتی فرستاده نمیشود.
- مدلهایی را که میخواهید علامت بزنید و «ذخیره (N مورد انتخابشده)» را بزنید. اگر سرویس مدلهایش را فهرست نمیکند، از «افزودن دستی شناسه مدل» استفاده کنید.
- پیش از ذخیره، Oriveo یک درخواست بسیار کوچک به اولین مدل انتخابشده میفرستد. اگر این آزمون موفق شود، اتصال ذخیره میشود؛ اگر نشود، در همان مرحله میمانید و میتوانید مشکل را درست کنید.

ترجیح میدهید همهچیز را خودتان تنظیم کنید؟ از «راهاندازی دستی» استفاده کنید
«راهاندازی دستی» همهچیز را در یک صفحه میآورد: نشانی، کلید، شناسهی مدل، نام اختیاری اتصال و پروتکل پیشفرض که روی حالت خودکار شروع میشود. «اعتبارسنجی و ذخیره» را بزنید. اگر بررسی ناموفق شود، هنوز چیزی ذخیره نشده است و کارت خطا گزینهی «ذخیره به هر حال (تأییدنشده)» را پیشنهاد میدهد، برای وقتی که میخواهید اتصال را نگه دارید و بعداً آزمایشش کنید.
آیا Oriveo پروتکل را خودکار تشخیص میدهد؟
بیشتر وقتها بله. سرویسهای هوش مصنوعی با یکی از چند قالب درخواست کار میکنند که به آنها پروتکل میگویند. Oriveo از چهار پروتکل پشتیبانی میکند: OpenAI Chat Completions، OpenAI Responses، Anthropic Messages و Gemini generateContent.
تشخیص برای هر مدل جداگانه انجام میشود. اگر سرویس دربارهی هر مدل اطلاعاتی بدهد، Oriveo از آن استفاده میکند؛ وگرنه از روی خانوادهی مدل، گزینههای محتمل را برمیگزیند. هنگام ذخیره، اولین مدل انتخابشده با یک درخواست واقعی آزموده میشود؛ بقیه بعداً، وقتی شروع به استفاده از آنها کنید، بررسی میشوند.
پس در بیشتر موارد نشانی و کلید کافی است. اگر مستندات سرویس پروتکل مشخصی را نام برده یا مدلی در بررسی ناموفق شده است، پروتکل را خودتان در «راهاندازی دستی» انتخاب کنید.
باید /v1 را به نشانی اضافه کنم؟
معمولاً نه. اگر فقط نشانی ریشه را وارد کنید، مثل https://api.example.com، Oriveo مسیر نسخهی استاندارد همان پروتکل را اضافه میکند: /v1 برای قالبهای OpenAI و Anthropic و /v1beta برای Gemini.
اگر نشانی از قبل نسخه دارد، مثل /api/paas/v4، Oriveo همان را نگه میدارد. اگر یک endpoint کامل را جایگذاری کنید که به /chat/completions، /responses، /messages یا :generateContent ختم میشود، Oriveo این انتها را حذف میکند و از آن برای تشخیص پروتکل سرویس استفاده میکند.
پیش از زدن «بعدی»، سطر «درخواست خواهد کرد: …» را نگاه کنید. اگر بررسی گفت «نشانی ممکن است به یک صفحه وب اشاره کند. بررسی کنید که /v1 جا نیفتاده باشد.»، نشانیتان را با مستندات سرویس مقایسه کنید.
| آنچه وارد میکنید | نشانیای که Oriveo درخواست میکند (قالب OpenAI) |
|---|---|
| https://api.example.com | https://api.example.com/v1 |
| https://api.example.com/v1 | https://api.example.com/v1 |
| https://api.example.com/v1/chat/completions | https://api.example.com/v1، با Chat Completions |
| https://api.example.com/api/paas/v4 | https://api.example.com/api/paas/v4 |
چه نشانیهایی پذیرفته میشوند؟
Oriveo برای محافظت از کلید شما چند قاعده دارد:
- نشانیهای عمومی باید با https:// شروع شوند. نشانی http:// روی اینترنت عمومی را نمیتوان آزمود یا ذخیره کرد.
- نشانیهایی که نام کاربری و رمز عبور درونشان است یا پارامتر کوئری دارند (هر چیزی بعد از «?») پذیرفته نمیشوند. Oriveo هرگز کلید API را از پارامترهای کوئری امتحان نمیکند.
- نشانیهای سادهی http:// در شبکهی خانگی یا VPN خصوصی، مثل سرور مدلی که روی رایانهی خودتان اجرا میشود، بهجای «سرویس واسط سفارشی» از ورودی جداگانهی محاسبات محلی اضافه میشوند («توان پردازشی محلی و شبکه محلی» در iPhone و «محاسبات محلی» در Android).
- در iPhone و Android، برنامه مستقیم به نشانی وصل میشود.
- در برنامهی وب، نشانیهای درخواست عمومی از طریق سرور Oriveo هدایت میشوند تا محدودیتهای CORS مرورگر دور زده شود (CORS یک قاعدهی امنیتی مرورگر است که جلوی بسیاری از درخواستهای مستقیم را میگیرد) — کلید API شما فقط برای همان درخواست در حافظه نگه داشته میشود و هرگز ذخیره یا ثبت نمیشود. نشانیهای درخواست در شبکه محلی شما مستقیم از همین دستگاه متصل میشوند و در هر دو حالت HTTPS الزامی است؛ برای نشانی سادهی http:// در شبکهی خانگی، به برنامهی iPhone یا Android و ورودی محاسبات محلی آن نیاز دارید.
- کلیدها روی این دستگاه میمانند و با همگامسازی ابری بارگذاری نمیشوند.
Base URL ارائهدهندگان داخلی
در Oriveo به اینها نیازی ندارید؛ کافی است ارائهدهنده را با نامش انتخاب کنید. اینجا آمدهاند چون مردم اغلب برای ابزارهای دیگر دنبالشان میگردند. هرکدام نشانی رسمی سازگار با OpenAI است که تا 18 نوامبر 2026 در مستندات همان ارائهدهنده آمده است.
- Anthropic لایهی سازگار با OpenAI خود را برای آزمایش و مقایسه معرفی میکند و راهنمای شروع سریع Mistral هم API آن را سازگار با OpenAI توصیف نمیکند. این دو را بهصورت ارائهدهندهی داخلی اضافه کنید.
| ارائهدهنده | Base URL سازگار با OpenAI |
|---|---|
| OpenAI | https://api.openai.com/v1 |
| Google Gemini | https://generativelanguage.googleapis.com/v1beta/openai/ |
| OpenRouter | https://openrouter.ai/api/v1 |
| DeepSeek | https://api.deepseek.com |
| xAI (Grok) | https://api.x.ai/v1 |
| Groq | https://api.groq.com/openai/v1 |
| Together AI | https://api.together.ai/v1 |
| Fireworks AI | https://api.fireworks.ai/inference/v1 |
| MiniMax (بینالمللی) | https://api.minimax.io/v1 |
| Z.ai (بینالمللی) | https://api.z.ai/api/paas/v4/ |
| Qwen (منطقهی سنگاپور) | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
| Kimi (بینالمللی) | https://api.moonshot.ai/v1 |
| SiliconFlow (بینالمللی) | https://api.siliconflow.com/v1 |
استفاده از سرویس واسط یا API شخص ثالث امن است؟
احتیاط کنید. هر سرویسی که میان شما و مدل قرار بگیرد، میتواند پرامپتها، فایلهای پیوست و پاسخها را بخواند و قیمتهایش را خودش تعیین میکند. Oriveo نمیتواند درون آن را ببیند یا آن را تضمین کند.
- هرگز کلید API حساب رسمی ارائهدهندهتان را به یک سرویس شخص ثالث ندهید. از کلیدی استفاده کنید که خود آن سرویس برایتان صادر کرده است.
- برای Oriveo کلید جداگانه بسازید و اگر سرویس اجازه میدهد، برایش سقف هزینه بگذارید یا موجودی کمی رویش نگه دارید.
- رمزهای عبور، شمارههای شناسایی یا اطلاعات محرمانهی کاری را از سرویسی که به آن اعتماد ندارید عبور ندهید.
- مصرفتان را در داشبورد خود سرویس بررسی کنید. عددهای هزینه در Oriveo تخمینیاند؛ سوابق خود سرویس ملاک نهایی است.
- اگر کلیدی لو رفت، آن را در داشبورد سرویس حذف کنید و کلید تازه بسازید.
چرا نقطهی اتصال سفارشی من وصل نمیشود؟
Oriveo در یک سطر میگوید چه چیزی اشتباه است. پیامها در نسخهی فارسی برنامه:
- برای کدهایی مثل 401، 402 و 429، راهنمای خطاهای کلید API ما معنای هرکدام را توضیح میدهد.
| پیام در Oriveo | چه چیزی را بررسی کنید |
|---|---|
| نشانی ممکن است به یک صفحه وب اشاره کند. بررسی کنید که /v1 جا نیفتاده باشد. | نشانی را با مستندات سرویس مقایسه کنید؛ مسیر نسخه را اضافه یا حذف کنید |
| کلید نامعتبر است. | کلید را دوباره از داشبورد سرویس کپی کنید |
| این کلید نمیتواند فهرست مدلها را بخواند. میتوانید مدلها را بهصورت دستی اضافه کنید. | در مرحلهی بعد، شناسهی مدل را خودتان اضافه کنید |
| اتصال برقرار نشد. شبکه یا پروکسی را بررسی کنید. | اتصال اینترنت و در دسترس بودن نشانی را بررسی کنید |
| سرویس در این نشانی درخواستها را محدود میکند. | کمی صبر کنید و دوباره امتحان کنید |
| این اتصال نتوانست به ارائهدهنده بالادست خود برسد. | ممکن است حساب خود سرویس در پشت آن نامعتبر باشد، اعتبارش تمام شده باشد یا با محدودیت نرخ روبهرو شده باشد؛ با گردانندهی آن تماس بگیرید |
پرسشهای متداول
نقطهی اتصال سفارشی API چیست؟
API سازگار با OpenAI چیست؟
کدام Base URL را وارد کنم؟
میتوانم در iPhone و Android از نقطهی اتصال سفارشی استفاده کنم؟
چرا Oriveo اتصال HTTPS را الزامی میداند؟
استفاده از سرویس واسط یا پروکسی API امن است؟
مطالب مرتبط
سرویس مدل خودتان را متصل کنید
برنامهی وب را باز کنید یا Oriveo را برای iPhone یا Android دانلود کنید، «سرویس واسط سفارشی» را انتخاب کنید و نشانی و کلید سرویس خود را جایگذاری کنید.
هنوز کلید API ندارید؟ با Oriveo Free بدون آن شروع کنید.