El error más fácil es tratar Rivya API y Rivya Studio como caminos que compiten.
Se entienden mejor como dos etapas del mismo producto. Studio es donde las personas exploran, eligen, revisan y continúan el trabajo visualmente. La API es donde un flujo de trabajo estable se vuelve parte de otro producto, script o proceso backend.
Si aún estás aprendiendo la superficie de API, empieza con qué es la Rivya API. Esta página es más específica: cómo decidir si una tarea concreta pertenece en Studio o en la API.
La decisión en una tabla
| Pregunta | Usa Studio cuando... | Usa la API cuando... |
|---|---|---|
| ¿El resultado sigue siendo exploratorio? | sí | no, el flujo de trabajo ya es repetible |
| ¿Una persona necesita comparar resultados? | sí | solo después de que tu app reciba resultados |
| ¿La elección de modelo es estable? | todavía no | sí, o se selecciona desde la lista de modelos de API |
| ¿La tarea necesita medios de referencia? | una persona aún los está preparando | tu app puede subirlos mediante Files API |
| ¿El resultado necesita actualizar otro sistema? | todavía no | sí, mediante polling o webhooks |
| ¿El uso de créditos necesita mantenerse visible? | sí, durante pruebas | sí, pero mediante controles de API a nivel de cuenta |
Esto no trata de qué superficie es más avanzada. Trata de si la tarea está lista para automatizarse.
Usa Studio mientras el trabajo sigue cambiando
Studio es el lugar correcto cuando la decisión humana sigue siendo el trabajo principal.
Eso incluye:
- elegir entre modelos de imagen, video, audio o chat
- probar si una dirección de prompt vale la pena conservar
- comparar resultados visuales lado a lado
- decidir si los medios de referencia ayudan o perjudican
- usar historial guardado para continuar desde un resultado anterior
Esto es especialmente cierto para trabajo creativo. Si el brief no está estable, automatizar la solicitud normalmente hace que la confusión vaya más rápido, no que sea más pequeña.
Usa la API cuando el flujo de trabajo es repetible
La API se vuelve el mejor camino cuando las entradas y los siguientes pasos son lo bastante predecibles.
Buenas señales:
- tu producto ya conoce el modelo o categoría de modelo que necesita
- la entrada del usuario puede mapearse a un request body estable
- un job backend puede hacer polling de estado sin que alguien mire una pantalla
- un webhook puede actualizar el registro correcto cuando termina una tarea
- la app puede explicar el uso de créditos al equipo o al responsable de la cuenta
En ese punto, usar Studio para cada ejecución puede convertirse en el camino más lento. La API permite que tu producto inicie la tarea directamente.
Un límite práctico: descubrimiento frente a integración
Usa Studio para descubrimiento.
Usa la API para integración.
Descubrimiento significa:
- "¿Qué modelo deberíamos usar?"
- "¿Qué forma de prompt funciona?"
- "¿Los medios de referencia mejoran esta tarea?"
- "¿La calidad del resultado es suficiente para este caso de uso?"
Integración significa:
- "Esta acción de usuario debe crear un job de generación."
- "Este job debe reintentarse de forma idempotente."
- "Este archivo debe subirse y adjuntarse a una solicitud de modelo."
- "Esta tarea completada debe actualizar nuestro registro de producto."
Ese límite evita que la API se convierta en una superficie de experimento oculta.
Cómo deberían influir los créditos en la decisión
Tanto Studio como el uso de API consumen los mismos créditos de cuenta de Rivya.
Eso significa que el comportamiento de créditos debe formar parte del diseño de producto, no ser una ocurrencia posterior.
Usa Studio primero cuando el equipo aún necesita aprender la forma de costo. Usa la API cuando la tarea sea lo bastante estable como para que el producto pueda explicar cuándo pueden reservarse o consumirse créditos.
Para las reglas públicas actuales, lee créditos de API. Si un flujo de trabajo es demasiado caro para explicarlo al responsable de la cuenta, todavía no está listo para automatización con API.
Dónde Files cambia la elección
Los medios de referencia suelen ser donde una integración se vuelve más seria.
En Studio, una persona puede subir, inspeccionar, reintentar y decidir si el archivo es suficientemente bueno. En la API, tu producto necesita manejar la ruta del archivo deliberadamente mediante Files API.
Usa Studio cuando:
- la imagen, video o audio de referencia aún necesita limpieza humana
- el equipo no sabe qué referencia debe guiar al modelo
- las reglas de archivo todavía no están claras para el usuario
Usa la API cuando:
- la app puede recopilar el archivo de forma segura
- los requisitos de referencia del modelo son conocidos
- el archivo puede subirse antes de la solicitud de generación o chat
- los errores pueden mostrarse en tu propio producto sin ocultar lo ocurrido
Files API es un puente útil, pero no elimina la necesidad de diseñar la experiencia de archivo.
Dónde Chat cambia la elección
Chat puede pertenecer a cualquiera de los dos lados.
Usa Rivya Chat directamente cuando una persona está explorando, escribiendo, revisando o decidiendo.
Usa Chat API cuando el turno de chat necesita vivir dentro de tu propio producto o flujo de trabajo de servidor. Eso puede incluir turnos non-streaming, SSE streaming opcional, sessions creadas por API y file attachments compatibles.
La pregunta clave es dónde debe vivir la conversación. Si la conversación es parte del trabajo de Rivya, usa Rivya. Si la conversación es parte de la experiencia de tu producto, usa la API.
Cuándo Webhooks son una señal
Si tu flujo de trabajo necesita API Webhooks, probablemente ya pasó la etapa manual de Studio.
Los webhooks son útiles cuando otro sistema necesita responder a tareas de generación completadas:
- marcar un recurso como listo
- notificar a un usuario
- mover un paso de revisión hacia adelante
- mover una tarea fallida a soporte o lógica de retry
Eso es trabajo de integración. Studio aún puede servir para probar la ruta de modelo, pero el bucle de producción pertenece en la API.
Un patrón seguro de migración
No muevas todo un flujo de trabajo a la API de una vez.
Usa esta secuencia:
- prueba la tarea manualmente en Studio
- escribe el modelo estable, la forma de prompt, los archivos de entrada y el resultado esperado
- lee API Models y la referencia del modelo
- envía una generación mediante API Quickstart
- agrega Files API solo si el modelo requiere medios de referencia
- agrega Webhooks solo después de que polling funcione
- agrega Chat API solo si el producto necesita turnos de chat fuera de Studio
Cada paso debería hacer que el flujo de trabajo sea más fácil de operar, no solo más automatizado.
Cuándo quedarse en Studio
Quédate en Studio cuando la tarea aún necesita:
- revisión subjetiva
- dar forma al prompt
- comparación visual
- exploración de modelos
- historial creativo guardado
- una persona decidiendo si el siguiente paso es imagen, video, audio o chat
Eso no es una debilidad. Studio está diseñado para esa etapa.
Cuándo pasar a API
Pasa a API cuando:
- la misma tarea se repite a menudo
- la entrada puede estructurarse
- el modelo es conocido
- la app necesita crear tareas desde su propia UI
- estado, errores y créditos pueden manejarse con claridad
- polling o webhooks encajan con el backend del producto
La API es más fuerte cuando convierte un flujo de trabajo de Rivya ya entendido en una acción de producto confiable.
Siguiente paso en Rivya
- Usa Developers para previsualizar la superficie de API.
- Lee Rivya API Quickstart antes de escribir código de producción.
- Lee API Authentication antes de guardar una API key.
- Lee cómo crear un flujo de trabajo de IA multimodal con Rivya API si la siguiente pregunta es cómo conectar modelos, archivos, chat y webhooks.
- Usa mover trabajo entre Rivya Chat, Image, Video y Audio si el proyecto aún pertenece al trabajo de Studio guiado por humanos.
