Preventivi e compatibilità di protocollo

Chiedere il preventivo di una richiesta esatta

Un preventivo ti dice quanto costa una richiesta precisa prima che tu paghi. È gratuito, non crea alcuna attività e non accantona denaro. Poi invii la stessa identica richiesta con il preventivo allegato, e così viene accettata solo al prezzo che ti è stato mostrato.

I comandi qui sotto sono per un terminale macOS o Linux, con SPICY_API_KEY impostata come spiegato nell’Avvio rapido. MODEL_ID_FROM_CATALOG è un segnaposto: al suo posto metti un valore model preso dal tuo catalogo in tempo reale (GET /api/v1/models), e prendi ogni campo di input dallo schema di quel modello.

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" }
}

curl https://api.spicyapi.ai/api/v1/jobs/quote \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

{
  "code": 200,
  "msg": "success",
  "data": {
    "quoteId": "QUOTE_ID_FROM_RESPONSE",
    "model": "MODEL_ID_FROM_CATALOG",
    "estimatedCost": "0.008",
    "maxCharge": "0.008",
    "currency": "USD",
    "quantity": "1",
    "unit": "per_image",
    "expiresAt": "2026-09-17T10:05:00Z"
  },
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" },
  "quoteId": "QUOTE_ID_FROM_RESPONSE",
  "expectedCost": "0.008"
}

SPICY_IDEMPOTENCY_KEY="$(uuidgen)"   # una volta per ogni nuova attività; riusala solo per reinviare questa stessa richiesta

curl https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  --data-binary @submit.json

Anche POST /api/v1/jobs/stream, lo stream di testo nativo, accetta un preventivo allo stesso modo; vedi Testo e streaming.

Rimediare a una risposta andata persa

Se un invio è andato in timeout o la connessione è caduta, non sai se la richiesta è stata accettata. Per createTask, retry e POST /v1/videos:

1. Reinvia la richiesta originale con la sua Idempotency-Key originale, usando la stessa chiave API. Ti torna l’attività originale, nel suo stato attuale, e non paghi due volte.
2. Non creare un’altra attività con una chiave nuova. Una chiave nuova significa una nuova generazione e un nuovo addebito.
3. Il reinvio di una richiesta già accettata resta valido anche dopo la scadenza del preventivo. La scadenza controlla l’accettazione, non l’attività che l’accettazione ha già creato.
4. Un 409 non significa «non creata». O la richiesta è cambiata (è un lavoro nuovo, che richiede una chiave nuova), oppure è stata inviata con un’altra chiave API dello stesso account (reinviala con la chiave originale). Vedi Idempotenza.
5. Per l’addebito definitivo, leggi cost e settled da recordInfo.

I preventivi negli strumenti ufficiali

La CLI e il server MCP chiedono un preventivo e interpellano una persona prima di ogni chiamata a pagamento, quindi non devi costruire tu questo passaggio:

• CLI: spicyapi tasks quote calcola il prezzo di una richiesta; spicyapi tasks create chiede di nuovo il preventivo, mostra l’importo e chiede conferma prima di creare l’attività. Vedi Costi, conferme e sicurezza.
• MCP: l’assistente può chiedere preventivi liberamente, ma per creare un’attività ti chiede conferma tramite il tuo client IA, mostrandoti il prezzo. Vedi Costi, conferme e sicurezza.
• SDK: quoteTask restituisce il preventivo; passa il suo quoteId e il suo estimatedCost a createTask o a run.

Compatibilità per testo e video

SpicyAPI parla anche i formati OpenAI, Anthropic e Google Gemini per i modelli di testo, e il formato OpenAI Videos per i video. L’elenco completo degli endpoint è in OpenAPI ed elenco degli endpoint; richieste, stream ed errori protocollo per protocollo sono in Testo e streaming.

URL di base. Il formato OpenAI usa https://api.spicyapi.ai/v1. Gli SDK Anthropic e Google GenAI aggiungono da soli /v1 o /v1beta, quindi imposta il loro URL di base su https://api.spicyapi.ai.

Credenziale. Una sola chiave API per tutti, nell’intestazione Authorization: Bearer. Sono accettate anche l’intestazione x-api-key usata dall’SDK Anthropic e l’intestazione x-goog-api-key usata dall’SDK Google GenAI. Un ?key= nell’URL, invece, non viene mai accettato.

Modello. Scegli un modello esatto dal catalogo in tempo reale. Il funzionamento di strumenti, messaggi con immagini e opzioni di generazione dipende dallo schema di quel modello, non dal protocollo che hai scelto.

Forma della risposta. Ogni protocollo restituisce la propria struttura di risposta, non quella della piattaforma {code, msg, data, request_id}.

Campi di ragionamento

I modelli di chat che espongono il testo del ragionamento possono restituire una stringa facoltativa in message.reasoning_content, oppure in delta.reasoning_content durante lo streaming. Quando prosegui dopo una chiamata a uno strumento, puoi conservarla nel messaggio dell’assistente corrispondente, se lo schema del modello in tempo reale lo supporta.

usage.completion_tokens_details.reasoning_tokens descrive la parte di ragionamento già inclusa in completion_tokens: non sommarla una seconda volta. Non tutti i modelli restituiscono il testo del ragionamento o questi dettagli sui token.

Due particolarità da conoscere prima di iniziare

• Responses richiede l’intera conversazione in input. previous_response_id non è supportato.
• Videos accetta un JSON con model, prompt, input_reference, seconds e size, che vengono mappati sui campi propri del modello. L’id del video restituito è anche un ID attività accettato da recordInfo. Il suo endpoint dei contenuti reindirizza con HTTP 302 a un URL firmato di breve durata.

Per un esempio di chat in streaming con i client ufficiali OpenAI, Anthropic e Google, vedi Usare un SDK ufficiale. La CLI e il server MCP inviano e seguono attività native; non trasmettono in streaming i token della chat.