Strumento a riga di comando (CLI)

Che cos’è la CLI

spicyapi è un piccolo programma che esegui in un terminale, la finestra in cui scrivi comandi invece di fare clic sui pulsanti. Ogni comando svolge un solo compito: elencare i modelli che il tuo account può usare, dirti quanto costerà una generazione, avviare la generazione di un’immagine o di un video, attendere che finisca e darti un link per scaricare il risultato.

Non scrivi alcun codice. Digiti un comando, premi Invio e leggi la risposta.

È la scelta giusta quando vuoi:

• provare i modelli e confrontarne i prezzi prima che qualcuno scriva un’integrazione;
• generare immagini o video dal tuo computer e salvare i file;
• ripetere lo stesso tipo di generazione senza dover cliccare ogni volta attraverso una pagina;
• controllare le impostazioni esatte di un modello prima di costruirci sopra qualcosa.

La CLI copre la generazione di immagini e video. I modelli di testo e di chat si chiamano tramite gli endpoint compatibili con la chat descritti in Testo e streaming.

Esistono altri tre strumenti ufficiali. Scegli la CLI se vuoi digitare i comandi tu stesso:

Scrivi in un altro linguaggio? Ci sono SDK ufficiali anche per Python, Go, PHP e Java.

Che cosa puoi fare

Nei comandi qui sopra, una parola tra parentesi angolari come <task-id> significa «metti qui il tuo valore», senza le parentesi.

Prima di iniziare

Ti servono quattro cose: un terminale, Node.js, una chiave API e un modo per eseguire la CLI. La prima volta richiede una decina di minuti.

node -v

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

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

npx @spicyapi/cli status

Il tuo primo risultato

Questo percorso guidato genera un’immagine e la scarica. Ogni passaggio mostra il comando, più o meno che cosa vedrai e che cosa è appena successo. I tuoi numeri, ID e orari saranno diversi.

spicyapi status

SpicyAPI is reachable — api.spicyapi.ai answered in 523 ms.

spicyapi balance

available: 12.34
held: 0.06
total: 12.40

spicyapi models list --modality image --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example image model",
      "modality": "image",
      "tasks": ["text-to-image"],
      "enabled": true,
      "available": true,
      "pricing": [
        { "variant": "", "unit": "per_image", "price": "0.03", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

{
  "model": "MODEL_ID_FROM_CATALOG",
  "enabled": true,
  "available": true,
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" },
      "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "9:16"] }
    },
    "additionalProperties": false
  }
}

cat > input.json <<'EOF'
{"prompt": "A paper lantern glowing on a rainy street at night, cinematic light"}
EOF

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: 0.03
maxCharge: 0.03
currency: USD
quantity: 1
unit: per_image
expiresAt: 2026-09-17T08:05:00Z

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z. Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241. Continue? [y/N]

Accepted: job_01k3m8x9q2z4v7n5p6r8s0t1w3
If waiting is interrupted: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
accepted: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","state":"queued","estimatedCost":"0.03","deadlineAt":"2026-09-17T08:30:00Z"}
task: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","model":"MODEL_ID_FROM_CATALOG","state":"succeeded","output":{"assets":[{"key":"tasks/…/result.png","url":"https://…","expiresAt":"2026-09-17T08:20:00Z","mime":"image/png","width":1024,"height":1024}]},"cost":"0.03","settled":true,…}

curl -L -o result.png "PASTE_THE_URL_HERE"

Come leggere l’output

• L’output normale mostra una coppia name: value per riga. I valori composti da più parti, come output o retention, vengono stampati come JSON su un’unica riga.
• --json stampa la risposta completa come JSON indentato. Funziona con ogni comando, prima o dopo il nome del comando: spicyapi --json balance e spicyapi balance --json sono equivalenti.
• I risultati vanno sull’output normale dello schermo; i messaggi vanno sull’output degli errori. I prezzi, la chiave di idempotenza, le righe Accepted: e gli errori sono messaggi. Quindi spicyapi --json tasks get <task-id> > task.json salva in task.json solo il risultato, mentre i messaggi continuano a comparire sullo schermo.
• Gli errori hanno la forma Error: <what went wrong> (request req_…), di solito seguiti da una riga Next: che dice che cosa fare. Con --json, un errore è un oggetto JSON su una riga con error, type, status, code e requestId, senza riga Next:. Quando non è impostata alcuna chiave, type vale MissingApiKeyError. Se contatti l’assistenza, riporta il valore req_….
• Il denaro è un importo in dollari statunitensi scritto come semplice testo senza il simbolo $, per esempio 0.03.
• Gli orari sono in UTC. La Z alla fine di 2026-09-17T08:05:00Z significa UTC.
• Il codice di uscita è 0 quando un comando riesce e diverso da 0 quando fallisce, e gli script possono controllarlo.

