Come funziona SpicyAPI

Se sei alle prime armi, parti da qui. Questa pagina spiega con parole semplici che cosa fa SpicyAPI, ti aiuta a scegliere il modo di usarlo più adatto a te e presenta la manciata di concetti che il resto della documentazione dà per scontati. Per leggerla non serve saper programmare.

Che cos’è SpicyAPI

SpicyAPI ti dà un’unica chiave API per modelli di immagini, video e testo di tanti produttori diversi, e ti fa pagare a consumo, in dollari statunitensi.

Senza SpicyAPI, usare più modelli di IA vuol dire aprire un account presso ogni azienda, imparare il formato di richiesta di ciascuna e ricaricare ogni saldo per conto suo. Con SpicyAPI hai un solo account e un solo saldo. Scegli un modello, invii il prompt (più un’immagine di riferimento, se il modello la accetta) e ti torna un’immagine, un video o del testo. Se passi a un altro modello, il modo in cui invii la richiesta e ritiri il risultato non cambia.

• Una chiave, tanti modelli. Tutti i modelli di immagini e video si usano allo stesso modo: invii un’attività e poi ne ritiri il risultato. I modelli di testo accettano anche i formati di richiesta delle librerie ufficiali di OpenAI, Anthropic e Google Gemini.
• Paghi a consumo, in dollari. A seconda del modello, il prezzo è per immagine, per secondo di video, per richiesta o per token. Non ci sono abbonamenti e non c’è alcun sistema di crediti o punti: il prezzo che vedi è l’importo in dollari che viene scalato dal saldo. Non c’è nemmeno un piano gratuito, quindi prima della prima generazione devi aggiungere fondi. Vedi Fatturazione.
• Quando un’attività viene accettata, il suo costo stimato viene accantonato dal saldo. Se va a buon fine paghi ciò che ha effettivamente consumato, mai più di quell’importo. Le attività fallite o scadute normalmente liberano l’intero importo accantonato. Alcuni rifiuti di contenuto vengono addebitati al preventivo accettato, solo se la pagina del modello indica esplicitamente questa eccezione. Controlla settled e cost per conoscere l’importo finale.
• Nessun interruttore dei contenuti da impostare. SpicyAPI non richiede nelle richieste alcun flag sulla modalità dei contenuti e non esegue una revisione dei contenuti richiesta per richiesta. Che cosa produce un modello dipende da quel modello: alcuni rifiutano o attenuano certe richieste. La responsabilità di come usi ciò che generi resta tua; vedi Responsabilità su contenuti e utilizzo.

SpicyAPI non serve la Cina continentale, e anche poche altre regioni sono soggette a restrizioni; trovi i dettagli nella stessa pagina.

Che cosa puoi creare

Il catalogo contiene anche qualche attività video più specialistica, come far muovere un personaggio seguendo il movimento di un’altra clip o prolungare una clip esistente. I modelli vengono aggiunti e ritirati nel tempo, quindi su che cosa esiste oggi fa sempre fede il catalogo in tempo reale.

Per vedere i modelli attuali con immagini, descrizioni e prezzi, apri spicyapi.ai/explore. Lo stesso elenco è disponibile anche senza account né chiave, in JSON grezzo, se vuoi consultarlo da un terminale:

curl "https://api.spicyapi.ai/console/v1/catalog/models?locale=en&strict=1"

Il comando stampa un lungo blocco di testo. Ogni modello riporta una modality (image, video o text), i suoi tasks e un price di partenza. Questo elenco pubblico serve per curiosare; una volta che hai una chiave, l’elenco dei modelli che la tua chiave può chiamare davvero arriva da GET /api/v1/models. Vedi Catalogo nel glossario.

Scegli il tuo percorso

Ci sono cinque modi per cominciare. Condividono lo stesso account, lo stesso saldo, gli stessi modelli e gli stessi prezzi, quindi puoi partire da uno e aggiungerne un altro più avanti.

Provalo nel browser

• Adatto a: chiunque voglia vedere che cosa fa un modello prima di decidere qualsiasi cosa. Niente da installare, niente codice.
• Che cosa ti serve: un browser. Puoi aprire qualsiasi modello e compilarne il modulo anche senza account. Per premere Esegui devi aver effettuato l’accesso e avere un saldo.
• Costa qualcosa? Ogni esecuzione viene addebitata come una chiamata API. Le attività fallite o scadute normalmente liberano l’intero importo accantonato. Alcuni rifiuti di contenuto vengono addebitati al preventivo accettato, solo se la pagina del modello indica esplicitamente questa eccezione. Controlla settled e cost per conoscere l’importo finale.
• Da dove partire: apri spicyapi.ai/explore, scegli un modello e usa la scheda Playground nella sua pagina. Le esecuzioni concluse compaiono anche in Log, nella console.

