Rivya API v1 schema sources, compatibility rules, public fields, read-only OpenAPI JSON contract를 검토하세요.

Rivya API v1은 다음 위치에서 read-only schema contract를 노출합니다.

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

이 route는 public contract output입니다. 사용자 session data를 읽지 않고, model jobs를 제출하지 않으며, private account data를 노출하지 않습니다.

Contract Sources

contract는 다음에서 파생됩니다.

public API request schemas
public error codes
public API model reference layer
/api/v1/models가 사용하는 동일한 model catalog

model list는 dynamic입니다. 손으로 작성한 model count에 의존하는 integrations를 만들지 마세요.

Version Policy

현재 API version은 v1입니다.

Backward-compatible changes에는 다음이 포함될 수 있습니다.

/api/v1/models에 model 추가
optional response field 추가
model의 optional request parameter 추가
새 public error code 추가

Breaking changes에는 새 version 또는 문서화된 migration path가 필요합니다.

Public Field Boundary

Public schema fields는 public names를 사용합니다.

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

internal task storage fields에 의존하지 마세요. 이것들은 public contract의 일부가 아닙니다.

Request Schema

POST /api/v1/generations는 다음을 받습니다.

model: 필수 public model ID
prompt: optional string이며, 많은 model에서 필요합니다.
params: model-specific parameters를 담는 optional object
client_request_id: 자체 trace ID를 위한 optional string

model-specific params는 Model API Reference를 사용하세요.

/api/v1/files가 반환한 reference media는 params.referenceMediaItems 안에 들어갑니다. schema는 url, kind, optional name, optional mimeType, optional durationSeconds, optional durationToken을 문서화합니다. Rivya는 POST /api/v1/generations에서 top-level files field를 받지 않습니다.

POST /api/v1/files는 file, kind, optional model, optional client_request_id가 있는 multipart form data를 받습니다. response는 PublicApiFile입니다. GET /api/v1/files/{fileId}는 API account가 소유한 files에 대해 같은 public file metadata를 반환합니다.

POST /api/v1/chat/completions는 model, message, optional session_id, optional controls, optional Files API file_id attachments, optional client_request_id를 받습니다. 완전한 non-streaming assistant message 하나를 반환합니다.

POST /api/v1/chat/completions/stream은 같은 request schema를 받고 session.created, message.delta, message.completed, usage.completed, heartbeat, error, done events가 포함된 text/event-stream을 반환합니다. Chat API v1은 raw messages array를 받지 않습니다.

Response Schemas

OpenAPI output은 다음 public response shapes를 문서화합니다.

ModelList for GET /api/v1/models
PublicApiModel and ModelParam for model selection and parameter forms
PublicApiFile for POST /api/v1/files and GET /api/v1/files/{fileId}
ReferenceMediaItem for file-backed generation parameters
PublicGeneration for create and status responses
GenerationResult and GenerationError for completed tasks
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits, and Chat stream event schemas for Chat API
CreditBalance for GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery, and WebhookTestResult for signed API webhooks
PublicApiError for stable error responses

이 schema는 client validation과 internal integration tests에 안전하게 사용할 수 있습니다. TypeScript SDK beta도 이 schema의 제약 안에 유지됩니다.

Example Governance

이 문서의 curl, JavaScript, Python examples는 schema와 같은 public field names를 사용합니다.

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

Chat examples additionally use:

chat:create
chat:read
file_id

Webhook examples additionally use:

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

model parameter가 바뀌면 먼저 model catalog와 public serializer를 업데이트하세요. docs와 debugger는 별도 table을 복사하지 말고 같은 public layer를 소비해야 합니다.

OpenAPI와 Schema Contract