Riferimento dei comandi

Ogni comando ha anche un aiuto integrato: aggiungi --help, per esempio spicyapi tasks create --help.

Opzioni globali e variabili d’ambiente

Queste opzioni funzionano con ogni comando.

status

Che cosa fa: verifica se SpicyAPI è in funzione e raggiungibile dal tuo computer.

spicyapi status

Nessuna opzione. Non serve la chiave. Gratuito.

Output: una frase. SpicyAPI is reachable — … answered in … ms. significa che è tutto a posto. could not be reached significa che il tuo computer non ha ricevuto risposta: controlla la rete o il proxy. is not healthy o reports it is not ready indicano un problema da parte nostra; gli incidenti in corso sono elencati su status.spicyapi.ai.

Con --json vedi i controlli grezzi. La risposta che conta è operational: true; una voce readiness con stato 404 è normale sull’indirizzo pubblico.

docs search

Che cosa fa: trova la pagina della documentazione su un argomento. Cerca in un piccolo indice incluso nella CLI, quindi funziona senza chiave e senza chiamare SpicyAPI. Ogni risultato rimanda alla pagina su questo sito di documentazione, docs.spicyapi.ai.

spicyapi docs search [words] [--limit <count>]

spicyapi docs search retention

slug: retention
title: Retention and destruction
summary: What the platform caps are, how far down you can dial them, how to destroy a task's content, and what we cannot promise.
keywords: ["privacy","delete","storage","retention","per-request retention","purge","destroy"]
url: https://docs.spicyapi.ai/docs/retention

Quando ci sono più risultati, vengono stampati uno dopo l’altro e ciascuno inizia con slug:. Se non trova nulla, lo dice ed esce comunque con codice 0:

No documentation matched "refnd". Try fewer or different words, or run `spicyapi docs search` without words to browse pages.

Con --json, quando non trova nulla stampa un elenco vuoto, []. Gratuito.

models list

Che cosa fa: elenca i modelli che il tuo account può chiamare oggi, con i prezzi che paga il tuo account.

spicyapi models list [options]

spicyapi models list --modality video --task image-to-video --json

Output: total e items. Usa --json, perché senza tutte le voci vengono stampate su una sola riga. I campi più utili di ogni voce:

Gratuito. La lettura dell’elenco dei modelli conta nel limite di richieste del tuo account, quindi non serve eseguirla prima di ogni generazione.

models get

Che cosa fa: mostra un modello per intero, comprese le impostazioni che accetta.

spicyapi models get <model>

spicyapi models get MODEL_ID_FROM_CATALOG --json

Output: gli stessi campi di models list, più inputSchema. In inputSchema leggi required (le impostazioni che devi inviare), properties (ogni impostazione ammessa e il suo tipo), enum (gli unici valori ammessi), minimum e maximum (i limiti numerici) e default (il valore usato quando ometti l’impostazione). Le voci chiamate x-ui sono suggerimenti per costruire moduli; puoi ignorarle. Gratuito.

balance

Che cosa fa: mostra quanto denaro è disponibile sul tuo account.

spicyapi balance

Nessuna opzione. Gratuito.

Output: available (quanto puoi spendere adesso), held (l’importo accantonato per le attività ancora in corso) e total, tutti in dollari statunitensi. Può includere anche funding, che suddivide il saldo tra fondi prepagati e bonus promozionali, indicando anche quando scadono i bonus e per quali modelli si possono usare. Non devi controllare il saldo prima di ogni generazione: tasks create lo controlla al posto tuo.

usage

Che cosa fa: mostra quante generazioni ha eseguito la chiave API attuale e quanto sono costate, raggruppate per giorno e per modello.

spicyapi usage [--from <date>] [--to <date>]

spicyapi usage --from 2026-09-01 --to 2026-10-01

