ตรวจแหล่งที่มาของโครงสร้างข้อมูล กฎความเข้ากันได้ ฟิลด์สาธารณะ และสัญญา OpenAPI JSON แบบอ่านอย่างเดียวของ Rivya API v1

Rivya API v1 เปิดเผยสัญญาโครงสร้างข้อมูลแบบอ่านอย่างเดียวที่:

https://rivya.ai/api/v1/openapi.json

เส้นทางนี้เป็นผลลัพธ์ของสัญญาสาธารณะ ไม่อ่านข้อมูลเซสชันผู้ใช้ ไม่ส่งงานไปยังโมเดล และไม่เปิดเผยข้อมูลบัญชีส่วนตัว

แหล่งที่มาของสัญญา

สัญญานี้มาจาก:

โครงสร้างคำขอของ API สาธารณะ
รหัสข้อผิดพลาดสาธารณะ
ชั้นข้อมูลอ้างอิงโมเดลของ API สาธารณะ
แค็ตตาล็อกโมเดลชุดเดียวกับที่ /api/v1/models ใช้

รายการโมเดลเปลี่ยนแปลงได้ จึงไม่ควรสร้างระบบเชื่อมต่อที่พึ่งจำนวนโมเดลแบบกำหนดตายตัว

นโยบายเวอร์ชัน

เวอร์ชัน API ปัจจุบันคือ v1

การเปลี่ยนแปลงที่เข้ากันได้กับเวอร์ชันก่อนหน้าอาจรวมถึง:

เพิ่มโมเดลใน /api/v1/models
เพิ่มฟิลด์คำตอบแบบไม่บังคับ
เพิ่มพารามิเตอร์คำขอแบบไม่บังคับสำหรับโมเดล
เพิ่มรหัสข้อผิดพลาดสาธารณะใหม่

การเปลี่ยนแปลงที่ไม่เข้ากันต้องใช้เวอร์ชันใหม่หรือมีเส้นทางย้ายระบบที่บันทึกไว้

ขอบเขตฟิลด์สาธารณะ

ฟิลด์ในโครงสร้างสาธารณะใช้ชื่อดังต่อไปนี้:

id
status
model
session_id
message
usage
reserved_credits
final_credits
created_at
updated_at
result
error

อย่าพึ่งพาฟิลด์ภายในที่ใช้จัดเก็บข้อมูลงาน เพราะฟิลด์เหล่านั้นไม่ได้เป็นส่วนหนึ่งของสัญญา API สาธารณะ

โครงสร้างคำขอ

POST /api/v1/generations รับ:

model: รหัสโมเดลสาธารณะที่จำเป็น
prompt: สตริงที่ไม่บังคับ แต่หลายโมเดลจำเป็นต้องใช้
params: ออบเจ็กต์ที่ไม่บังคับสำหรับพารามิเตอร์เฉพาะโมเดล
client_request_id: สตริงที่ไม่บังคับสำหรับรหัสติดตามของคุณเอง

ใช้ เอกสารอ้างอิง API ของแต่ละโมเดล สำหรับ params เฉพาะโมเดล

สื่ออ้างอิงที่ /api/v1/files คืนมาต้องอยู่ในสคีมา params.referenceMediaItems ซึ่งระบุ url, kind และฟิลด์ที่เลือกส่งได้ ได้แก่ name, mimeType, durationSeconds / durationToken, width / height / sizeBytes / imageDimensionsToken รวมถึง framesPerSecond / videoBitrateMbps / videoMetadataToken รูปภาพอ้างอิงของ Image5, Grok Imagine Image 2.0 และ Wan 3.0 ทุกรูปต้องใช้โทเคนรูปภาพที่ลงลายเซ็นและขนาดไฟล์เป็นไบต์จากคำตอบการอัปโหลดเดิมที่ผูกกับโมเดล ส่วน Layer Decomposition ยังบังคับใช้ขีดจำกัดทางเรขาคณิตที่ระบุไว้ วิดีโออ้างอิงของ Video8 และ Wan 3.0 ทุกรายการต้องใช้โทเคนระยะเวลาที่ลงลายเซ็นและข้อมูลกำกับวิดีโอที่ลงลายเซ็นจากคำตอบการอัปโหลดเดิมที่ผูกกับโมเดล Rivya ไม่รับฟิลด์ files ที่ระดับบนสุดของ POST /api/v1/generations

