Rivya AI Docs

OpenAPI اور schema contract

Rivya API v1 schema sources، compatibility rules، public fields، اور read-only OpenAPI JSON contract کا جائزہ لیں۔

2026/05/11 کو آخری review

Rivya API v1 یہاں read-only schema contract expose کرتا ہے:

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

یہ route public contract output ہے۔ یہ user session data نہیں پڑھتا، model jobs submit نہیں کرتا، اور private account data expose نہیں کرتا۔

Contract sources

Contract ان sources سے derive ہوتا ہے:

  • public API request schemas
  • public error codes
  • public API model reference layer
  • وہی model catalog جو /api/v1/models استعمال کرتا ہے

Model list dynamic ہے۔ ایسی integrations نہ بنائیں جو manually written model count پر depend کرتی ہوں۔

Version policy

Current API version v1 ہے۔

Backward-compatible changes میں یہ شامل ہو سکتے ہیں:

  • /api/v1/models میں model add کرنا
  • optional response field add کرنا
  • کسی model کے لیے optional request parameter add کرنا
  • نیا public error code add کرنا

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 model، message، optional session_id، optional controls، optional Files API file_id attachments، اور optional client_request_id accept کرتا ہے۔ یہ ایک complete non-streaming assistant message return کرتا ہے۔

POST /api/v1/chat/completions/stream same request schema accept کرتا ہے اور text/event-stream return کرتا ہے، جس میں session.created، message.delta، message.completed، usage.completed، heartbeat، error، اور done events شامل ہوتے ہیں۔ Chat API v1 raw messages array accept نہیں کرتا۔

Response schemas

OpenAPI output یہ public response shapes document کرتا ہے:

  • ModelList for GET /api/v1/models
  • PublicApiModel اور ModelParam model selection اور parameter forms کے لیے
  • PublicApiFile for POST /api/v1/files and GET /api/v1/files/{fileId}
  • ReferenceMediaItem file-backed generation parameters کے لیے
  • PublicGeneration create اور status responses کے لیے
  • GenerationResult اور GenerationError completed tasks کے لیے
  • ChatCompletionRequest، ChatCompletion، ChatSession، ChatMessage، ChatUsage، ChatCredits، اور Chat API کے لیے Chat stream event schemas
  • CreditBalance for GET /api/v1/credits
  • WebhookEndpoint، WebhookEvent، WebhookDelivery، اور WebhookTestResult signed API webhooks کے لیے
  • PublicApiError 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 یہ استعمال کرتے ہیں:

  • chat:create
  • chat:read
  • file_id

Webhook examples additionally یہ استعمال کرتے ہیں:

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

جب model parameter change ہو تو پہلے model catalog اور public serializer update کریں۔ Docs اور debugger کو separate table copy کرنے کے بجائے اسی public layer کو consume کرنا چاہیے۔

API models

Rivya API models list کریں، model IDs، categories، prompt limits، reference media، readiness states، اور Files API dependencies سمجھیں۔

Rivya API quickstart

API key create کریں، model choose کریں، asynchronous generation job submit کریں، اور optional SSE streaming کے ساتھ Chat API turn send کریں۔

فہرست

Contract sources
Version policy
Public field boundary
Request schema
Response schemas
Example governance
Related pages