Questo comando copre tutto settembre: --to è il primo giorno non incluso. Ometti entrambe le opzioni per vedere gli ultimi sette giorni, oggi compreso.

Output: from, to, currency, totalCalls, totalSpend, poi days (per ogni giorno: calls, succeeded, failed, spend) e models (gli stessi numeri per modello). totalSpend conta solo gli addebiti definitivi. days e models descrivono le stesse attività in due modi, quindi non sommarli tra loro. Per l’intero account invece che per una sola chiave, usa la pagina Consumi della console.

Gratuito. È limitato a 30 chiamate al minuto, quindi usalo per controllare i totali, non dentro un ciclo.

tasks quote

Che cosa fa: ti dice esattamente quanto costerebbe una generazione, senza avviarla e senza accantonare alcun importo.

spicyapi tasks quote --model <model> --input-file <path>

Output: quoteId, model, estimatedCost, maxCharge, currency, quantity (per esempio il numero di secondi addebitati), unit e expiresAt. Un preventivo vale cinque minuti.

Gratuito, senza conferma. Usalo per confrontare modelli o impostazioni. Non è obbligatorio eseguirlo prima di tasks create, che chiede un proprio preventivo.

tasks create

Che cosa fa: avvia la generazione di un’immagine o di un video. Costa denaro. La CLI mostra sempre prima il prezzo e chiede conferma.

spicyapi tasks create --model <model> --input-file <path> [options]

Che cosa succede, nell’ordine:

1. La CLI legge il tuo input e controlla che sia un oggetto JSON. Se non hai fornito alcun input, si ferma qui.
2. Se nessuno può rispondere a una domanda, per esempio dentro uno script, e non hai passato --yes, si ferma qui.
3. Chiede un preventivo e stampa l’addebito stimato, l’addebito massimo, la scadenza del preventivo e la chiave di idempotenza.
4. Chiede Continue? [y/N]. Si prosegue solo con y o yes. La risposta predefinita è no.
5. Crea l’attività al prezzo del preventivo. L’importo stimato viene accantonato dal tuo saldo, e quell’importo è anche il massimo che l’attività può costare.
6. Senza --wait, stampa idempotencyKey, taskId, state (queued), estimatedCost e deadlineAt, poi ritorna. Con --wait, stampa subito Accepted: <task-id> e un comando di ripristino, attende, poi stampa idempotencyKey, accepted e l’attività finita in task.

deadlineAt è l’ora limite entro cui l’attività può finire prima di terminare come expired. Non indica quando scadono il link di download o i file.

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Su macOS e Linux puoi anche passare l’input direttamente nel comando:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-json '{"prompt": "A paper lantern on a rainy street"}'

Quando l’attesa fallisce con un errore (e non per Ctrl + C), le ultime righe ripetono tutto ciò che ti serve, così non devi scorrere indietro per ritrovare la riga Accepted::

Error: task job_01k3m8x9q2z4v7n5p6r8s0t1w3 did not reach a terminal state within 600000ms
Task job_01k3m8x9q2z4v7n5p6r8s0t1w3 was accepted and may still be running; only the wait stopped.
Recover: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3
To replay the same request without creating a second task, reuse --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241.

Se l’errore ha una soluzione nota, come un 429 o un errore del server, segue una riga Next:. Con --json, le stesse informazioni si trovano nell’oggetto di errore come taskId, idempotencyKey e recover.

tasks wait

Che cosa fa: attende un’attività che hai già avviato, finché non finisce.

spicyapi tasks wait <task-id> [options]

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000

Output: l’attività finita, con gli stessi campi di tasks get, non appena il suo stato è succeeded, failed o expired. Se l’attività è riuscita ma i suoi file vengono ancora copiati, attende ancora un po’.

Se il tempo limite si esaurisce, vedi Error: task … did not reach a terminal state within 600000ms. Non è un fallimento: l’attività è ancora in corso. Attendi di nuovo, se serve con un --wait-timeout-ms più lungo. Interrompere un’attesa non annulla mai un’attività. Gratuito.

tasks get

Che cosa fa: mostra un’attività in questo momento: il suo stato, il costo, i link ai risultati e quando verranno eliminati i suoi contenuti.

spicyapi tasks get <task-id>

Usa la stessa chiave API che ha creato l’attività: con un’altra chiave ottieni «not found».

