Glossario

Questa documentazione usa parole tecniche perché il prodotto è un’API. Qui trovi ciascuna di queste parole spiegata con un linguaggio semplice, in ordine alfabetico. Ogni voce ha tre parti: che cosa significa la parola in generale, che cosa significa in SpicyAPI e quale pagina contiene tutti i dettagli.

Le altre pagine rimandano direttamente alle singole voci, quindi se una parola ti blocca altrove, con ogni probabilità la trovi qui. Per il quadro d’insieme, parti da Come funziona SpicyAPI.

Accantonamento, liquidazione e svincolo

Le tre fasi del pagamento di un’attività. Un accantonamento è denaro messo da parte ma non ancora speso, come quando un hotel blocca un importo sulla tua carta.

In SpicyAPI:

• Accantonamento: quando un’attività viene accettata, il suo costo stimato (estimatedCost) viene messo da parte dal saldo e compare come held. Non è ancora un addebito, ed è anche il massimo che quell’attività potrà mai costare.
• Liquidazione: quando l’attività riesce, ti viene addebitato ciò che ha effettivamente consumato, mai più dell’importo accantonato. Quello che avanza torna sul saldo disponibile. settled: true sull’attività significa che l’importo in cost è definitivo.
• Svincolo: 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.

Vedi: Fatturazione

Agent Skill

Una cartella di istruzioni scritte che un assistente di programmazione IA legge prima di mettersi al lavoro, un po’ come il manuale operativo che si consegna a un nuovo collega. Non contiene alcun programma e da sola non fa nulla.

In SpicyAPI: lo Skill ufficiale, pubblicato come @spicyapi/skill, insegna ad assistenti come Claude Code, Codex o Cursor a usare SpicyAPI nel modo corretto: leggere il catalogo in tempo reale invece di tirare a indovinare, mostrarti il prezzo prima di un lavoro a pagamento, riutilizzare le chiavi di idempotenza e non incollare mai la tua chiave API nel codice. Si installa con npx skills add spicyapi-ai/spicy-skill. Funziona bene insieme al server MCP.

Vedi: Agent Skill

API

Sigla di application programming interface, cioè interfaccia di programmazione delle applicazioni: un insieme fisso di richieste che un programma può inviare a un altro, con le risposte che ne riceve. Un sito web è fatto perché le persone ci clicchino sopra; un’API è fatta perché i programmi la chiamino.

In SpicyAPI: l’API è la strada attraverso cui ogni strumento raggiunge i modelli. Il Playground, la CLI, il server MCP e l’SDK inviano tutti ad api.spicyapi.ai gli stessi tipi di richieste che può inviare il tuo codice.

Vedi: OpenAPI ed elenco degli endpoint

Asset e URL di output

Un asset è un singolo file prodotto da un’attività, per esempio un’immagine o un video. Il suo URL di output è l’indirizzo web da cui lo scarichi.

In SpicyAPI: un’attività conclusa elenca i propri file in output.assets[]. Ognuno ha un url che puoi scaricare direttamente, senza chiave API, più expiresAt, mime (il tipo di file) e i dati sulle dimensioni. Il link dura circa 20 minuti; per averne uno nuovo, richiedi di nuovo l’attività. Il file vero e proprio viene conservato al massimo per circa 14 giorni, quindi salva una copia di tutto ciò che ti serve. Un asset con pending: true è ancora in fase di archiviazione (riprova tra qualche secondo); uno con unavailable: true è sparito per sempre.

Vedi: Attività asincrone · Media

Attività

Un’unità di lavoro che gira in background: la consegni e ne ritiri il risultato più tardi.

In SpicyAPI: ogni generazione di immagini o video è un’attività. POST /api/v1/jobs/createTask la accetta e restituisce un ID attività che inizia con job_; poi fai polling sull’attività oppure ricevi un webhook quando finisce. Tramite l’API, un’attività si può leggere solo con la stessa chiave API che l’ha creata; la pagina Log della console mostra tutte le attività del tuo account. Un’attività accettata non si può annullare.

Vedi: Attività asincrone · Impegno dell’attività e nuovi tentativi

Callback

