Attività asincrone

La generazione è asincrona: invio e recupero sono due chiamate separate.

In parole semplici:

1. Invia l'attività e ricevi subito un taskId. Non è ancora completata; il suo prezzo viene accantonato dal saldo come riserva.
2. Torna più tardi e chiedi «questo taskId è terminato?»: è il polling, e basta chiedere ogni pochi secondi. Oppure fornisci un indirizzo web e ti inviamo il risultato lì quando è pronto: è una callback, cioè un webhook.
3. Quando state è succeeded, il link al file si trova in data.output.assets[0].url. Aprilo o scaricalo entro circa 20 minuti; se è scaduto, interroga di nuovo l'attività per ottenerne uno nuovo. Un'attività riuscita non costa più della riserva; le attività fallite e scadute normalmente la liberano, con eccezioni dichiarate nella pagina del modello per alcuni rifiuti di contenuto addebitati. Leggi settled e cost per l'addebito finale.

Perché non una sola chiamata? Le immagini richiedono secondi; i video normalmente minuti. Un endpoint sincrono lascerebbe il processo bloccato su una connessione e qualsiasi interruzione ti lascerebbe senza risultato né un modo sicuro per riprovare: non sapresti se il tentativo precedente è già in esecuzione. Separare le chiamate rende l'ID dell'attività il riferimento stabile: riconnettiti e continua a interrogare lo stesso ID.

1. Crea un'attività

POST /api/v1/jobs/createTask

Header

Corpo

callBackUrl deve essere un indirizzo HTTPS pubblico raggiungibile dai nostri server su internet. Vengono rifiutati URL http:// in chiaro, una porta esplicita diversa da 443 o 80, URL con nome utente o password, indirizzi IP privati o di loopback e nomi host che non si risolvono: il corpo della callback contiene il prompt e i link firmati ai risultati. Per questo http://localhost non funziona nello sviluppo locale: usa il polling oppure esponi la macchina tramite un tunnel che fornisca un indirizzo HTTPS pubblico. I valori non validi restituiscono HTTP 400 con code: 400 applicativo, msg: "Invalid callback URL" e un request_id. L'errore non ripete URL, nome host, indirizzo IP o dettagli DNS. Controlliamo nuovamente la destinazione alla connessione; consulta Webhook.

Risposta

HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
Retry-After: 2

Lo stato del trasporto è 202 Accepted. Il corpo usa comunque la struttura standard, quindi il code applicativo di successo resta 200. Location è l'indirizzo da interrogare e Retry-After: 2 suggerisce quanti secondi attendere prima della prima interrogazione.

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.008",
    "deadlineAt": "2026-08-28T09:42:04Z"
  },
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

Errori di creazione

Questi sono gli errori normalmente incontrati nella prima integrazione. Quando createTask restituisce un errore non viene riservato né addebitato nulla.

Elenco completo: Errori.

Prima di iniziare: scegli un modello e un input valido

Gli esempi seguenti richiedono un ID di modello reale e un input accettato da quel modello. Il catalogo può fornirli entrambi: includeExamples=1 aggiunge input che hanno già superato la convalida dello schema di ciascun modello. Serve jq, un piccolo strumento JSON da riga di comando; sostituisci image con video o audio per altri tipi di modello.

curl -s "https://api.spicyapi.ai/api/v1/models?modality=image&includeExamples=1" \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  | jq -c '.data.items[] | select(.enabled and .available) | {model, input: .examples[0].input}'

Ogni riga stampata è un corpo di richiesta pronto con due campi, model e input. Scegline una. Se una riga mostra "input": null, quel modello non ha un esempio salvato: leggi il suo inputSchema da GET /api/v1/models/{model} e scrivi tu l'input. Consulta Catalogo dei modelli e schemi.

Esempi

MODEL_ID_FROM_CATALOG sotto è soltanto un segnaposto: sostituisci l'intero corpo della richiesta con la riga scelta dal catalogo corrente. Non inviare letteralmente il segnaposto.

