La Rivya API es la ruta para desarrolladores que quieren usar capacidades de modelos de Rivya desde su propio producto, script o flujo de trabajo.
No es un producto separado de Rivya Studio. Usa el mismo límite de cuenta, la misma wallet de créditos y la misma capa pública de modelos que los usuarios ven en Rivya. La diferencia es cómo empieza el trabajo: en vez de hacer clics en Studio, tu aplicación envía solicitudes con una API key.
Si necesitas detalles de endpoints, empieza con Rivya API Overview y Rivya API Quickstart. Este artículo es la explicación a nivel de producto: para qué sirve la API, dónde encaja y cuándo no debería ser la primera ruta.
La versión corta
Rivya API v1 permite que una cuenta con sesión iniciada cree API keys y llame capacidades de modelos de Rivya desde fuera de la interfaz web.
La superficie actual de API incluye:
- descubrimiento de modelos mediante la lista de modelos de API
- jobs asíncronos de generación de imagen, video y audio
- uploads de Files API para modelos que necesitan medios de referencia
- polling de estado de generación con public task IDs
- comprobaciones de créditos de cuenta
- turnos de Chat API, incluido SSE streaming opcional
- webhooks firmados para finalización de generación
- una TypeScript SDK beta para equipos que quieren un client wrapper
El hub público para desarrolladores es Developers. Es la mejor entrada si quieres una visión guiada, enlaces a la configuración de API keys y un flujo de debugger seguro.
Por qué Rivya tiene una API
Studio es útil cuando una persona sigue eligiendo modelos, dando forma a prompts, revisando resultados y decidiendo qué hacer después.
La API es útil cuando esa decisión ya se convirtió en un flujo operativo o de producto repetible.
Ejemplos comunes:
- un producto quiere generar variaciones de imagen después de que un usuario envía un brief
- un flujo de marketing necesita crear borradores visuales desde entradas estructuradas de campaign
- una herramienta interna necesita enviar jobs de video o audio sin pedir que alguien abra el navegador
- un sistema de soporte o contenido quiere un turno de modelo de chat dentro de su propia interfaz
- un servicio backend quiere callbacks firmados cuando terminan generation jobs
En esos casos, Rivya API mantiene el trabajo conectado a la misma cuenta de Rivya en vez de obligar a crear otro stack para billing, elección de modelos y estado de tarea.
Qué no reemplaza la API
La API no reemplaza todas las razones para usar Rivya directamente.
Usa Studio o las superficies públicas de trabajo cuando:
- el prompt aún necesita exploración humana
- la elección de modelo no está estable
- un creador necesita comparar resultados visualmente
- el proyecto depende de historial guardado y revisión manual
- el equipo no ha decidido qué formato de entrada y resultado debería volverse repetible
Usa la API cuando el flujo de trabajo sea lo bastante claro para automatizarse.
Ese límite importa. Una pregunta creativa vaga suele pertenecer primero en Studio. Un flujo de producto conocido con entradas predecibles puede moverse a la API.
Los bloques principales
Piensa en la API como seis piezas conectadas.
| Bloque | Qué maneja | Dónde leer después |
|---|---|---|
| API keys | Acceso server-to-server desde tu cuenta | API Authentication |
| Models | Public model IDs e información de readiness | API Models |
| Generations | Jobs asíncronos de imagen, video y audio | Create Generation |
| Files | Uploads de imagen, video o audio de referencia | Files API |
| Chat | Turnos de chat non-streaming o streaming | Chat API |
| Webhooks | Eventos firmados de completion para generation jobs | API Webhooks |
Los docs de API son la fuente para la forma de request y response. Este artículo debe ayudarte a decidir qué pieza necesitas primero.
Cómo funcionan los créditos
El uso de API consume la misma wallet de créditos de cuenta de Rivya que Studio.
Eso significa que la API no es un proxy anónimo de modelos. Una solicitud pertenece a una cuenta de Rivya, usa una API key creada por esa cuenta y sigue el mismo límite de créditos a nivel de producto descrito en API Credits.
Esto es útil para equipos porque los experimentos en Studio y el uso de API permanecen en un solo modelo operativo. Puedes probar un modelo manualmente y luego mover la parte repetible a una integración sin crear una segunda capa de billing.
Cómo encajan los Files
Algunos modelos pueden ejecutarse solo desde texto. Otros necesitan una imagen, video o archivo de audio de referencia.
Para integraciones con API, esas referencias deben pasar por Files API. La carga crea un registro de archivo gestionado que puede pasarse a parámetros de modelo compatibles.
La regla práctica es simple:
- si un modelo acepta entrada solo de texto, empieza con el endpoint de generation
- si un modelo necesita medios de referencia, sube primero el archivo
- si el modelo es un modelo de chat con image attachments, usa Chat API y file IDs
No diseñes tu integración alrededor de flujos de carga solo del navegador o sesiones guardadas de Studio. La API tiene su propio límite público de archivos por una razón.
Dónde ayudan los Webhooks
Polling es el camino de primera integración más fácil. Envía un generation job, guarda el public task ID y consulta hasta que tenga éxito o falle.
Los webhooks se vuelven útiles cuando la integración se parece más a producción:
- no quieres un worker haciendo polling de cada job
- tu app necesita actualizar un registro cuando termina la generación
- quieres un evento firmado que pueda reintentarse de forma segura
- los jobs fallidos necesitan moverse a una ruta clara de recuperación
Para el contrato de evento firmado, usa API Webhooks. Mantén estrecho el webhook receiver: verifica firmas, maneja eventos duplicados y evita poner valores secretos en logs.
Un buen primer proyecto de API
El mejor primer proyecto de API suele ser pequeño y concreto.
Por ejemplo:
- crea una API key en ajustes
- llama la lista de modelos
- elige un modelo disponible
- envía un generation job con una idempotency key
- haz polling del status endpoint
- revisa créditos antes y después
- solo entonces agrega Files API, Chat API o Webhooks
Esa ruta te da una integración funcional sin mezclar cada función de API en la primera prueba.
Cuándo la API es el punto de partida equivocado
La API probablemente no es el primer paso correcto cuando:
- el equipo aún no eligió una familia de modelos
- el resultado deseado sigue cambiando en cada ejecución
- el prompt depende de gusto y revisión manual
- la integración ocultaría el uso de créditos a las personas que necesitan entenderlo
- el producto necesita una demo pública antes que automatización
En esos casos, empieza desde Image, Video, Audio, Chat o AI Models. Cuando la ruta sea repetible, mueve la parte estable a la API.
A dónde ir después
- Abre Developers para el hub público de API y debugger.
- Lee Rivya API Quickstart para hacer la primera solicitud segura.
- Lee API Authentication antes de poner una key en un servidor.
- Lee API Models antes de elegir model IDs.
- Lee cuándo usar Rivya API en vez de Studio si el límite de producto aún no está claro.
- Lee cómo crear un flujo de trabajo de IA multimodal con Rivya API cuando estés planificando una integración completa de imagen, video, audio o chat.
