Developer guide

การเรียกใช้ API

เส้นทางที่เข้ากันได้กับ API และกฎการสตรีม·เสียง

เส้นทางการเรียกใช้ของเกตเวย์ CLEVI แบ่งออกเป็นข้อกำหนดที่เข้ากันได้กับ OpenAI และข้อกำหนดที่เข้ากันได้กับ Anthropic
ทั้งสองข้อกำหนดใช้คีย์ API เดียวกัน และสามารถเรียกใช้โมเดลการอนุมานแบบสนทนาได้ด้วยข้อกำหนดใดก็ได้
เส้นทางการสร้างเวกเตอร์ฝังตัวและเส้นทางเสียง·วอยซ์มีเฉพาะในข้อกำหนดที่เข้ากันได้กับ OpenAI เท่านั้น
ส่วนข้อกำหนดที่เข้ากันได้กับ Anthropic มีเส้นทาง messages, count_tokens และ models

เปิดใช้การสตรีมด้วย stream ในเนื้อหาคำขอ และไม่รองรับการฝังตัวและโมเดล·เส้นทางบางส่วน เส้นทางเสียง·วอยซ์ปฏิบัติตามกฎที่แตกต่างจากการอนุมานทั่วไป เช่น ส่งคืนเสียงโดยตรงและจัดเก็บผลลัพธ์ไว้ใน CleviDrive เป็นเวลา 3 วัน

ID โมเดลและการเรียกใช้ที่อนุญาตสำหรับแต่ละโมเดลอยู่ในหน้าของโมเดล ส่วนส่วนหัวการยืนยันตัวตนและ base URL อยู่ในหน้าการยืนยันตัวตนด้วยคีย์ API

การเลือกเส้นทาง

เลือกเส้นทางตามสิ่งที่คุณต้องการทำและ SDK ที่ใช้งานอยู่ เส้นทางในตารางคือเส้นทางสัมพัทธ์ที่ต่อท้าย base URL ของแต่ละข้อกำหนด

สิ่งที่ต้องการทำ	ข้อกำหนด	เส้นทาง
การอนุมานแบบสนทนา ใช้ OpenAI SDK	เข้ากันได้กับ OpenAI	POST /chat/completions หรือ POST /responses
การอนุมานแบบสนทนา ใช้ Anthropic SDK	เข้ากันได้กับ Anthropic	POST /v1/messages
การสร้างเวกเตอร์ฝังตัว	เข้ากันได้กับ OpenAI	POST /embeddings
การสังเคราะห์·ถอดเสียง การจัดการวอยซ์	เข้ากันได้กับ OpenAI	เส้นทางภายใต้ /audio และ /voices
ตรวจสอบโมเดลที่สามารถเรียกใช้ได้	ทั้งสองแบบ	GET /models

เส้นทางที่เข้ากันได้กับ OpenAI

base URL ของข้อกำหนดที่เข้ากันได้กับ OpenAI คือ https://platform.clevi.net/api/v2/aiservice/openai/v1 เนื้อหาคำขอและการตอบกลับเป็นไปตามข้อกำหนดของ OpenAI ตารางด้านล่างแสดงเส้นทางทั้งหมดตามโฮสต์สำหรับเส้นทางการอนุมานและโมเดล ส่วนเส้นทางเสียง·วอยซ์สรุปไว้ในส่วนเส้นทางเสียงและวอยซ์ด้านล่าง

เมธอด	เส้นทาง	คำอธิบาย
POST	/api/v2/aiservice/openai/v1/chat/completions	ส่งคำขอการอนุมานแบบสนทนา หากเปิดใช้ stream ระบบจะตอบกลับผ่าน SSE
POST	/api/v2/aiservice/openai/v1/responses	เรียกใช้งานตามข้อกำหนด Responses รองรับ stream
GET	/api/v2/aiservice/openai/v1/responses/{responseId}	ดึงข้อมูลการตอบกลับที่จัดเก็บไว้ 1 รายการ
GET	/api/v2/aiservice/openai/v1/responses/{responseId}/input_items	ดึงรายการอินพุตของการตอบกลับที่จัดเก็บไว้
POST	/api/v2/aiservice/openai/v1/responses/{responseId}/cancel	ยกเลิกการตอบกลับที่กำลังดำเนินการอยู่เบื้องหลัง
DELETE	/api/v2/aiservice/openai/v1/responses/{responseId}	ลบการตอบกลับที่จัดเก็บไว้
POST	/api/v2/aiservice/openai/v1/completions	ส่งคำขอการเติมข้อความแบบเดิม รองรับ stream
POST	/api/v2/aiservice/openai/v1/embeddings	สร้าง embeddings ไม่รองรับการสตรีม
GET	/api/v2/aiservice/openai/v1/models	ส่งคืนรายการโมเดลที่สามารถเรียกใช้งานด้วยคีย์นี้ได้
GET	/api/v2/aiservice/openai/v1/models/{modelId}	ดึงข้อมูลโมเดล 1 รายการ หากไม่สามารถเข้าถึงโมเดลได้ ระบบจะส่งคืน 404

