Crea un workflow multimodale con Rivya API

Una buona integrazione Rivya API non è solo una richiesta a un modello.

La maggior parte dei workflow prodotto reali ha una piccola catena: scegliere il modello giusto, preparare l'input, caricare file di riferimento quando servono, inviare un job, osservare lo stato, gestire i credit e notificare il prodotto quando il risultato è pronto.

Questo articolo mostra la forma di pianificazione. Usa Rivya API Quickstart per il percorso eseguibile più breve e usa i docs API per i campi esatti delle richieste.

Parti dal momento prodotto

Prima di scegliere endpoint, descrivi il momento prodotto in una frase.

Esempi:

• Crea una bozza immagine prodotto quando un venditore invia un brief listing.
• Genera un breve concept video dopo che un campaign manager approva una direzione still.
• Invia un turno chat dentro uno strumento di ricerca interno e fai streaming della risposta all'utente.
• Carica un'immagine di riferimento, invia una richiesta modello supportata e notifica l'utente quando il risultato è pronto.

Quella frase impedisce all'integrazione di diventare una raccolta sciolta di chiamate API.

Mappa il workflow prima di scrivere codice

Usa questa tabella prima di aprire lo schema della richiesta.

Il workflow dovrebbe essere abbastanza chiaro da dare a ogni area API una ragione di esistere.

Passaggio 1: crea una key per l'integrazione

Crea una API key per l'app, l'ambiente o il workflow specifico che la userà.

Evita di usare una sola key per tutto. Dare nomi alle key in base allo scopo rende più semplice la revisione successiva:

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

Leggi Autenticazione API prima di salvare la key. Il secret completo viene mostrato una sola volta, quindi il tuo team dovrebbe salvarlo subito nello secret store server-side corretto.

Passaggio 2: scegli i modelli dalla lista API pubblica

Non hardcodare un modello solo perché ha funzionato in un test manuale.

Usa Modelli API e Riferimento API modelli per confermare:

• ID modello pubblico
• se è disponibile tramite API
• modalità di input supportata
• aspettative su prompt e parametri
• se Files API è richiesta
• comportamento dei credit e note di readiness

Qui molte integrazioni diventano più pulite. Un modello perfetto per un test manuale in Studio potrebbe non essere il primo modello giusto per un flusso prodotto automatizzato.

Passaggio 3: decidi se Files API fa parte della prima versione

Se il modello può partire da input testuale, mantieni la prima versione text-only.

Aggiungi Files API solo quando il workflow ha davvero bisogno di media di riferimento.

Quando serve, definisci:

• quali tipi di file il prodotto accetta
• chi possiede lo step di cleanup dei file
• cosa succede quando l'upload fallisce
• come i dati file restituiti passano nei parametri del modello
• se lo stesso file deve essere riusato o caricato di nuovo

Questo evita che un'esperienza file fragile resti nascosta dietro un pulsante generate dall'aspetto pulito.

Passaggio 4: invia un solo job di generazione

Per generazione immagine, video e audio, il pattern normale è:

1. preparare ID modello, prompt e parametri supportati
2. aggiungere una idempotency key per retry sicuri
3. inviare tramite endpoint di generazione
4. salvare l'ID task pubblico
5. fare polling dello stato finché il task raggiunge uno stato terminale

Usa Crea generazione per la forma della richiesta e Stato generazione per gestire il risultato.

Il prodotto dovrebbe trattare queued, processing, succeeded e failed come stati visibili all'utente. Non far leggere agli utenti dettagli di sistema né indovinare perché un job è lento.

Passaggio 5: usa Chat API per i modelli chat

I modelli chat dovrebbero usare Chat API, non l'endpoint di generazione.

Conta perché il lavoro chat ha comportamenti diversi:

• i turni chat possono appartenere a sessioni create via API
• non-streaming e streaming SSE hanno esperienze utente diverse
• gli allegati immagine usano file ID da Files API
• la liquidazione dei credit segue il turno chat invece di un normale task media asincrono

Se il tuo prodotto ha bisogno di una risposta assistant dentro la propria interfaccia, Chat API può essere il percorso giusto. Se l'utente sta ancora esplorando idee, Rivya Chat o Studio possono essere migliori.

Passaggio 6: parti dal polling, poi aggiungi webhooks

Per una prima versione, il polling è più facile da ragionare.

Aggiungi API Webhooks quando:

• il prodotto ha molti job asincroni
• i client in attesa non dovrebbero fare polling diretto
• i sistemi downstream hanno bisogno di eventi di completamento firmati
• retry e gestione duplicati sono già progettati

I receiver webhook dovrebbero essere noiosi e rigidi: verificare la firma, accettare eventi duplicate-safe, aggiornare un solo record prodotto e loggare solo ciò che è sicuro loggare.

Passaggio 7: rendi visibili i credit nel prodotto

Rivya API usa gli stessi credit account di Studio.

La tua integrazione dovrebbe decidere quanto mostrarne. Come minimo, il team dovrebbe sapere:

• quale account possiede la API key
• quale workflow può consumare credit
• cosa succede quando i credit sono troppo bassi
• come vengono spiegati gli stati di generazione falliti
• dove indirizzare qualcuno per domande su credit e billing

Usa API Credits, Credit e billing in Rivya e Come ragionare su credit, pack e piani Rivya per il modello wallet visibile all'utente.

Una prima versione piccola

Una buona prima versione è intenzionalmente limitata.

Per esempio:

1. una API key
2. un modello immagine selezionato
3. nessun upload file per ora
4. una richiesta di generazione
5. un percorso di status polling
6. una preview risultato semplice nel tuo prodotto
7. un messaggio di errore credit chiaro

Questa versione prova la connessione prima di aggiungere altre parti mobili.

Una versione più completa

Dopo che la prima versione funziona, un workflow più pieno potrebbe aggiungere:

• Files API per immagini o video di riferimento
• controlli parametri specifici del modello
• idempotency legata al tuo record prodotto
• webhooks firmati per il completamento
• Chat API per turni assistant
• uno stream eventi server-side quando la chat richiede output live
• viste admin o support per job falliti

Ogni aggiunta dovrebbe rispondere a un reale bisogno prodotto. Se serve solo a far sembrare la demo più grande, lasciala fuori.

Errori comuni di integrazione

Evita questi pattern:

• partire con ogni feature API insieme
• nascondere l'uso dei credit al proprietario dell'account
• usare assunzioni solo Studio in un flusso API
• trattare gli upload file come un dettaglio secondario
• ritentare richieste di generazione senza idempotency
• usare Chat API per job che dovrebbero essere generazione asincrona
• usare endpoint di generazione per turni chat
• loggare API key complete, webhook secret o dettagli temporanei dei file

Il workflow API più sicuro è esplicito su ownership, stato e gestione dei fallimenti.

Dove andare dopo

• Parti da Developers per l'hub API pubblico.
• Usa Rivya API Quickstart per eseguire la prima richiesta.
• Usa Modelli API prima di selezionare gli ID modello.
• Usa Files API solo quando il modello ha davvero bisogno di media di riferimento.
• Usa Chat API per turni chat e risposte chat in streaming.
• Usa API Webhooks quando il polling non basta più.
• Se il workflow ha ancora bisogno di esplorazione umana, leggi Quando usare Rivya API invece di Studio prima di automatizzarlo.