Planifiez un flux API Rivya entre modèles, fichiers, tâches de génération, échanges de chat, webhooks, crédits et retour vers la révision produit.
Workflow
Publié le 12 mai 2026Dernière revue le 29 août 2026Auteur:Équipe éditoriale 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.
Le workflow ci-dessous décrit le contrat d'API publique implémenté. Avant de développer, vérifiez que l'accès à l'API publique est activé pour le déploiement et le compte, que le modèle choisi est prêt pour l'API et que les fonctions facultatives, comme les webhooks, sont réellement disponibles.
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.
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 :
préparer l'ID de modèle, le prompt et les paramètres pris en charge
ajouter une clé d'idempotence pour les relances sûres
soumettre via l'endpoint de génération
enregistrer l'ID public de tâche
interroger le statut jusqu'à ce que la tâche atteigne un état terminal
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.
Si les webhooks sont activés pour le déploiement, 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
