Xem các 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. Route không đọc dữ liệu phiên của người dùng, không gửi tác vụ 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 của API công khai
mã lỗi công khai
lớp tham chiếu mô hình API công khai
cùng danh mục mô hình mà /api/v1/models sử dụng

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

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 một phiên bản mới hoặc lộ trình chuyển đổi đượ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

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

Schema yêu cầu

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

model: ID mô hình công khai, bắt buộc
prompt: chuỗi tùy chọn, bắt buộc với nhiều mô hình
params: đối tượng tùy chọn chứa tham số dành riêng cho mô hình
client_request_id: chuỗi tùy chọn dùng làm ID theo dõi của bạn

Dùng Tài liệu tham chiếu API mô hình để biết params dành riêng cho từng mô hình.

Nội dung tham chiếu do /api/v1/files trả về phải nằm trong params.referenceMediaItems. Schema ghi rõ url, kind, name tùy chọn, mimeType tùy chọn, durationSeconds / durationToken tùy chọn, width / height / sizeBytes / imageDimensionsToken tùy chọn và framesPerSecond / videoBitrateMbps / videoMetadataToken tùy chọn. Mỗi ảnh tham chiếu Image5, Grok Imagine Image 2.0 hoặc Wan 3.0 đều cần token ảnh có chữ ký và kích thước byte được ràng buộc từ phản hồi tải lên ban đầu có gắn mô hình; Layer Decomposition còn áp dụng các giới hạn hình học đã được ghi trong tài liệu. Mỗi video tham chiếu Video8 và Wan 3.0 đều cần token thời lượng có chữ ký và siêu dữ liệu video có chữ ký từ phản hồi tải lên ban đầu được gắn với mô hình. 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 dữ liệu biểu mẫu multipart với file, kind, model tùy chọn và client_request_id tùy chọn. Phản hồi là PublicApiFile, bao gồm size_bytes, kích thước ảnh có thể là null, image_dimensions_token, cùng các trường có thể là null video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes và video_metadata_token. GET /api/v1/files/{fileId} trả về siêu dữ liệu công khai cho các tệp thuộc tài khoản API, nhưng token siêu dữ liệu có chữ ký chưa được lưu có thể là null và phải được thay thế bằng cách tải tệp lên lại.

video_metadata_token được ràng buộc với tài khoản API, mô hình đích, URL, kiểu MIME, kích thước, tốc độ khung hình, bitrate và kích thước byte của tệp tải lên. Token này không thay thế duration_token; video tham chiếu Video8 và Wan 3.0 sử dụng cả hai hợp đồng phải cung cấp cả hai token. Token thời lượng âm thanh của Wan 3.0 còn ràng buộc kiểu MIME và kích thước byte của tệp tải lên.

Với wan-3-0-video, params chỉ chấp nhận seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed và referenceMediaItems. Các chế độ văn bản, khung hình và tham chiếu loại trừ lẫn nhau. Thời lượng thông minh là -1, giữ trước 30 giây và không hợp lệ khi dùng cùng video tham chiếu; mọi trường tùy ý, nội dung không có chữ ký, lối tắt file-to-video và lối tắt link-to-video đều bị từ chối theo nguyên tắc đóng khi xác thực thất bại.

POST /api/v1/chat/completions chấp nhận model, message, session_id tùy chọn, các tùy chọn điều khiển, ảnh đính kèm bằng file_id từ Files API và client_request_id tùy chọn. Điểm cuối này trả về một tin nhắn hoàn chỉnh của trợ lý theo chế độ không truyền phát.

POST /api/v1/chat/completions/stream chấp nhận cùng schema yêu cầu 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 messages thô.

Schema phản hồi

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 việc chọn mô hình và biểu mẫu tham số
PublicApiFile cho POST /api/v1/files và GET /api/v1/files/{fileId}
ReferenceMediaItem cho tham số tạo nội dung 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à các schema sự kiện truyền phát 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 bước xác thực phía máy khách và kiểm thử tích hợp nội bộ. TypeScript SDK beta tiếp tục tuân theo 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 danh mục mô hình và bộ tuần tự hóa công khai trước. Tài liệu và công cụ gỡ lỗi nên dùng cùng lớp công khai đó thay vì sao chép một bảng riêng.

OpenAPI và hợp đồng schema