# Paste one line printed by the command above between the single quotes.
TASK='{"model":"MODEL_ID_FROM_CATALOG","input":{"prompt":"a folded paper lantern, hard side light"}}'
# One new key per new task. After a network error, rerun only the curl command
# so the same key is sent again and no second task is created.
IDEMPOTENCY_KEY="$(uuidgen)"

curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data "$TASK"

Dovresti vedere il corpo 202 mostrato sopra, con code: 200 e un taskId. Conserva taskId: serve per recuperare il risultato. Per ricevere una callback, aggiungi nel JSON "callBackUrl":"https://…" con il tuo indirizzo HTTPS.

const res = await fetch('https://api.spicyapi.ai/api/v1/jobs/createTask', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPICY_API_KEY}`,
    'Content-Type': 'application/json',
    // One key per logical request; reuse it across retries
    'Idempotency-Key': 'order-8814-render-1',
  },
  body: JSON.stringify({
    model: 'MODEL_ID_FROM_CATALOG',
    input: { prompt: 'a folded paper lantern, hard side light' },
    // Your own public HTTPS endpoint; delete this line to poll instead
    callBackUrl: 'https://your-app.example.com/hooks/spicy',
  }),
});

const body = await res.json();
if (res.status !== 202 || body.code !== 200) throw new Error(`${res.status} ${body.code} ${body.msg}`);
console.log(body.data.taskId, body.data.deadlineAt);

import os, requests

res = requests.post(
    "https://api.spicyapi.ai/api/v1/jobs/createTask",
    headers={
        "Authorization": f"Bearer {os.environ['SPICY_API_KEY']}",
        "Content-Type": "application/json",
        # One key per logical request; reuse it across retries
        "Idempotency-Key": "order-8814-render-1",
    },
    json={
        "model": "MODEL_ID_FROM_CATALOG",
        "input": {"prompt": "a folded paper lantern, hard side light"},
        # Your own public HTTPS endpoint; delete this line to poll instead
        "callBackUrl": "https://your-app.example.com/hooks/spicy",
    },
)

body = res.json()
if res.status_code != 202 or body["code"] != 200:
    raise RuntimeError(f'{res.status_code} {body["code"]} {body["msg"]}')
print(body["data"]["taskId"], body["data"]["deadlineAt"])

2. Stati

Un'attività accettata è irreversibile: né queued né running prevede un'azione di annullamento. L'API può ancora leggere i record storici canceled, ma nessuna nuova azione di un utente o operatore crea questo stato.

Verifica lo stato terminale con state non appartenente a {queued, running}, invece di elencare i valori terminali. Questo gestisce in sicurezza i record storici canceled e impedisce che un futuro stato terminale provochi polling senza fine.

2.5 Evita il ciclo di polling con wait

Aggiungi ?wait=<seconds> a createTask e manteniamo aperta la connessione fino allo stato terminale dell'attività, così la prima chiamata può evitare del tutto un ciclo di polling.

curl -X POST "https://api.spicyapi.ai/api/v1/jobs/createTask?wait=30" \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID_FROM_CATALOG","input":{"prompt":"a lighthouse at dusk"}}'

Il massimo è 60 secondi. I valori superiori vengono limitati anziché rifiutati; qualsiasi valore che non sia un intero positivo viene ignorato anziché rifiutato. Un refuso in un parametro di ottimizzazione non dovrebbe far fallire una generazione altrimenti valida.

Il tetto dipende dal timeout di 100 secondi del livello edge davanti all'API. Oltre quella soglia la connessione viene interrotta dalla CDN, non da noi, e riceveresti un 524 senza ID dell'attività né stato recuperabile, mentre l'attività esiste e i fondi sono già riservati. Sessanta secondi lasciano spazio alla richiesta stessa.

Per le integrazioni in produzione i webhook restano la soluzione migliore: nessuna connessione resta aperta e ricevi notizie anche delle attività più lunghe di qualsiasi periodo di attesa avresti scelto.

3. Interroga un'attività

GET /api/v1/jobs/recordInfo?taskId=job_…

Un solo parametro di query obbligatorio: taskId. Un'attività può essere letta soltanto con la stessa chiave API che l'ha creata. L'interrogazione con una chiave diversa, anche un'altra chiave del tuo account o quella sostitutiva dopo la rotazione, restituisce 404, come un'attività inesistente, così le differenze negli errori non possono essere usate per enumerare ID altrui. La stessa regola vale per download-url e retry. Prima di ruotare una chiave, completa il recupero dei risultati delle attività create con quella vecchia.

curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3" \
  -H "Authorization: Bearer $SPICY_API_KEY"

L'interrogazione è gratuita. Sostituisci l'ID dell'esempio con il tuo taskId.

Campi della risposta

Quattro scadenze distinte

• Il tuo tempo di attesa lo scegli tu. Interrompere l'attesa non annulla l'attività remota: conserva taskId e interroga la stessa attività più tardi per riprendere.
• deadlineAt è la scadenza di esecuzione del server. Un reinvio idempotente non la estende; un retry esplicito crea una nuova attività con una propria scadenza. Leggi lo stato terminale e settled, invece di dedurre un rimborso da un timer locale.
• output.assets[].expiresAt fa scadere un link temporaneo al risultato, normalmente dopo 20 minuti. Una nuova interrogazione aggiorna il link senza creare un'altra attività.
• I file generati vengono conservati al massimo per circa 14 giorni dal completamento; gli input caricati sulla piattaforma per un giorno al massimo. Sono limiti della piattaforma: puoi impostare periodi più brevi in Conservazione e distruzione o distruggere su richiesta il contenuto di un'attività. Aggiornare un link non estende la conservazione dei file sottostanti.

Se usi l'SDK JavaScript, client.run({ model, input }, { idempotencyKey, onAccepted, timeoutMs }) invia una volta e interroga con attese crescenti da 2 a un massimo di 10 secondi; timeoutMs è soltanto il tempo di attesa locale, quindi salva l'ID da onAccepted. Consulta SDK. Preferisci i webhook per le attività in background. Dopo aver verificato una callback completa del risultato, usa direttamente il risultato senza un'altra interrogazione dell'attività.

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "MODEL_ID_FROM_CATALOG",
    "state": "succeeded",
    "input": { "prompt": "a folded paper lantern, hard side light" },
    "output": {
      "assets": [
        {
          "key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/9f3c1d0a7b4e2f68c5a1d3e9b0472fa1.png",
          "url": "https://example.r2.cloudflarestorage.com/results/result.png?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
          "expiresAt": "2026-08-28T09:32:11Z",
          "mime": "image/png",
          "width": 1024,
          "height": 1024,
          "bytes": 1483920
        }
      ]
    },
    "cost": "0.008",
    "settled": true,
    "createdAt": "2026-08-28T09:12:04Z",
    "deadlineAt": "2026-08-28T09:42:04Z",
    "completedAt": "2026-08-28T09:12:11Z",
    "contentState": "present"
  },
  "request_id": "req_01k3m8xa1b2c3d4e5f6g7h8j9k0m"
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "MODEL_ID_FROM_CATALOG",
    "state": "failed",
    "errorCode": "upstream_failed",
    "errorMessage": "Generation failed; the charge has been refunded",
    "cost": "0",
    "settled": true,
    "createdAt": "2026-08-28T09:12:04Z",
    "deadlineAt": "2026-08-28T09:42:04Z",
    "completedAt": "2026-08-28T09:12:39Z",
    "contentState": "present"
  },
  "request_id": "req_01k3m8xb2c3d4e5f6g7h8j9k0m1n"
}

Struttura dell'output

output ha due parti indipendenti. I file generati, immagini, video e audio, arrivano in output.assets[]. I risultati testuali arrivano in output.text, come stringa semplice.

La maggior parte dei modelli compila una sola parte, ma un modello può compilarle entrambe. Quella ricevuta dipende dall'endpoint, non dalla sua modality: un endpoint speech-to-text è raggruppato sotto audio nel catalogo perché legge audio, ma risponde con testo.

const { text, assets = [] } = task.output ?? {};
if (text) console.log(text);
for (const asset of assets) console.log(asset.url);

Il resto della sezione descrive assets[].

I campi di cui non disponiamo vengono omessi, non impostati a null o 0. Gestiscili come facoltativi.

Due indicatori richiedono una gestione:

• pending: true: il file è ancora in fase di copia nella nostra archiviazione e key e url sono temporaneamente vuoti. Interroga di nuovo dopo qualche secondo; chiamare download-url senza key in quel momento restituisce 409.
• unavailable: true: il file è scaduto o definitivamente indisponibile dopo un errore di trasferimento. È perso definitivamente; aspettare non aiuta, quindi rigenera. Se non è stato possibile archiviare nessun file di un'attività riuscita, quella attività non viene addebitata.

I risultati di scomposizione in livelli aggiungono il campo layer. Il primo file è l'immagine di base, cioè la sorgente senza gli elementi separati, con zIndex 0; tutti gli altri file sono livelli PNG trasparenti. Sovrapponili in ordine crescente di zIndex per ricostruire l'immagine. boundingBox contiene [x1, y1, x2, y2] in pixel dell'immagine di base: ridimensiona il livello per riempire quel riquadro e tornerà al suo posto. I modelli che non riportano le posizioni lo omettono, e i livelli restano utilizzabili come elementi ritagliati indipendenti. name è l'etichetta assegnata dal modello e compare soltanto quando la fornisce. La fatturazione conta ogni immagine restituita, inclusa la base.

4. Prima le callback, polling come alternativa

Il polling consiste nell'interrogare ripetutamente recordInfo finché l'attività non termina. Una callback significa che inviamo una volta l'attività conclusa al tuo server. Entrambi forniscono gli stessi dati.

Usa le callback in produzione. Un video di tre minuti interrogato una volta al secondo genera 180 richieste con pochissime informazioni nuove. L'attuale protezione dell'API pubblica da 1.000 richieste ogni 10 secondi non limita il normale utilizzo a pagamento, ma un polling serrato crea traffico inutile e un ciclo fuori controllo esaurisce la propria disponibilità di lettura finché recordInfo non comincia a restituire 429.

Il polling ha senso in due situazioni: sviluppo locale e servizi senza un ingresso pubblico.

Aumenta gradualmente l'attesa durante il polling

Un'impostazione che funziona:

• Parti da 2–3 secondi. Un intervallo più breve è inutile; anche i modelli di immagini più veloci richiedono alcuni secondi.
• Moltiplica per 1,5, con un massimo di 10–15 secondi.
• Fermati alla scadenza dell'attività, non dopo un numero fisso di minuti. Alcuni modelli video possono impiegare fino a un'ora, quindi un timeout fisso di 10 minuti abbandona attività che stanno funzionando normalmente. Usa deadlineAt dalla risposta di createTask, aggiungendo qualche minuto affinché il server registri l'esito.

// created is the data object returned by createTask.
async function waitForTask(created) {
  // Stop a few minutes after the server's own deadline.
  const giveUpAt = Date.parse(created.deadlineAt) + 5 * 60 * 1000;
  let wait = 2000;

  while (Date.now() < giveUpAt) {
    await new Promise((r) => setTimeout(r, wait));
    wait = Math.min(wait * 1.5, 15000);

    const res = await fetch(
      `https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=${encodeURIComponent(created.taskId)}`,
      { headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` } },
    );
    const body = await res.json();

    // Being rate-limited is not a task failure — honour Retry-After
    if (body.code === 429) {
      wait = Number(res.headers.get('retry-after') ?? 1) * 1000;
      continue;
    }
    if (body.code !== 200) throw new Error(`${body.code} ${body.msg}`);

    // Terminal means "not one of the two in-flight states"
    const { state } = body.data;
    if (state !== 'queued' && state !== 'running') return body.data;
  }
  // Not a failure: query this taskId again later instead of resubmitting.
  throw new Error(`stopped waiting for ${created.taskId}`);
}

