ตรวจแหล่งที่มาของ schema, compatibility rules, public fields และ read-only OpenAPI JSON contract ของ Rivya API v1

Rivya API v1 เปิดเผย schema contract แบบ read-only ที่:

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

route นี้เป็นผลลัพธ์ของ public contract ไม่อ่านข้อมูล user session, ไม่ส่ง model jobs และไม่เปิดเผยข้อมูลบัญชีส่วนตัว

แหล่งที่มาของ Contract

contract มาจาก:

schema คำขอของ public API
รหัสข้อผิดพลาดสาธารณะ
เลเยอร์ reference โมเดลของ public API
model catalog ชุดเดียวกับที่ /api/v1/models ใช้

model list เป็น dynamic อย่าสร้าง integrations ที่พึ่งจำนวนโมเดลแบบเขียนด้วยมือ

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

API version ปัจจุบันคือ v1

การเปลี่ยนแปลงที่ backward-compatible อาจรวมถึง:

เพิ่ม model ใน /api/v1/models
เพิ่ม optional response field
เพิ่ม optional request parameter สำหรับโมเดล
เพิ่ม public error code ใหม่

breaking changes ต้องมี version ใหม่หรือ migration path ที่บันทึกไว้

ขอบเขต Public Field

public schema fields ใช้ชื่อสาธารณะ:

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

อย่าพึ่ง internal task storage fields เพราะไม่ได้เป็นส่วนหนึ่งของ public contract

Schema ของคำขอ

POST /api/v1/generations รับ:

model: public model ID ที่จำเป็น
prompt: string แบบ optional แต่หลายโมเดลต้องใช้
params: object แบบ optional สำหรับ parameters เฉพาะโมเดล
client_request_id: string แบบ optional สำหรับ trace ID ของคุณเอง

ใช้ Model API Reference สำหรับ params เฉพาะโมเดล

reference media ที่ /api/v1/files คืนมาต้องอยู่ใน params.referenceMediaItems schema ระบุ url, kind, optional name, optional mimeType, optional durationSeconds และ optional durationToken Rivya ไม่รับ field files ระดับบนสุดใน POST /api/v1/generations

POST /api/v1/files รับ multipart form data พร้อม file, kind, optional model และ optional client_request_id response คือ PublicApiFile ส่วน GET /api/v1/files/{fileId} คืน file metadata สาธารณะชุดเดียวกันสำหรับไฟล์ที่ API account เป็นเจ้าของ

POST /api/v1/chat/completions รับ model, message, optional session_id, optional controls, optional Files API file_id attachments และ optional client_request_id โดยคืน assistant message แบบ non-streaming ที่สมบูรณ์หนึ่งรายการ

POST /api/v1/chat/completions/stream รับ request schema เดียวกันและคืน text/event-stream พร้อม events session.created, message.delta, message.completed, usage.completed, heartbeat, error และ done Chat API v1 ไม่รับ raw messages array

Schema ของ Response

OpenAPI output บันทึก public response shapes เหล่านี้:

ModelList สำหรับ GET /api/v1/models
PublicApiModel และ ModelParam สำหรับ model selection และ parameter forms
PublicApiFile สำหรับ POST /api/v1/files และ GET /api/v1/files/{fileId}
ReferenceMediaItem สำหรับ generation parameters ที่อิงไฟล์
PublicGeneration สำหรับ create และ status responses
GenerationResult และ GenerationError สำหรับ tasks ที่เสร็จแล้ว
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits และ Chat stream event schemas สำหรับ Chat API
CreditBalance สำหรับ GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery และ WebhookTestResult สำหรับ signed API webhooks
PublicApiError สำหรับ stable error responses

schema นี้ปลอดภัยสำหรับ client validation และ internal integration tests ส่วน TypeScript SDK beta ยังคงถูกจำกัดด้วย schema นี้

ตัวอย่าง governance

ตัวอย่าง curl, JavaScript และ Python ใน docs เหล่านี้ใช้ public field names ชุดเดียวกับ schema:

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

เมื่อ model parameter เปลี่ยน ให้อัปเดต model catalog และ public serializer ก่อน docs และ debugger ควรใช้ public layer ชุดเดียวกัน แทนการคัดลอกตารางแยกอีกชุด

OpenAPI และ Schema Contract