OpenAPI e indice degli endpoint
Contratto OpenAPI 3.1 scaricabile, tutti gli endpoint pubblici con le rispettive guide, header condivisi e origine API di produzione.
Il contratto pubblico leggibile dalle macchine è disponibile come OpenAPI 3.1 YAML. Usalo per generare un client o validare l'integrazione rispetto agli endpoint pubblici attuali.
Origine API di produzione
https://api.spicyapi.ai è l'unica origine di produzione dichiarata da OpenAPI in servers[0].url. Le API delle attività usano /api/v1; la compatibilità dei protocolli usa /v1 e /v1beta.
Queste API della piattaforma permettono di selezionare modelli, ottenere stime e monitorare la spesa senza aprire la console. Il catalogo dei modelli include i prezzi dell'account; usa un preventivo con gli input esatti quando il prezzo dipende dai parametri. La cronologia delle attività e l'utilizzo sono limitati alla chiave API con cui effettui la chiamata. Creazione delle chiavi, rotazione e impostazioni del budget restano nella console. Ogni tabella rimanda alla guida che spiega per intero l'endpoint.
API per individuare modelli, prezzi e informazioni sull'account
| Metodo | Percorso | Scopo | Guida |
|---|---|---|---|
GET | /console/v1/catalog/models | Catalogo pubblico per la valutazione: senza chiave API, prezzi standard, limite di richieste per indirizzo sorgente | Avvio rapido |
GET | /api/v1/models | Leggere modelli utilizzabili, prezzi dell'account e schemi facoltativi | Catalogo dei modelli |
GET | /api/v1/models/{model} | Leggere un modello e il suo JSON Schema completo | Catalogo dei modelli |
POST | /api/v1/jobs/quote | Ottenere un preventivo della richiesta esatta valido cinque minuti, senza creare un'attività né bloccare fondi | Preventivi |
GET | /api/v1/chat/credit | Leggere saldo disponibile, bloccato e totale | Fatturazione |
GET | /api/v1/usage | Leggere chiamate della chiave attuale e spesa liquidata in USD per data e modello | Fatturazione |
API di generazione e delle attività
| Metodo | Percorso | Scopo | Guida |
|---|---|---|---|
GET | /api/v1/jobs | Elencare la cronologia delle attività della chiave API attuale con paginazione a cursore | Attività |
POST | /api/v1/jobs/createTask | Creare un'attività di generazione asincrona | Attività |
GET | /api/v1/jobs/recordInfo | Leggere un'attività creata con la chiave API della chiamata | Attività |
POST | /api/v1/jobs/retry | Creare una nuova attività da un'attività fallita o scaduta; le registrazioni storiche annullate restano compatibili | Azioni sulle attività |
POST | /api/v1/jobs/purge | Distruggere gli artefatti e il prompt di un'attività in stato finale; la registrazione di fatturazione resta intatta | Conservazione |
POST | /api/v1/jobs/stream | Eseguire un modello di testo e trasmettere la risposta in streaming via SSE | Testo e streaming |
API dei media
| Metodo | Percorso | Scopo | Guida |
|---|---|---|---|
POST | /api/v1/common/upload-url | Emettere un ticket per il caricamento diretto dei media | Media |
POST | /api/v1/files/{fileId}/commit | Verificare e confermare un caricamento diretto, restituendo l'URI spicy:// pronto per l'attività | Media |
POST | /api/v1/files/import | Importare un file di pesi LoRA da un link, con un token di accesso facoltativo usato una sola volta e mai salvato; restituisce l'URI spicy:// pronto per l'attività | Pesi dell'adattatore |
POST | /api/v1/common/download-url | Emettere un URL temporaneo per scaricare l'output di un'attività (facoltativo: le attività concluse ne includono già uno) | Media |
POST | /api/v1/assets | Salvare un file nella libreria di asset (Idempotency-Key obbligatorio) | Media |
GET | /api/v1/assets | Elencare i tuoi asset salvati (filtri favorite, collectionId, q; ordine con sort) | Media |
GET | /api/v1/assets/usage | Consultare piano, utilizzo e limiti della libreria di asset | Media |
GET | /api/v1/assets/{assetId} | Ottenere un asset con un nuovo link di anteprima privato | Media |
PATCH | /api/v1/assets/{assetId} | Rinominare un asset o cambiarne il flag favorite | Media |
DELETE | /api/v1/assets/{assetId} | Eliminare un asset | Media |
GET | /api/v1/assets/entities | Elencare i personaggi della tua libreria di asset (sola lettura) | Media |
GET | /api/v1/assets/entities/{entityId} | Ottenere un personaggio con le immagini in ordine (sola lettura) | Media |
Autenticazione e struttura delle risposte
Ogni endpoint tranne il catalogo pubblico richiede la chiave API come Authorization: Bearer sk-spicy-…; gli endpoint di compatibilità (/v1, /v1beta) accettano anche x-api-key, inviato dagli SDK Anthropic, e x-goog-api-key, inviato dagli SDK Google GenAI. Una chiave nella query string dell'URL non viene mai accettata. Attività, nuovi tentativi, distruzioni e link di download sono visibili soltanto alla chiave API che ha creato l'attività; consulta Autenticazione.
Le risposte JSON delle API delle attività condividono la struttura {code,msg,data,request_id}; gli endpoint di compatibilità usano i formati dei rispettivi protocolli. L'esito di un'attività è espresso da data.state, non dal code della struttura esterna. Consulta Errori.
Header di richiesta usati fra gli endpoint
| Header | Destinazione | Scopo |
|---|---|---|
Authorization: Bearer … | Tutto tranne il catalogo pubblico | La tua chiave API |
Idempotency-Key | jobs/createTask, jobs/retry, jobs/stream, POST /v1/videos e gli endpoint di testo /v1 e /v1beta | Rende sicuro reinviare dopo un errore di rete. Negli endpoint delle attività restituisce l'attività originale; negli endpoint di testo impedisce un secondo addebito ma non può restituire una risposta persa. Consulta Idempotenza |
X-Spicy-Retention | jobs/createTask, jobs/stream | Accorcia il periodo di conservazione degli output e del prompt di questa attività, in secondi. Consulta Conservazione |
Accept-Language | Qualsiasi endpoint | Lingua dei messaggi di errore; i codici non cambiano mai. Consulta Errori |
Usare il file OpenAPI
- Provare le richieste senza scrivere codice: importa il file OpenAPI collegato all'inizio della pagina in un client API come Postman, Insomnia o Bruno, poi imposta il token bearer sulla tua chiave API. Ricorda che creare attività costa denaro.
- Generare un client: passa lo stesso file a un generatore di codice OpenAPI 3.1 per il tuo linguaggio.
Modifiche al contratto
- Non conservare i parametri dei modelli come uno snapshot permanente scritto nel codice; leggi
inputSchemada/models/{model}. - Accetta campi di risposta sconosciuti, ma non indovinare mai campi di richiesta sconosciuti.
- Usa lo YAML OpenAPI per generare codice o eseguire test del contratto prima del rilascio.
Endpoint di compatibilità
| Metodo | Percorso | Protocollo |
|---|---|---|
GET | /v1/models | Models |
POST | /v1/chat/completions | Chat Completions |
POST | /v1/responses | Responses |
POST | /v1/messages | Messages |
POST | /v1beta/models/{model}:generateContent | Gemini generateContent |
POST | /v1beta/models/{model}:streamGenerateContent | Gemini streamGenerateContent |
POST | /v1/videos | Videos |
GET | /v1/videos/{videoId} | Stato del video |
GET | /v1/videos/{videoId}/content | Contenuto del video |
Gli endpoint di testo sono trattati in Testo e streaming; la loro tariffazione è in Preventivi e compatibilità.
Il pacchetto TypeScript ufficiale è @spicyapi/sdk. Per Python e Go, oppure se non puoi aggiungere una dipendenza, i client di riferimento copiabili qui sotto chiamano questi endpoint usando soltanto il runtime del linguaggio. Quello Python gestisce da solo un intero lavoro con media: caricare e confermare un file di riferimento, confermare il prezzo con un preventivo, creare l'attività e interrogarla fino a uno stato finale, leggere il risultato che sia composto da file o testo, aggiornare un link di output scaduto, distruggere poi i contenuti archiviati e verificare una firma webhook. Quello Go copre la stessa pipeline, con un contesto per ogni chiamata e un errore tipizzato recuperabile con errors.As. Quello TypeScript copre creazione delle attività, nuovi tentativi, lettura dello stato e attesa con un limite; per i caricamenti e il resto delle funzionalità in Node.js, usa l'SDK.
Client di riferimento da copiare
Esempi senza dipendenze che coprono la ricerca dei modelli, la creazione di un’attività, il nuovo tentativo dopo un errore, la lettura dello stato, tutti gli stati finali, l’attesa con un limite, l’idempotenza e gli errori. Un’attività già accettata non può essere annullata.
Sono esempi di documentazione, non pacchetti npm o PyPI né moduli Go pubblicati. Dieci minuti sono un limite di attesa locale, non uno SLA di produzione.