Cuando el despliegue tiene habilitado el acceso a la API pública y tu cuenta dispone de él, la Rivya API es el contrato para desarrolladores que permite usar las capacidades compatibles de los modelos de Rivya desde tu producto, script o flujo de trabajo.
No es un producto independiente de Rivya Studio. Usa los mismos límites de cuenta, el mismo saldo de créditos y el mismo catálogo público de modelos que ven los usuarios. La diferencia está en cómo empieza el trabajo: en vez de operar desde Studio, tu aplicación envía solicitudes con una clave de API.
Si necesitas los detalles de las rutas, empieza por Descripción general de la API de Rivya e Inicio rápido de la API de Rivya. Este artículo ofrece la visión de producto: para qué sirve la API, dónde encaja y cuándo no debería ser la primera opción.
La versión corta
Rivya API v1 permite que una cuenta apta y con sesión iniciada cree claves de API y llame desde fuera de la interfaz web a los modelos de Rivya preparados para API. Las páginas para desarrolladores describen el contrato implementado; el despliegue actual, los permisos de la cuenta y la disponibilidad del modelo determinan si la solicitud puede ejecutarse.
La superficie de API implementada incluye:
descubrimiento de modelos mediante la lista de modelos de API
tareas asíncronas de generación de imagen, video y audio
subidas mediante la API de archivos para modelos que necesitan medios de referencia
consultas del estado de generación mediante identificadores públicos de tarea
comprobaciones de créditos de cuenta
turnos de la API de Chat, incluido el streaming SSE opcional
webhooks firmados para la finalización de la generación cuando estén habilitados en el despliegue
una versión beta del SDK TypeScript para equipos que quieren un cliente simplificado
El portal para desarrolladores es el mejor punto de entrada si quieres una visión guiada, enlaces a la configuración de claves de API y una ruta segura para depurar.
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.
Cuando el acceso a la API está habilitado, algunos ejemplos habituales son:
un producto quiere generar variaciones de imagen después de que un usuario envía los requisitos
un flujo de marketing necesita crear borradores visuales a partir de entradas estructuradas de campaña
una herramienta interna necesita enviar tareas 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 del servidor quiere devoluciones firmadas cuando terminan las tareas de generación
En esos casos, la API de Rivya mantiene el trabajo conectado a la misma cuenta en vez de obligar a crear otra infraestructura para la facturación, la elección de modelos y el estado de las tareas.
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 |
|---|---|---|
| Claves de API | Acceso entre servidores desde tu cuenta | Autenticación de la API |
| Modelos | Identificadores públicos e información de disponibilidad | Modelos de la API |
| Generaciones | Tareas asíncronas de imagen, video y audio | Crear una generación |
| Archivos | Subidas de imágenes, videos o audios de referencia | API de archivos |
| Chat | Turnos de chat con o sin streaming | API de Chat |
| Webhooks | Eventos firmados para tareas de generación, cuando estén habilitados | Webhooks de la API |
La documentación de la API define el formato de las solicitudes y respuestas. Este artículo te ayuda a decidir qué pieza necesitas primero.
Cómo funcionan los créditos
El uso de la API consume el mismo saldo de créditos de la cuenta que Studio.
Eso significa que la API no actúa como intermediario anónimo de modelos. Cada solicitud pertenece a una cuenta de Rivya, utiliza una clave creada por ella y respeta el mismo límite de créditos descrito en Créditos de la API.
Esto resulta útil porque los experimentos en Studio y el uso de la API comparten el mismo modelo operativo. Puedes probar un modelo manualmente y trasladar después la parte repetible a una integración sin crear otra capa de facturación.
Cómo encajan los Files
Algunos modelos pueden ejecutarse solo desde texto. Otros necesitan una imagen, video o archivo de audio de referencia.
En una integración con la API, esas referencias deben pasar por la API de archivos. La subida crea un registro gestionado que puede usarse con los parámetros compatibles del modelo.
La regla práctica es simple:
si un modelo acepta solo texto, empieza por la ruta de generación
si un modelo necesita medios de referencia, sube primero el archivo
si es un modelo de chat con imágenes adjuntas, usa la API de Chat e identificadores de archivo
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
La consulta periódica de estado es la forma más sencilla de iniciar una integración. Envía una tarea de generación, guarda su identificador público y consulta hasta que termine o falle.
Cuando el despliegue tiene los webhooks habilitados, estos ganan utilidad a medida que la integración se acerca a producción:
no quieres un proceso consultando continuamente cada tarea
tu app necesita actualizar un registro cuando termina la generación
quieres un evento firmado que pueda reintentarse de forma segura
las tareas fallidas necesitan una ruta clara de recuperación
Para el contrato de eventos firmados, consulta API Webhooks. Confirma que la función esté disponible antes de diseñar en torno a ella. Mantén el receptor acotado: verifica firmas, procesa eventos duplicados y evita registrar secretos.
Un buen primer proyecto de API
El mejor primer proyecto de API suele ser pequeño y concreto.
Por ejemplo:
confirma que el despliegue y la cuenta tengan habilitado el acceso a la API
crea una clave de API en ajustes
consulta la lista de modelos
elige un modelo preparado para API
envía un trabajo de generación con una clave de idempotencia
consulta la ruta de estado
revisa los créditos antes y después
solo entonces agrega las funciones que exponga el despliegue, como 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 por Imagen, Video, Audio, Chat o Modelos de IA. Cuando la ruta sea repetible, traslada la parte estable a la API.
A dónde ir después
Abre el portal para desarrolladores para acceder a la API pública y a las herramientas de depuración.
Lee Rivya API Quickstart para hacer la primera solicitud segura.
Lee Autenticación de la API antes de guardar una clave en un servidor.
Lee Modelos de la API antes de elegir identificadores de modelo.
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.