Chiedi al tuo assistente IA

• Adatto a: chi usa già un assistente IA come Claude, Cursor, VS Code, Codex, Windsurf o Gemini CLI e vuole esplorare i modelli, confrontare i prezzi e generare immagini o video semplicemente chattando. Anche gli sviluppatori lo usano per esplorare prima di costruire.
• Che cosa ti serve: Node.js 22.13 o successivo, una chiave API e un’app assistente che supporti MCP. I passaggi a pagamento funzionano solo nelle app in grado di mostrarti una domanda di conferma.
• Costa qualcosa? Esplorare, chiedere preventivi e consultare i risultati è gratis. Avviare o ripetere una generazione si ferma prima e ti mostra il prezzo; l’assistente non può rispondere a quella domanda al posto tuo.
• Da dove partire: il server MCP mette a disposizione dell’assistente le azioni di SpicyAPI. L’Agent Skill insegna a un assistente di programmazione IA a scrivere integrazioni con SpicyAPI nel modo sicuro, e si abbina bene al server MCP.

Digita comandi in un terminale

• Adatto a: confrontare prezzi, generare immagini e video sul tuo computer salvando i file, ripetere lo stesso tipo di lavoro o lanciare un semplice script. Senza programmare.
• Che cosa ti serve: un terminale, Node.js 22.13 o successivo e una chiave API salvata nella variabile d’ambiente SPICY_API_KEY.
• Costa qualcosa? Solo spicyapi tasks create e spicyapi tasks retry possono addebitarti qualcosa, ed entrambi chiedono conferma prima di qualsiasi addebito.
• Da dove partire: Strumento a riga di comando (CLI).

Crea workflow a nodi in ComfyUI

• Adatto a: chi lavora già con ComfyUI e vuole usare modelli ospitati accanto ai propri nodi locali: concatenare un modello di immagini a un modello video, aggiungere una colonna sonora o lasciare che un modello di chat scriva il prompt.
• Che cosa ti serve: ComfyUI sul tuo computer o su un server e una chiave API. I modelli di SpicyAPI girano sui nostri server, quindi per loro non serve nessuna GPU.
• Costa qualcosa? Ogni esecuzione viene addebitata come una chiamata API. Ogni nodo mostra la propria tariffa, quota prima dell’esecuzione e può fermare qualsiasi esecuzione che superi un limite da te impostato.
• Da dove partire: Nodi ComfyUI.

Scrivi codice

• Adatto a: aggiungere la generazione di immagini, video o testo alla tua app, al backend del tuo sito o a una pipeline di dati.
• Che cosa ti serve: codice che giri su un server o sul tuo computer, perché una chiave API non va mai messa in una pagina web o in un’app mobile. Esistono SDK ufficiali per TypeScript (Node.js 22.13 o successivo), Python 3.11+, Go 1.23+, PHP 8.1+ e Java 17+; da qualsiasi altro linguaggio puoi chiamare direttamente l’API HTTP.
• Costa qualcosa? Ogni generazione accettata viene addebitata. Preventivi, letture del catalogo e consultazioni delle attività sono gratis.
• Da dove partire: l’SDK TypeScript per Node.js, oppure gli SDK Python, Go, PHP e Java. Per l’HTTP puro con esempi in curl, Node.js, Python e Go usa l’Avvio rapido; vedi Testo e streaming per i modelli di chat e il tutorial da immagine a video per un esempio completo dall’inizio alla fine.

Concetti che incontrerai ovunque

Per provare il Playground non ti serve nulla di tutto ciò, ma tutte le altre pagine lo danno per scontato. Qui ogni concetto ha una o due frasi, un link alla pagina che ne cura i dettagli e una voce più lunga, in linguaggio semplice, nel glossario.

Che cosa succede quando generi qualcosa