Un altro nome del webhook. In SpicyAPI l’indirizzo si passa nel campo callBackUrl quando crei un’attività.

Caricamento

Inviare un file dal tuo computer a un server perché possa essere usato lì.

In SpicyAPI: un modello che accetta in input un’immagine, un video o un audio può riceverlo in tre modi: un link HTTPS pubblico al file, una piccola immagine incorporata nella richiesta come data URI (fino a 1 MiB) oppure un file caricato. Il caricamento richiede tre passaggi: chiedi un ticket (POST /api/v1/common/upload-url), invii il file all’indirizzo indicato nel ticket, poi lo confermi con il commit (POST /api/v1/files/{fileId}/commit). Il commit restituisce un indirizzo spicy:// da inserire nel campo di input del modello, utilizzabile per un giorno. Le immagini possono arrivare a 10 MiB, audio e video a 90 MiB e 600 secondi. uploadFile() dell’SDK, spicyapi files upload e il server MCP eseguono per te tutti e tre i passaggi.

Vedi: Media

Catalogo

L’elenco dei modelli disponibili, con i loro prezzi e gli input che ciascuno accetta.

In SpicyAPI: esistono due versioni dello stesso elenco.

• Il catalogo pubblico non richiede account né chiave. È quello che mostra spicyapi.ai/explore e che restituisce GET /console/v1/catalog/models. Usalo per esplorare e confrontare.
• Il catalogo autenticato, cioè GET /api/v1/models chiamato con la tua chiave API, è l’unica fonte affidabile dei modelli che la tua chiave può chiamare in questo momento, ai prezzi del tuo account. Prima di un lavoro a pagamento, scegli una voce in cui enabled e available valgono entrambi true.

Il comando della CLI spicyapi models list, il metodo dell’SDK listModels() e lo strumento MCP spicyapi_models_list leggono tutti il catalogo autenticato.

Vedi: Catalogo dei modelli e schemi

Chiave API

Una stringa segreta che dimostra che una richiesta arriva da te. Trattala come una password usata dai programmi.

In SpicyAPI: le chiavi iniziano con sk-spicy- e si creano nella pagina Chiavi API della console. Una chiave viene mostrata una sola volta: se la perdi, creane una nuova. Ogni richiesta invia la chiave nell’intestazione Authorization: Bearer. Tieni le chiavi sul tuo computer o sul tuo server, mai in una pagina web, in un’app mobile, in un repository pubblico, in uno screenshot o in una chat. Ogni chiave può avere i propri limiti di spesa, un elenco di modelli consentiti e un elenco di indirizzi IP consentiti.

Vedi: Autenticazione · Configura il tuo account

Chiave di idempotenza

Un’etichetta che inventi tu per un singolo lavoro, così che inviare due volte la stessa richiesta esegua il lavoro una volta sola. «Idempotente» vuol dire che rifare una cosa non produce ulteriori effetti.

In SpicyAPI: inviala nell’intestazione Idempotency-Key quando crei o ripeti un’attività, per esempio order-8814-render-1. Se la connessione cade e non sai se l’attività è partita, invia di nuovo la stessa richiesta con la stessa chiave e la stessa chiave API entro 24 ore: ti torna l’attività originale e non paghi due volte. Usa una chiave nuova per ogni nuovo lavoro. Se riutilizzi una chiave con una richiesta diversa, la richiesta viene rifiutata con 409. Le chiavi possono arrivare a 128 caratteri.

Vedi: Idempotenza

CLI

Sigla di command-line interface, cioè interfaccia a riga di comando: un programma che usi digitando comandi in un terminale invece di cliccare pulsanti.

In SpicyAPI: il comando spicyapi, pubblicato come @spicyapi/cli, ti permette di elencare i modelli, controllare i prezzi, creare attività di immagini e video, attenderle e scaricarne i risultati senza scrivere codice. Solo tasks create e tasks retry costano denaro, ed entrambi ti chiedono prima conferma. Richiede Node.js 22.13 o successivo; puoi avviarlo con npx @spicyapi/cli senza installarlo.

Vedi: Strumento a riga di comando (CLI)