Campi dell’output:

L’output normale termina con un riepilogo in linguaggio semplice, come Outputs expire: … o Content: Destroyed — you removed the outputs …. Ogni chiamata restituisce link di download nuovi. Gratuito.

tasks list

Che cosa fa: elenca le attività create con la chiave API attuale, una pagina alla volta.

spicyapi tasks list [options]

spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --state failed

Output: items (ciascuna voce con taskId, model, state, cost, settled, createdAt, deadlineAt e completedAt), hasMore e nextCursor. Se hasMore vale true, esegui di nuovo lo stesso comando con gli stessi --from e --to, aggiungendo --cursor e il valore di nextCursor. L’elenco non contiene link di download; usa tasks get per l’attività che ti interessa. Gratuito.

tasks retry

Che cosa fa: esegue di nuovo un’attività failed o expired, come nuova attività con un nuovo ID. Costa denaro.

spicyapi tasks retry <task-id> [options]

Chiede Retry source task … Continue? [y/N]. A differenza di tasks create, non mostra un prezzo prima di chiedere. La nuova attività viene addebitata al prezzo attuale del modello, quindi, se il prezzo conta, controllalo prima con spicyapi models get <model>.

Output: idempotencyKey, il nuovo taskId, sourceTaskId (l’originale), state, estimatedCost (l’importo accantonato) e deadlineAt.

• Si possono ripetere solo le attività failed ed expired, più quelle canceled più vecchie. Per un’altra versione di un risultato riuscito, usa tasks create.
• L’input originale viene riutilizzato senza modifiche, quindi un nuovo tentativo aiuta solo quando il fallimento era temporaneo. Controlla prima errorCode; vedi Ripetere un’attività fallita ed Errori.
• Se l’input puntava a un file caricato che nel frattempo è scaduto, il nuovo tentativo fallisce; carica di nuovo il file e usa tasks create.
• Il nuovo tentativo mantiene l’impostazione di conservazione dell’attività originale.
• Se tasks create ha perso la connessione prima che tu vedessi un ID attività, non si tratta di un’attività fallita. Segui invece i passaggi di ripristino in Riprendere un’attività dopo un’attesa interrotta.

tasks purge

Che cosa fa: elimina per sempre i media generati, il payload del risultato (i dati del risultato archiviati), il prompt e l’altro testo dell’input di un’attività conclusa, subito, invece di aspettare che scadano.

spicyapi tasks purge <task-id> [--yes]

Un’attività ancora queued o running non può essere distrutta. Non può nemmeno essere annullata, perché non esiste alcun comando né alcuna API di annullamento: attendi che finisca con spicyapi tasks wait <task-id>, poi distruggine i contenuti.

Il comando spiega che cosa verrà eliminato e ti chiede conferma, perché l’operazione non si può annullare. Prima scarica tutto ciò che vuoi conservare.

Output: taskId, contentState (purged), purgedAt, contentRemovedBy (user), billingRetained (sempre true) e mediaDeletionPending, seguiti da una riga che indica che cosa è stato distrutto e che i media archiviati vengono rimossi entro circa un minuto. Se contentState è ancora present, questa volta non è stato rimosso nulla; riprova più tardi.

Gratuito, e non è un rimborso: la voce contabile, l’importo addebitato, il modello, lo stato, gli orari e l’ID della richiesta restano registrati. Vedi Conservazione e distruzione.

files upload

Che cosa fa: carica un file dal tuo computer, per esempio l’immagine di partenza per una generazione da immagine a video, e ti restituisce un indirizzo spicy:// da inserire nell’input.

spicyapi files upload <path> [--content-type <type>]

Sono supportate le immagini .jpg, .jpeg, .png, .webp e .gif fino a 10 MiB, i video .mp4 e .webm e l’audio .mp3 e .wav fino a 90 MiB e 600 secondi. Un modello può fissare limiti propri più bassi.

spicyapi files upload ./start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z
width: 1280
height: 720

Output: copia il valore uri esattamente come viene stampato nell’impostazione del modello dedicata al file, spesso image_url. Si può usare fino a expiresAt, di norma un giorno. Dopo, carica di nuovo il file. Il caricamento è gratuito.

files download-url

Che cosa fa: crea un nuovo link di download per il risultato di un’attività conclusa. Stampa il link, ma non salva il file.