// created = body.data from the createTask example above
const task = await waitForTask(created);
if (task.state === 'succeeded') console.log(task.output.assets[0].url);
else console.log(task.state, task.errorCode);

import os, time, requests
from datetime import datetime

BASE = "https://api.spicyapi.ai/api/v1"
AUTH = {"Authorization": f"Bearer {os.environ['SPICY_API_KEY']}"}


def wait_for_task(created: dict) -> dict:
    """created is the data object returned by createTask."""
    # Stop a few minutes after the server's own deadline.
    deadline = datetime.fromisoformat(created["deadlineAt"].replace("Z", "+00:00"))
    give_up_at = deadline.timestamp() + 5 * 60
    wait = 2.0

    while time.time() < give_up_at:
        time.sleep(wait)
        wait = min(wait * 1.5, 15.0)

        res = requests.get(f"{BASE}/jobs/recordInfo", headers=AUTH, params={"taskId": created["taskId"]})
        body = res.json()

        # Being rate-limited is not a task failure — honour Retry-After
        if body["code"] == 429:
            wait = float(res.headers.get("retry-after", 1))
            continue
        if body["code"] != 200:
            raise RuntimeError(f'{body["code"]} {body["msg"]}')

        # Terminal means "not one of the two in-flight states"
        if body["data"]["state"] not in ("queued", "running"):
            return body["data"]

    # Not a failure: query this taskId again later instead of resubmitting.
    raise TimeoutError(f'stopped waiting for {created["taskId"]}')


