OpenAPI and Schema Contract

Rivya API v1 এখানে read-only schema contract expose করে:

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

এই route একটি public contract output। এটি user session data read করে না, model jobs submit করে না, এবং private account data expose করে না।

Contract Sources

contract derived হয়:

• public API request schemas
• public error codes
• public API model reference layer
• /api/v1/models যে একই model catalog ব্যবহার করে

model list dynamic। manually written model count-এর ওপর depend করে এমন integrations build করবেন না।

Version Policy

current API version হলো v1।

Backward-compatible changes অন্তর্ভুক্ত করতে পারে:

• /api/v1/models-এ model যোগ করা
• optional response field যোগ করা
• কোনো model-এর optional request parameter যোগ করা
• new public error code যোগ করা

Breaking changes-এর জন্য new version বা documented 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-এর ওপর depend করবেন না। এগুলো public contract-এর অংশ নয়।

Request Schema

POST /api/v1/generations accepts:

• model: required public model ID
• prompt: optional string, অনেক models-এর জন্য required
• params: model-specific parameters সহ optional object
• client_request_id: আপনার trace ID-এর জন্য optional string

model-specific params-এর জন্য Model API Reference ব্যবহার করুন।

/api/v1/files থেকে returned reference media params.referenceMediaItems-এর ভিতরে থাকে। schema url, kind, optional name, optional mimeType, optional durationSeconds এবং optional durationToken document করে। Rivya POST /api/v1/generations-এ top-level files field accept করে না।

POST /api/v1/files multipart form data accept করে, যেখানে file, kind, optional model এবং optional client_request_id থাকে। response হলো PublicApiFile। GET /api/v1/files/{fileId} API account-owned files-এর জন্য একই public file metadata return করে।

POST /api/v1/chat/completions accepts model, message, optional session_id, optional controls, optional Files API file_id attachments এবং optional client_request_id। এটি একটি complete non-streaming assistant message return করে।

POST /api/v1/chat/completions/stream একই request schema accept করে এবং session.created, message.delta, message.completed, usage.completed, heartbeat, error ও done events সহ text/event-stream return করে। Chat API v1 raw messages array accept করে না।

Response Schemas

OpenAPI output এই public response shapes document করে:

• 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-এর জন্য safe। TypeScript SDK beta এই schema দ্বারাই constrained থাকে।

Example Governance

এই docs-এর 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 update করুন। docs এবং debugger আলাদা table copy না করে একই public layer consume করা উচিত।

Related Pages

• API Models
• Rivya TypeScript SDK
• Model API Reference
• Create Generation
• Chat API
• API Webhooks
• API Errors and Limits