Integrazione in produzione

Usa questa pagina come checklist prima che utenti veri o denaro vero dipendano dalla tua integrazione. Ogni sezione dice che cosa fare, perché conta e dove trovare i dettagli. Se non hai ancora fatto una prima chiamata, parti da Configura il tuo account e dall’avvio rapido.

Scegli un modello e un protocollo

• Scegli un modello che la tua chiave può davvero chiamare. Chiama GET /api/v1/models con la tua chiave API e usa solo i modelli in cui sia enabled sia available valgono true. Dalla stessa risposta leggi l’inputSchema del modello (l’elenco dei campi che accetta) e gli examples. La pagina di un modello sul sito ti dice che cosa sa fare quel modello, ma non dimostra che la tua chiave possa chiamarlo in questo momento. Vedi Catalogo dei modelli e schemi.
• Usa il punto di accesso giusto. Le attività di immagini, video e altri media usano l’API delle attività sotto /api/v1 (createTask, poi recordInfo oppure una callback). I modelli di testo si possono chiamare anche con client compatibili con OpenAI o Anthropic sotto /v1, oppure con client compatibili con Gemini sotto /v1beta. Vedi Testo e streaming.
• Autenticati solo con una chiave API. Il cookie di accesso alla console non è una credenziale API e non va mai copiato nel codice.

Proteggi le chiavi e il saldo

• Tieni la chiave sul tuo server. Mettila in una variabile d’ambiente (SPICY_API_KEY) sul tuo backend, mai nel codice che gira nel browser, nelle app mobili o in un repository pubblico. Vedi Autenticazione.
• Una chiave per ogni ambiente e servizio. Dai a ogni chiave il nome di ciò che la usa (ad esempio «production-worker»), così puoi revocarne una senza fermare le altre.
• Imposta i limiti sulla chiave di produzione: un limite giornaliero dimensionato su una giornata storta, un budget mensile, i modelli consentiti e, per le chiamate lato server, gli IP consentiti. Vedi le restrizioni per singola chiave. Quando modifichi una chiave, ricorda che un limite lasciato vuoto significa nessun limite.
• Controlla le date di scadenza. Una chiave con data di scadenza smette di funzionare alla fine di quel giorno (UTC) e restituisce lo stesso 401 di una chiave revocata. Segna la data in calendario, oppure non impostarne una per un backend destinato a durare a lungo.
• Non restare senza fondi a metà di un lotto. Un’attività rifiutata per saldo insufficiente restituisce 40201 e non entra mai in coda. Attiva l’Avviso di saldo basso in Notifiche e valuta la ricarica automatica.
• Valgono anche i limiti del team. Se la tua chiave appartiene a un team, i limiti giornaliero e mensile del team possono bloccare le attività con 40202 anche quando i limiti della chiave non sono stati raggiunti, e ogni attività viene pagata con il saldo del proprietario del team. Vedi Limiti di spesa.
• Pianifica la rotazione della chiave di firma dei webhook. Ruotare la chiave nella console non prevede sovrapposizione: la vecchia chiave smette subito di firmare. Anche le consegne per cui sono ancora in corso nuovi tentativi vengono firmate con la nuova chiave. Ruota in un momento tranquillo, distribuisci subito la nuova chiave al tuo ricevitore e recupera con recordInfo tutto ciò che ti è sfuggito. Vedi Webhook.

Prepara l’input sul tuo server

• Convalida rispetto allo schema attuale. Rispetta i tipi di campo, i valori consentiti e i requisiti condizionali di inputSchema, e convalida di nuovo dopo aver cambiato modello: ogni modello ha il suo.
• Invia i media nel modo supportato. Usa un URL https:// raggiungibile pubblicamente oppure un input Base64 supportato. Per i file locali, richiedi un URL di caricamento, invia i byte con PUT, chiama files/{fileId}/commit, poi passa l’URI spicy:// restituito nel campo di input del modello. Vedi Media.
• Usa ogni file caricato finché è valido. Un URI spicy:// funziona fino all’expiresAt indicato nella risposta del commit (1 giorno per impostazione predefinita). Non richiedere in blocco URL di caricamento che poi non usi: quelli inutilizzati contano per un limite. Vedi Limiti di frequenza.

Chiedi un preventivo prima di accettare un addebito

