Rivya AI
Rivya Journal
Sigue explorando
Continúa con guías relacionadas, notas de producto y desgloses de flujo de trabajo del equipo de Rivya.
Categorías
Una buena integración con Rivya API no es solo una solicitud a un modelo.
La mayoría de flujos reales de producto tienen una pequeña cadena: elegir el modelo correcto, preparar la entrada, subir archivos de referencia cuando haga falta, enviar una tarea, observar el estado, manejar créditos y notificar al producto cuando el resultado está listo.
Este artículo muestra la forma de planificación. Usa Inicio rápido de Rivya API para la ruta ejecutable más corta, y usa la documentación de API para los campos exactos de la solicitud.
El flujo que sigue describe el contrato implementado de la API pública. Antes de construirlo, confirma que el despliegue y la cuenta tienen acceso a la API pública, que el modelo elegido admite llamadas por API y que las funciones opcionales, como los webhooks, están realmente disponibles.
Antes de elegir las rutas de la API, describe en una frase el momento del producto que debe activarlas.
Ejemplos:
Crear un borrador de imagen de producto cuando un vendedor envía los requisitos de un anuncio.
Generar un concepto de video corto después de que un responsable de campaña aprueba una dirección de imagen fija.
Enviar un turno de chat dentro de una herramienta interna de investigación y transmitir la respuesta al usuario.
Subir una imagen de referencia, enviar una solicitud de modelo compatible y notificar al usuario cuando el resultado esté listo.
Esa frase evita que la integración se convierta en una colección suelta de llamadas API.
Usa esta tabla antes de abrir el esquema de solicitud.
| Paso del flujo | Pregunta de producto | Área API |
|---|---|---|
| Acceso de cuenta | ¿Qué cuenta de Rivya posee el uso? | Autenticación de API |
| Elección de modelo | ¿Qué ID público de modelo encaja con esta tarea? | Modelos de API |
| Entrada de referencia | ¿El modelo necesita medios subidos? | Files API |
| Generación | ¿Es una tarea asíncrona de imagen, video o audio? | Crear generación |
| Chat | ¿Es un turno de modelo de chat en lugar de una tarea de generación? | Chat API |
| Estado | ¿Cómo sabrá el producto que el resultado está listo? | Estado de generación |
| Evento de finalización | ¿Otro sistema debe recibir una devolución firmada y están habilitados los webhooks? | API Webhooks |
| Créditos | ¿Cómo entenderá el equipo el costo? | Créditos de API |
El flujo debería ser lo bastante claro como para que cada área API tenga una razón de existir.
Crea una clave API para la app, el entorno o el flujo específico que la usará.
Evita usar una sola clave para todo. Nombrar claves por propósito facilita la revisión posterior:
production-image-workflow
staging-video-tests
internal-chat-assistant
webhook-smoke-test
Lee Autenticación de API antes de guardar la clave. El secreto completo se muestra una sola vez, así que tu equipo debería guardarlo de inmediato en el almacén de secretos correcto del lado servidor.
No fijes un modelo en el código solo porque funcionó en una prueba manual.
Usa Modelos de API y Referencia de API de modelos para confirmar:
el ID público del modelo
si está disponible a través de la API
modo de entrada compatible
expectativas de prompt y parámetros
si se requiere Files API
comportamiento de créditos y notas de preparación
Aquí es donde muchas integraciones se vuelven más limpias. Un modelo perfecto para una prueba manual en Studio puede no ser el primer modelo correcto para un flujo de producto automatizado.
Si el modelo puede ejecutarse desde entrada de texto, mantén la primera versión solo con texto.
Agrega Files API solo cuando el flujo realmente necesite medios de referencia.
Cuando lo necesite, define:
qué tipos de archivo acepta el producto
quién posee el paso de limpieza de archivos
qué pasa cuando falla la subida
cómo se pasan los datos de archivo devueltos a los parámetros del modelo
si el mismo archivo debería reutilizarse o subirse de nuevo
Esto evita que una experiencia de archivos frágil quede escondida detrás de un botón de generación que parece limpio.
Para generación de imagen, video y audio, el patrón normal es:
prepara el ID del modelo, el prompt y los parámetros compatibles
agrega una clave de idempotencia para reintentos seguros
envía la solicitud por la ruta de generación
guarda el ID público de tarea
haz sondeo del estado hasta que la tarea llegue a un estado terminal
Usa Crear generación para la forma de la solicitud y Estado de generación para manejar el resultado.
El producto debería tratar queued, processing, succeeded y failed como estados visibles para el usuario. No hagas que los usuarios lean detalles del sistema ni adivinen por qué una tarea tarda.
Los modelos de chat deben usar la API de Chat, no la ruta de generación.
Eso importa porque el trabajo de chat tiene comportamiento diferente:
los turnos de chat pueden pertenecer a sesiones creadas por API
las rutas sin streaming y con streaming SSE tienen experiencias de usuario diferentes
los adjuntos de imagen usan IDs de archivo de Files API
la liquidación de créditos sigue al turno de chat, no a una tarea asíncrona normal de medios
Si tu producto necesita una respuesta de asistente dentro de su propia interfaz, Chat API puede ser la ruta correcta. Si el usuario todavía está explorando ideas, Rivya Chat o Studio puede ser mejor.
Para una primera versión, el sondeo es más fácil de razonar.
Si el despliegue tiene habilitados los webhooks, agrega API Webhooks cuando:
el producto tenga muchas tareas asíncronas
los clientes en espera no deban hacer sondeo directo
los sistemas posteriores necesiten eventos de finalización firmados
el manejo de reintentos y duplicados ya esté diseñado
Los receptores de webhook deberían ser simples y estrictos: verificar la firma, aceptar eventos seguros ante duplicados, actualizar un solo registro de producto y registrar solo lo que sea seguro registrar.
Rivya API usa los mismos créditos de cuenta que Studio.
Tu integración debería decidir cuánto mostrar de eso. Como mínimo, el equipo debería saber:
qué cuenta posee la clave API
qué flujo puede consumir créditos
qué pasa cuando los créditos son demasiado bajos
cómo se explican los estados de generación fallida
adónde enviar a alguien para preguntas de créditos y facturación
Usa Créditos de API, Créditos y facturación en Rivya y Cómo pensar en los créditos, paquetes y planes de Rivya para el modelo de cartera visible para el usuario.
Una buena primera versión es intencionalmente limitada.
Por ejemplo:
una clave API
un modelo de imagen seleccionado
sin subida de archivos todavía
una solicitud de generación
una ruta simple de sondeo de estado
una vista previa simple del resultado en tu producto
un mensaje claro de error de créditos
Esa versión prueba la conexión antes de agregar más partes móviles.
Después de que funcione la primera versión, un flujo más completo podría agregar:
Files API para imágenes o videos de referencia
controles de parámetros específicos del modelo
idempotencia atada a tu registro de producto
webhooks firmados para la finalización, cuando la función esté habilitada
Chat API para turnos de asistente
un flujo de eventos del lado servidor cuando el chat necesite salida en vivo
vistas de administración o soporte para tareas fallidas
Cada adición debería responder a una necesidad real de producto. Si solo hace que la demo se vea más grande, déjala fuera.
Evita estos patrones:
empezar con todas las funciones de API a la vez
ocultar el uso de créditos al dueño de la cuenta
usar supuestos solo de Studio dentro de un flujo API
tratar las subidas de archivos como un detalle secundario
reintentar solicitudes de generación sin idempotencia
usar Chat API para tareas que deberían ser generación asíncrona
usar rutas de generación para turnos de chat
registrar claves API completas, secretos de webhook o detalles temporales de archivos
El flujo API más seguro es explícito sobre propiedad, estado y manejo de fallos.
Empieza desde Desarrolladores para el hub público de API.
Usa Inicio rápido de Rivya API para ejecutar la primera solicitud.
Usa Modelos de API antes de seleccionar IDs de modelo.
Usa Files API solo cuando el modelo realmente necesite medios de referencia.
Usa Chat API para turnos de chat y respuestas de chat en streaming.
Usa API Webhooks cuando el sondeo ya no sea suficiente y tengas habilitado el acceso a webhooks.
Si el flujo todavía necesita exploración humana, lee Cuándo usar Rivya API en lugar de Studio antes de automatizarlo.
