Construire un workflow multimodal avec l'API Rivya

Une bonne intégration API Rivya n'est pas une seule requête vers un seul modèle.

La plupart des vrais workflows produit forment une petite chaîne : choisir le bon modèle, préparer l'entrée, importer des fichiers de référence si nécessaire, soumettre un job, suivre le statut, gérer les crédits et notifier le produit lorsque le résultat est prêt.

Cet article montre la forme de planification. Utilisez Rivya API Quickstart pour le chemin exécutable le plus court, et les docs API pour les champs exacts des requêtes.

Commencer par le moment produit

Avant de choisir des endpoints, décrivez le moment produit en une phrase.

Exemples :

• Créer un brouillon d'image produit lorsqu'un vendeur soumet un brief de listing.
• Générer un concept de courte vidéo après validation d'une direction still par un responsable de campagne.
• Envoyer un tour chat dans un outil de recherche interne et streamer la réponse vers l'utilisateur.
• Importer une image de référence, soumettre une requête de modèle prise en charge et notifier l'utilisateur lorsque le résultat est prêt.

Cette phrase évite que l'intégration devienne une collection lâche d'appels API.

Cartographier le workflow avant d'écrire du code

Utilisez ce tableau avant d'ouvrir le schéma de requête.

Le workflow doit être assez clair pour que chaque zone API ait une raison d'exister.

Étape 1 : créer une clé pour l'intégration

Créez une clé API pour l'app, l'environnement ou le workflow spécifique qui l'utilisera.

Évitez d'utiliser une seule clé pour tout. Nommer les clés par usage facilite la revue plus tard :

• production-image-workflow
• staging-video-tests
• internal-chat-assistant
• webhook-smoke-test

Lisez API Authentication avant de stocker la clé. Le secret complet n'est affiché qu'une fois, donc votre équipe doit l'enregistrer immédiatement dans le bon gestionnaire de secrets côté serveur.

Étape 2 : choisir les modèles depuis la liste API publique

Ne hard-codez pas un modèle seulement parce qu'il a fonctionné dans un test manuel.

Utilisez API Models et Model API Reference pour confirmer :

• l'ID de modèle public
• s'il est disponible via l'API
• le mode d'entrée pris en charge
• les attentes de prompt et de paramètres
• si Files API est requis
• le comportement de crédits et les notes de disponibilité

C'est là que beaucoup d'intégrations deviennent plus propres. Un modèle parfait dans un test Studio manuel n'est pas toujours le bon premier modèle pour un flux produit automatisé.

Étape 3 : décider si Files API fait partie de la première version

Si le modèle peut tourner depuis une entrée texte, gardez la première version en texte seul.

Ajoutez Files API seulement lorsque le workflow a vraiment besoin de médias de référence.

Quand c'est le cas, définissez :

• quels types de fichiers le produit accepte
• qui possède l'étape de nettoyage des fichiers
• ce qui se passe si l'upload échoue
• comment les données de fichier retournées passent dans les paramètres du modèle
• si le même fichier doit être réutilisé ou importé à nouveau

Cela évite de cacher une expérience fichier fragile derrière un bouton de génération qui semble propre.

Étape 4 : soumettre un seul job de génération

Pour la génération image, vidéo et audio, le schéma normal est :

1. préparer l'ID de modèle, le prompt et les paramètres pris en charge
2. ajouter une clé d'idempotence pour les relances sûres
3. soumettre via l'endpoint de génération
4. enregistrer l'ID public de tâche
5. interroger le statut jusqu'à ce que la tâche atteigne un état terminal

Utilisez Create Generation pour la forme de requête et Generation Status pour le traitement du résultat.

Le produit doit traiter queued, processing, succeeded et failed comme des états visibles par l'utilisateur. Ne demandez pas aux utilisateurs de lire des détails système ou de deviner pourquoi un job est lent.

Étape 5 : utiliser Chat API pour les modèles chat

Les modèles chat doivent utiliser Chat API, pas l'endpoint de génération.

