Developer guide
شروع سریع
شروع سریع
این سند از دریافت کلید API CLEVI تا ارسال نخستین درخواست و دریافت پاسخ را پوشش میدهد. با یک آدرس و یک کلید، cip-5.5-im و cip-5.5-mm را فراخوانی میکنید. درخواستها و پاسخها از قالب OpenAI Chat Completions پیروی میکنند؛ بنابراین کافی است در OpenAI SDK که استفاده میکردید، فقط دو مقدار base_url و api_key را تغییر دهید. مسیرهای مخصوص Anthropic SDK و مسیرهای embedding و صوت در سند فراخوانی API آمدهاند.
دریافت کلید API
کلید را از صفحه کلیدهای API در کنسول CLEVI Cloud دریافت میکنید. در همان صفحه میتوانید کلید را لغو کرده و محدوده استفاده را مدیریت کنید. با طی کردن مراحل زیر، یک کلید برای استفاده در درخواستها دریافت میکنید.
- در https://platform.clevi.net/account/login وارد شوید یا حساب ایجاد کنید.
- در https://clevi.app/cloud یک workspace اضافه کنید.
- به https://clevi.app/cloud/keys بروید.
- یک کلید جدید ایجاد کنید و مقدار آن را کپی کنید.
- مقدار کپیشده را در متغیر محیطی ذخیره کنید.
کلید دریافتشده را جایگزین sk-... در مثالهای این سند کنید. اگر آن را با دستور زیر در متغیر محیطی ذخیره کنید، میتوانید مثالهای بعدی را بدون تغییر کپی و اجرا کنید.
export CLEVI_API_KEY="sk-..."انتخاب مدل
نامهای زیر را عیناً در فیلد model بدنه درخواست وارد کنید. هر دو مدل از یک آدرس و یک قالب درخواست یکسان استفاده میکنند و ورودیهای متنی و تصویری را میپذیرند.
- cip-5.5-im
- cip-5.5-mm
| شناسه مدل | اندازه | محدودیت ورودی | حداکثر خروجی | کارهای مناسب |
|---|---|---|---|---|
| cip-5.5-im | 360B | 256K | 64K | کارهایی با هدف و محدوده مشخص. سرعت پاسخ و توان عملیاتی در اولویت است. |
| cip-5.5-mm | 800B | 512K | 64K | کارهای پیچیدهای که چندین منبع و شرط را ترکیب میکنند. برای تحلیل زمینههای طولانی و عاملهای چندمرحلهای استفاده میشود. |
مدلهایی که واقعاً میتوانید از حساب خود فراخوانی کنید، بر اساس فهرست مدلهای Playground و پاسخ GET /models تعیین میشوند. فهرست کامل مدلها و فراخوانیهای مجاز برای هر مدل در مستندات مدل، و میزان تقریبی اعتبار کسرشده در صفحه میزان مصرف کنسول قرار دارد.
POST /api/v2/aiservice/openai/v1/chat/completions
آرایه پیامها و نام مدل را دریافت کرده و پیامهای تولیدشده توسط مدل را در آرایه choices برمیگرداند. نشانی کامل https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions است. بدنه درخواست application/json است و احراز هویت با قرار دادن پیشوند Bearer و کلید در هدر Authorization انجام میشود. میتوانید کلید را با هدر X-API-Key نیز ارسال کنید؛ اگر هر دو هدر مشخص شوند، مقدار X-API-Key در اولویت قرار میگیرد.
| نام | نوع | الزامی | توضیحات |
|---|---|---|---|
| model | string | بله | cip-5.5-im یا cip-5.5-mm |
| messages | array | بله | آرایهای از اشیای پیام گفتگو. حداقل ۱ مورد |
| messages[].role | string | بله | یکی از system · user · assistant |
| messages[].content | string | بله | متن پیام |
| stream | boolean | خیر | اگر true باشد، پاسخ را بهصورت قطعههای Server-Sent Events دریافت میکنید |
| max_tokens | integer | خیر | حداکثر تعداد توکنهایی که در پاسخ تولید میشود |
| temperature | number | خیر | هرچه مقدار بیشتر باشد، احتمال دریافت پاسخهای متفاوت برای یک درخواست بیشتر میشود |
curl https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions \
-H "Authorization: Bearer $CLEVI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "cip-5.5-im",
"messages": [
{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}
]
}'import os
import requests
url = "https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions"
response = requests.post(
url,
headers={"Authorization": f"Bearer {os.environ['CLEVI_API_KEY']}"},
json={
"model": "cip-5.5-im",
"messages": [{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
},
timeout=60,
)
print(response.json()["choices"][0]["message"]["content"])const url =
"https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions";
const response = await fetch(url, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CLEVI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "cip-5.5-im",
messages: [{ role: "user", content: "CLEVI API를 한 문장으로 설명해 줘." }],
}),
});
const data = await response.json();
console.log(data.choices[0].message.content);نمونه پاسخ. مقادیر id، created و usage در هر درخواست متفاوت هستند.
{
"id": "chatcmpl-3f0a9c72",
"object": "chat.completion",
"created": 1755500000,
"model": "cip-5.5-im",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "CLEVI API는 주소 하나로 여러 모델을 호출하는 채팅 완료 API입니다."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 21,
"completion_tokens": 19,
"total_tokens": 40
}
}فراخوانی با OpenAI SDK
base_url مربوط به OpenAI SDK را به https://platform.clevi.net/api/v2/aiservice/openai/v1 تغییر دهید و کلید CLEVI را در api_key قرار دهید. سایر کدهای فراخوانی را بدون تغییر نگه دارید.
# pip install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["CLEVI_API_KEY"],
base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)
completion = client.chat.completions.create(
model="cip-5.5-mm",
messages=[{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
)
print(completion.choices[0].message.content)// npm install openai
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.CLEVI_API_KEY,
baseURL: "https://platform.clevi.net/api/v2/aiservice/openai/v1",
});
const completion = await client.chat.completions.create({
model: "cip-5.5-mm",
messages: [{ role: "user", content: "CLEVI API를 한 문장으로 설명해 줘." }],
});
console.log(completion.choices[0].message.content);دریافت بهصورت جریانی
اگر در بدنه درخواست stream را روی true قرار دهید، سرور با Server-Sent Events پاسخ میدهد. همراه با اولین قطعه، هدرهای Content-Type: text/event-stream، Cache-Control: no-cache و X-Accel-Buffering: no ارسال میشوند و در هر قطعه بعدی، یک شیء chat.completion.chunk در خط data: قرار میگیرد. آخرین خط data: [DONE] است. مثالهای Python و TypeScript زیر از همان client ساختهشده در بخش قبل استفاده میکنند.
curl -N https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions \
-H "Authorization: Bearer $CLEVI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "cip-5.5-im",
"messages": [{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
"stream": true
}'stream = client.chat.completions.create(
model="cip-5.5-im",
messages=[{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="")const stream = await client.chat.completions.create({
model: "cip-5.5-im",
messages: [{ role: "user", content: "CLEVI API를 한 문장으로 설명해 줘." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}نمونهای از قطعه.
data: {"id":"chatcmpl-3f0a9c72","object":"chat.completion.chunk","model":"cip-5.5-im","choices":[{"index":0,"delta":{"content":"CLEVI"},"finish_reason":null}]}
data: {"id":"chatcmpl-3f0a9c72","object":"chat.completion.chunk","model":"cip-5.5-im","choices":[{"index":0,"delta":{"content":" API는"},"finish_reason":null}]}
data: {"id":"chatcmpl-3f0a9c72","object":"chat.completion.chunk","model":"cip-5.5-im","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]اگر هنگام استریم خطایی رخ دهد، همان JSON خطا در یک خط data: ارسال میشود و کد وضعیت HTTP نیز تغییر میکند.
خطا
درخواست ناموفق، علت را با کد وضعیت HTTP اعلام میکند. اگر upstream کد 4xx یا 5xx برگرداند، همان کد منتقل میشود. ابتدا راهکارهای جدول زیر را بررسی کنید و اگر همان کد تکرار شد، زمان درخواست، بدنه ارسالشده و X-Request-Id را ثبت کنید.
| کد | معنا | راهکار |
|---|---|---|
| 400 | بدنهٔ درخواست با قالب مطابقت ندارد | بررسی کنید که model و messages وجود داشته باشند و JSON بسته شده باشد |
| 401 | کلید وجود ندارد یا منقضی یا باطل شده است | وضعیت کلید را در صفحهٔ کلیدهای API بررسی کنید و مطمئن شوید سربرگ Authorization با Bearer شروع میشود |
| 403 | مجوز دسترسی به مدل را ندارید، از حد استفاده عبور کردهاید یا اعتبار کافی ندارید | دلیل را در error.message بررسی کنید. حد استفاده را در سهمیهٔ استفادهٔ اختصاصیافته در نمای کلی، و موجودی و طرح را در بخش طرح و اعتبار مشاهده کنید |
| 404 | مدل وجود ندارد، با این کلید قابل دسترسی نیست یا مسیر وجود ندارد | بررسی کنید نام مدل در پاسخ GET /models وجود داشته باشد و آدرس با /api/v2/aiservice/openai/v1/chat/completions پایان یابد |
| 429 | ارائهدهندهٔ بالادستی محدودیت سرعت اعمال کرده است | اگر سربرگ Retry-After وجود دارد، بهاندازهٔ زمان مشخصشده صبر کنید؛ در غیر این صورت، فاصلهٔ بین تلاشها را هر بار دو برابر کنید و دوباره ارسال کنید |
| 5xx | خطای موقتی در درگاه یا سرویس بالادستی است | فاصلهٔ بین تلاشها را هر بار دو برابر کنید و دوباره ارسال کنید؛ اگر تکرار شد، آن را همراه با X-Request-Id از طریق راهنما و تماس با ما اطلاع دهید |
کد 402 برگردانده نمیشود. کمبود اعتبار و عبور از حد استفاده با کد 403 اعلام میشوند. بدنهٔ خطا قالب زیر را دارد و دلیل در error.message قرار میگیرد.
{"error":{"message":"API key is required.","type":"invalid_request_error"}}اگر سربرگ X-Request-Id را در درخواست قرار دهید، هنگام تماس، درخواست با همان مقدار پیگیری میشود. اگر آن را ارسال نکنید، سرور مقدار را ایجاد میکند.
مراحل بعدی
مقایسهٔ نتایج با تغییر نام مدل و پارامترها در محیط آزمایشی انجام میشود. ایجاد یا باطل کردن کلید، در صفحهٔ کلیدهای API انجام میشود. اسناد زیر را نیز مطالعه کنید.
- مدلها: فهرست کامل مدلها، مشخصات هر مدل و فراخوانیهای مجاز
- فراخوانی API: مسیر سازگار با Anthropic، مسیرهای embedding و صوت، و قوانین streaming
- کدهای خطا: جدول کامل کدهای وضعیت و قوانین تلاش مجدد