POST /api/v1/files รับข้อมูลฟอร์มหลายส่วนแบบ multipart/form-data พร้อม file, kind และฟิลด์ที่เลือกส่งได้คือ model กับ client_request_id คำตอบเป็น PublicApiFile ซึ่งมี size_bytes, มิติรูปภาพที่อาจเป็นค่าว่าง, image_dimensions_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes และ video_metadata_token ที่อาจเป็นค่าว่าง ส่วน GET /api/v1/files/{fileId} คืนข้อมูลกำกับสาธารณะของไฟล์ที่บัญชี API เป็นเจ้าของ แต่โทเคนข้อมูลกำกับที่ลงลายเซ็นและไม่ได้จัดเก็บไว้อาจเป็น null จึงต้องอัปโหลดไฟล์ใหม่

video_metadata_token ผูกกับบัญชี API โมเดลเป้าหมาย URL ชนิด MIME มิติ อัตราเฟรม บิตเรต และขนาดไฟล์เป็นไบต์ โทเคนนี้ใช้แทน duration_token ไม่ได้ วิดีโออ้างอิงของ Video8 และ Wan 3.0 ที่ใช้สัญญาทั้งสองแบบต้องส่งโทเคนทั้งคู่ ส่วนโทเคนระยะเวลาของเสียงใน Wan 3.0 ยังผูกกับชนิด MIME และขนาดไฟล์เป็นไบต์ด้วย

สำหรับ wan-3-0-video นั้น params รับเฉพาะ seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed และ referenceMediaItems โหมดข้อความ เฟรม และอ้างอิงเลือกได้เพียงโหมดเดียว ระยะเวลาอัจฉริยะใช้ค่า -1 มีค่าทดแทน 30 วินาที และใช้กับวิดีโออ้างอิงไม่ได้ ฟิลด์อื่น สื่อที่ไม่มีลายเซ็น และทางลัด file-to-video หรือ link-to-video จะถูกปฏิเสธโดยไม่ใช้การประมวลผลสำรอง

POST /api/v1/chat/completions รับ model, message และฟิลด์ที่เลือกส่งได้ ได้แก่ session_id, ตัวควบคุมต่างๆ, ไฟล์แนบ file_id จาก Files API และ client_request_id โดยคืนข้อความตอบกลับจากผู้ช่วยแบบไม่สตรีมที่สมบูรณ์หนึ่งรายการ

POST /api/v1/chat/completions/stream รับสคีมาคำขอเดียวกัน และคืน text/event-stream พร้อมเหตุการณ์ session.created, message.delta, message.completed, usage.completed, heartbeat, error และ done โดย Chat API v1 ไม่รับอาร์เรย์ messages แบบดิบ

สคีมาของคำตอบ

OpenAPI ระบุรูปแบบคำตอบสาธารณะดังต่อไปนี้:

ModelList สำหรับ GET /api/v1/models
PublicApiModel และ ModelParam สำหรับการเลือกโมเดลและแบบฟอร์มพารามิเตอร์
PublicApiFile สำหรับ POST /api/v1/files และ GET /api/v1/files/{fileId}
ReferenceMediaItem สำหรับพารามิเตอร์การสร้างที่อิงกับไฟล์
PublicGeneration สำหรับคำตอบเมื่อสร้างและตรวจสถานะ
GenerationResult และ GenerationError สำหรับงานที่เสร็จแล้ว
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits และสคีมาเหตุการณ์สตรีมของแชตสำหรับ Chat API
CreditBalance สำหรับ GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery และ WebhookTestResult สำหรับเว็บฮุก API ที่ลงลายเซ็น
PublicApiError สำหรับคำตอบข้อผิดพลาดที่มีรูปแบบคงที่

โครงสร้างนี้ใช้ตรวจสอบข้อมูลฝั่งไคลเอนต์และทดสอบการเชื่อมต่อภายในได้อย่างปลอดภัย ส่วน TypeScript SDK รุ่นทดสอบยังคงยึดตามโครงสร้างนี้

ตัวอย่างการกำกับสัญญา

ตัวอย่าง curl, JavaScript และ Python ในเอกสารเหล่านี้ใช้ชื่อฟิลด์สาธารณะชุดเดียวกับโครงสร้าง:

Authorization: Bearer rvya_sk_...
Idempotency-Key
model
prompt
message
session_id
params
client_request_id

ตัวอย่าง Chat ใช้เพิ่มเติม:

chat:create
chat:read
file_id

ตัวอย่าง Webhook ใช้เพิ่มเติม:

Rivya-Webhook-Signature
Rivya-Webhook-Timestamp
webhooks:manage

เมื่อพารามิเตอร์ของโมเดลเปลี่ยน ให้อัปเดตแค็ตตาล็อกโมเดลและตัวแปลงข้อมูลสาธารณะก่อน เอกสารและเครื่องมือดีบักควรใช้ชั้นข้อมูลสาธารณะชุดเดียวกัน แทนการคัดลอกตารางแยกอีกชุด

สัญญาและโครงสร้าง OpenAPI