Crea un flujo multimodal con Rivya API

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.

Empieza por el momento de producto

Antes de elegir endpoints, describe el momento de producto en una frase.

Ejemplos:

• Crear un borrador de imagen de producto cuando un vendedor envía un brief de listing.
• 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.

Mapea el flujo antes de escribir código

Usa esta tabla antes de abrir el esquema de solicitud.

El flujo debería ser lo bastante claro como para que cada área API tenga una razón de existir.

Paso 1: Crea una clave para la integración

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.

Paso 2: Elige modelos desde la lista pública de API

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.

Paso 3: Decide si Files API forma parte de la primera versión

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.

Paso 4: Envía una tarea de generación

Para generación de imagen, video y audio, el patrón normal es:

1. prepara el ID del modelo, el prompt y los parámetros compatibles
2. agrega una clave de idempotencia para reintentos seguros
3. envía por el endpoint de generación
4. guarda el ID público de tarea
5. 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.

Paso 5: Usa Chat API para modelos de chat

Los modelos de chat deberían usar Chat API, no el endpoint 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.

Paso 6: Empieza con sondeo, luego agrega webhooks

Para una primera versión, el sondeo es más fácil de razonar.

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.

Paso 7: Haz visibles los créditos en el producto

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 Primera Versión Pequeña

Una buena primera versión es intencionalmente limitada.

Por ejemplo:

1. una clave API
2. un modelo de imagen seleccionado
3. sin subida de archivos todavía
4. una solicitud de generación
5. una ruta simple de sondeo de estado
6. una vista previa simple del resultado en tu producto
7. un mensaje claro de error de créditos

Esa versión prueba la conexión antes de agregar más partes móviles.

Una versión más completa

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 finalización
• 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.

Errores comunes de integración

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 endpoints 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.

A dónde ir después

• 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.
• Si el flujo todavía necesita exploración humana, lee Cuándo usar Rivya API en lugar de Studio antes de automatizarlo.