Жылдам бастау

Бұл құжат CLEVI API кілтін алып, алғашқы сұрауды жіберіп, жауап алғанға дейінгі қадамдарды қамтиды. Бір мекенжай және бір кілт арқылы cip-5.5-im мен cip-5.5-mm модельдерін шақырасыз. Сұраулар мен жауаптар OpenAI Chat Completions пішіміне сәйкес келеді, сондықтан қолданыстағы OpenAI SDK ішінде тек base_url және api_key мәндерін өзгерту жеткілікті. Anthropic SDK жолы және эмбеддинг пен дауысқа арналған жолдар API шақыру құжатында берілген.

API кілтін алу

Кілт CLEVI Cloud консоліндегі API кілттері бетінде жасалады. Сол бетте кілтті жоюға және оның пайдалану ауқымын басқаруға болады. Төмендегі ретпен орындасаңыз, сұрауларда пайдаланылатын бір кілт аласыз.

1. https://platform.clevi.net/account/login мекенжайында жүйеге кіріңіз немесе тіркелгі жасаңыз.
2. https://clevi.app/cloud мекенжайында жұмыс кеңістігін қосыңыз.
3. https://clevi.app/cloud/keys мекенжайына өтіңіз.
4. Жаңа кілтті алып, мәнін көшіріңіз.
5. Көшірілген мәнді орта айнымалысында сақтаңыз.

Осы құжаттағы мысалдарда sk-... орнына алған кілтіңізді қойыңыз. Оны төмендегі пәрмен арқылы орта айнымалысында сақтасаңыз, кейінгі мысалдарды сол күйінде көшіріп орындауға болады.

export CLEVI_API_KEY="sk-..."

Модельді таңдау

Сұрау денесінің model өрісіне төмендегі атауларды өзгеріссіз енгізіңіз. Екі модель де бір мекенжай мен бірдей сұрау пішімін пайдаланады және мәтін мен кескіндерді кіріс ретінде қабылдайды.

• cip-5.5-im
• cip-5.5-mm

Тіркелгіңізден нақты шақыруға болатын модельдер тізімі плейграундтағы модельдер тізімі мен GET /models жауабына негізделеді. Толық модельдер тізімі және әр модельге рұқсат етілген шақырулар модельдер құжатында, ал күтілетін шегерілетін кредит мөлшері консольдегі пайдалану бетінде көрсетілген.

POST /api/v2/aiservice/openai/v1/chat/completions

Хабарлар массиві мен модель атауын қабылдап, модель жасаған хабарды choices массивіне салып қайтарады. Толық мекенжайы — https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions . Сұрау денесі application/json пішімінде болады, ал аутентификация үшін Authorization тақырыбына Bearer префиксі мен кілт енгізіледі. Кілтті X-API-Key тақырыбы арқылы да жіберуге болады; екі тақырып та көрсетілсе, X-API-Key мәні басым қолданылады.

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 арқылы шақыру

OpenAI SDK ішіндегі base_url мәнін https://platform.clevi.net/api/v2/aiservice/openai/v1 мәніне өзгертіп, api_key параметріне CLEVI кілтін енгізіңіз. Қалған шақыру кодын өзгертпей қалдырыңыз.

# 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 тақырыптары келеді, ал кейінгі әр фрагментте data: жолында chat.completion.chunk нысаны қамтылады. Соңғы жол — 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 мәнін сақтап қойыңыз.

402 қайтарылмайды. Кредиттің жеткіліксіздігі мен пайдалану шегінен асу 403 ретінде келеді. Қате денесі төмендегі пішімде болады, ал себеп error.message ішінде беріледі.

{"error":{"message":"API key is required.","type":"invalid_request_error"}}

Сұрауға X-Request-Id тақырыбын қоссаңыз, қолдау қызметіне хабарласқан кезде осы мән арқылы бақылауға болады. Жібермесеңіз, оны сервер береді.

Келесі қадам

Модель атаулары мен параметрлерін өзгертіп, нәтижелерді салыстыру үшін Playground пайдаланылады. Кілттерді жасау немесе жою үшін API кілттері экраны пайдаланылады. Әрі қарай оқуға болатын құжаттар:

• Модельдер: барлық модельдердің тізімі, модель сипаттамалары және рұқсат етілген шақырулар
• API шақыру: Anthropic үйлесімді жолы, ендіру және дауыс жолдары, ағынмен жіберу ережелері
• Қате кодтары: барлық күй кодтарының кестесі және қайта әрекет жасау ережелері

Playground ашу

API кілттерін басқару