Developer guide

فراخوانی API

مسیرهای سازگار با API و قوانین استریم و صوت

مسیرهای فراخوانی در دروازه CLEVI به مشخصات سازگار با OpenAI و مشخصات سازگار با Anthropic تقسیم می‌شوند.
هر دو مشخصات از یک کلید API استفاده می‌کنند و مدل‌های استدلالی مکالمه‌ای را می‌توان با هر یک از این مشخصات فراخوانی کرد.
مسیرهای embedding و صوت و voice فقط در مشخصات سازگار با OpenAI ارائه می‌شوند و
مشخصات سازگار با Anthropic سه مسیر messages، count_tokens و models را ارائه می‌دهد.

استریم با گزینه stream در بدنه درخواست فعال می‌شود و embedding و برخی مدل‌ها و مسیرها از آن پشتیبانی نمی‌کنند. مسیرهای صوت و voice از قوانین متفاوتی نسبت به استدلال معمول پیروی می‌کنند؛ برای مثال، صوت را بدون تغییر برمی‌گردانند و خروجی‌ها را به مدت ۳ روز در CleviDrive نگهداری می‌کنند.

شناسه مدل و فراخوانی‌های مجاز برای هر مدل در صفحه مدل‌ها، و هدر احراز هویت و base URL در صفحه احراز هویت با کلید API قرار دارند.

انتخاب مسیر

بر اساس کاری که می‌خواهید انجام دهید و SDK مورد استفاده، مسیر را انتخاب کنید. مسیرهای جدول، مسیرهای نسبی‌ای هستند که پس از base URL هر مشخصات قرار می‌گیرند.

کاری که می‌خواهید انجام دهید	مشخصات	مسیر
استدلال مکالمه‌ای، استفاده از 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 مشخصات سازگار با OpenAI برابر با https://platform.clevi.net/api/v2/aiservice/openai/v1 است. بدنه درخواست و پاسخ از مشخصات OpenAI پیروی می‌کنند. جدول زیر مسیرهای استدلال و مدل را به‌صورت مسیر کامل بر اساس میزبان نشان می‌دهد؛ مسیرهای صوت و voice در بخش‌های بعدی مربوط به مسیرهای صوت و 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 برمی‌گرداند.

این یک نمونه حداقلی برای فراخوانی chat/completions است. به‌جای sk-... کلیدی را که در صفحه کلید API صادر کرده‌اید و در model، شناسه مدل را از صفحه مدل وارد کنید.

Bash

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": "안녕하세요"}]
  }'

مسیرهای دیگر

مسیرهای زیر برای تشخیص، سازگاری با نسخه‌های قدیمی و انتقال استفاده می‌شوند.

مسیر	توضیحات
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 برگردانده می‌شود.

تمام فیلدهای درخواست و پاسخ را می‌توان در سند OpenAPI 3.0 https://platform.clevi.net/api/v2/console/openapi/cloud-inference-v1 مشاهده کرد. فهرست مسیرها در این سند تولید می‌شود و سند فقط با جلسه‌ای که به کنسول وارد شده است باز می‌شود. می‌توان با همین سند کلاینت ایجاد کرد.

مسیر سازگار با Anthropic

base URL مشخصات سازگار با Anthropic، 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	فهرست مدل‌ها را به‌صورت صفحه‌بندی مبتنی بر cursor برمی‌گرداند. limit بین 1 تا 1000 است و در صورت خارج شدن از این محدوده، 400 برگردانده می‌شود.
GET	/api/v2/aiservice/anthropic/v1/models/{modelId}	یک مدل را دریافت می‌کند. اگر مدل قابل دسترسی نباشد، 404 برگردانده می‌شود.

این یک نمونه حداقلی برای فراخوانی messages است.

Bash

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": "안녕하세요"}]
  }'

اگر هدر anthropic-version حذف شود، مقدار 2023-06-01 در نظر گرفته می‌شود. درگاه هدرهای anthropic-version و anthropic-beta را بدون تغییر منتقل می‌کند.

استریمینگ (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 را برمی‌گرداند. این مسیری است که تا زمان امکان محاسبه دقیق و فقط یک‌باره میزان مصرف پاسخ‌های پس‌زمینه بسته نگه داشته شده است.

همراه با اولین قطعه، سه هدر زیر ارسال می‌شوند. پس از آن، در هر قطعه یک خط data: ارسال و بلافاصله flush می‌شود؛ اگر سرویس بالادستی نام رویداد را ارائه کرده باشد، خط event: نیز همراه آن ارسال می‌شود.

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]

اگر هنگام استریمینگ خطایی رخ دهد، همان JSON خطای فراخوانی معمولی در یک خط data: ارسال می‌شود و کد وضعیت HTTP نیز تغییر می‌کند.

مسیرهای صوتی و صدا

مسیرهای مدیریت 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 را در پاسخ قرار می‌دهد.
انتخاب Product	audio/speech و audio/transcriptions، Product را با استفاده از model در بدنه درخواست انتخاب می‌کنند. مسیرهای صدا و تشخیص به هدر X-Product-Sku یا پارامتر product_sku در query نیاز دارند.
مالکیت صدا	صداهای کپی‌شده یا ثبت‌شده متعلق به ایجادکننده آن‌ها هستند. تلاش برای سنتز یا حذف صدای متعلق به مالک دیگر، کد 403 را برمی‌گرداند و فهرست GET /voices نیز فقط صداهای متعلق به خودتان را شامل می‌شود.
اندازه و زمان	حداکثر اندازه درخواست 28 MiB و محدودیت زمانی فراخوانی upstream، 5 دقیقه است.
ازدحام provider	اگر upstream دچار ازدحام باشد، کد 409 بدون تغییر منتقل می‌شود و در صورت وجود Retry-After، آن مقدار نیز همراه پاسخ منتقل می‌شود. دروازه دوباره تلاش نمی‌کند و درخواست را در صف قرار نمی‌دهد.

فراخوانی API

انتخاب مسیر

مسیر سازگار با OpenAI

مسیرهای دیگر

مسیر سازگار با Anthropic

استریمینگ (SSE)

مسیرهای صوتی و صدا

زبان و منطقه

پیشنهادی

شرق آسیا

جنوب شرق آسیا

جنوب آسیا

آسیای مرکزی

خاورمیانه و قفقاز

غرب اروپا و جنوب اروپا

بریتانیا و ایرلند

شمال اروپا

اروپای مرکزی و بالکان

شرق اروپا

شرق افریقا

غرب افریقا و مرکز افریقا

جنوب افریقا

امریکا

اقیانوسیه