Developer guide
احراز هویت با کلید API
هدر حاوی کلید API و base URL برای تنظیم در SDK
درگاه CLEVI مسیر سازگار با OpenAI و مسیر سازگار با Anthropic را با یک کلید API احراز هویت می‌کند.
مقادیر قابل تنظیم در کلاینت شامل هدر احراز هویت حاوی کلید و base URL مربوط به SDK است؛ قالب هدر مجاز و base URL مجاز در هر استاندارد متفاوت است.
پس از تکمیل تنظیمات، با دریافت فهرست مدل‌ها می‌توانید بلافاصله وضعیت احراز هویت را بررسی کنید.
در صورت شکست احراز هویت، کد 401 و پس از موفقیت احراز هویت، اگر شرایط مجوز یا سقف استفاده برآورده نشود، کد 403 بازگردانده می‌شود.
کلید API را از صفحه کلیدهای API در کنسول صادر کنید. در همان صفحه می‌توانید ابطال کلید و محدوده استفاده از آن را مدیریت کنید.
هدر احراز هویت
هر دو استاندارد کلید API را در یک هدر درخواست قرار می‌دهند. از یکی از هدرهای X-API-Key و Authorization استفاده می‌شود و قالب مجاز بسته به استاندارد متفاوت است.
| هدر | سازگار با OpenAI | سازگار با Anthropic |
|---|---|---|
| X-API-Key: <کلید> | مجاز | مجاز |
| Authorization: Bearer <کلید> | مجاز | مجاز |
| Authorization: <کلید> (بدون Bearer) | رد می‌شود | مجاز |
هنگام استفاده از هدر Authorization در مسیر سازگار با OpenAI، پیشوند Bearer الزامی است. اگر فقط کلید را بدون پیشوند ارسال کنید، درگاه درخواست را رد می‌کند.
نام هدرها به حروف کوچک و بزرگ حساس نیستند؛ بنابراین هدر x-api-key که توسط Anthropic SDK ارسال می‌شود نیز بدون تغییر کار می‌کند. اگر هر دو هدر مشخص شوند، مقدار X-API-Key در اولویت قرار می‌گیرد.
base URL
SDK مورد استفاده قبلی را می‌توانید با تغییر base URL به آدرس زیر، بدون تغییرات دیگر استفاده کنید. تفاوت دو آدرس در داشتن یا نداشتن /v1 است؛ بنابراین آدرس متناسب با استاندارد را عیناً تعیین کنید.
| استاندارد | base URL | قواعد مسیر |
|---|---|---|
| سازگار با OpenAI | https://platform.clevi.net/api/v2/aiservice/openai/v1 | /v1 را تا انتها در base URL وارد کنید. |
| سازگار با Anthropic | https://platform.clevi.net/api/v2/aiservice/anthropic | از آنجا که Anthropic SDK، /v1 را مستقیماً به مسیر درخواست اضافه می‌کند، آدرس پیش از /v1 به پایان می‌رسد. |
بررسی احراز هویت
پس از تنظیم کلید و base URL، با دریافت فهرست مدل‌ها می‌توانید وضعیت احراز هویت را بررسی کنید. مثال‌های زیر همین درخواست را با curl، OpenAI SDK و Anthropic SDK اجرا می‌کنند. به‌جای sk-... کلیدی را وارد کنید که در صفحه کلید API صادر کرده‌اید.
هنگام دریافت فهرست با curl، در هر دو مشخصات باید مسیر کامل را تا /v1/models تعیین کنید. دستور اول از هدر X-API-Key برای مسیر سازگار با OpenAI و دستور دوم از هدر Authorization برای مسیر سازگار با Anthropic استفاده می‌کند.
curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
-H "X-API-Key: sk-..."
curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
-H "Authorization: Bearer sk-..." \
-H "anthropic-version: 2023-06-01"در OpenAI SDK، نشانی شامل /v1 را در base_url تعیین کنید.
from openai import OpenAI
client = OpenAI(
api_key="sk-...",
base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)
for model in client.models.list():
print(model.id)در Anthropic SDK، base_url را با نشانی‌ای تعیین کنید که پیش از /v1 پایان می‌یابد.
برای احراز هویت، همان هدر x-api-key را که SDK ارسال می‌کند استفاده کنید.
from anthropic import Anthropic
client = Anthropic(
api_key="sk-...",
base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)
for model in client.models.list(limit=20).data:
print(model.id)در هر یک از مثال‌ها، اگر پاسخ 200 باشد، احراز هویت با موفقیت انجام شده است و data پاسخ شامل فهرست مدل‌هایی است که می‌توانید با این کلید فراخوانی کنید. اگر پاسخ 401 بود، علت را طبق ترتیب بخش بعدی بررسی کنید.
احراز هویت ناموفق
اگر کلیدی ارسال کنید که وجود نداشته باشد، منقضی شده باشد یا لغو شده باشد، پاسخ 401 برگردانده می‌شود. اگر در مسیر سازگار با OpenAI بدون کلید فراخوانی کنید، بدنه زیر برگردانده می‌شود و در مسیر سازگار با Anthropic، مقدار error.type برابر با authentication_error است.
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}اگر پاسخ 401 دریافت کردید، به‌ترتیب زیر بررسی کنید.
- وضعیت کلید را در صفحه کلید API بررسی کنید. اگر کلید منقضی یا لغو شده است، کلید جدیدی صادر کنید.
- بررسی کنید نام هدر X-API-Key یا Authorization باشد.
- اگر در مسیر سازگار با OpenAI از هدر Authorization استفاده می‌کنید، بررسی کنید پیشوند Bearer وجود داشته باشد.
پس از اصلاح، دوباره دریافت فهرست مدل‌ها را در بخش بررسی احراز هویت اجرا کنید و بررسی کنید که پاسخ 200 دریافت می‌شود.
هدرهای مورد استفاده مشترک
همه هدرهای زیر اختیاری هستند. برای ردیابی مشکلات، توصیه می‌کنیم X-Request-Id را تعیین کنید.
| هدر | کاربرد | در صورت حذف |
|---|---|---|
| X-Request-Id | شناسه‌ای برای ردیابی درخواست است. مسیر سازگار با Anthropic همین مقدار را در هدر request-id پاسخ بازمی‌گرداند. | توسط سرور صادر می‌شود. |
| X-Region-Code | منطقه‌ای را که باید فراخوانی شود مشخص می‌کند. | global است. |
| X-Product-Sku (همچنین می‌توان آن را با product_sku در query مشخص کرد) | Product SKU مورد استفاده برای صورتحساب را مستقیماً مشخص می‌کند. هدر بر query اولویت دارد و عمدتاً در مسیرهای صوتی و voice استفاده می‌شود. | در مسیرهای voice نمی‌توان آن را حذف کرد. audio/speech و audio/transcriptions، Product را با model در بدنه درخواست انتخاب می‌کنند. |
| anthropic-version / anthropic-beta | در مسیر سازگار با Anthropic بدون تغییر ارسال می‌شود. | نسخه 2023-06-01 است. |
اگر خطاهای 5xx تکرار شدند، همراه با X-Request-Id از طریق راهنمایی و تماس با ما اطلاع دهید. اگر مقدار را مستقیماً مشخص کرده باشید، می‌توان آن را بلافاصله با گزارش‌های کلاینت تطبیق داد.