# created = body["data"] from the createTask example above
task = wait_for_task(created)
if task["state"] == "succeeded":
    print(task["output"]["assets"][0]["url"])
else:
    print(task["state"], task.get("errorCode"))

5. Controlla il saldo

GET /api/v1/chat/credit restituisce available, ciò che può finanziare nuove attività, held, bloccato dalle attività in corso, e total. available può essere negativo quando utilizzi credito approvato, e i fondi promozionali elencati in funding.grants possono finanziare soltanto alcuni modelli. Dettagli completi: Controllare il saldo.

curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

Cronologia delle attività e recupero

GET /api/v1/jobs elenca le attività visibili create dalla chiave API corrente. Usalo per ritrovare il lavoro dopo un riavvio dell'applicazione o una callback persa. Sono esclusi i record nascosti e le attività di altre chiavi. Le risposte contengono ID, modello, stato, costo, stato del regolamento, date e ore e, quando registrato, il requestId della chiamata che ha creato l'attività; per una chiamata di testo coincide con l'header X-Request-Id. Non includono prompt, input, output o link ai file. Recupera un'attività selezionata con recordInfo per ottenere il risultato.

Filtra per state, un model esatto del catalogo o un alias, e date UTC from / to (YYYY-MM-DD, estremo iniziale incluso e finale escluso). L'intervallo predefinito è di sette giorni fino a domani UTC; il massimo è 92 giorni. limit è 20 per impostazione predefinita e non può superare 100.

