Tutorial: da immagine a video

Procurati un account, un saldo e una chiave API

Segui prima Configura il tuo account. Alla fine dovresti avere:

• un account SpicyAPI con del denaro sul saldo;
• una chiave API, che inizia con sk-spicy-;
• quella chiave salvata in una variabile d’ambiente chiamata SPICY_API_KEY. Una variabile d’ambiente è un valore con un nome che il terminale passa ai programmi che esegue, così la chiave non deve mai comparire in un comando o nel tuo codice.

Controlla che la chiave sia impostata nella finestra del terminale che stai usando, senza stampare la chiave intera:

echo "${SPICY_API_KEY:0:9}"

Dovresti vedere sk-spicy-. Se non vedi nulla o compare un errore, la chiave non è impostata in questa finestra; torna a Configura il tuo account.

Metti l’immagine in una cartella di lavoro

Crea una cartella per questo tutorial e apri il terminale al suo interno. Ogni comando di questa pagina va eseguito da questa cartella, e ogni file che viene creato finisce qui.

mkdir -p ~/spicy-video
cd ~/spicy-video

Copia l’immagine in quella cartella e chiamala start-frame.jpg (oppure start-frame.png se è un PNG; in quel caso usa quel nome ovunque questa pagina scrive start-frame.jpg).

Com’è fatta una buona immagine di partenza:

• Formato e dimensione: JPEG, PNG, WebP o GIF, fino a 10 MiB (circa 10 megabyte). Un modello può fissare limiti propri più severi, che vedrai nel passaggio 1.
• Il file deve essere davvero in quel formato. SpicyAPI controlla il contenuto del file, non solo il nome. Le foto scattate con il telefono sono spesso in HEIC, e rinominarne una in .jpg non la converte. Prima aprila ed esportala o salvala come JPEG.
• Forma: l’immagine diventa il primo fotogramma. Usa un’immagine orizzontale per un video orizzontale e una verticale per un video verticale; alcuni modelli offrono anche un’impostazione aspect_ratio.
• Diritti: usa un’immagine che hai il diritto di usare.

Prepara lo strumento che hai scelto

npm install -g @spicyapi/cli
spicyapi --version

spicyapi balance

1. Scegli un modello e leggi le sue impostazioni

Fai così: elenca i modelli da immagine a video che il tuo account può usare, scegline uno, poi leggi quali impostazioni accetta.

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

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example video model",
      "modality": "video",
      "tasks": ["image-to-video"],
      "enabled": true,
      "available": true,
      "quantityField": "duration_seconds",
      "maxOutputDurationSeconds": 10,
      "taskTimeoutSeconds": 1800,
      "pricing": [
        { "variant": "720p", "unit": "per_second", "price": "…", "currency": "USD" },
        { "variant": "1080p", "unit": "per_second", "price": "…", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

Che cosa guardare nell’elenco:

Come leggere le impostazioni. inputSchema è l’elenco delle impostazioni del modello, scritto in JSON Schema:

• required elenca le impostazioni che devi inviare. Per questo tipo di modello image_url è sempre tra queste, e la maggior parte dei modelli richiede anche prompt.
• properties elenca tutte le impostazioni che il modello accetta, ciascuna con un type, una description in inglese semplice e spesso enum (gli unici valori ammessi), minimum e maximum, e default (il valore usato quando ometti l’impostazione).
• Dentro ogni impostazione, x-ui contiene indicazioni per la visualizzazione. x-ui.affects_price: true significa che cambiare quell’impostazione cambia il prezzo.
• Alcuni modelli aggiungono condizioni al livello principale, come «se invii A devi inviare anche B». Spicy Schema spiega come leggerle.
• examples contiene input completi che il server ha già verificato: sono un punto di partenza sicuro.

Le impostazioni che incontrerai più spesso. I nomi sono gli stessi per tutti i modelli, ma ogni modello ne accetta solo alcuni, ciascuno con i propri valori ammessi:

Che cosa è appena successo: hai letto il catalogo in tempo reale del tuo account, compresi i tuoi prezzi. Non è stato addebitato nulla. Leggere il catalogo conta nel limite di richieste del tuo account, quindi non serve ripeterlo prima di ogni video: rifallo quando cambi modello o ricevi un 400.

2. Carica la tua immagine

Fai così: carica start-frame.jpg e copia l’indirizzo spicy:// che ricevi. Il caricamento è gratuito.

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

Che cosa è appena successo: la tua immagine è stata salvata in forma privata per il tuo account, controllata (il suo formato reale deve corrispondere al tipo dichiarato) e ha ricevuto un indirizzo spicy://. Quell’indirizzo non è un link web: solo il tuo account può usarlo, e solo dentro l’input di un’attività. Si può usare per un giorno (vedi expiresAt); dopo, carica di nuovo l’immagine.

Se il caricamento fallisce:

3. Descrivi il video e controlla il prezzo

Fai così: scrivi le impostazioni in un file chiamato input.json, poi chiedi un preventivo.

Scrivi input.json. Parti dalle due impostazioni che ogni modello da immagine a video accetta. Metti la tua frase in prompt e sostituisci il valore di image_url con l’uri che hai copiato nel passaggio 2:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}

Le impostazioni che ometti usano il default del modello. Per sceglierle tu, aggiungi solo impostazioni presenti nelle properties del tuo modello, con valori che il modello ammette. Per esempio, se il tuo modello elenca duration_seconds e resolution e ammette questi valori:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5,
  "resolution": "720p"
}

