Developer guide

بانگکردنی API

ڕێڕەوی هاوشێوەی API و یاساکانی stream و دەنگ

ڕێڕەوی بانگکردنی گەیتوەی CLEVI بە دوو ستاندارد دابەش دەبێت: ستانداردی گونجاو لەگەڵ OpenAI و ستانداردی گونجاو لەگەڵ Anthropic.
هەردوو ستانداردەکە هەمان کلیلەی API بەکاردێنن، و مۆدێلەکانی بیرکردنەوەی گفتوگۆیی بە هەر یەکێک لەو دوو ستانداردە بانگ دەکرێن.
ڕێڕەوی embedding و دەنگ و voice تەنها لە ستانداردی گونجاو لەگەڵ OpenAI هەیە،
و ستانداردی گونجاو لەگەڵ Anthropic سێ ڕێڕەوی messages، count_tokens و models پێشکەش دەکات.

پەخشکردن لە ڕێگەی stream لە ناوەڕۆکی داواکارییەکە چالاک دەکرێت، و embedding و هەندێک مۆدێل و ڕێڕەو پشتگیری ناکرێن. ڕێڕەوی دەنگ و voice یاسای جیاواز لە بیرکردنەوەی ئاسایی پەیڕەو دەکات، لەوانە گەڕاندنەوەی ڕاستەوخۆی دەنگ و هەڵگرتنی بەرهەمەکان لە CleviDrive بۆ ماوەی 3 ڕۆژ.

ناسنامەی مۆدێل و بانگکردنی ڕێگەپێدراو بۆ هەر مۆدێلێک لە پەڕەی مۆدێلەکان، و هێدەرەکانی authentication و base URL لە پەڕەی authentication بە کلیلەی 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	ئیمبێدینگ دروست دەکات. پشتگیری لە پەخشی بەردەوام ناکات.
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 دەکات؛ تەنها ئەگەر upstream ناوی ڕووداو پێشکەش کردبێت، هێڵی 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 بە بەکارهێنانی model لە ناوەڕۆکی داواکارییەکە Product هەڵدەبژێرن. ڕێڕەوی دەنگ و پشکنین پێویستی بە سەردێڕی X-Product-Sku یان پرسیاری product_sku هەیە.
خاوەندارێتی دەنگ	ئەو دەنگانەی کۆپی یان تۆمار کراون، سەر بە لایەنی دروستکەرەوە دەبن. ئەگەر هەوڵی بەکارهێنان بۆ دەنگی خاوەندارێکی تر بۆ دەرهێنانی دەنگ یان سڕینەوەی بدرێت، 403 دەگەڕێنێتەوە و لیستی GET /voices تەنها دەنگەکانی خاوەنی خۆت لەخۆدەگرێت.
قەبارە و کات	سنووری داواکاری 28 MiB ـە و کاتی سنوورداری بانگکردنی upstream، 5 خولەکە.
قەرەباڵغی provider	ئەگەر upstream قەرەباڵغ بێت، 409 بە هەمان شێوە دەگوازرێتەوە و ئەگەر Retry-After هەبێت، ئەو نرخەش لەگەڵیدا دەگوازرێتەوە. گەیت‌وەی هەوڵی دووبارە ناداتەوە و لە ڕیزیشی نادات.

بانگکردنی API

هەڵبژاردنی ڕێڕەو

ڕێڕەوی گونجاو لەگەڵ OpenAI

ڕێڕەوەکانی تر

ڕێڕەوی گونجاو لەگەڵ Anthropic

ستریمینگ (SSE)

ڕێڕەوەکانی دەنگ و دەنگی گویێر

زمان و ناوچە

پێشنیارکراو

ڕۆژهەڵاتی ئاسیا

باشووری ڕۆژھەڵاتی ئاسیا

باشووری ئاسیا

ناوەڕاستی ئاسیا

ڕۆژهەڵاتی ناوەڕاست و قەفقاس

ڕۆژاوای ئەورووپا and باشووری ئەورووپا

شانشینی یەکگرتوو and ئیرلەند

باکووری ئەورووپا

ئەورووپای ناوەندی و بالکان

ڕۆژهەڵاتی ئەورووپا

ڕۆژھەڵاتی ئەفریقا

ڕۆژاوای ئەفریقا and ناوەڕاستی ئەفریقا

باشووری ئەفریقا

ئەمەریکای باکوور و باشوور

ئۆقیانووسیا