C'est important, car le travail chat a un comportement différent :

• les tours chat peuvent appartenir à des sessions créées par l'API
• le non-streaming et le streaming SSE créent des expériences utilisateur différentes
• les pièces jointes image utilisent les IDs de fichier de Files API
• le règlement des crédits suit le tour chat plutôt qu'une tâche média asynchrone classique

Si votre produit a besoin d'une réponse assistant dans sa propre interface, Chat API peut être le bon chemin. Si l'utilisateur explore encore des idées, Rivya Chat ou Studio peut être plus adapté.

Étape 6 : commencer par le polling, puis ajouter les webhooks

Pour une première version, le polling est plus facile à raisonner.

Ajoutez API Webhooks lorsque :

• le produit a beaucoup de jobs asynchrones
• les clients en attente ne devraient pas poller directement
• les systèmes aval ont besoin d'événements de fin signés
• la gestion des retries et des doublons est déjà conçue

Les récepteurs webhook doivent être simples et stricts : vérifier la signature, accepter les événements sans risque de doublon, mettre à jour un seul enregistrement produit et ne logger que ce qui est sûr.

Étape 7 : rendre les crédits visibles dans le produit

L'API Rivya utilise les mêmes crédits de compte que Studio.

Votre intégration doit décider combien de cette information afficher. Au minimum, l'équipe doit savoir :

• quel compte possède la clé API
• quel workflow peut consommer des crédits
• ce qui se passe lorsque les crédits sont trop bas
• comment expliquer les états de génération échoués
• où envoyer quelqu'un pour les questions de crédits et de facturation

Utilisez API Credits, Crédits et facturation dans Rivya et Comprendre les crédits, packs et plans Rivya pour le modèle wallet visible par l'utilisateur.

Une petite première version

Une bonne première version est volontairement limitée.

Par exemple :

1. une clé API
2. un modèle image sélectionné
3. pas encore d'upload de fichier
4. une requête de génération
5. un chemin de polling de statut
6. un aperçu simple du résultat dans votre produit
7. un message d'erreur crédits clair

Cette version prouve la connexion avant d'ajouter plus de pièces mobiles.

Une version plus complète

Après validation de la première version, un workflow plus complet peut ajouter :

• Files API pour les images ou vidéos de référence
• contrôles de paramètres spécifiques au modèle
• idempotence liée à votre enregistrement produit
• webhooks signés pour la fin de tâche
• Chat API pour les tours assistant
• stream d'événements côté serveur lorsque le chat a besoin d'une sortie en temps réel
• vues admin ou support pour les jobs échoués

Chaque ajout doit répondre à un vrai besoin produit. S'il ne fait que rendre la démo plus grande, laissez-le de côté.

Erreurs d'intégration fréquentes

Évitez ces schémas :

• commencer avec toutes les fonctionnalités API à la fois
• cacher l'usage des crédits au propriétaire du compte
• utiliser des hypothèses propres à Studio dans un flux API
• traiter les uploads de fichiers comme un détail secondaire
• relancer des requêtes de génération sans idempotence
• utiliser Chat API pour des jobs qui devraient être des générations asynchrones
• utiliser les endpoints de génération pour les tours chat
• logger des clés API complètes, secrets webhook ou détails de fichiers temporaires

Le workflow API le plus sûr est explicite sur la propriété, l'état et la gestion des échecs.

Où aller ensuite

• Commencez depuis Developers pour le hub API public.
• Utilisez Rivya API Quickstart pour lancer la première requête.
• Utilisez API Models avant de choisir des IDs de modèle.
• Utilisez Files API seulement lorsque le modèle a vraiment besoin de médias de référence.
• Utilisez Chat API pour les tours chat et les réponses chat en streaming.
• Utilisez API Webhooks lorsque le polling ne suffit plus.
• Si le workflow a encore besoin d'exploration humaine, lisez Quand utiliser l'API Rivya plutôt que Studio avant de l'automatiser.