Developer guide
فراخوانی API
مسیرهای سازگار با API و قوانین استریم و صدا
این صفحه مسیرهایی را پوشش میدهد که پس از احراز هویت، واقعاً فراخوانی میشوند.
این صفحه شامل فهرست مسیرهای سازگار با OpenAI و Anthropic، نحوه دریافت پاسخ هنگام فعالکردن stream در بدنه درخواست،
و ترتیب قوانین قابلاعمال فقط بر مسیرهای صدا و voice است.
شناسه مدل و فراخوانیهای مجاز برای هر مدل در صفحه مدلها، و هدر احراز هویت و base URL در صفحه احراز هویت با کلید API قرار دارند.
مسیر انجام کار
هر دو استاندارد سازگار از یک کلید API استفاده میکنند و مدلهای استدلال مکالمهای را میتوان با هر یک از این دو استاندارد فراخوانی کرد. بر اساس کاری که میخواهید انجام دهید و SDK مورد استفادهتان، مسیر را انتخاب کنید.
| کار موردنظر | استاندارد | مسیر |
|---|---|---|
| استدلال مکالمهای، استفاده از OpenAI SDK | سازگار با OpenAI | POST /chat/completions یا POST /responses |
| استدلال مکالمهای، استفاده از Anthropic SDK | سازگار با Anthropic | POST /v1/messages |
| ایجاد embedding | سازگار با OpenAI | POST /embeddings |
| تولید و رونویسی صدا، مدیریت voice | سازگار با OpenAI | مسیرهای زیر /audio و /voices |
| بررسی مدلهای قابل فراخوانی | هر دو | GET /models |
مسیر سازگار با OpenAI
base URL برابر با https://platform.clevi.net/api/v2/aiservice/openai/v1 است و بدنه درخواست و پاسخ از استاندارد OpenAI پیروی میکند. جدول زیر مسیرهای استدلال و مدل را نشان میدهد؛ مسیرهای صدا و voice در بخش بعدی بهطور جداگانه آمدهاند.
| روش | مسیر | توضیح |
|---|---|---|
| POST | /api/v2/aiservice/openai/v1/chat/completions | استدلال مکالمهای. در صورت فعال کردن stream، پاسخ از طریق SSE ارسال میشود. |
| POST | /api/v2/aiservice/openai/v1/responses | فراخوانی مطابق با مشخصات Responses. از stream پشتیبانی میکند. |
| GET | /api/v2/aiservice/openai/v1/responses/{responseId} | یک پاسخ ذخیرهشده را دریافت میکند. |
| GET | /api/v2/aiservice/openai/v1/responses/{responseId}/input_items | فهرست موارد ورودی پاسخ ذخیرهشده. |
| POST | /api/v2/aiservice/openai/v1/responses/{responseId}/cancel | پاسخ در حال پردازش در پسزمینه را لغو میکند. |
| DELETE | /api/v2/aiservice/openai/v1/responses/{responseId} | پاسخ ذخیرهشده را حذف میکند. |
| POST | /api/v2/aiservice/openai/v1/completions | تکمیل متن قدیمی. از stream پشتیبانی میکند. |
| POST | /api/v2/aiservice/openai/v1/embeddings | ایجاد embedding. از پخش جریانی پشتیبانی نمیکند. |
| GET | /api/v2/aiservice/openai/v1/models | فهرست مدلهایی که میتوان با این کلید فراخوانی کرد. |
| GET | /api/v2/aiservice/openai/v1/models/{modelId} | دریافت یک مدل. اگر قابل دسترسی نباشد، 404 است. |
curl https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions \
-H "X-API-Key: sk-..." \
-H "Content-Type: application/json" \
-d '{
"model": "cip-5.5-im",
"messages": [{"role": "user", "content": "안녕하세요"}]
}'در قسمت sk-... کلید صادرشده از صفحه کلید API و در قسمت model، ID صفحه مدل را وارد کنید.
مسیرهای دیگر
| مسیر | توضیحات |
|---|---|
| GET /api/v2/aiservice/openai/v1/healthz | وضعیت provider صوتی را بررسی میکند. |
| /api/v2/aiservice/openai/v1/api/status · /api/options · /api/generate · /outputs/{filename} | وضعیت و گزینههای Cosa قدیمی را دریافت میکند، فراخوانی ایجاد (multipart) را انجام میدهد و خروجیها را دانلود میکند. |
| /api/v2/aiservice/openai/v1/{routeKey} (GET · POST · PUT · PATCH · DELETE) | مسیرهای provider که در بالا ذکر نشدهاند را با اعمال قوانین واسطهگری میکند. فراخوانی chat/completions، completions، embeddings و responses از طریق واسطهگری POST با خطای 404 مواجه میشود و این چهار مورد توسط مسیرهای اختصاصی پردازش میشوند. |
مسیرهای سازگار با Anthropic
base URL برابر با https://platform.clevi.net/api/v2/aiservice/anthropic است و Anthropic SDK بهطور خودکار /v1 را به مسیر اضافه میکند. بدنه درخواست و پاسخ از مشخصات Anthropic Messages پیروی میکند.
| روش | مسیر | توضیحات |
|---|---|---|
| POST | /api/v2/aiservice/anthropic/v1/messages | فراخوانی مطابق مشخصات Messages. به model، messages و max_tokens نیاز دارد و از stream پشتیبانی میکند. |
| POST | /api/v2/aiservice/anthropic/v1/messages/count_tokens | فقط تعداد توکنهای ورودی را بدون هزینه تخمین میزند. نیازی به max_tokens نیست. |
| GET | /api/v2/aiservice/anthropic/v1/models | فهرست مدلها با صفحهبندی مبتنی بر مکاننما است. limit باید بین 1 تا 1000 باشد و در غیر این صورت خطای 400 رخ میدهد. |
| GET | /api/v2/aiservice/anthropic/v1/models/{modelId} | دریافت یک مدل. اگر قابل دسترسی نباشد، خطای 404 رخ میدهد. |
curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/messages \
-H "X-API-Key: sk-..." \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "cip-5.5-im",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "안녕하세요"}]
}'پخش جریانی (SSE)
اگر در بدنه درخواست "stream": true را قرار دهید، سرور با Server-Sent Events پاسخ میدهد. بسته به مسیر و مدل، رفتار به شکل زیر متفاوت است.
| هدف | رفتار |
|---|---|
| OpenAI سازگار با POST /chat/completions · POST /completions · POST /responses | از stream پشتیبانی میکند. |
| Anthropic سازگار با POST /v1/messages | از stream پشتیبانی میکند. |
| POST /embeddings | از استریمینگ پشتیبانی نمیکند. |
| مدلهای سری جستوجوی Ivy (مانند ivy-4-mm-search) | حتی اگر stream را فعال کنید، سرور آن را خاموش کرده و پاسخ را یکباره ارسال میکند. |
| GET /responses/{responseId}?stream=true | با کد 400 رد میشود. این مسیری است که تا زمانی که امکان محاسبه دقیق و تنها یکباره میزان مصرف پاسخهای پسزمینه فراهم شود، بسته نگه داشته شده است. |
همراه با اولین قطعه، سه هدر زیر ارسال میشوند. پس از آن، برای هر قطعه یک خط event: (فقط در صورتی که upstream نام رویداد را ارائه کرده باشد) و یک خط data: ارسال و بلافاصله flush میشود.
- Content-Type: text/event-stream
- Cache-Control: no-cache
- X-Accel-Buffering: no
قطعههای مسیر سازگار با Anthropic بهصورت جفتِ خط event و خط data ارسال میشوند.
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"안"}}قطعههای chat/completions در قالب خط data ارسال میشوند و در پایان، data: [DONE] بدون تغییر منتقل میشود.
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[...]}
data: [DONE]مسیرهای صوت و صدا
مسیرهای مدیریت صدا برای TTS·STT و Cosa در مشخصات سازگار با OpenAI قرار دارند و چند قانون آنها با استنتاج معمولی متفاوت است. مدلهایی که هر مسیر مجاز میداند، در جدول Cosa صفحه مدل آمدهاند.
| متد | مسیر | توضیحات |
|---|---|---|
| POST | /api/v2/aiservice/openai/v1/audio/speech | متن را به گفتار تبدیل کرده و فایل صوتی را مستقیماً دانلود میکند. |
| POST | /api/v2/aiservice/openai/v1/audio/transcriptions | فایل صوتی را به متن تبدیل میکند (multipart). |
| POST | /api/v2/aiservice/openai/v1/audio/speech/clone | با صدای شبیهسازیشده، گفتار تولید میکند (multipart). |
| GET | /api/v2/aiservice/openai/v1/voices | فهرست صداهایی که میتوانم استفاده کنم. |
| POST | /api/v2/aiservice/openai/v1/voices | یک صدا را با نمونه صوتی ثبت میکند (multipart). |
| POST | /api/v2/aiservice/openai/v1/voices/design | با استفاده از متن توصیفی، صدای ترکیبی ایجاد میکند. |
| DELETE | /api/v2/aiservice/openai/v1/voices/{voiceId} | صدا را حذف میکند. فقط مالک میتواند این کار را انجام دهد. |
| قانون | محتوا |
|---|---|
| تحویل باینری | پاسخ موفق audio/speech، audio/speech/clone و outputs/{filename}، ضمن ارسال مستقیم صوت، آن را همزمان در CleviDrive ذخیره میکند. |
| هدرهای رسید | X-Clevi-Drive-File-Id، X-Clevi-Drive-File-Version-Id، X-Clevi-Drive-Download-Url، X-Clevi-Drive-Expires-At و X-Clevi-Drive-Retention-Days: 3 برگردانده میشوند. مدت نگهداری 3 روز است و پس از آن 404 برگردانده میشود. |
| انتخاب Product | برای audio/speech و audio/transcriptions، Product با model موجود در بدنه انتخاب میشود. مسیرهای صدا و تشخیص به هدر X-Product-Sku یا پارامتر پرسوجوی product_sku نیاز دارند. |
| مالکیت صدا | صداهای ایجاد یا ثبتشده به ایجادکننده آنها تعلق دارند. تلاش برای ترکیب یا حذف با صدای دیگران با خطای 403 مواجه میشود و فهرست GET /voices نیز فقط صداهای متعلق به خود کاربر را نشان میدهد. |
| اندازه و زمان | حد بالای درخواست 28 MiB و محدودیت زمانی فراخوانی upstream، 5 دقیقه است. |
| ازدحام provider | اگر upstream مشغول باشد، کد 409 بدون تغییر منتقل میشود و در صورت وجود Retry-After، آن مقدار نیز منتقل خواهد شد. دروازه دوباره تلاش نمیکند و درخواست را در صف قرار نمیدهد. |