Developer guide

เริ่มต้นอย่างรวดเร็ว

เริ่มต้นอย่างรวดเร็ว

เอกสารนี้ครอบคลุมตั้งแต่การออก API คีย์ของ CLEVI การส่งคำขอแรก ไปจนถึงการรับการตอบกลับ คุณสามารถเรียกใช้ cip-5.5-im และ cip-5.5-mm ด้วยที่อยู่หนึ่งรายการและคีย์หนึ่งรายการ โดยคำขอและการตอบกลับเป็นไปตามรูปแบบ OpenAI Chat Completions ดังนั้นเพียงเปลี่ยนสองค่า ได้แก่ base_url และ api_key ใน OpenAI SDK ที่คุณใช้อยู่ เส้นทางสำหรับ Anthropic SDK และเส้นทางสำหรับ Embedding กับเสียงอยู่ในเอกสารการเรียกใช้ API

การออก API คีย์

คีย์จะออกให้จากหน้าคีย์ API ในคอนโซล CLEVI Cloud คุณสามารถยกเลิกคีย์และจัดการขอบเขตการใช้งานได้จากหน้าเดียวกัน ทำตามขั้นตอนด้านล่างเพื่อรับคีย์หนึ่งรายการสำหรับใช้ส่งคำขอ

  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
รหัสโมเดลขนาดขีดจำกัดอินพุตเอาต์พุตสูงสุดงานที่เหมาะสม
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ใช่อาร์เรย์ของออบเจ็กต์ข้อความในการสนทนา อย่างน้อย 1 รายการ
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 หากอัปสตรีมส่งคืน 4xx·5xx ระบบจะส่งต่อรหัสดังกล่าวโดยตรง โปรดตรวจสอบวิธีรับมือในตารางด้านล่างก่อน และหากรหัสเดิมเกิดซ้ำ ให้เก็บเวลาที่ส่งคำขอ เนื้อหาที่ส่ง และ X-Request-Id ไว้

รหัสสถานะ HTTP
รหัสความหมายวิธีรับมือ
400เนื้อหาคำขอไม่ตรงตามรูปแบบตรวจสอบว่ามี model และ messages และ JSON ปิดครบถ้วน
401ไม่มีคีย์ หรือคีย์หมดอายุหรือถูกเพิกถอนแล้วตรวจสอบสถานะคีย์ในหน้าคีย์ API และตรวจสอบว่า Authorization header เริ่มต้นด้วย Bearer
403ไม่มีสิทธิ์เข้าถึงโมเดล ใช้เกินขีดจำกัด หรือเครดิตไม่เพียงพอตรวจสอบสาเหตุจาก error.message ขีดจำกัดดูได้ที่โควตาการใช้งานที่จัดสรรในภาพรวม ส่วนยอดคงเหลือและแพ็กเกจดูได้ที่แพ็กเกจและเครดิต
404ไม่มีโมเดล ไม่สามารถเข้าถึงโมเดลด้วยคีย์นี้ หรือไม่มีเส้นทางตรวจสอบว่ามีชื่อโมเดลอยู่ในการตอบกลับของ GET /models และที่อยู่ลงท้ายด้วย /api/v2/aiservice/openai/v1/chat/completions
429ผู้ให้บริการอัปสตรีมจำกัดอัตราการส่งคำขอหากมี Retry-After header ให้รอตามเวลานั้น หากไม่มี ให้เพิ่มช่วงเวลาระหว่างการลองใหม่เป็นสองเท่าทุกครั้งก่อนส่งอีกครั้ง
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

ภาษาและภูมิภาค

ภาษาที่แปลโดยเครื่องแปลจะถูกแปลโดย clevi/cip-5.5-im และมีการระบุว่าเป็นภาษาที่แปลโดยเครื่องแปล ใช้กับภาษาที่มีชุดเว็บไซต์เผยแพร่แล้ว

137 ภาษา

แนะนำ

1

เอเชียตะวันออก

7

เอเชียตะวันออกเฉียงใต้

11

เอเชียใต้

18

เอเชียกลาง

5

ตะวันออกกลางและคอเคซัส

10

ยุโรปตะวันตกและยุโรปใต้

17

สหราชอาณาจักรและไอร์แลนด์

4

ยุโรปเหนือ

10

ยุโรปกลางและบอลข่าน

14

ยุโรปตะวันออก

5

แอฟริกาตะวันออก

8

แอฟริกาตะวันตกและแอฟริกากลาง

9

แอฟริกาตอนใต้

8

อเมริกา

5

โอเชียเนีย

5