Codice di errore

Un valore breve e fisso che dice a un programma che cosa è andato storto, così può reagire senza leggere il testo del messaggio.

In SpicyAPI: ce ne sono di due tipi.

• code nella struttura di risposta descrive la richiesta in sé. 200 indica il successo; tra gli altri ci sono 400 (richiesta non valida), 401 (problema con la chiave), 40201 (saldo insufficiente), 40202 (raggiunto un limite di spesa) e 429 (troppe richieste). È un codice applicativo, più preciso dello stato HTTP che viaggia insieme a esso.
• errorCode compare su un’attività che era stata accettata ma poi è fallita. Assume uno di nove valori: invalid_request, unsupported_combination, content_rejected, rate_limited, upstream_unavailable, generation_failed, timeout, invalid_asset o upstream_failed.

I messaggi corrispondenti, msg ed errorMessage, sono pensati per le persone: la loro formulazione può cambiare e possono arrivare nella lingua che hai scelto. I programmi devono prendere decisioni solo in base ai codici.

Vedi: Errori

Compatibile con OpenAI

Che accetta richieste nello stesso formato dell’API di OpenAI, così un software scritto per OpenAI funziona cambiando soltanto l’indirizzo e la chiave.

In SpicyAPI: i modelli di testo si possono chiamare tramite POST /v1/chat/completions e POST /v1/responses nel formato OpenAI, POST /v1/messages nel formato Anthropic e /v1beta/models/… nel formato Google Gemini, sempre con la stessa chiave API. Punta la libreria ufficiale openai su https://api.spicyapi.ai/v1. Qualsiasi modello di testo funziona con qualsiasi di questi formati. Questi endpoint applicano il prezzo in vigore nel momento in cui la richiesta viene accettata e non accettano preventivi, quindi imposta dei limiti di spesa sulla chiave.

Vedi: Testo e streaming

Conservazione

Per quanto tempo i dati archiviati vengono tenuti prima di essere eliminati.

In SpicyAPI:

Puoi accorciare la conservazione di file generati, caricamenti e testo dei prompt nella pagina Protezione dati della console, oppure per una singola attività con l’intestazione X-Spicy-Retention, e puoi distruggere i contenuti in qualsiasi momento con la distruzione (purge). Nessuna impostazione può allungare un periodo.

Vedi: Conservazione e distruzione

Distruzione dei contenuti (purge)

Cancellare definitivamente, su richiesta, i contenuti archiviati, invece di aspettare che scadano.

In SpicyAPI: POST /api/v1/jobs/purge (oppure Distruggi gli output nei Log della console, spicyapi tasks purge, purgeTask()) elimina i file generati di un’attività conclusa, il suo risultato e il testo del prompt contenuto nell’input. La registrazione di fatturazione resta: importo, modello, stato, orari e request_id. La distruzione non annulla l’attività, non rimborsa nulla ed è irreversibile. Funziona solo sulle attività concluse.

Vedi: Conservazione e distruzione

Endpoint

Una specifica richiesta accettata da un’API, identificata da un metodo HTTP (come GET per leggere o POST per inviare) e da un percorso.

In SpicyAPI: per esempio, POST /api/v1/jobs/createTask avvia una generazione e GET /api/v1/jobs/recordInfo legge un’attività. L’indirizzo completo è l’URL di base seguito dal percorso.

Vedi: OpenAPI ed elenco degli endpoint

Firma (HMAC)

Un codice calcolato a partire da un messaggio e da un segreto condiviso, con cui chi riceve può verificare che il messaggio sia autentico e non sia stato modificato lungo la strada. HMAC è il metodo standard per calcolarlo.

In SpicyAPI: ogni consegna di webhook porta un’intestazione X-Webhook-Signature: un HMAC-SHA256 calcolato sull’ID attività, sull’orario della consegna e su un’impronta del corpo esatto, usando la tua chiave di firma dei webhook. Generi o ruoti quella chiave nella pagina Webhook della console, e viene mostrata solo in quel momento; se non l’hai mai copiata, ruotala da lì. Verifica la firma prima di fidarti di una consegna, con verifyWebhook dell’SDK o con spicyapi webhooks verify, e rifiuta le consegne il cui timestamp si discosta di più di cinque minuti dall’ora attuale.