spicyapi files download-url <task-id> [--key <key>]

Output: key, url ed expiresAt. Il link funziona per circa 20 minuti; aprilo in un browser o scaricalo con curl. Un’attività non ancora riuscita risponde «not found». Se il file viene ancora copiato ricevi un errore di conflitto; aspetta qualche secondo e riprova. Una volta eliminati i file dell’attività, non si può più creare alcun link. Gratuito.

webhooks verify

Che cosa fa: se gestisci un server che riceve le callback di SpicyAPI (vedi --callback-url), verifica che una callback salvata sia autentica e non modificata. Viene eseguito interamente sul tuo computer e non richiede alcuna chiave API.

spicyapi webhooks verify --body-file <path> --timestamp <seconds> --signature <base64> --payload-version <version>

Output: in caso di successo, payload (il contenuto della callback), payloadVersion, taskId, deliveryId (versione 2) e timestamp. Se qualcosa non corrisponde, stampa un errore ed esce con un codice diverso da zero. Gratuito.

Al momento della registrazione viene creata automaticamente una chiave di firma, ma il suo valore non viene mai mostrato. Per averne una da copiare, apri Webhook nella console e fai clic su Genera (oppure su Ruota, se una chiave è già configurata). La nuova chiave viene mostrata una sola volta. La rotazione ha effetto immediato, senza periodo di sovrapposizione: la vecchia chiave smette subito di firmare. Vedi Webhook.

Ricette comuni

Generare un’immagine

spicyapi models list --modality image --json
spicyapi models get MODEL_ID_FROM_CATALOG --json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Scegli un ID con il primo comando, costruisci input.json a partire dalle impostazioni mostrate dal secondo, poi esegui il terzo e conferma con y. Il percorso guidato in Il tuo primo risultato spiega ogni passaggio.

Trasformare un’immagine in un video

spicyapi models list --modality video --task image-to-video --json
spicyapi models get MODEL_ID_FROM_CATALOG --json

spicyapi files upload ./start-frame.jpg

{
  "prompt": "Slow push-in, rain running down the window",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5
}

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait --wait-timeout-ms 1800000

L’immagine caricata si può usare per un giorno. Dopo, caricala di nuovo.

Riprendere un’attività dopo un’attesa interrotta

Un’attività continua a girare anche se il terminale si chiude, la rete cade, il computer va in sospensione o l’attesa scade. Come ritrovarla dipende da che cosa hai visto:

• Hai visto Accepted: job_…, oppure una riga Recover: sotto l’errore. Hai l’ID attività. Attendi di nuovo, oppure limitati a consultarla:

  spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000
  spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

• Hai visto solo la riga Idempotency-Key:, per esempio perché la connessione è caduta mentre l’attività veniva creata. Esegui di nuovo lo stesso comando, con lo stesso modello e lo stesso input, e aggiungi quella chiave:

  spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241 --wait

  La CLI mostra il prezzo e chiede di nuovo conferma, ma se il primo tentativo era stato accettato, SpicyAPI ti restituisce quella stessa attività invece di avviarne, e addebitarne, una seconda. Funziona per 24 ore con la stessa chiave API. Se il primo tentativo non era mai arrivato, l’attività viene creata adesso, una sola volta.

• Non hai né l’uno né l’altra. Elenca le tue attività recenti e ritrovala in base all’orario e al modello:

  spicyapi --json tasks list --limit 10

Ripetere un’attività fallita

Per prima cosa scopri perché è fallita:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Poi leggi errorCode. 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. tasks retry invia di nuovo lo stesso input, quindi aiuta solo quando la causa era temporanea:

L’elenco completo è in Errori.

Quando un nuovo tentativo ha senso, eseguilo. Crea, e addebita, una nuova attività:

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait

Esportare i consumi

Salva in un file un mese di consumi della chiave attuale:

spicyapi --json usage --from 2026-09-01 --to 2026-10-01 > usage-2026-09.json

Il file contiene i totali giornalieri e per modello. Per un elenco attività per attività, salva allo stesso modo spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --limit 100, seguendo nextCursor finché hasMore vale true. I dati dell’intero account e le fatture si trovano nella console.

Eseguire la CLI da uno script

