Revisa fuentes de schema de Rivya API v1, reglas de compatibilidad, campos públicos y el contrato JSON de OpenAPI de solo lectura.

Rivya API v1 expone un contrato de schema de solo lectura en:

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

Esta 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:

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

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, requerido
prompt: string opcional, requerido por muchos modelos
params: objeto opcional con parámetros específicos del modelo
client_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 y mimeType opcionales, durationSeconds / durationToken opcionales, width / height / sizeBytes / imageDimensionsToken opcionales y framesPerSecond / videoBitrateMbps / videoMetadataToken opcionales. 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 vinculado de la respuesta original de subida asociada al modelo; Layer Decomposition también aplica sus límites geométricos documentados. Cada video de referencia para Video8 o Wan 3.0 exige el token firmado de duración y los metadatos de video firmados de la respuesta original 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 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:

ModelList para GET /api/v1/models
PublicApiModel y ModelParam para selección de modelos y formularios de parámetros
PublicApiFile para POST /api/v1/files y GET /api/v1/files/{fileId}
ReferenceMediaItem para parámetros de generación respaldados por archivos
PublicGeneration para respuestas de creación y estado
GenerationResult y GenerationError para tareas completadas
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits y schemas de eventos de stream de Chat para Chat API
CreditBalance para GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery y WebhookTestResult para API webhooks firmados
PublicApiError para 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-Key
model
prompt
message
session_id
params
client_request_id

Los ejemplos de Chat también usan:

chat:create
chat:read
file_id

Los ejemplos de Webhook también usan:

Rivya-Webhook-Signature
Rivya-Webhook-Timestamp
webhooks: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.

Contrato de OpenAPI y schema