1. Scegli un modello e ne compili gli input.
2. Se vuoi, chiedi un preventivo: il prezzo esatto, gratis.
3. Invii. SpicyAPI accetta la richiesta come attività, ti restituisce un ID attività e accantona dal saldo il costo stimato.
4. Il modello lavora in background. Le immagini di solito richiedono pochi secondi; i video spesso qualche minuto.
5. L’attività termina. Se è riuscita, paghi ciò che ha effettivamente consumato, mai più dell’importo accantonato. Le attività fallite o scadute normalmente liberano l’intero importo accantonato. Alcuni rifiuti di contenuto vengono addebitati al preventivo accettato, solo se la pagina del modello indica esplicitamente questa eccezione. Controlla settled e cost per conoscere l’importo finale.
6. Ritiri il risultato, perché SpicyAPI richiama il tuo server oppure perché lo chiedi tu, e scarichi il file. I link di download sono temporanei e i file vengono conservati per un tempo limitato, quindi salva ciò che vuoi tenere.

ID del modello

Ogni modello ha un ID esatto nella forma publisher/model/task. Copialo dal catalogo in tempo reale (GET /api/v1/models, spicyapi models list o listModels()) invece di andare a memoria o di prenderlo da una pagina web: i modelli vengono aggiunti, messi in pausa e ritirati. Negli esempi di codice di questa documentazione, al posto dell’ID reale trovi scritto MODEL_ID_FROM_CATALOG. Catalogo dei modelli e schemi · Glossario: ID del modello

Le attività e i loro stati

La generazione di immagini e video è asincrona: inviare la richiesta e ritirare il risultato sono due passaggi separati, legati da un ID attività che inizia con job_. Un’attività passa da queued a running e si chiude come succeeded, failed o expired; qualsiasi stato diverso da queued o running è definitivo. I modelli di testo, invece, rispondono sulla stessa connessione, spesso parola per parola. Attività asincrone · Testo e streaming · Glossario: stato dell’attività

Preventivo

Un preventivo calcola il prezzo della tua richiesta esatta senza avviare nulla e senza accantonare denaro. Vale cinque minuti. Se invii la richiesta con quel preventivo e nel frattempo il prezzo o la richiesta sono cambiati, l’invio viene rifiutato anziché addebitato a un importo diverso. Preventivi e compatibilità di protocollo · Glossario: preventivo

Chiave di idempotenza

Un’etichetta che scegli tu per un singolo lavoro e che invii insieme alla richiesta. Se la connessione cade e rimandi la stessa richiesta con la stessa etichetta e la stessa chiave API entro 24 ore, ti torna l’attività originale invece di avviarne, e pagarne, una seconda. La CLI e il server MCP la creano per te; con l’SDK o con l’HTTP puro la passi tu. Idempotenza · Glossario: chiave di idempotenza

Callback

Invece di chiedere in continuazione se un’attività è finita, puoi assegnarle un callBackUrl: un indirizzo HTTPS pubblico sul tuo server. Quando l’attività finisce, SpicyAPI invia lì il risultato, firmato, così puoi verificare che arrivi davvero da SpicyAPI. Chiedere ripetutamente, cioè fare polling, va benissimo finché fai prove sul tuo computer. Webhook · Glossario: webhook

Per quanto tempo vengono conservati i risultati

Il link di download di un risultato dura circa 20 minuti; per averne uno nuovo, richiedi di nuovo l’attività. I file generati vengono conservati al massimo per circa 14 giorni, i file caricati per un giorno e il testo dei prompt per 30 giorni; puoi accorciare tutti e tre i periodi, oppure distruggere su richiesta i contenuti di una singola attività. I dati di fatturazione restano conservati molto più a lungo. Scarica tutto ciò che vuoi tenere. Conservazione e distruzione · Glossario: conservazione

Saldo e limiti di spesa

Il saldo è un importo prepagato in dollari statunitensi. Ogni chiave API può avere inoltre un limite di spesa giornaliero, uno mensile e uno complessivo, che imposti tu. Quando il saldo non basta a coprire un’attività ricevi l’errore 40201; quando raggiungi un limite ricevi 40202. In nessuno dei due casi viene creata un’attività o addebitato qualcosa. Fatturazione · Autenticazione · Glossario: limite di spesa

La prima volta, passo per passo

Dove trovare aiuto

• Risposte rapide: Domande frequenti, Glossario, Diagnosi e ripristino ed Errori.
• Il servizio funziona? status.spicyapi.ai.
• Parla con noi: apri una conversazione nella pagina Assistenza della console, oppure usa la pagina dei contatti. Indica il request_id o l’ID attività e l’orario in UTC. Non inviare mai la tua chiave API.

Per proseguire