In uno script nessuno può rispondere a Continue? [y/N], quindi i comandi a pagamento si rifiutano di partire se non aggiungi --yes. Quando lo fai:

• chiedi prima un preventivo e controlla il prezzo nello script;
• assegna a ogni generazione una propria --idempotency-key fissa, come poster-2026-09-17-v1, così eseguire lo script due volte non addebita due volte;
• aggiungi --json e leggi state dal risultato: un comando che esce con codice 0 non ha necessariamente prodotto un’attività riuscita;
• imposta limiti di spesa sulla chiave nella console.

spicyapi --json tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key poster-2026-09-17-v1 --yes --wait > result.json

Costi, conferme e sicurezza

Quali comandi costano denaro. Solo tasks create e tasks retry. I prezzi sono in dollari statunitensi. Chiedere preventivi, elencare, controllare, caricare, scaricare ed eliminare è gratuito.

Vedere prima il prezzo. tasks quote calcola il prezzo di una richiesta senza avviare nulla. tasks create chiede un proprio preventivo e mostra Estimated charge e maximum charge prima di chiedere conferma. Quando l’attività viene accettata, l’importo stimato viene accantonato (held) ed è anche il massimo che ti può essere addebitato. Quando l’attività riesce paghi ciò che è stato effettivamente prodotto, mai più di quell’importo, e l’eventuale differenza torna sul tuo saldo.

La conferma. Continue? [y/N] significa che la risposta è no, a meno che tu non digiti y. --yes risponde al posto tuo, quindi usalo solo quando conosci il prezzo. Se la CLI gira dove non può fare domande, come in uno script o con un input passato tramite pipe, e manca --yes, si rifiuta di procedere invece di dare per scontato un sì. tasks purge chiede conferma allo stesso modo, perché l’eliminazione non si può annullare. Anche tasks retry chiede conferma, ma senza mostrare prima un prezzo.

La chiave di idempotenza, in parole semplici. È un’etichetta per una generazione, come un numero d’ordine. Ogni tasks create e tasks retry ne stampa una. Se la connessione a internet cade e non sai se la generazione è partita, esegui di nuovo lo stesso comando con --idempotency-key e il valore stampato: riottieni l’attività originale e non paghi due volte. L’etichetta vale per 24 ore con la stessa chiave API. Non riutilizzarla per una generazione diversa: la stessa chiave con un input diverso viene rifiutata.

Nessun annullamento. Una volta accettata, un’attività non può essere annullata. Ctrl + C, la chiusura del terminale o la revoca della chiave fermano soltanto l’attesa; l’attività arriva alla fine e viene addebitata normalmente.

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.

Scarica ciò che vuoi conservare. I file dei risultati vengono conservati al massimo per circa 14 giorni, o meno se lo prevedono il tuo account o --retention, poi vengono eliminati per sempre. I link di download durano circa 20 minuti, ma finché il file esiste puoi sempre chiederne uno nuovo. I file caricati si possono usare per un giorno. Il testo dei prompt viene cancellato dopo 30 giorni per impostazione predefinita. Le registrazioni di fatturazione vengono conservate. Vedi Conservazione e distruzione.

Limiti di spesa. Ogni chiave può avere limiti giornalieri, mensili e complessivi, da impostare nella pagina Chiavi API. Le chiavi nuove non hanno alcun limite finché non ne imposti uno. Un’attività che supererebbe un limite viene rifiutata prima di partire.

La tua chiave. La CLI legge la chiave solo da SPICY_API_KEY, non la stampa mai e nei suggerimenti degli errori ne mostra al massimo i primi nove caratteri (sk-spicy-).

Per approfondire: Fatturazione, Idempotenza, Impegno dell’attività e nuovi tentativi.

Risoluzione dei problemi

Cerca il messaggio che vedi. Gli errori di SpicyAPI terminano con (request req_…); se contatti l’assistenza, includi quel valore, ma non inviare mai la tua chiave.

Ogni codice di errore è spiegato in Errori, e i passaggi di ripristino sono in Diagnosi e ripristino.

Codice sorgente

Il pacchetto ha licenza MIT ed è sviluppato in modo aperto su github.com/spicyapi-ai/spicy-cli. È lì che si legge il codice dietro a ogni comando di questa pagina, si segnala un comportamento diverso da quello descritto e si propone una modifica.

Prossimi passi