Vai al contenuto principale

SDK ufficiali

SDK ufficiali per cinque linguaggi

Installa un pacchetto e richiama i modelli di immagini, video e audio dal tuo server. L’SDK gestisce autenticazione e attesa dei risultati: tu scrivi solo la richiesta e leggi la risposta.

Cosa fa l’SDK per te

Scrivi una sola chiamata di funzione. L’SDK firma la richiesta, carica i tuoi file, attende il risultato e te lo restituisce come dati tipizzati.

  1. Il tuo codiceUna chiamata di funzione
  2. SDK ufficialeFirma le richieste, carica i file, attende i risultati
  3. Modelli di immagini, video e audioStessi modelli e prezzi del sito
Senza SDK invii tu le stesse richieste via HTTPS. L’SDK elimina solo il codice ripetitivo.

Ideale per

  • Servizi backendGenera contenuti dentro la tua API o la tua coda di lavori.
  • Script e lavori batchCrea molte attività da un foglio di calcolo o da un job pianificato.
  • App con un serverTieni la chiave sul server e invia i file pronti agli utenti.

Parti in tre passaggi

  1. Passaggio 1

    Crea una chiave API

    Creane una nella console e salvala come SPICY_API_KEY sul tuo server.

  2. Passaggio 2

    Installa il pacchetto

    Scegli il tuo linguaggio qui sotto ed esegui la riga di installazione.

  3. Passaggio 3

    Crea un’attività, leggi il risultato

    Invia un prompt, attendi l’attività, poi salva il file che restituisce.

Scegli il tuo linguaggio

Ogni SDK è pubblicato sul registro principale del suo linguaggio e usa la stessa API. Cambia scheda per vedere la riga di installazione e una richiesta completa.

TypeScript

@spicyapi/sdk

Richiede Node.js 22.13+

Il tuo server crea le attività e archivia i risultati. Installa, esporta la chiave, esegui.

Installa · bash
npm install @spicyapi/sdk
export SPICY_API_KEY="injected from your secret manager"
Crea un’attività e leggi il risultato · ts
import { randomUUID } from "node:crypto";
import { SpicyClient } from "@spicyapi/sdk";

const client = new SpicyClient();
const model = await client.getModel("MODEL_ID_FROM_CATALOG");
const task = await client.run(
  { model: model.model, input: { prompt: "A cinematic night portrait" } },
  { idempotencyKey: randomUUID() },
);
console.log(task.state, task.output?.assets?.[0]?.url);

Cosa succede dopo l’invio

La generazione di immagini e video continua anche dopo che la chiamata di creazione ha risposto. Conserva l’ID dell’attività, poi lascia che sia un webhook o un controllo di stato a tempo limitato a dirti quando è finita.

  1. createTaskInvia con una chiave di idempotenza: una generazione viene accettata una volta sola.
  2. taskIdLa risposta arriva subito, mentre l’attività continua l’esecuzione.
  3. Webhook / recordInfoPrima un webhook firmato; il polling limitato serve solo a recuperare.
  4. output.assetsURL pronti all’uso. Tieni una tua copia di tutto ciò che conta.

Chiamare da browser o app mobile

Una chiave dentro un’app client è una chiave pubblica. Tienila sul tuo server: @spicyapi/proxy aggiunge le credenziali alle richieste del tuo front-end, così l’app non le vede mai.

  • Chiave dentro l’appChiunque può leggerla e spendere il tuo saldo.
    1. App con la chiave dentro
    2. SpicyAPI
  • Chiave sul tuo serverL’app parla con il tuo server, e il proxy aggiunge la chiave.
    1. Browser o telefono
    2. Il tuo server + proxy
    3. SpicyAPI
@spicyapi/proxy
npm install @spicyapi/proxy
next.js
// app/api/spicy/proxy/route.ts
export { GET, POST } from "@spicyapi/proxy/nextjs";
export const runtime = "nodejs";

Prima di andare online

  • 01Verifica che il modello sia disponibile in questo momento.
  • 02Valida i campi esatti mostrati sulla sua pagina modello.
  • 03Tieni la chiave API solo sul server.
  • 04Mostra il costo stimato prima dell’invio.
  • 05Conserva il taskId fuori dalla sessione del browser.
  • 06Verifica le firme dei webhook oppure limita i controlli di stato.
  • 07Tratta un’attività accettata come definitiva e non annullabile.

Risolvi gli errori più comuni

Di solito i problemi iniziali sono uno di questi tre. Ogni scheda mostra cosa vedi e l’unica cosa da cambiare.

  • 401

    Chiave API non valida

    All’API non è arrivata nessuna chiave, o è sbagliata. Imposta SPICY_API_KEY nello stesso ambiente in cui gira il tuo codice.

  • attesa

    Attività ancora in corso

    I video possono richiedere qualche minuto. Attendi con un limite di tempo o usa un webhook. Rinviare senza la stessa Idempotency-Key crea una seconda attività a pagamento.

  • link

    Link del risultato scaduto

    I link di download durano poco. Chiedi un link nuovo per l’attività invece di conservare quello vecchio.

Domande frequenti