Ometti i filtri che non usi: un valore vuoto come model=, un parametro ripetuto o sconosciuto restituisce 400. Un'interrogazione che dura più di cinque secondi restituisce 503; riprova con un intervallo di date più breve.

curl --fail-with-body \
  'https://api.spicyapi.ai/api/v1/jobs?from=2026-09-01&to=2026-09-07&state=failed&limit=20' \
  -H "Authorization: Bearer $SPICY_API_KEY"

Leggi data.items. Se data.hasMore è true, passa data.nextCursor come cursor della richiesta successiva, lasciando invariati tutti i filtri e le date esplicite. L'ordine è decrescente per createdAt, poi per ID dell'attività. Le pagine riflettono lo stato corrente delle attività, non una fotografia immutabile. Non costruire autonomamente i cursori. Elencare la cronologia non crea né ritenta mai un'attività.

La stessa funzione è disponibile tramite client.listTasks(...), spicyapi tasks list e lo strumento MCP di sola lettura spicyapi_tasks_list. Mantieni cost in USD come stringa decimale; quando settled è false, è ancora la stima riservata, non un addebito finale.

Se la risposta di creazione è andata persa, riprova prima la richiesta invariata con il suo Idempotency-Key originale. Una pagina della cronologia vuota non autorizza a creare di nuovo lo stesso lavoro a pagamento con una nuova chiave.