Salva il file nella cartella di lavoro:

cat > input.json <<'EOF'
{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}
EOF

Usa le virgolette dritte semplici ("), non quelle tipografiche, e non mettere la virgola dopo l’ultima impostazione.

Chiedi il preventivo:

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

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

Che cosa è appena successo: SpicyAPI ha confrontato il tuo input con le impostazioni del modello e ha calcolato il prezzo di questa richiesta esatta. Non è stato avviato nulla e non è stato addebitato nulla. estimatedCost è l’importo che verrà accantonato se avvii adesso, e maxCharge è il massimo che può costare. quantity e unit mostrano che cosa paghi, per esempio 5 secondi.

Un preventivo vale cinque minuti e solo per questo input esatto. Cambia la durata o la risoluzione e chiedi un nuovo preventivo per confrontare i prezzi. Il preventivo esegue gli stessi controlli dell’avvio dell’attività, quindi i problemi emergono qui, gratis: un 400 significa che l’input non corrisponde alle impostazioni del modello (correggi input.json con l’aiuto del passaggio 1), e un 40201 significa che il saldo non basterebbe. Il passaggio 7 elenca gli altri codici.

4. Avvia la generazione

La chiave di idempotenza, in parole semplici. È un’etichetta per un video, come un numero d’ordine. Se la connessione cade e non sai se il video è partito, invia di nuovo la stessa richiesta con la stessa etichetta: SpicyAPI ti restituisce l’attività che ha già avviato, invece di avviarne (e addebitarne) una seconda. Un’etichetta vale per 24 ore con la stessa chiave API. Per un video diverso usa un’etichetta nuova: la stessa etichetta con un input diverso viene rifiutata con 409. Maggiori dettagli in Idempotenza.

Fai così:

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

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

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
taskId: job_01k3m8x9q2z4v7n5p6r8s0t1w3
state: queued
estimatedCost: …
deadlineAt: 2026-09-17T08:35:00Z

Che cosa è appena successo: SpicyAPI ha accettato la generazione, che adesso è un’attività, e ha accantonato estimatedCost dal tuo saldo. È anche il massimo che questo video può costare. state: queued significa che l’attività aspetta il suo turno. deadlineAt è l’ora entro cui deve finire; se a quell’ora non è conclusa, termina come expired e non viene addebitato nulla. deadlineAt non indica quando scadono i tuoi file.

Passare il preventivo significa «accetta la richiesta solo al prezzo che mi è stato mostrato». Se nel frattempo il prezzo o l’input sono cambiati, la richiesta viene rifiutata con 40901 invece di accantonare un importo diverso. La CLI lo fa per te.

Se la connessione è caduta e non hai mai visto un ID attività, non ricominciare semplicemente con un’etichetta nuova: creeresti e pagheresti un secondo video. Ripeti la richiesta con la stessa etichetta:

• CLI: spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key <the value you copied> (al posto di <the value you copied> metti il valore che hai copiato). Vedi Riprendere un’attività dopo un’attesa interrotta.
• SDK: esegui di nuovo node generate.mjs --yes; riusa idempotency-key.txt.
• HTTP: esegui di nuovo il blocco «Avvia il video»; riusa idempotency-key.txt.

Se il passaggio 4 è stato rifiutato, non è stato creato nulla e non è stato addebitato nulla; la causa e la soluzione sono nel passaggio 7.

5. Aspetta il video

Fai così: controlla l’attività finché non finisce. Di solito i video richiedono qualche minuto.

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

{
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "state": "succeeded",
  "output": {
    "assets": [
      {
        "key": "tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4",
        "url": "https://…",
        "expiresAt": "2026-09-17T08:40:00Z",
        "mime": "video/mp4",
        "durationSeconds": 5,
        "width": 1280,
        "height": 720,
        "bytes": 4839211
      }
    ]
  },
  "cost": "…",
  "settled": true
}

Che cosa è appena successo: il tuo strumento ha chiesto a SpicyAPI lo stato dell’attività ogni pochi secondi. Gli stati sono queued (in attesa), running (in generazione) e poi uno stato finale: succeeded, failed o expired. Dopo la riuscita il file viene copiato nello storage di SpicyAPI, il che richiede qualche secondo in più; fino ad allora il risultato mostra pending: true. cost è definitivo quando settled vale true.

• Chiudere il terminale o premere Ctrl + C non annulla l’attività. Interrompe solo l’attesa. Conserva l’ID attività ed esegui di nuovo questo passaggio più tardi.
• Non controllare più spesso di una volta ogni pochi secondi. Ogni controllo di un’attività usa la disponibilità di lettura dell’account, indipendentemente dall’avvio delle attività; vedi Limiti di frequenza.
• Per un’app o un server, lascia che sia SpicyAPI ad avvisarti quando l’attività è finita, invece di chiederlo tu: vedi Ricevi un avviso invece di aspettare.

6. Scarica e conserva il video

Fai così: ottieni un link di download nuovo e salva il file sul tuo computer.

spicyapi files download-url job_01k3m8x9q2z4v7n5p6r8s0t1w3

key: tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4
url: https://…
expiresAt: 2026-09-17T08:52:00Z

curl -L -o my-video.mp4 "PASTE_THE_URL_HERE"

Che cosa è appena successo: ogni risultato arriva con un link di download diretto. Il link funziona per circa 20 minuti e non richiede la chiave API: non aggiungerci mai la tua chiave. Quando scade, chiedi di nuovo l’attività (oppure usa files download-url) per ottenerne uno nuovo.

7. Quando qualcosa va storto

I problemi sono di due tipi, e si gestiscono in modo diverso.

Una richiesta viene rifiutata. Il comando o la chiamata riceve subito un errore. Non è stato creato nulla e non è stato addebitato nulla. Il messaggio spiega il motivo, e l’errore riporta un code e un ID richiesta (req_…) da citare se contatti l’assistenza.

L’attività fallisce. L’attività è stata accettata, ma termina come failed o expired invece che succeeded. L’attività mostra un errorCode che dice perché e un errorMessage che lo spiega più nel dettaglio a parole. 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.

Leggilo:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Poi decidi che cosa fare in base a errorCode, non in base a come è formulato il messaggio:

Qualsiasi altro valore va trattato come upstream_failed. L’elenco completo è in Errori.

Esegui di nuovo un’attività fallita. Un nuovo tentativo crea una nuova attività con lo stesso modello e lo stesso input, al prezzo attuale del modello. Costa denaro, come il passaggio 4, e mantiene l’input originale: se quell’input usava un caricamento che nel frattempo è scaduto, carica di nuovo l’immagine e avvia invece una nuova attività.

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

Si possono ripetere solo le attività failed ed expired. Per una versione diversa di un video riuscito, torna al passaggio 3 con un’etichetta nuova. Non c’è modo di annullare un’attività una volta accettata. Maggiori dettagli in Impegno dell’attività e nuovi tentativi.