Contrato y esquema de OpenAPI
Revisa las fuentes del esquema de Rivya API v1, las reglas de compatibilidad, los campos públicos y el contrato JSON de OpenAPI de solo lectura.
Última revisión el 26 de agosto de 2026
Rivya API v1 expone un contrato de esquema 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/modelsañ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 esquema 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.
Esquema de la 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 deben ir dentro de params.referenceMediaItems. El esquema documenta url, kind, los campos opcionales name y mimeType, durationSeconds / durationToken, width / height / sizeBytes / imageDimensionsToken y framesPerSecond / videoBitrateMbps / videoMetadataToken. Cada imagen de referencia de Image5, Grok Imagine Image 2.0 o Wan 3.0 exige el token firmado de imagen y el tamaño asociado de la respuesta de subida vinculada al modelo; Layer Decomposition aplica además sus límites geométricos documentados. Cada vídeo de referencia de Video8 o Wan 3.0 exige el token firmado de duración y los metadatos de vídeo firmados de la respuesta de subida vinculada al modelo. 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, e incluye size_bytes, dimensiones de imagen anulables, image_dimensions_token y los campos de video anulables video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes y video_metadata_token. GET /api/v1/files/{fileId} devuelve metadatos públicos de archivos de la cuenta de API, pero un token firmado de metadatos que no se haya persistido puede ser null y debe sustituirse volviendo a subir el archivo.
video_metadata_token está vinculado a la cuenta de API, el modelo objetivo, la URL, el tipo MIME, las dimensiones, la frecuencia de fotogramas, el bitrate y el tamaño en bytes de la subida. No sustituye a duration_token; los videos de referencia de Video8 y Wan 3.0 que usan ambos contratos deben proporcionar los dos tokens. Los tokens de duración de audio de Wan 3.0 también vinculan el tipo MIME y el tamaño de la subida en bytes.
Para wan-3-0-video, params solo acepta seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed y referenceMediaItems. Las escenas de texto, fotogramas y referencia son mutuamente excluyentes. La duración inteligente es -1, reserva 30 segundos y no es válida con video de referencia; las claves arbitrarias, los medios sin firmar y los accesos directos de archivo a video o de enlace a video se rechazan de forma cerrada.
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 esquema de solicitud y devuelve text/event-stream con los eventos session.created, message.delta, message.completed, usage.completed, heartbeat, error y done. Chat API v1 no acepta un array sin procesar 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 esquema puede usarse para validar el cliente y realizar pruebas internas de integración. La beta del SDK de TypeScript sigue limitada por este esquema.
Gobernanza de ejemplos
Los ejemplos de curl, JavaScript y Python de esta documentación usan los mismos nombres de campo públicos que el esquema:
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.