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 คุณสามารถยกเลิกคีย์และจัดการขอบเขตการใช้งานได้จากหน้าเดียวกัน ทำตามขั้นตอนด้านล่างเพื่อรับคีย์หนึ่งรายการสำหรับใช้ส่งคำขอ
- เข้าสู่ระบบหรือสร้างบัญชีที่ https://platform.clevi.net/account/login
- เพิ่มเวิร์กสเปซที่ https://clevi.app/cloud
- ไปที่ 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 | ใช่ | อาร์เรย์ของออบเจ็กต์ข้อความในการสนทนา อย่างน้อย 1 รายการ |
| 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 หากอัปสตรีมส่งคืน 4xx·5xx ระบบจะส่งต่อรหัสดังกล่าวโดยตรง โปรดตรวจสอบวิธีรับมือในตารางด้านล่างก่อน และหากรหัสเดิมเกิดซ้ำ ให้เก็บเวลาที่ส่งคำขอ เนื้อหาที่ส่ง และ X-Request-Id ไว้
| รหัส | ความหมาย | วิธีรับมือ |
|---|---|---|
| 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 เส้นทางสำหรับการฝังเวกเตอร์และเสียง และกฎการสตรีม
- รหัสข้อผิดพลาด: ตารางรหัสสถานะทั้งหมดและกฎการลองใหม่