Vedi: Webhook

ID del modello

Il nome esatto che invii per scegliere un modello.

In SpicyAPI: gli ID hanno la forma publisher/model/task: chi ha creato il modello, quale modello e versione, e che cosa fa l’endpoint. Gli endpoint di modifica delle immagini terminano con edit. Copia sempre l’ID dal catalogo in tempo reale (GET /api/v1/models, spicyapi models list o listModels()), mai a memoria o da una pagina web, perché i modelli vengono aggiunti, messi in pausa e ritirati. Negli esempi di questa documentazione, dove andrebbe un ID reale trovi scritto MODEL_ID_FROM_CATALOG; se invii il segnaposto così com’è, la richiesta fallisce.

Vedi: Catalogo dei modelli e schemi

JSON

Un formato di testo semplice per dati strutturati, fatto di nomi e valori racchiusi tra parentesi graffe. Lo usa quasi ogni API, perché qualsiasi linguaggio di programmazione è in grado di leggerlo.

In SpicyAPI: richieste e risposte sono in JSON. Una richiesta di attività minima si presenta così:

{ "model": "MODEL_ID_FROM_CATALOG", "input": { "prompt": "A paper lantern on a rainy street at night" } }

MODEL_ID_FROM_CATALOG sta al posto di un ID del modello reale, preso dal catalogo in tempo reale. Gli importi di denaro viaggiano sempre come testo, per esempio "0.008", così nessun importo viene mai arrotondato per sbaglio.

Vedi: Avvio rapido

Limite di frequenza

Un tetto al numero di richieste che puoi inviare in un certo periodo di tempo, così un programma fuori controllo non può sovraccaricare un servizio.

In SpicyAPI: per impostazione predefinita l’API nativa ammette 1.000 richieste ogni 10 secondi per account, per le letture e altrettante per le scritture, e ciascuna quota è condivisa tra tutte le chiavi dell’account. Il polling conta come lettura, quindi un ciclo di polling intenso non può bloccare l’invio delle tue attività. Chi lo supera riceve 429 con un’intestazione Retry-After che indica quanti secondi aspettare. Il limite conta le richieste, non le attività: le attività già in esecuzione non lo consumano.

Vedi: Limiti di frequenza

Limite di spesa

Un tetto di spesa che fissi in anticipo, così un errore o una chiave trapelata non possono consumare tutto il tuo saldo.

In SpicyAPI: ogni chiave API può avere un limite giornaliero, uno mensile e uno complessivo in dollari statunitensi, che imposti tu; le chiavi nuove non ne hanno alcuno finché non ne aggiungi uno. I team possono aggiungere budget giornalieri e mensili, e la piattaforma ha un proprio limite giornaliero. Un’attività che supererebbe uno qualsiasi di questi limiti viene rifiutata con 40202 prima di partire, e non viene addebitato nulla. I limiti giornalieri ripartono alle 00:00 UTC e quelli mensili il 1º del mese; i limiti complessivi non ripartono mai. Inserire 0 significa nessun limite a quel livello.

Vedi: Fatturazione · Autenticazione

MCP

Sigla di Model Context Protocol: uno standard aperto che permette agli assistenti IA di caricare capacità aggiuntive, chiamate strumenti, da piccoli programmi chiamati server MCP.

In SpicyAPI: il server ufficiale, @spicyapi/mcp, gira sul tuo computer e dà ad assistenti come Claude, Cursor, VS Code o Codex 15 strumenti SpicyAPI: esplorare i modelli, ottenere preventivi, creare attività, caricare file e recuperare i risultati. Quando si tratta di avviare, ripetere o distruggere un’attività, il server si ferma e chiede conferma a te, mostrando il prezzo quando ce n’è uno; l’assistente non può rispondere al posto tuo. Richiede Node.js 22.13 o successivo.

Vedi: Server MCP

Modalità

Il tipo di media con cui lavora un modello.

