Offizielle SDKs
Offizielle SDKs für fünf Sprachen
Installieren Sie ein Paket und rufen Sie Bild-, Video- und Audiomodelle von Ihrem eigenen Server aus auf. Das SDK übernimmt Authentifizierung und Warten auf Ergebnisse – Sie schreiben nur die Anfrage und lesen die Antwort.
Was das SDK für Sie übernimmt
Sie schreiben einen einzigen Funktionsaufruf. Das SDK signiert die Anfrage, lädt Ihre Dateien hoch, wartet auf das Ergebnis und liefert es als typisierte Daten zurück.
- Ihr CodeEin Funktionsaufruf
- Offizielles SDKSigniert Anfragen, lädt Dateien hoch, wartet auf Ergebnisse
- Bild-, Video- und AudiomodelleDieselben Modelle und Preise wie auf der Website
Ideal für
- Backend-DiensteMedien direkt in Ihrer eigenen API oder Job-Queue erzeugen.
- Skripte und Batch-JobsViele Tasks aus einer Tabelle oder einem geplanten Job anlegen.
- Apps mit ServerDer Schlüssel bleibt auf dem Server, fertige Dateien gehen an die Nutzer.
In drei Schritten loslegen
- Schritt 1
API-Schlüssel anlegen
Erstellen Sie ihn in der Konsole und legen Sie ihn als SPICY_API_KEY auf Ihrem Server ab.
- Schritt 2
Paket installieren
Wählen Sie unten Ihre Sprache und führen Sie die Installationszeile aus.
- Schritt 3
Task erstellen, Ergebnis lesen
Prompt senden, auf den Task warten und die gelieferte Datei speichern.
Ihre Sprache wählen
Jedes SDK erscheint in der Haupt-Registry seiner Sprache und spricht dieselbe API. Wechseln Sie die Tabs für die Installationszeile und eine vollständige Anfrage.
TypeScript
@spicyapi/sdkBenötigt Node.js 22.13+
Ihr Server erstellt Aufgaben und speichert Ergebnisse. Installieren, Schlüssel exportieren, ausführen.
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
spicyapiBenötigt Python 3.11+
Derselbe Ablauf in pythonischer Form: Kosten schätzen, Aufgabe anlegen, auf den Endzustand warten.
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-goBenötigt Go 1.23+
Nur die Standardbibliothek, Ihr Modulgraph wächst also nicht. Mit go get sofort verfügbar.
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/spicyapiBenötigt PHP 8.1+, ext-json, ext-hash
Assoziative Arrays und benannte Argumente, ganz ohne Bibliotheksabhängigkeiten.
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.0Benötigt Java 17+, Jackson
Records und Jackson; run() erledigt Anlegen und Warten in einem Aufruf.
<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);
}Was nach dem Absenden passiert
Bild- und Videogenerierung läuft weiter, nachdem der Create-Aufruf geantwortet hat. Speichern Sie die Task-ID und lassen Sie sich per Webhook oder zeitlich begrenzter Statusabfrage melden, wann der Task fertig ist.
- createTaskMit Idempotency-Key senden; dieselbe Generierung wird nur einmal angenommen.
- taskIdDie Antwort kommt sofort zurück, während der Task weiterläuft.
- Webhook / recordInfoZuerst der signierte Webhook; Polling nur zur Wiederherstellung.
- output.assetsSofort nutzbare URLs. Kopieren Sie, was Sie behalten wollen.
Aufruf aus Browser oder Mobile-App
Ein in einer Client-App eingebauter Schlüssel kann von Nutzern ausgelesen werden. Halten Sie ihn auf Ihrem Server: @spicyapi/proxy ergänzt die Zugangsdaten bei Anfragen Ihres Frontends, sodass die App sie nie erhält.
- Schlüssel in der AppJeder kann ihn auslesen und Ihr Guthaben verbrauchen.
- App mit eingebautem Schlüssel
- SpicyAPI
- Schlüssel auf Ihrem ServerDie App spricht mit Ihrem Server, der Proxy ergänzt den Schlüssel.
- Browser oder Smartphone
- Ihr Server + Proxy
- SpicyAPI
npm install @spicyapi/proxy// app/api/spicy/proxy/route.ts
export { GET, POST } from "@spicyapi/proxy/nextjs";
export const runtime = "nodejs";Vor dem Livegang
- 01Aktuelle Modellverfügbarkeit bestätigen.
- 02Exakte Felder der Modellseite validieren.
- 03API-Schlüssel nur serverseitig halten.
- 04Schätzung vor dem Absenden zeigen.
- 05taskId außerhalb der Browser-Sitzung speichern.
- 06Webhook-Signatur oder Abfragegrenze prüfen.
- 07Angenommene Aufträge als nicht abbrechbar behandeln.
Häufige Fehler beheben
Die meisten Anfangsprobleme sind eines dieser drei. Jede Karte zeigt, was Sie sehen und was Sie ändern müssen.
- 401
Ungültiger API-Schlüssel
Bei der API kam kein oder ein falscher Schlüssel an. Setzen Sie SPICY_API_KEY in derselben Umgebung, in der Ihr Code läuft.
- Warten
Task läuft noch
Videos können einige Minuten dauern. Warten Sie mit Zeitlimit oder nutzen Sie einen Webhook. Ein erneutes Senden ohne denselben Idempotency-Key erzeugt einen zweiten kostenpflichtigen Task.
- Link
Ergebnislink abgelaufen
Download-Links sind nur kurz gültig. Fordern Sie für den Task einen frischen Link an, statt den alten zu speichern.
