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.
- Il tuo codiceUna chiamata di funzione
- SDK ufficialeFirma le richieste, carica i file, attende i risultati
- Modelli di immagini, video e audioStessi modelli e prezzi del sito
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
- Passaggio 1
Crea una chiave API
Creane una nella console e salvala come SPICY_API_KEY sul tuo server.
- Passaggio 2
Installa il pacchetto
Scegli il tuo linguaggio qui sotto ed esegui la riga di installazione.
- 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/sdkRichiede Node.js 22.13+
Il tuo server crea le attività e archivia i risultati. Installa, esporta la chiave, esegui.
npm install @spicyapi/sdk
export SPICY_API_KEY="injected from your secret manager"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);Python
spicyapiRichiede Python 3.11+
Lo stesso percorso in forma pythonica: preventivo, creazione, attesa dello stato finale.
pip install spicyapi
export SPICY_API_KEY="injected from your secret manager"import uuid
from spicyapi import SpicyClient, output_assets
client = SpicyClient() # reads SPICY_API_KEY from the environment
model = client.get_model("MODEL_ID_FROM_CATALOG")
quote = client.quote_task(
model=model["model"],
input_data={"prompt": "A cinematic night portrait"},
)
print(quote["estimatedCost"], quote["maxCharge"]) # decide before you spend
task = client.create_task(
model=model["model"],
input_data={"prompt": "A cinematic night portrait"},
idempotency_key=str(uuid.uuid4()),
quote_id=quote["quoteId"],
expected_cost=quote["estimatedCost"],
)
final = client.wait_for_terminal(task["taskId"])
for asset in output_assets(final):
print(asset["url"])Go
github.com/spicyapi-ai/spicy-goRichiede Go 1.23+
Solo libreria standard, quindi il tuo grafo dei moduli non cresce. Disponibile subito con go get.
go get github.com/spicyapi-ai/spicy-go
export SPICY_API_KEY="injected from your secret manager"client, err := spicy.New(spicy.Options{}) // reads SPICY_API_KEY from the environment
if err != nil {
return err
}
request := spicy.CreateTaskInput{
Model: "MODEL_ID_FROM_CATALOG",
Input: map[string]any{"prompt": "A cinematic night portrait"},
}
quote, err := client.Quote(ctx, request)
if err != nil {
return err
}
request.QuoteID = quote.QuoteID
request.ExpectedCost = quote.EstimatedCost
// Store this next to your own record of the job before sending it: its whole
// purpose is to still be there after the crash that lost the response.
key, err := spicy.NewIdempotencyKey()
if err != nil {
return err
}
task, err := client.CreateTask(ctx, request, key, spicy.CreateTaskOptions{})
if err != nil {
return err
}
final, err := client.WaitForTerminal(ctx, task.TaskID, spicy.WaitOptions{})
if err != nil {
return err
}
for _, asset := range final.ReadyAssets() {
log.Println(asset.URL)
}PHP
spicyapi/spicyapiRichiede PHP 8.1+, ext-json, ext-hash
Array associativi e argomenti con nome, senza alcuna dipendenza.
composer require spicyapi/spicyapiuse SpicyApi\SpicyClient;
$client = new SpicyClient(); // reads SPICY_API_KEY from the environment
$quote = $client->quote('MODEL_ID_FROM_CATALOG', ['prompt' => 'A cinematic night portrait']);
printf("at most %s\n", $quote['maxCharge']); // decide before you spend
$task = $client->createTask(
model: $quote['model'],
input: ['prompt' => 'A cinematic night portrait'],
idempotencyKey: SpicyClient::idempotencyKey(),
quoteId: $quote['quoteId'],
expectedCost: $quote['estimatedCost'],
);
$final = $client->waitForTerminal($task['taskId']);
foreach (SpicyClient::readyAssets($final) as $asset) {
echo $asset['url'], "\n";
}Java
ai.spicyapi:spicyapi-java:0.1.0Richiede Java 17+, Jackson
Record e Jackson; run() fa creazione e attesa in una sola chiamata.
<dependency>
<groupId>ai.spicyapi</groupId>
<artifactId>spicyapi-java</artifactId>
<version>0.1.0</version>
</dependency>SpicyClient client = SpicyClient.builder().apiKeyFromEnvironment().build();
CreateTaskRequest request = CreateTaskRequest.of(
"MODEL_ID_FROM_CATALOG",
Map.of("prompt", "A cinematic night portrait"));
TaskQuote quote = client.quote(request); // free; reserves nothing
System.out.println("this will cost at most " + quote.maxCharge());
TaskRecord task = client.run( // createTask + waitForTerminal
request.withQuote(quote), UUID.randomUUID().toString());
// Transcription and similar endpoints answer in text and return no files at all.
task.outputText().ifPresent(System.out::println);
for (TaskAsset asset : task.assets()) {
asset.url().ifPresent(System.out::println);
}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.
- createTaskInvia con una chiave di idempotenza: una generazione viene accettata una volta sola.
- taskIdLa risposta arriva subito, mentre l’attività continua l’esecuzione.
- Webhook / recordInfoPrima un webhook firmato; il polling limitato serve solo a recuperare.
- 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.
- App con la chiave dentro
- SpicyAPI
- Chiave sul tuo serverL’app parla con il tuo server, e il proxy aggiunge la chiave.
- Browser o telefono
- Il tuo server + proxy
- SpicyAPI
npm install @spicyapi/proxy// 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.
