La Rivya API è il percorso developer per usare le capacità dei modelli Rivya dal tuo prodotto, script o workflow.
Non è un prodotto separato da Rivya Studio. Usa lo stesso confine account, lo stesso wallet di credit e lo stesso livello pubblico di modelli che gli utenti vedono in Rivya. La differenza è come inizia il lavoro: invece di cliccare dentro Studio, la tua applicazione invia richieste con una API key.
Se ti servono dettagli sugli endpoint, parti da Rivya API Overview e Rivya API Quickstart. Questo articolo è la spiegazione a livello prodotto: a cosa serve l'API, dove si inserisce e quando non dovrebbe essere il primo percorso.
La versione breve
Rivya API v1 permette a un account con login di creare API key e chiamare capacità dei modelli Rivya dall'esterno dell'interfaccia web.
La superficie API corrente include:
- discovery dei modelli tramite la lista modelli API
- job asincroni di generazione immagine, video e audio
- upload Files API per modelli che richiedono media di riferimento
- polling dello stato generazione con task ID pubblici
- controlli dei credit account
- turni Chat API, incluso streaming SSE opzionale
- webhooks firmati per completamento generazioni
- TypeScript SDK beta per team che vogliono un client wrapper
L'hub developer pubblico è Developers. È il miglior ingresso se vuoi una panoramica guidata, link alle impostazioni API key e un flusso debugger sicuro.
Perché Rivya ha un'API
Studio è utile quando una persona sta ancora scegliendo modelli, modellando prompt, rivedendo output e decidendo cosa fare dopo.
L'API è utile quando quella decisione è diventata un workflow prodotto o operativo ripetibile.
Esempi comuni:
- un prodotto vuole generare varianti immagine dopo che un utente invia un brief
- un workflow marketing deve creare bozze visive da input campagna strutturati
- uno strumento interno deve inviare job video o audio senza chiedere a qualcuno di aprire il browser
- un sistema support o contenuti vuole un turno modello chat nella propria interfaccia
- un servizio backend vuole callback firmate quando i job di generazione terminano
In questi casi, Rivya API mantiene il lavoro collegato allo stesso account Rivya invece di costringere a uno stack separato per billing, selezione modello e stato task.
Cosa non sostituisce l'API
L'API non sostituisce ogni motivo per usare Rivya direttamente.
Usa Studio o le superfici pubbliche di lavoro quando:
- il prompt ha ancora bisogno di esplorazione umana
- la scelta del modello non è stabile
- un creator deve confrontare output visivamente
- il progetto dipende da history salvata e revisione manuale
- il team non ha deciso quale formato input e output dovrebbe diventare ripetibile
Usa l'API quando il workflow è abbastanza chiaro da essere automatizzato.
Questo confine conta. Una domanda creativa vaga di solito appartiene prima a Studio. Un flusso prodotto noto con input prevedibili può passare all'API.
I blocchi principali
Pensa all'API come a sei pezzi collegati.
| Blocco | Cosa gestisce | Dove leggere dopo |
|---|---|---|
| API key | Accesso server-to-server dal tuo account | Autenticazione API |
| Modelli | ID modello pubblici e informazioni di readiness | Modelli API |
| Generazioni | Job asincroni immagine, video e audio | Crea generazione |
| File | Upload di immagini, video o audio di riferimento | Files API |
| Chat | Turni chat non-streaming o streaming | Chat API |
| Webhooks | Eventi di completamento firmati per job di generazione | API Webhooks |
I docs API sono la fonte per forma di richieste e risposte. Questo articolo dovrebbe aiutarti a decidere quale pezzo ti serve per primo.
Come funzionano i credit
L'uso API attinge dallo stesso wallet di credit account Rivya di Studio.
Significa che l'API non è un proxy anonimo per modelli. Una richiesta appartiene a un account Rivya, usa una API key creata da quell'account e segue lo stesso confine di credit a livello prodotto descritto in API Credits.
È utile per i team perché esperimenti Studio e uso API restano in un solo modello operativo. Puoi testare manualmente un modello, poi spostare la parte ripetibile in un'integrazione senza creare un secondo livello di billing.
Come si inseriscono i file
Alcuni modelli possono partire solo da testo. Altri hanno bisogno di un'immagine, video o file audio di riferimento.
Per integrazioni API, quei riferimenti dovrebbero passare da Files API. L'upload crea un record file gestito che può essere passato nei parametri modello supportati.
La regola pratica è semplice:
- se un modello accetta input text-only, parti dall'endpoint di generazione
- se un modello ha bisogno di media di riferimento, carica prima il file
- se il modello è chat con allegati immagine, usa Chat API e file ID
Non progettare la tua integrazione intorno a flussi upload solo browser o sessioni Studio salvate. L'API ha un proprio confine pubblico dei file per una ragione.
Dove aiutano i webhooks
Il polling è il primo percorso di integrazione più semplice. Invia un job di generazione, salva il task ID pubblico e fai polling finché riesce o fallisce.
I webhooks diventano utili quando l'integrazione è più simile alla produzione:
- non vuoi un worker che faccia polling per ogni job
- la tua app deve aggiornare un record quando la generazione termina
- vuoi un evento firmato che possa essere ritentato in sicurezza
- i job falliti devono entrare in un percorso di recovery chiaro
Per il contratto degli eventi firmati, usa API Webhooks. Mantieni stretto il receiver webhook: verifica le firme, gestisci eventi duplicati ed evita di mettere valori secret nei log.
Un buon primo progetto API
Il miglior primo progetto API è di solito piccolo e concreto.
Per esempio:
- crea una API key nelle impostazioni
- chiama la lista modelli
- scegli un modello disponibile
- invia un job di generazione con una idempotency key
- fai polling dell'endpoint di stato
- controlla i credit prima e dopo
- solo dopo aggiungi Files API, Chat API o Webhooks
Questo percorso ti dà un'integrazione funzionante senza mescolare ogni feature API nel primo test.
Quando l'API è il punto di partenza sbagliato
Probabilmente l'API non è il primo passo giusto quando:
- il team non ha ancora scelto una famiglia di modelli
- l'output desiderato cambia ancora a ogni run
- il prompt dipende da gusto e revisione manuale
- l'integrazione nasconderebbe l'uso dei credit alle persone che devono capirlo
- il prodotto ha bisogno di una demo pubblica prima di aver bisogno di automazione
In quei casi, parti da Image, Video, Audio, Chat o AI Models. Quando il percorso è ripetibile, sposta la parte stabile nell'API.
Dove andare dopo
- Apri Developers per l'hub API pubblico e il debugger.
- Leggi Rivya API Quickstart per fare la prima richiesta sicura.
- Leggi Autenticazione API prima di mettere una key su un server.
- Leggi Modelli API prima di scegliere gli ID modello.
- Leggi Quando usare Rivya API invece di Studio se il confine prodotto è ancora poco chiaro.
- Leggi Come costruire un workflow AI multimodale con Rivya API quando stai pianificando un'integrazione completa immagine, video, audio o chat.