นี่คือตัวอย่างขั้นต่ำสำหรับเรียกใช้ chat/completions แทนที่ sk-... ด้วยคีย์ที่ออกให้จากหน้าคีย์ API และใส่ ID จากหน้ารุ่นโมเดลในช่อง model

Bash

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions \
  -H "X-API-Key: sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cip-5.5-im",
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'

เส้นทางอื่นๆ

เส้นทางต่อไปนี้มีไว้สำหรับการวินิจฉัย ความเข้ากันได้กับระบบเดิม และการส่งต่อ

เส้นทาง	คำอธิบาย
GET /api/v2/aiservice/openai/v1/healthz	ตรวจสอบสถานะของ provider เสียง
/api/v2/aiservice/openai/v1/api/status · /api/options · /api/generate · /outputs/{filename}	เส้นทางสำหรับตรวจสอบสถานะและตัวเลือกของ Cosa รุ่นเก่า เรียกใช้การสร้าง (multipart) และดาวน์โหลดผลลัพธ์
/api/v2/aiservice/openai/v1/{routeKey} (GET · POST · PUT · PATCH · DELETE)	ถ่ายทอดเส้นทางของ provider ที่ไม่มีอยู่ในตารางด้านบนโดยใช้กฎที่กำหนด เส้นทาง chat/completions, completions, embeddings และ responses ดำเนินการโดยเส้นทางเฉพาะ จึงจะส่งคืน 404 หากเรียกใช้ผ่านการถ่ายทอด POST

สามารถตรวจสอบฟิลด์ทั้งหมดของคำขอและการตอบกลับได้ในเอกสาร OpenAPI 3.0 https://platform.clevi.net/api/v2/console/openapi/cloud-inference-v1 รายการเส้นทางสร้างขึ้นจากเอกสารนี้ และเอกสารจะเปิดได้เฉพาะผ่านเซสชันที่เข้าสู่ระบบคอนโซลเท่านั้น คุณสามารถสร้างไคลเอ็นต์จากเอกสารเดียวกันนี้ได้

เส้นทางที่เข้ากันได้กับ Anthropic

base URL ของข้อกำหนดที่เข้ากันได้กับ Anthropic คือ https://platform.clevi.net/api/v2/aiservice/anthropic และ Anthropic SDK จะเพิ่ม /v1 ลงในเส้นทางคำขอโดยตรง เนื้อหาคำขอและการตอบกลับเป็นไปตามข้อกำหนด Anthropic Messages

เมธอด	เส้นทาง	คำอธิบาย
POST	/api/v2/aiservice/anthropic/v1/messages	เรียกใช้ตามข้อกำหนด Messages โดยต้องระบุ model, messages และ max_tokens และรองรับ stream
POST	/api/v2/aiservice/anthropic/v1/messages/count_tokens	ประมาณจำนวนโทเค็นอินพุตเท่านั้นโดยไม่มีค่าใช้จ่าย ไม่จำเป็นต้องระบุ max_tokens
GET	/api/v2/aiservice/anthropic/v1/models	ส่งคืนรายการโมเดลด้วยวิธีการแบ่งหน้าโดยใช้เคอร์เซอร์ ค่า limit อยู่ระหว่าง 1~1000 และหากอยู่นอกช่วงจะส่งคืน 400
GET	/api/v2/aiservice/anthropic/v1/models/{modelId}	เรียกดูโมเดล 1 รายการ หากไม่สามารถเข้าถึงโมเดลได้ จะส่งคืน 404

ตัวอย่างขั้นต่ำสำหรับการเรียกใช้ messages

Bash

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/messages \
  -H "X-API-Key: sk-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cip-5.5-im",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'

หากละเว้นส่วนหัว anthropic-version ระบบจะถือว่าเป็น 2023-06-01 เกตเวย์จะส่งต่อส่วนหัว anthropic-version และ anthropic-beta ตามเดิม

การสตรีม (SSE)

เมื่อตั้งค่า stream เป็น true ในเนื้อหาคำขอ เซิร์ฟเวอร์จะตอบกลับเป็น Server-Sent Events การรองรับจะแตกต่างกันตามเส้นทางและโมเดลดังต่อไปนี้

เป้าหมาย	การทำงาน
OpenAI ที่เข้ากันได้ POST /chat/completions · POST /completions · POST /responses	รองรับ stream
Anthropic ที่เข้ากันได้ POST /v1/messages	รองรับ stream
POST /embeddings	ไม่รองรับการสตรีม
โมเดลกลุ่มการค้นหาของ Ivy (เช่น ivy-4-mm-search)	แม้จะเปิด stream เซิร์ฟเวอร์จะปิดใช้งานและตอบกลับทั้งหมดในครั้งเดียว
GET /responses/{responseId}?stream=true	ส่งคืน 400 เส้นทางนี้ถูกปิดไว้จนกว่าจะสามารถวัดปริมาณการใช้งานของการตอบกลับเบื้องหลังได้อย่างถูกต้องเพียงครั้งเดียว