In SpicyAPI: ogni voce del catalogo ha una modality, come image, video o text, e un elenco di tasks, come text-to-image o image-to-video. Usali per filtrare il catalogo, per esempio GET /api/v1/models?modality=video&task=image-to-video.

Vedi: Catalogo dei modelli e schemi

Node.js

Un programma gratuito che esegue JavaScript fuori dal browser. Molti strumenti per sviluppatori sono scritti in JavaScript e per funzionare hanno bisogno che sia installato.

In SpicyAPI: l’SDK, la CLI e il server MCP richiedono Node.js 22.13 o successivo; l’installer usato dallo Skill chiede la 22.20 o successiva. Installa la versione LTS da nodejs.org, poi verificala in un terminale con node --version. Node.js non ti serve per il Playground, né se chiami l’API da un altro linguaggio.

Vedi: CLI: prima di iniziare

npm e npx

npm è il gestore di pacchetti che arriva insieme a Node.js: scarica e installa pacchetti JavaScript. npx, incluso anch’esso, esegue un pacchetto senza installarlo in modo permanente.

In SpicyAPI: i quattro strumenti per Node.js sono pacchetti npm: @spicyapi/sdk, @spicyapi/cli, @spicyapi/mcp e @spicyapi/skill. Per esempio, npm install @spicyapi/sdk aggiunge l’SDK TypeScript a un progetto, e npx @spicyapi/cli status esegue la CLI una volta, senza installarla. Gli SDK per Python, Go, PHP e Java si installano invece con gli strumenti dei rispettivi ecosistemi; vedi la pagina di ciascun SDK.

Vedi: SDK TypeScript · Strumento a riga di comando (CLI)

Playground

Un modulo su un sito web con cui provi un modello compilando dei campi e premendo un pulsante, senza scrivere codice.

In SpicyAPI: ogni pagina di modello su spicyapi.ai ha una scheda Playground. Anche senza account puoi compilare il modulo e vedere la richiesta che ne risulta; per eseguirla devi aver effettuato l’accesso e avere un saldo. Ogni esecuzione mostra prima il costo stimato, viene addebitata come una chiamata API e compare nei Log della console.

Vedi: Come funziona SpicyAPI

Polling

Chiedere a un server più e più volte se qualcosa è finito, invece di aspettare che sia lui ad avvisarti.

In SpicyAPI: fai polling su un’attività con GET /api/v1/jobs/recordInfo?taskId=… finché il suo stato non è più queued né running. Aspetta 2–3 secondi prima del primo controllo, allunga ogni attesa di circa 1,5 volte fino a 10–15 secondi e smetti di aspettare a una scadenza scelta da te. Smettere di aspettare non ferma l’attività. Il polling conta nel tuo limite di frequenza, quindi in produzione preferisci un webhook.

Vedi: Attività asincrone

Preventivo

Un prezzo calcolato in anticipo per una singola richiesta esatta.

In SpicyAPI: POST /api/v1/jobs/quote riceve lo stesso corpo che invieresti per creare l’attività e restituisce estimatedCost, maxCharge ed expiresAt, senza creare alcuna attività e senza accantonare denaro. Non costa nulla e vale cinque minuti. Se invii la richiesta con i quoteId ed expectedCost restituiti e nel frattempo la richiesta o il prezzo sono cambiati, l’invio viene rifiutato con 40901 invece di addebitarti un importo diverso. La CLI e il server MCP chiedono automaticamente un preventivo prima di creare un’attività.

Vedi: Preventivi e compatibilità di protocollo

request_id

Un identificativo che il server associa a una singola richiesta, così da poterla ritrovare nei log.

In SpicyAPI: ogni risposta nativa riporta un request_id (per esempio req_01k3…), inviato anche nell’intestazione X-Request-Id, sia in caso di successo sia in caso di errore. Conservalo nei tuoi log e indicalo quando contatti l’assistenza. In un webhook di versione 2, invece, request_id identifica quella consegna (whd_…) e resta invariato quando la consegna viene ritentata.

Vedi: Errori · Webhook

Saldo

Il denaro nel tuo account con cui paghi le generazioni.

