Xem nguồn schema, quy tắc tương thích, trường công khai và hợp đồng OpenAPI JSON chỉ đọc của Rivya API v1.

Rivya API v1 công bố hợp đồng schema chỉ đọc tại:

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

Route này là đầu ra hợp đồng công khai. Nó không đọc dữ liệu session người dùng, không gửi job mô hình và không để lộ dữ liệu tài khoản riêng tư.

Nguồn hợp đồng

Hợp đồng được suy ra từ:

schema yêu cầu API công khai
mã lỗi công khai
lớp tham chiếu mô hình API công khai
cùng catalog mô hình mà /api/v1/models sử dụng

Danh sách mô hình là động. Đừng xây dựng tích hợp phụ thuộc vào số lượng mô hình viết tay.

Chính sách phiên bản

Phiên bản API hiện tại là v1.

Thay đổi tương thích ngược có thể bao gồm:

thêm một mô hình vào /api/v1/models
thêm một trường phản hồi tùy chọn
thêm một tham số yêu cầu tùy chọn cho một mô hình
thêm một mã lỗi công khai mới

Thay đổi phá vỡ tương thích cần phiên bản mới hoặc đường di chuyển được ghi rõ.

Ranh giới trường công khai

Các trường schema công khai dùng tên công khai:

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

Đừng phụ thuộc vào trường lưu trữ tác vụ nội bộ. Chúng không thuộc hợp đồng công khai.

Request schema

POST /api/v1/generations chấp nhận:

model: public model ID bắt buộc
prompt: string tùy chọn, bắt buộc với nhiều mô hình
params: object tùy chọn với tham số riêng theo mô hình
client_request_id: string tùy chọn cho trace ID của bạn

Dùng Tham chiếu API mô hình cho params riêng theo mô hình.

Media tham chiếu được /api/v1/files trả về thuộc về params.referenceMediaItems. Schema ghi rõ url, kind, name tùy chọn, mimeType tùy chọn, durationSeconds tùy chọn và durationToken tùy chọn. Rivya không chấp nhận trường files cấp cao nhất trong POST /api/v1/generations.

POST /api/v1/files chấp nhận multipart form data với file, kind, model tùy chọn và client_request_id tùy chọn. Phản hồi là PublicApiFile. GET /api/v1/files/{fileId} trả về cùng metadata tệp công khai cho các tệp thuộc tài khoản API.

POST /api/v1/chat/completions chấp nhận model, message, session_id tùy chọn, các điều khiển tùy chọn, ảnh đính kèm file_id từ Files API và client_request_id tùy chọn. Endpoint này trả về một assistant message hoàn chỉnh không streaming.

POST /api/v1/chat/completions/stream chấp nhận cùng request schema và trả về text/event-stream với các sự kiện session.created, message.delta, message.completed, usage.completed, heartbeat, error và done. Chat API v1 không chấp nhận mảng raw messages.

Response schemas

OpenAPI output ghi nhận các cấu trúc phản hồi công khai này:

ModelList cho GET /api/v1/models
PublicApiModel và ModelParam cho lựa chọn mô hình và form tham số
PublicApiFile cho POST /api/v1/files và GET /api/v1/files/{fileId}
ReferenceMediaItem cho tham số generation dựa trên tệp
PublicGeneration cho phản hồi tạo và trạng thái
GenerationResult và GenerationError cho tác vụ đã hoàn tất
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits và schema sự kiện stream Chat cho Chat API
CreditBalance cho GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery và WebhookTestResult cho API webhooks có chữ ký
PublicApiError cho phản hồi lỗi ổn định

Schema này an toàn để dùng cho xác thực client và kiểm thử tích hợp nội bộ. TypeScript SDK beta tiếp tục bị ràng buộc bởi schema này.

Quản trị ví dụ

Các ví dụ curl, JavaScript và Python trong tài liệu này dùng cùng tên trường công khai như schema:

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

Ví dụ Chat còn dùng:

chat:create
chat:read
file_id

Ví dụ webhook còn dùng:

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

Khi tham số mô hình thay đổi, hãy cập nhật catalog mô hình và public serializer trước. Tài liệu và debugger nên tiêu thụ cùng lớp công khai đó thay vì sao chép một bảng riêng.

OpenAPI và hợp đồng schema