เซิร์ฟเวอร์จะส่งส่วนหัวสามรายการต่อไปนี้พร้อมกับชังก์แรก หลังจากนั้นจะส่งบรรทัด data: ในแต่ละชังก์และ flush ทันที โดยจะส่งบรรทัด event: มาพร้อมกันเฉพาะเมื่ออัปสตรีมให้ชื่อเหตุการณ์มาเท่านั้น

Content-Type: text/event-stream
Cache-Control: no-cache
X-Accel-Buffering: no

ชังก์ของเส้นทางที่เข้ากันได้กับ Anthropic จะจับคู่บรรทัด event กับบรรทัด data

텍스트

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"안"}}

ชังก์ของ chat/completions จะมาในรูปแบบบรรทัด data และส่งต่อ data: [DONE] ตามเดิมในตอนท้าย

텍스트

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[...]}

data: [DONE]

หากเกิดข้อผิดพลาดระหว่างการสตรีม ระบบจะส่ง JSON ข้อผิดพลาดเช่นเดียวกับการเรียกใช้ทั่วไปในบรรทัด data: เดียว และรหัสสถานะ HTTP จะเปลี่ยนแปลงไปพร้อมกัน

เส้นทางเสียงและวอยซ์

เส้นทาง TTS·STT และการจัดการวอยซ์ของ Cosa อยู่ในข้อกำหนดที่เข้ากันได้กับ OpenAI และมีกฎบางประการที่แตกต่างจากการอนุมานทั่วไป โปรดตรวจสอบในตาราง Cosa ของหน้าโมเดลว่าโมเดลใดอนุญาตให้ใช้เส้นทางใด

เมธอด	เส้นทาง	คำอธิบาย
POST	/api/v2/aiservice/openai/v1/audio/speech	สังเคราะห์ข้อความเป็นเสียงและส่งคืนเสียงโดยตรง
POST	/api/v2/aiservice/openai/v1/audio/transcriptions	ถอดเสียงเป็นข้อความ (multipart)
POST	/api/v2/aiservice/openai/v1/audio/speech/clone	สังเคราะห์เสียงด้วยวอยซ์ที่โคลน (multipart)
GET	/api/v2/aiservice/openai/v1/voices	ส่งคืนรายการวอยซ์ที่ผู้เรียกใช้สามารถใช้งานได้
POST	/api/v2/aiservice/openai/v1/voices	ลงทะเบียนวอยซ์จากตัวอย่างเสียง (multipart)
POST	/api/v2/aiservice/openai/v1/voices/design	สร้างวอยซ์สังเคราะห์จากคำอธิบาย
DELETE	/api/v2/aiservice/openai/v1/voices/{voiceId}	ลบวอยซ์ เฉพาะเจ้าของเท่านั้นที่สามารถลบได้

กฎต่อไปนี้ใช้กับเส้นทางเสียงและวอยซ์เท่านั้น

กฎ	เนื้อหา
การส่งไบนารี	การตอบกลับสำเร็จของ audio/speech, audio/speech/clone และ outputs/{filename} จะส่งไฟล์เสียงโดยตรงพร้อมบันทึกลงใน CleviDrive
ส่วนหัวใบเสร็จ	รวมส่วนหัว X-Clevi-Drive-File-Id, X-Clevi-Drive-File-Version-Id, X-Clevi-Drive-Download-Url, X-Clevi-Drive-Expires-At, X-Clevi-Drive-Retention-Days: 3 ไว้ในการตอบกลับ
การเลือก Product	audio/speech และ audio/transcriptions ใช้ model ในเนื้อหาคำขอเพื่อเลือก Product เส้นทางเสียงและการวินิจฉัยต้องใช้ส่วนหัว X-Product-Sku หรือคำค้น product_sku
สิทธิ์ความเป็นเจ้าของเสียง	เสียงที่โคลนหรือลงทะเบียนจะเป็นของผู้สร้าง หากพยายามสังเคราะห์หรือลบเสียงของเจ้าของรายอื่น ระบบจะส่งคืน 403 และรายการ GET /voices จะรวมเฉพาะเสียงของผู้ใช้เอง
ขนาดและเวลา	ขนาดคำขอสูงสุดคือ 28 MiB และระยะเวลาจำกัดของการเรียกอัปสตรีมคือ 5 นาที
ความแออัดของ provider	หากอัปสตรีมมีความแออัด ระบบจะส่งต่อ 409 โดยตรง และหากมี Retry-After ก็จะส่งต่อค่านั้นไปพร้อมกัน เกตเวย์จะไม่ลองใหม่หรือใส่ลงคิว

การเรียกใช้ API

การเลือกเส้นทาง

เส้นทางที่เข้ากันได้กับ OpenAI

เส้นทางอื่นๆ

เส้นทางที่เข้ากันได้กับ Anthropic

การสตรีม (SSE)

เส้นทางเสียงและวอยซ์

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

แนะนำ

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

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

เอเชียใต้

เอเชียกลาง

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

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

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

ยุโรปเหนือ

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

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

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

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

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

อเมริกา

โอเชียเนีย