In SpicyAPI: un saldo prepagato in dollari statunitensi, senza crediti né punti. Quello che versi non scade mai; il bonus promozionale ha una sua data di scadenza. Aggiungi fondi dalla pagina Fatturazione della console. GET /api/v1/chat/credit restituisce tre importi scritti come testo, per esempio "128.42": available (spendibile), held (accantonato per le attività ancora in corso) e total. Alcuni account hanno anche bonus promozionali o una linea di credito approvata, che compaiono in un dettaglio a parte. Non esiste un piano gratuito: gli account nuovi partono da zero.

Vedi: Fatturazione · Configura il tuo account

Schema di input

Una descrizione leggibile dalle macchine di quali campi può contenere una richiesta, di che tipo è ciascuno e quali valori sono ammessi.

In SpicyAPI: ogni modello ha il proprio inputSchema, scritto in JSON Schema. Elenca i campi che puoi mettere in input, come prompt, image_url o duration_seconds, con i loro limiti e valori predefiniti. Il server confronta ogni richiesta con lo schema, e basta un solo campo sconosciuto per ottenere un errore 400. Il Playground costruisce il proprio modulo a partire dallo stesso schema, e gli examples del catalogo sono input completi che lo hanno già superato.

Vedi: Catalogo dei modelli e schemi · Contratto Spicy Schema

SDK

Sigla di software development kit: una libreria di codice già pronta che aggiungi al tuo programma, così non devi costruire a mano ogni richiesta.

In SpicyAPI: esistono cinque SDK ufficiali: @spicyapi/sdk per TypeScript e JavaScript su Node.js, più uno ciascuno per Python, Go, PHP e Java. Ognuno si occupa della chiave, dell’attesa delle attività, dei nuovi tentativi, dei caricamenti e della verifica dei webhook, così bastano un paio di chiamate per portare un’attività dall’invio al risultato. Funzionano tutti solo sui server, non nei browser né nelle app mobili, e nessuno di loro copre i modelli di chat.

Vedi: SDK TypeScript · SDK Python · SDK Go · SDK PHP · SDK Java

Spazio di lavoro e team

Uno spazio condiviso in cui più persone usano le stesse chiavi, attività e budget sotto un unico account.

In SpicyAPI: lo spazio di lavoro di un team ha membri con ruoli: owner, admin, developer, billing e readonly. Ogni membro vede i riepiloghi delle attività e i consumi; owner, admin e developer vedono anche input e risultati delle attività. Le nuove attività del team le paga l’account del proprietario, e i membri non vedono mai il saldo né i pagamenti personali del proprietario. I team possono impostare budget giornalieri e mensili.

Vedi: Console e team

Stato dell’attività

Il punto in cui si trova un’attività nel suo ciclo di vita.

In SpicyAPI:

I record più vecchi possono mostrare anche canceled, che le attività nuove non raggiungono mai. Considera qualsiasi stato diverso da queued o running uno stato terminale.

Vedi: Attività asincrone

Stato HTTP

Un numero di tre cifre all’inizio di ogni risposta web che indica, a grandi linee, com’è andata la richiesta. 2xx significa che ha funzionato, 4xx che qualcosa nella richiesta non andava e 5xx che il server ha avuto un problema.

In SpicyAPI: la creazione di un’attività risponde 202 Accepted, che significa che l’attività è stata accettata, non che è già finita. Le risposte native riportano anche un code applicativo più preciso: per esempio, un saldo insufficiente è HTTP 402 con code 40201. Nel tuo codice scegli uno dei due su cui basare le decisioni e restaci fedele.

Vedi: Errori

Stato terminale

Uno stato finale: una volta che un’attività lo raggiunge, non cambia mai più.

In SpicyAPI: qualsiasi stato dell’attività diverso da queued o running è terminale: succeeded, failed, expired e, nei record più vecchi, canceled. Nel codice verifica «né queued né running» invece di elencare gli stati finali, così il codice continua a funzionare anche se ne viene aggiunto uno nuovo. I webhook vengono inviati solo quando un’attività raggiunge uno stato terminale. Si possono distruggere solo le attività concluse, e si possono ripetere le attività failed o expired.

Vedi: Attività asincrone