• Mostra il prezzo prima di spendere. Invia model, input e callBackUrl completi a POST /api/v1/jobs/quote. Mostra estimatedCost, maxCharge, la valuta (USD) ed expiresAt alla persona che paga. Un preventivo è gratuito: non crea alcuna attività e non accantona fondi.
• Invia ciò che è stato confermato. Un preventivo dura cinque minuti. Dopo la conferma, invia la stessa richiesta a createTask aggiungendo quoteId ed expectedCost.
• Gestisci 40901. Significa che il preventivo è scaduto, oppure che dopo il preventivo sono cambiati l’input o il prezzo. Chiedi un nuovo preventivo e mostra il nuovo importo; non accettare mai in silenzio un importo più alto. Vedi Preventivi.
• Mantieni gli importi esatti. Gli importi sono stringhe decimali come "0.008". Salvali e sommali con aritmetica decimale, non in virgola mobile. Vedi Fatturazione.

Registra l’operazione di business

Sono i tuoi dati a permetterti di riprendere il filo quando una chiamata di rete si interrompe a metà.

• Salva prima dell’invio: l’ID del tuo ordine o della tua operazione, una breve descrizione della richiesta senza segreti né prompt completi (quanto basta per riconoscerla in seguito) e l’Idempotency-Key che invierai.
• Salva dopo l’accettazione: il taskId e il request_id della risposta.
• Riusa la chiave per lo stesso invio. Invia di nuovo l’Idempotency-Key originale per lo stesso account, la stessa chiave API e la stessa richiesta entro 24 ore: ti viene restituita l’attività originale invece di un secondo addebito. Vedi Idempotenza.
• Considera un timeout come «esito ignoto», non come «fallito». Recupera l’invio originale con la sua chiave prima di decidere se crearne uno nuovo. Vedi Diagnosi e ripristino.
• Sappi quanto costa un nuovo tentativo. Riprovare un’attività già fallita crea una nuova attività, alle condizioni e ai prezzi attuali.

Gestisci callback e risultati in modo affidabile

• Verifica ogni callback. Controlla firma e timestamp sui byte originali della richiesta prima di interpretarla, poi elimina i duplicati e salva l’evento. Vedi Webhook.
• Rispondi subito. Rispondi immediatamente con un 2xx e svolgi il lavoro lento nella tua coda.
• Aspettati duplicati e ritardi. Decidi che cosa fare in base allo state dell’attività, non all’ordine in cui arrivano le callback.
• Tieni il polling come riserva. Se una callback tarda, leggi recordInfo con pause sempre più lunghe invece che ogni secondo.
• Leggi il segnale giusto. L’HTTP 202 di createTask significa che l’attività è stata accettata. state: "succeeded" significa che la generazione è terminata. settled: true significa che l’addebito è definitivo.

Limita la concorrenza e conserva i risultati

• Limita le attività in corso per ogni account e dai alle tue richieste delle scadenze. Ogni attività accettata tiene accantonati dei fondi finché non viene liquidata.
• Rispetta Retry-After in caso di 429, ed evita che molti client facciano polling in sincronia ogni secondo. Vedi Limiti di frequenza.
• Metti in cache i dati del catalogo per poco tempo e in modo privato, e non trattare mai un preventivo come un listino prezzi permanente.
• Archivia i risultati che devi conservare. I link di download durano 20 minuti; i media generati vengono conservati al massimo per circa 14 giorni e i caricamenti per un giorno. Puoi accorciare questi periodi, oppure eliminare prima i contenuti di un’attività con POST /api/v1/jobs/purge. Accorciare un’impostazione di conservazione può rimuovere anche i risultati di attività che hai già eseguito: vedi Conservazione e distruzione.
• Non contare sulla disconnessione per fermare il lavoro. Un’attività accettata continua a girare e non può essere annullata.

Verifica prima del lancio

Inizia dalle chiamate gratuite: il catalogo (GET /api/v1/models), il tuo saldo (GET /api/v1/chat/credit) e un preventivo. Poi esegui una piccola generazione reale passando per il tuo flusso di conferma dei costi: viene addebitata come qualsiasi altra attività. Controlla che la tua integrazione gestisca ciascuno di questi casi:

Registra nei log request_id, taskId, l’orario, lo state e gli importi. Tieni chiavi API e prompt completi fuori dai log generali.

Flussi correlati

Preventivi e compatibilità di protocollo · Catalogo dei modelli e schemi · Media · Webhook · Errori · Diagnosi e ripristino · Fatturazione · Conservazione e distruzione