Contrato de OpenAPI y schema
Revisa fuentes de schema de Rivya API v1, reglas de compatibilidad, campos públicos y el contrato JSON de OpenAPI de solo lectura.
Última revisión el 2026/05/11
Rivya API v1 expone un contrato de schema de solo lectura en:
https://rivya.ai/api/v1/openapi.jsonEsta ruta es una salida de contrato público. No lee datos de sesión de usuario, no envía trabajos de modelo y no expone datos privados de cuenta.
Fuentes del contrato
El contrato se deriva de:
- schemas de solicitud de la API pública
- códigos públicos de error
- la capa pública de referencia de modelos de la API
- el mismo catálogo de modelos usado por
/api/v1/models
La lista de modelos es dinámica. No construyas integraciones que dependan de un conteo de modelos escrito manualmente.
Política de versión
La versión actual de la API es v1.
Los cambios retrocompatibles pueden incluir:
- añadir un modelo a
/api/v1/models - añadir un campo de respuesta opcional
- añadir un parámetro de solicitud opcional para un modelo
- añadir un nuevo código público de error
Los cambios incompatibles requieren una versión nueva o una ruta de migración documentada.
Límite de campos públicos
Los campos del schema público usan nombres públicos:
idstatusmodelsession_idmessageusagereserved_creditsfinal_creditscreated_atupdated_atresulterror
No dependas de campos internos de almacenamiento de tareas. No forman parte del contrato público.
Schema de solicitud
POST /api/v1/generations acepta:
model: ID público del modelo, requeridoprompt: string opcional, requerido por muchos modelosparams: objeto opcional con parámetros específicos del modeloclient_request_id: string opcional para tu propio ID de trazabilidad
Usa la referencia de modelos de la API para ver params específicos de cada modelo.
Los medios de referencia devueltos por /api/v1/files pertenecen dentro de params.referenceMediaItems. El schema documenta url, kind, name opcional, mimeType opcional, durationSeconds opcional y durationToken opcional. Rivya no acepta un campo files de nivel superior en POST /api/v1/generations.
POST /api/v1/files acepta datos multipart form con file, kind, model opcional y client_request_id opcional. La respuesta es PublicApiFile. GET /api/v1/files/{fileId} devuelve los mismos metadatos públicos de archivo para archivos que pertenecen a la cuenta de API.
POST /api/v1/chat/completions acepta model, message, session_id opcional, controles opcionales, adjuntos file_id opcionales de Files API y client_request_id opcional. Devuelve un mensaje completo del assistant sin streaming.
POST /api/v1/chat/completions/stream acepta el mismo schema de solicitud y devuelve text/event-stream con eventos session.created, message.delta, message.completed, usage.completed, heartbeat, error y done. Chat API v1 no acepta un array raw de messages.
Schemas de respuesta
La salida OpenAPI documenta estas formas públicas de respuesta:
ModelListparaGET /api/v1/modelsPublicApiModelyModelParampara selección de modelos y formularios de parámetrosPublicApiFileparaPOST /api/v1/filesyGET /api/v1/files/{fileId}ReferenceMediaItempara parámetros de generación respaldados por archivosPublicGenerationpara respuestas de creación y estadoGenerationResultyGenerationErrorpara tareas completadasChatCompletionRequest,ChatCompletion,ChatSession,ChatMessage,ChatUsage,ChatCreditsy schemas de eventos de stream de Chat para Chat APICreditBalanceparaGET /api/v1/creditsWebhookEndpoint,WebhookEvent,WebhookDeliveryyWebhookTestResultpara API webhooks firmadosPublicApiErrorpara respuestas de error estables
El schema es seguro para validación de cliente y pruebas internas de integración. La beta del SDK TypeScript se mantiene restringida por este schema.
Gobernanza de ejemplos
Los ejemplos de curl, JavaScript y Python en esta documentación usan los mismos nombres de campo públicos que el schema:
Authorization: Bearer rvya_sk_...Idempotency-Keymodelpromptmessagesession_idparamsclient_request_id
Los ejemplos de Chat también usan:
chat:createchat:readfile_id
Los ejemplos de Webhook también usan:
Rivya-Webhook-SignatureRivya-Webhook-Timestampwebhooks:manage
Cuando cambia un parámetro de modelo, actualiza primero el catálogo de modelos y el serializer público. La documentación y el depurador deben consumir esa misma capa pública en lugar de copiar una tabla separada.
Páginas relacionadas
Modelos de la API
Lista modelos de Rivya API y entiende IDs de modelo, categorías, límites de prompt, medios de referencia, estados de preparación y dependencias de Files API.
Inicio rápido de Rivya API
Crea una clave API, elige un modelo, envía un trabajo asíncrono de generación y manda un turno de Chat API con streaming SSE opcional.