Streaming (SSE)

Inviare una risposta un pezzo alla volta, man mano che viene prodotta, su un’unica connessione aperta, invece che tutta insieme alla fine. SSE, sigla di server-sent events, è il formato web più diffuso per farlo.

In SpicyAPI: i modelli di testo possono trasmettere la risposta parola per parola tramite gli endpoint compatibili (per esempio con stream: true su /v1/chat/completions) o tramite l’endpoint nativo POST /api/v1/jobs/stream. Ogni protocollo segnala a modo suo la fine dello stream. Chiudere la connessione in anticipo interrompe la ricezione del testo ma non ferma il modello, e il consumo viene addebitato lo stesso. Il testo in streaming non viene archiviato, quindi non si può recuperare in seguito.

Vedi: Testo e streaming

Struttura di risposta (envelope)

Un involucro esterno fisso in cui viene inserita ogni risposta, così un programma sa sempre dove guardare.

In SpicyAPI: le risposte dell’API nativa (sotto /api/v1) hanno questo aspetto:

{ "code": 200, "msg": "success", "data": {}, "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2" }

code è un codice applicativo (200 significa successo), msg è un messaggio leggibile da una persona, data contiene la risposta e in caso di errore manca del tutto, e request_id identifica questa richiesta. Gli endpoint compatibili con OpenAI, Anthropic e Gemini usano invece le strutture dei rispettivi protocolli.

Vedi: Errori

Terminale

Una finestra di testo in cui digiti comandi e premi Invio per eseguirli. Su macOS è l’app Terminale (Terminal); su Windows usa PowerShell; sulla maggior parte dei desktop Linux se ne apre uno con Ctrl + Alt + T. Da non confondere con uno stato terminale.

In SpicyAPI: il terminale ti serve per eseguire la CLI, per installare strumenti Node.js come il server MCP o lo Skill e per provare gli esempi curl di questa documentazione.

Vedi: CLI: prima di iniziare

URL di base

La prima parte, sempre uguale, di ogni indirizzo usato da un’API. La scrivi una volta sola nel codice o nelle impostazioni dello strumento, e ogni richiesta ci aggiunge dopo il proprio percorso.

In SpicyAPI: ce ne sono due.

Le richieste in formato Google Gemini vanno a https://api.spicyapi.ai/v1beta. Le librerie ufficiali di Anthropic e di Google GenAI aggiungono da sole la parte con la versione, quindi per loro imposti soltanto https://api.spicyapi.ai.

Vedi: Avvio rapido · Testo e streaming

Variabile d’ambiente

Un valore con un nome che il terminale passa a ogni programma che avvia. Permette a un programma di leggere un’impostazione, per esempio una chiave segreta, senza che il valore compaia scritto in un file o in un comando.

In SpicyAPI: l’SDK, la CLI, il server MCP e gli esempi di codice di questa documentazione leggono la tua chiave API da una variabile chiamata SPICY_API_KEY. Per impostarla nella finestra del terminale in cui ti trovi:

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

Questa impostazione viene dimenticata quando chiudi la finestra. La pagina della CLI spiega come renderla permanente e come verificarla senza stampare l’intera chiave.

Vedi: CLI: prima di iniziare · Configura il tuo account

Webhook

Un indirizzo sul tuo server che un altro servizio chiama quando succede qualcosa, così non devi continuare a chiedere. Si chiama anche callback.

In SpicyAPI: inserisci un indirizzo HTTPS pubblico in callBackUrl quando crei un’attività. Quando l’attività raggiunge uno stato terminale, SpicyAPI invia lì una richiesta POST con lo stesso contenuto che restituirebbe recordInfo, firmata con la tua chiave di firma dei webhook. Rispondi con uno stato 2xx qualsiasi entro 15 secondi; altrimenti la consegna viene ritentata, fino a otto tentativi in circa nove ore, e puoi rinviarla dalla pagina Webhook della console. Non arriva alcuna notifica quando un’attività si limita a partire. Gli indirizzi locali come http://localhost:3000 non possono ricevere webhook, quindi mentre sviluppi sul tuo computer usa il polling.

Vedi: Webhook