Run
Un run è una singola richiesta di generazione. Quando chiami l'API, Runbase crea un run, lo invia al modello AI sottostante e restituisce il risultato quando è pronto.
Ogni run segue un ciclo di vita:
POST /api/v1/runs → pending → processing → succeeded (or failed)
Stati del run
| Stato | Significato |
|---|---|
pending | In coda, in attesa che un worker lo prenda in carico |
processing | In generazione attiva presso il provider AI |
succeeded | Generazione completata — output.urls contiene il risultato |
failed | Generazione fallita — error descrive cosa è andato storto |
Asincrono per progettazione
Tutta la generazione è asincrona. Quando crei un run, l'API risponde immediatamente con status: "pending" e un ID del run. Poi esegui il polling di GET /api/v1/runs/:id finché lo stato non è succeeded o failed.
I tempi di completamento variano in base al modello, al carico del provider e alla complessità dell'input:
- I modelli immagine di solito completano più velocemente dei modelli video
- I modelli video dipendono molto dalla durata, dalla risoluzione e dal tempo di coda del provider
Costo e rimborsi
Il costo viene detratto dal tuo balance quando il run viene creato, non quando viene completato. Questo riserva i fondi in anticipo.
Se il run fallisce, il costo totale viene rimborsato automaticamente sul tuo balance. Non paghi mai per generazioni fallite.
Modelli
Runbase è un gateway unificato verso modelli di più provider. Ogni modello ha un ID univoco nel formato provider/model-name (ad es. openai/gpt-image-2, bytedance/seedance-2).
Tutti i modelli condividono la stessa API a due endpoint:
POST /api/v1/runs— crea un run con un ID modello e un inputGET /api/v1/runs/:id— controlla lo stato e recupera i risultati
Lo schema di input varia in base al modello (parametri diversi per prompt, dimensione, qualità, image_urls, ecc.), ma il wrapper della richiesta/risposta è sempre lo stesso.
Autenticazione
Ogni richiesta API richiede una chiave API nell'header Authorization come token Bearer. Le chiavi iniziano con sk- e possono essere create nella dashboard. Vedi Authentication per i dettagli.
Balance
Runbase utilizza un balance prepagato. Ricarichi il tuo balance e ogni run ne deduce una parte in base al prezzo del modello. Vedi Billing per i dettagli.