La Rivya API est le chemin développeur pour utiliser les capacités de modèles Rivya depuis votre propre produit, script ou workflow.
Ce n'est pas un produit séparé de Rivya Studio. Elle utilise la même frontière de compte, le même portefeuille de crédits et la même couche publique de modèles que les utilisateurs voient dans Rivya. La différence est la façon dont le travail démarre : au lieu de cliquer dans Studio, votre application envoie des requêtes avec une clé API.
Si vous avez besoin des détails d'endpoints, commencez par Vue d'ensemble de la Rivya API et Rivya API Quickstart. Cet article est l'explication au niveau produit : à quoi sert l'API, où elle s'insère et quand elle ne doit pas être le premier chemin.
La version courte
Rivya API v1 permet à un compte connecté de créer des clés API et d'appeler les capacités de modèles Rivya hors de l'interface web.
La surface API actuelle inclut :
- la découverte de modèles via la liste des modèles API
- des tâches asynchrones de génération image, vidéo et audio
- les imports Files API pour les modèles qui ont besoin de médias de référence
- le polling du statut de génération avec des ID de tâches publics
- les vérifications de crédits du compte
- les tours Chat API, avec streaming SSE optionnel
- les webhooks signés pour la fin de génération
- un SDK TypeScript beta pour les équipes qui veulent un wrapper client
Le hub développeur public est Developers. C'est la meilleure entrée si vous voulez une vue guidée, des liens vers les réglages de clés API et un flux de debugger sûr.
Pourquoi Rivya a une API
Studio est utile lorsqu'une personne choisit encore les modèles, façonne les prompts, relit les sorties et décide quoi faire ensuite.
L'API est utile lorsque cette décision est devenue un workflow produit ou opérationnel répétable.
Exemples courants :
- un produit veut générer des variations d'images après qu'un utilisateur soumet un brief
- un workflow marketing doit créer des brouillons visuels depuis des entrées de campagne structurées
- un outil interne doit soumettre des tâches vidéo ou audio sans demander à quelqu'un d'ouvrir le navigateur
- un système de support ou de contenu veut un tour de modèle chat dans sa propre interface
- un service backend veut des callbacks signés lorsque les tâches de génération se terminent
Dans ces cas, Rivya API garde le travail connecté au même compte Rivya au lieu d'imposer une pile séparée pour la facturation, le choix de modèle et le statut de tâche.
Ce que l'API ne remplace pas
L'API ne remplace pas toutes les raisons d'utiliser Rivya directement.
Utilisez Studio ou les surfaces publiques de travail lorsque :
- le prompt a encore besoin d'exploration humaine
- le choix de modèle n'est pas stable
- un créateur doit comparer les sorties visuellement
- le projet dépend de l'historique enregistré et de la revue manuelle
- l'équipe n'a pas décidé quels formats d'entrée et de sortie doivent devenir répétables
Utilisez l'API lorsque le workflow est assez clair pour être automatisé.
Cette frontière compte. Une question créative vague appartient généralement d'abord à Studio. Un flux produit connu avec des entrées prévisibles peut passer à l'API.
Les principaux blocs de construction
Pensez à l'API comme à six pièces connectées.
| Bloc | Ce qu'il gère | Où lire ensuite |
|---|---|---|
| Clés API | Accès serveur à serveur depuis votre compte | API Authentication |
| Models | ID de modèles publics et informations de disponibilité | API Models |
| Generations | Tâches async image, vidéo et audio | Create Generation |
| Files | Imports d'images, vidéos ou audios de référence | Files API |
| Chat | Tours de chat non-streaming ou streaming | Chat API |
| Webhooks | Événements signés de fin pour les tâches de génération | API Webhooks |
Les documents API sont la source pour la forme des requêtes et réponses. Cet article doit vous aider à décider de quelle pièce vous avez besoin en premier.
Comment fonctionnent les crédits
L'usage API puise dans le même portefeuille de crédits de compte Rivya que Studio.
Cela signifie que l'API n'est pas un proxy de modèles anonyme. Une requête appartient à un compte Rivya, utilise une clé API créée par ce compte et suit la même frontière de crédits au niveau produit décrite dans Crédits API.
C'est utile pour les équipes, car les expériences Studio et l'usage API restent dans un seul modèle opérationnel. Vous pouvez tester un modèle manuellement, puis déplacer la partie répétable dans une intégration sans créer une deuxième couche de facturation.
Comment les fichiers s'insèrent
Certains modèles peuvent fonctionner avec du texte seul. D'autres ont besoin d'une image, d'une vidéo ou d'un fichier audio de référence.
Pour les intégrations API, ces références doivent passer par Files API. L'import crée un enregistrement de fichier géré qui peut être transmis aux paramètres de modèle pris en charge.
La règle pratique est simple :
- si un modèle accepte une entrée texte seule, commencez par l'endpoint de génération
- si un modèle a besoin de médias de référence, importez le fichier d'abord
- si le modèle est un modèle chat avec pièces jointes image, utilisez Chat API et des ID de fichiers
Ne concevez pas votre intégration autour de flux d'import uniquement navigateur ou de sessions Studio enregistrées. L'API a sa propre frontière publique de fichiers pour une raison.
Où les webhooks aident
Le polling est le chemin d'intégration le plus simple pour commencer. Soumettez une tâche de génération, enregistrez l'ID de tâche public et interrogez jusqu'à réussite ou échec.
Les webhooks deviennent utiles lorsque l'intégration ressemble davantage à de la production :
- vous ne voulez pas qu'un worker interroge chaque tâche
- votre app doit mettre à jour un enregistrement lorsque la génération se termine
- vous voulez un événement signé qui peut être rejoué en sécurité
- les tâches échouées doivent entrer dans un chemin de récupération clair
Pour le contrat d'événement signé, utilisez API Webhooks. Gardez le receiver webhook étroit : vérifiez les signatures, gérez les événements dupliqués et évitez de placer des valeurs secrètes dans les logs.
Un bon premier projet API
Le meilleur premier projet API est généralement petit et concret.
Par exemple :
- créer une clé API dans les réglages
- appeler la liste des modèles
- choisir un modèle disponible
- soumettre une tâche de génération avec une clé d'idempotence
- interroger l'endpoint de statut
- vérifier les crédits avant et après
- seulement ensuite ajouter Files API, Chat API ou Webhooks
Ce chemin vous donne une intégration fonctionnelle sans mélanger toutes les fonctionnalités API dans le premier test.
Quand l'API est le mauvais point de départ
L'API n'est probablement pas la bonne première étape lorsque :
- l'équipe n'a pas encore choisi une famille de modèles
- la sortie souhaitée change à chaque exécution
- le prompt dépend du goût et de la revue manuelle
- l'intégration masquerait l'usage des crédits aux personnes qui doivent le comprendre
- le produit a besoin d'une démo publique avant d'avoir besoin d'automatisation
Dans ces cas, commencez par Image, Video, Audio, Chat ou AI Models. Une fois le chemin répétable, déplacez la partie stable vers l'API.
Où aller ensuite
- Ouvrez Developers pour le hub API public et le debugger.
- Lisez Rivya API Quickstart pour faire la première requête sûre.
- Lisez API Authentication avant de mettre une clé sur un serveur.
- Lisez API Models avant de choisir des ID de modèles.
- Lisez Quand utiliser Rivya API plutôt que Studio si la frontière produit reste floue.
- Lisez Comment construire un workflow IA multimodal avec Rivya API lorsque vous planifiez une intégration complète image, vidéo, audio ou chat.
