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 دریافت می‌کنید. در همان صفحه می‌توانید کلید را لغو کرده و محدوده استفاده را مدیریت کنید. با طی کردن مراحل زیر، یک کلید برای استفاده در درخواست‌ها دریافت می‌کنید.

  1. در https://platform.clevi.net/account/login وارد شوید یا حساب ایجاد کنید.
  2. در https://clevi.app/cloud یک workspace اضافه کنید.
  3. به https://clevi.app/cloud/keys بروید.
  4. یک کلید جدید ایجاد کنید و مقدار آن را کپی کنید.
  5. مقدار کپی‌شده را در متغیر محیطی ذخیره کنید.

کلید دریافت‌شده را جایگزین sk-... در مثال‌های این سند کنید. اگر آن را با دستور زیر در متغیر محیطی ذخیره کنید، می‌توانید مثال‌های بعدی را بدون تغییر کپی و اجرا کنید.

export CLEVI_API_KEY="sk-..."

انتخاب مدل

نام‌های زیر را عیناً در فیلد model بدنه درخواست وارد کنید. هر دو مدل از یک آدرس و یک قالب درخواست یکسان استفاده می‌کنند و ورودی‌های متنی و تصویری را می‌پذیرند.

  • cip-5.5-im
  • cip-5.5-mm
شناسه مدلاندازهمحدودیت ورودیحداکثر خروجیکارهای مناسب
cip-5.5-im360B256K64Kکارهایی با هدف و محدوده مشخص. سرعت پاسخ و توان عملیاتی در اولویت است.
cip-5.5-mm800B512K64Kکارهای پیچیده‌ای که چندین منبع و شرط را ترکیب می‌کنند. برای تحلیل زمینه‌های طولانی و عامل‌های چندمرحله‌ای استفاده می‌شود.

مدل‌هایی که واقعاً می‌توانید از حساب خود فراخوانی کنید، بر اساس فهرست مدل‌های 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 در اولویت قرار می‌گیرد.

پارامترهای درخواست
نامنوعالزامیتوضیحات
modelstringبلهcip-5.5-im یا cip-5.5-mm
messagesarrayبلهآرایه‌ای از اشیای پیام گفتگو. حداقل ۱ مورد
messages[].rolestringبلهیکی از system · user · assistant
messages[].contentstringبلهمتن پیام
streambooleanخیراگر true باشد، پاسخ را به‌صورت قطعه‌های Server-Sent Events دریافت می‌کنید
max_tokensintegerخیرحداکثر تعداد توکن‌هایی که در پاسخ تولید می‌شود
temperaturenumberخیرهرچه مقدار بیشتر باشد، احتمال دریافت پاسخ‌های متفاوت برای یک درخواست بیشتر می‌شود
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 را ثبت کنید.

کد وضعیت HTTP
کدمعناراهکار
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
  • کدهای خطا: جدول کامل کدهای وضعیت و قوانین تلاش مجدد

باز کردن محیط آزمایشی

مدیریت کلیدهای API

CLEVI

زبان و منطقه

زبان‌های ترجمه‌شده با ماشین علامت‌گذاری شده‌اند. دسترس‌پذیری بر اساس بسته منتشرشده سایت است.

۱۳۶ زبان

پیشنهادی

1

شرق آسیا

7

جنوب شرق آسیا

11

جنوب آسیا

18

آسیای مرکزی

5

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

10

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

16

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

4

شمال اروپا

10

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

14

شرق اروپا

5

شرق افریقا

8

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

9

جنوب افریقا

8

امریکا

5

اقیانوسیه

5