Glossar

Weil das Produkt eine API ist, verwendet diese Dokumentation Fachbegriffe. Diese Seite erklärt jeden davon in einfacher Sprache, alphabetisch sortiert. Jeder Eintrag hat drei Teile: was das Wort allgemein bedeutet, was es bei SpicyAPI bedeutet und welche Seite die vollständigen Details enthält.

Andere Seiten verlinken direkt auf einzelne Einträge. Wenn Sie also an anderer Stelle über ein Wort stolpern, steht es sehr wahrscheinlich hier. Den Gesamtüberblick finden Sie unter So funktioniert SpicyAPI.

Agent Skill

Ein Ordner mit schriftlichen Anweisungen, den ein KI-Coding-Assistent liest, bevor er mit einer Arbeit beginnt, ähnlich einem Betriebshandbuch, das man neuen Kollegen in die Hand gibt. Er enthält kein Programm und tut von sich aus nichts.

Bei SpicyAPI: Der offizielle Skill, veröffentlicht als @spicyapi/skill, bringt Assistenten wie Claude Code, Codex oder Cursor bei, SpicyAPI richtig zu nutzen: den Live-Katalog lesen statt zu raten, Ihnen vor kostenpflichtiger Arbeit den Preis zeigen, Idempotenzschlüssel wiederverwenden und Ihren API-Schlüssel nie in Code einfügen. Sie installieren ihn mit npx skills add spicyapi-ai/spicy-skill. Er arbeitet gut mit dem MCP-Server zusammen.

Siehe: Agent Skill

API

Kurz für Application Programming Interface, auf Deutsch Programmierschnittstelle: ein fester Satz von Anfragen, die ein Programm an ein anderes senden kann, samt der Antworten, die es darauf erhält. Eine Website ist dafür gemacht, dass Menschen klicken; eine API ist dafür gemacht, dass Programme sie aufrufen.

Bei SpicyAPI: Über die API erreicht jedes Werkzeug die Modelle. Playground, CLI, MCP-Server und SDK senden alle dieselbe Art von Anfragen an api.spicyapi.ai, die auch Ihr eigener Code senden kann.

Siehe: OpenAPI und Endpunktübersicht

API-Schlüssel

Eine geheime Zeichenfolge, die belegt, dass eine Anfrage von Ihnen kommt. Behandeln Sie sie wie ein Passwort, das Programme benutzen.

Bei SpicyAPI: Schlüssel beginnen mit sk-spicy- und werden in der Konsole auf der Seite API-Schlüssel angelegt. Ein Schlüssel wird nur ein einziges Mal angezeigt; geht er verloren, legen Sie einen neuen an. Jede Anfrage sendet den Schlüssel im Header Authorization: Bearer. Bewahren Sie Schlüssel auf Ihrem eigenen Computer oder Server auf, niemals in einer Webseite, einer mobilen App, einem öffentlichen Repository, auf einem Screenshot oder in einem Chat. Jeder Schlüssel kann eigene Ausgabenlimits, eine Liste erlaubter Modelle und eine Liste erlaubter IP-Adressen haben.

Siehe: Authentifizierung · Konto einrichten

Arbeitsbereich und Team

Ein gemeinsamer Bereich, in dem mehrere Personen unter einem Konto dieselben Schlüssel, Tasks und Budgets nutzen.

Bei SpicyAPI: Ein Team-Arbeitsbereich hat Mitglieder mit Rollen: owner, admin, developer, billing und readonly. Jedes Mitglied sieht Task-Übersichten und Verbrauch; owner, admin und developer sehen zusätzlich die Eingaben und Ergebnisse der Tasks. Das Konto des Inhabers bezahlt die neuen Tasks des Teams, und Mitglieder sehen nie das eigene Guthaben oder die Zahlungen des Inhabers. Teams können Tages- und Monatsbudgets festlegen.

Siehe: Konsole und Arbeitsbereiche

Asset und Ausgabe-URL

Ein Asset ist eine einzelne Datei, die ein Task erzeugt hat, etwa ein Bild oder ein Video. Seine Ausgabe-URL ist die Webadresse, von der Sie es herunterladen.

Bei SpicyAPI: Ein fertiger Task listet seine Dateien in output.assets[]. Jede hat eine url, die Sie direkt und ohne API-Schlüssel herunterladen können, dazu expiresAt, mime (den Dateityp) und Angaben zur Größe. Der Link gilt etwa 20 Minuten; fragen Sie den Task erneut ab, um einen frischen zu erhalten. Die Datei selbst wird höchstens etwa 14 Tage aufbewahrt, speichern Sie also eine Kopie von allem, was Sie brauchen. Ein Asset mit pending: true wird gerade noch gespeichert (versuchen Sie es in ein paar Sekunden erneut); eines mit unavailable: true ist endgültig weg.

Siehe: Asynchrone Tasks · Medien

Aufbewahrung

Wie lange gespeicherte Daten erhalten bleiben, bevor sie gelöscht werden.

Bei SpicyAPI:

Wie lange erzeugte Dateien, Uploads und Prompt-Texte aufbewahrt werden, können Sie in der Konsole auf der Seite Datenschutz verkürzen, für einen einzelnen Task auch mit dem Header X-Spicy-Retention. Mit Purge vernichten Sie Inhalte jederzeit. Keine Einstellung macht eine Frist länger.

Siehe: Datenaufbewahrung und Löschung

Ausgabenlimit

Eine Obergrenze für Ausgaben, die Sie im Voraus festlegen, damit ein Fehler oder ein in falsche Hände geratener Schlüssel nicht Ihr gesamtes Guthaben aufbrauchen kann.

Bei SpicyAPI: Jeder API-Schlüssel kann ein Tageslimit, ein Monatslimit und ein Gesamtlimit in US-Dollar haben, die Sie selbst festlegen; neue Schlüssel haben keines, bis Sie eines hinzufügen. Teams können zusätzlich Tages- und Monatsbudgets festlegen, und die Plattform hat ein eigenes Tageslimit. Ein Task, der eine dieser Grenzen überschreiten würde, wird schon vor dem Start mit 40202 abgelehnt, und es wird nichts berechnet. Tageslimits beginnen um 00:00 UTC neu, Monatslimits am 1. des Monats; Gesamtlimits beginnen nie neu. Die Eingabe 0 bedeutet, dass auf dieser Ebene kein Limit gilt.

Siehe: Abrechnung · Authentifizierung

Basis-URL

Der feste erste Teil jeder Adresse, die eine API verwendet. Sie tragen ihn einmal in Ihrem Code oder in den Einstellungen Ihres Werkzeugs ein, und jede Anfrage hängt ihren eigenen Pfad daran an.

Bei SpicyAPI: Es gibt zwei.

Anfragen im Google-Gemini-Format gehen an https://api.spicyapi.ai/v1beta. Die offiziellen Bibliotheken von Anthropic und Google GenAI hängen den Versionsteil selbst an; für sie tragen Sie deshalb nur https://api.spicyapi.ai ein.

Siehe: Schnellstart · Text und Streaming

Callback

Ein anderer Name für einen Webhook. Bei SpicyAPI übergeben Sie die Adresse beim Erstellen eines Tasks im Feld callBackUrl.

CLI

Kurz für Command-Line Interface, auf Deutsch Kommandozeile: ein Programm, das Sie bedienen, indem Sie Befehle in ein Terminal tippen, statt Schaltflächen anzuklicken.

Bei SpicyAPI: Mit dem Befehl spicyapi, veröffentlicht als @spicyapi/cli, listen Sie Modelle auf, prüfen Preise, erstellen Bild- und Video-Tasks, warten auf deren Abschluss und laden die Ergebnisse herunter, ohne Code zu schreiben. Nur tasks create und tasks retry kosten Geld, und beide fragen vorher nach. Die CLI braucht Node.js 22.13 oder neuer; mit npx @spicyapi/cli führen Sie sie ohne Installation aus.

Siehe: Kommandozeilen-Tool (CLI)

Eingabeschema

Eine maschinenlesbare Beschreibung, welche Felder eine Anfrage enthalten darf, welchen Typ jedes Feld hat und welche Werte erlaubt sind.

Bei SpicyAPI: Jedes Modell hat sein eigenes inputSchema, geschrieben in JSON Schema. Es listet die Felder, die Sie in input angeben können, etwa prompt, image_url oder duration_seconds, mit ihren Grenzen und Standardwerten. Der Server prüft jede Anfrage dagegen, und schon ein einziges unbekanntes Feld ergibt einen 400-Fehler. Der Playground baut sein Formular aus demselben Schema, und die examples im Katalog sind vollständige Eingaben, die diese Prüfung bereits bestanden haben.

Siehe: Modellkatalog und Schemas · Spicy Schema

Endpunkt

Eine bestimmte Anfrage, die eine API annimmt, benannt durch eine HTTP-Methode (etwa GET zum Lesen oder POST zum Senden) und einen Pfad.

Bei SpicyAPI: Zum Beispiel startet POST /api/v1/jobs/createTask eine Generierung, und GET /api/v1/jobs/recordInfo liest einen Task. Die vollständige Adresse besteht aus der Basis-URL, gefolgt vom Pfad.

Siehe: OpenAPI und Endpunktübersicht

Endzustand

Ein abschließender Status: Hat ein Task ihn erreicht, ändert er sich nie wieder.

Bei SpicyAPI: Jeder Task-Status außer queued oder running ist ein Endzustand: succeeded, failed, expired und bei älteren Datensätzen canceled. Prüfen Sie im Code auf „nicht queued und nicht running“, statt die Endzustände aufzuzählen; so funktioniert Ihr Code weiter, falls ein neuer hinzukommt. Webhooks werden nur gesendet, wenn ein Task einen Endzustand erreicht. Nur beendete Tasks lassen sich per Purge löschen, und Tasks mit failed oder expired lassen sich wiederholen.

Siehe: Asynchrone Tasks

Envelope

Eine feste äußere Hülle, in die jede Antwort verpackt ist, damit ein Programm immer weiß, wo es nachsehen muss.

Bei SpicyAPI: Antworten der nativen API (unter /api/v1) sehen so aus:

{ "code": 200, "msg": "success", "data": {}, "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2" }

code ist ein Business-Code (200 bedeutet Erfolg), msg eine für Menschen lesbare Meldung, data enthält die Antwort und fehlt bei einem Fehler ganz, und request_id kennzeichnet diese Anfrage. Die mit OpenAI, Anthropic und Gemini kompatiblen Endpunkte verwenden stattdessen die Antwortformen ihres jeweiligen Protokolls.

Siehe: Fehler

Fehlercode

Ein kurzer, fester Wert, der einem Programm sagt, was schiefgelaufen ist, damit es reagieren kann, ohne den Meldungstext zu lesen.

Bei SpicyAPI: Es gibt zwei Arten.

• code im Envelope beschreibt die Anfrage selbst. 200 bedeutet Erfolg; weitere Werte sind unter anderem 400 (ungültige Anfrage), 401 (Problem mit dem Schlüssel), 40201 (Guthaben zu niedrig), 40202 (ein Ausgabenlimit ist erreicht) und 429 (zu viele Anfragen). Es ist ein Business-Code und damit genauer als der HTTP-Status, der mitgesendet wird.
• errorCode erscheint bei einem Task, der angenommen wurde und danach fehlgeschlagen ist. Er hat einen von neun Werten: invalid_request, unsupported_combination, content_rejected, rate_limited, upstream_unavailable, generation_failed, timeout, invalid_asset oder upstream_failed.

Die zugehörigen Meldungen msg und errorMessage sind für Menschen gedacht: Ihr Wortlaut kann sich ändern, und sie können in der von Ihnen gewählten Sprache zurückkommen. Programme sollten ausschließlich nach den Codes verzweigen.

Siehe: Fehler

Guthaben

Das Geld auf Ihrem Konto, mit dem Generierungen bezahlt werden.

Bei SpicyAPI: Ein vorausbezahltes Guthaben in US-Dollar, ohne Credits oder Punkte. Was Sie einzahlen, verfällt nie; Bonusguthaben hat ein eigenes Verfallsdatum. Sie laden es in der Konsole auf der Seite Abrechnung auf. GET /api/v1/chat/credit liefert drei Beträge als Text, etwa "128.42": available (frei verfügbar), held (für noch laufende Tasks reserviert) und total. Manche Konten haben außerdem Bonusguthaben aus Aktionen oder eine bewilligte Kreditlinie; diese erscheinen in einer eigenen Aufschlüsselung. Einen kostenlosen Tarif gibt es nicht: Neue Konten starten bei null.

Siehe: Abrechnung · Konto einrichten

HTTP-Status

Eine dreistellige Zahl am Anfang jeder Webantwort, die grob sagt, wie die Anfrage verlaufen ist. 2xx heißt, es hat funktioniert, 4xx, dass mit der Anfrage etwas nicht stimmte, und 5xx, dass der Server ein Problem hatte.

Bei SpicyAPI: Das Erstellen eines Tasks antwortet mit 202 Accepted. Das heißt, der Task wurde angenommen, nicht, dass er schon fertig ist. Native Antworten tragen außerdem einen genaueren Business-Code code: Zu wenig Guthaben ist zum Beispiel HTTP 402 mit code 40201. Entscheiden Sie sich in Ihrem Code für einen der beiden Werte, nach dem Sie verzweigen, und bleiben Sie dabei.

Siehe: Fehler

Idempotenzschlüssel

Eine Kennung, die Sie sich für einen bestimmten Arbeitsauftrag ausdenken, damit dieselbe Anfrage, zweimal gesendet, die Arbeit trotzdem nur einmal auslöst. Idempotent bedeutet: Etwas ein weiteres Mal zu tun, hat keine zusätzliche Wirkung.

Bei SpicyAPI: Senden Sie ihn beim Erstellen oder Wiederholen eines Tasks im Header Idempotency-Key, zum Beispiel order-8814-render-1. Bricht Ihre Verbindung ab und Sie wissen nicht, ob der Task gestartet ist, senden Sie dieselbe Anfrage mit demselben Idempotenzschlüssel und demselben API-Schlüssel innerhalb von 24 Stunden erneut: Sie erhalten den ursprünglichen Task zurück und zahlen nicht doppelt. Verwenden Sie für jeden neuen Arbeitsauftrag einen neuen Idempotenzschlüssel. Wird ein Idempotenzschlüssel mit einer anderen Anfrage wiederverwendet, lehnt der Server mit 409 ab. Idempotenzschlüssel dürfen bis zu 128 Zeichen lang sein.

Siehe: Idempotenz

JSON

Ein reines Textformat für strukturierte Daten, bestehend aus Namen und Werten in geschweiften Klammern. Fast jede API verwendet es, weil jede Programmiersprache es lesen kann.

Bei SpicyAPI: Anfragen und Antworten sind JSON. Eine minimale Task-Anfrage sieht so aus:

{ "model": "MODEL_ID_FROM_CATALOG", "input": { "prompt": "A paper lantern on a rainy street at night" } }

MODEL_ID_FROM_CATALOG steht für eine echte Modell-ID aus dem Live-Katalog. Geldbeträge werden immer als Text gesendet, etwa "0.008", damit nie ein Betrag versehentlich gerundet wird.

Siehe: Schnellstart

Katalog

Die Liste der verfügbaren Modelle mit ihren Preisen und den Eingaben, die jedes Modell annimmt.

Bei SpicyAPI: Es gibt zwei Fassungen derselben Liste.

• Der öffentliche Katalog braucht weder Konto noch Schlüssel. Ihn zeigt spicyapi.ai/explore, und ihn liefert GET /console/v1/catalog/models. Nutzen Sie ihn zum Stöbern und Vergleichen.
• Der authentifizierte Katalog, GET /api/v1/models mit Ihrem API-Schlüssel, ist die einzige verlässliche Quelle dafür, welche Modelle Ihr Schlüssel gerade aufrufen kann, und zwar zu den Preisen Ihres Kontos. Wählen Sie vor kostenpflichtiger Arbeit einen Eintrag, bei dem enabled und available beide true sind.

Der CLI-Befehl spicyapi models list, die SDK-Methode listModels() und das MCP-Tool spicyapi_models_list lesen alle den authentifizierten Katalog.

Siehe: Modellkatalog und Schemas

Kostenschätzung

Ein im Voraus berechneter Preis für genau eine Anfrage (englisch „quote“).

Bei SpicyAPI: POST /api/v1/jobs/quote nimmt denselben Anfragerumpf, den Sie absenden würden, und liefert estimatedCost, maxCharge und expiresAt, ohne einen Task anzulegen oder Geld zu reservieren. Das kostet nichts und gilt fünf Minuten. Senden Sie mit der zurückgegebenen quoteId und expectedCost ab und haben sich Anfrage oder Preis inzwischen geändert, wird die Übermittlung mit 40901 abgelehnt, statt einen anderen Betrag zu berechnen. CLI und MCP-Server holen vor dem Erstellen eines Tasks automatisch eine Kostenschätzung ein.

Siehe: Kostenschätzungen und Kompatibilität

MCP

Kurz für Model Context Protocol: ein offener Standard, über den KI-Assistenten zusätzliche Fähigkeiten, sogenannte Tools, aus kleinen Programmen laden, den MCP-Servern.

Bei SpicyAPI: Der offizielle Server @spicyapi/mcp läuft auf Ihrem eigenen Computer und gibt Assistenten wie Claude, Cursor, VS Code oder Codex 15 SpicyAPI-Tools an die Hand: Modelle durchsuchen, Kostenschätzungen einholen, Tasks erstellen, Dateien hochladen und Ergebnisse abrufen. Das Starten, Wiederholen oder Vernichten eines Tasks hält an und bittet Sie um Bestätigung, wo es einen Preis gibt, mit diesem Preis; der Assistent kann nicht an Ihrer Stelle antworten. Der Server braucht Node.js 22.13 oder neuer.

Siehe: MCP-Server

Modalität

Die Art von Medien, mit der ein Modell arbeitet.

Bei SpicyAPI: Jeder Katalogeintrag hat eine modality wie image, video oder text und eine Liste von tasks wie text-to-image oder image-to-video. Damit filtern Sie den Katalog, zum Beispiel GET /api/v1/models?modality=video&task=image-to-video.

Siehe: Modellkatalog und Schemas

Modell-ID

Der exakte Name, den Sie senden, um ein Modell auszuwählen.

Bei SpicyAPI: IDs haben die Form publisher/model/task: wer das Modell entwickelt hat, welches Modell in welcher Version und was der Endpunkt tut. Endpunkte für Bildbearbeitung enden auf edit. Kopieren Sie eine ID immer aus dem Live-Katalog (GET /api/v1/models, spicyapi models list oder listModels()), nie aus dem Gedächtnis oder von einer Webseite, denn Modelle kommen hinzu, werden pausiert und eingestellt. Beispiele in dieser Dokumentation schreiben MODEL_ID_FROM_CATALOG dorthin, wo eine echte ID hingehört; wer den Platzhalter selbst sendet, erhält einen Fehler.

Siehe: Modellkatalog und Schemas

Node.js

Ein kostenloses Programm, das JavaScript außerhalb eines Webbrowsers ausführt. Viele Entwicklerwerkzeuge sind in JavaScript geschrieben und setzen es voraus.

Bei SpicyAPI: SDK, CLI und MCP-Server brauchen Node.js 22.13 oder neuer; das Installationsprogramm, das der Skill verwendet, verlangt 22.20 oder neuer. Installieren Sie die LTS-Version von nodejs.org und prüfen Sie sie danach im Terminal mit node --version. Für den Playground brauchen Sie Node.js nicht, ebenso wenig, wenn Sie die API aus einer anderen Programmiersprache aufrufen.

Siehe: CLI: Bevor Sie beginnen

npm und npx

npm ist der Paketmanager, der mit Node.js mitkommt: Er lädt JavaScript-Pakete herunter und installiert sie. npx, ebenfalls enthalten, führt ein Paket aus, ohne es dauerhaft zu installieren.

Bei SpicyAPI: Die vier Node.js-Werkzeuge sind npm-Pakete: @spicyapi/sdk, @spicyapi/cli, @spicyapi/mcp und @spicyapi/skill. Zum Beispiel fügt npm install @spicyapi/sdk das TypeScript-SDK einem Projekt hinzu, und npx @spicyapi/cli status führt die CLI einmalig aus, ohne sie zu installieren. Die SDKs für Python, Go, PHP und Java installieren Sie stattdessen mit den Werkzeugen ihres jeweiligen Ökosystems; siehe die Seite des jeweiligen SDKs.

Siehe: TypeScript-SDK · Kommandozeilen-Tool (CLI)

OpenAI-kompatibel

Nimmt Anfragen im selben Format an wie die API von OpenAI, sodass für OpenAI geschriebene Software funktioniert, wenn Sie nur Adresse und Schlüssel ändern.

Bei SpicyAPI: Textmodelle lassen sich über POST /v1/chat/completions und POST /v1/responses im OpenAI-Format aufrufen, über POST /v1/messages im Anthropic-Format und über /v1beta/models/… im Google-Gemini-Format, jeweils mit demselben API-Schlüssel. Richten Sie die offizielle Bibliothek openai auf https://api.spicyapi.ai/v1 aus. Jedes Textmodell funktioniert mit jedem dieser Formate. Diese Endpunkte berechnen den Preis, der bei Annahme der Anfrage gilt, und nehmen keine Kostenschätzung entgegen; setzen Sie deshalb Ausgabenlimits für den Schlüssel.

Siehe: Text und Streaming

Playground

Ein Formular auf einer Website, in dem Sie ein Modell ausprobieren, indem Sie Felder ausfüllen und auf eine Schaltfläche klicken, ohne Code zu schreiben.

Bei SpicyAPI: Jede Modellseite auf spicyapi.ai hat einen Tab Playground. Ohne Konto können Sie das Formular ausfüllen und sehen, welche Anfrage daraus entsteht; zum Ausführen müssen Sie angemeldet sein und Guthaben haben. Jeder Lauf zeigt zuerst seine geschätzten Kosten, wird wie ein API-Aufruf abgerechnet und erscheint in der Konsole unter Logs.

Siehe: So funktioniert SpicyAPI

Polling

Einen Server immer wieder fragen, ob etwas fertig ist, statt darauf zu warten, benachrichtigt zu werden.

Bei SpicyAPI: Sie pollen einen Task mit GET /api/v1/jobs/recordInfo?taskId=…, bis sein Status nicht mehr queued oder running ist. Warten Sie vor der ersten Abfrage 2 bis 3 Sekunden, verlängern Sie jede weitere Wartezeit etwa um das 1,5-Fache, bis 10 bis 15 Sekunden erreicht sind, und hören Sie zu einer selbst gewählten Frist auf zu warten. Das Aufhören stoppt den Task nicht. Polling zählt gegen Ihr Rate Limit; im Produktivbetrieb ist ein Webhook deshalb die bessere Wahl.

Siehe: Asynchrone Tasks

Purge

Gespeicherte Inhalte auf Anforderung endgültig löschen, statt zu warten, bis ihre Frist abläuft.

Bei SpicyAPI: POST /api/v1/jobs/purge (oder Ergebnisse zerstören in den Logs der Konsole, spicyapi tasks purge, purgeTask()) löscht die erzeugten Dateien eines beendeten Tasks, sein Ergebnis und den Prompt-Text in seiner Eingabe. Der Abrechnungsdatensatz bleibt erhalten: Betrag, Modell, Status, Zeitstempel und request_id. Purge ist kein Abbrechen, erstattet nichts und lässt sich nicht rückgängig machen. Es funktioniert nur bei Tasks, die bereits beendet sind.

Siehe: Datenaufbewahrung und Löschung

Rate Limit

Eine Obergrenze dafür, wie viele Anfragen Sie in einem bestimmten Zeitraum senden dürfen, damit ein außer Kontrolle geratenes Programm einen Dienst nicht überlasten kann.

Bei SpicyAPI: Die native API erlaubt standardmäßig 1.000 Anfragen pro 10 Sekunden pro Konto. Das gilt jeweils getrennt für Lese- und für Schreibanfragen; beide Kontingente teilen sich alle Schlüssel des Kontos. Polling zählt als Leseanfrage, eine intensive Polling-Schleife kann das Einreichen von Tasks also nicht blockieren. Wer darüber liegt, erhält 429 mit einem Header Retry-After, der angibt, wie viele Sekunden zu warten sind. Gezählt werden Anfragen, nicht Tasks: Bereits laufende Tasks verbrauchen nichts davon.

Siehe: Rate Limits

request_id

Eine Kennung, die der Server an eine einzelne Anfrage hängt, damit sich genau diese Anfrage in Logs wiederfinden lässt.

Bei SpicyAPI: Jede native Antwort trägt request_id (zum Beispiel req_01k3…), zusätzlich im Header X-Request-Id, bei Erfolg wie bei Fehlern. Bewahren Sie sie in Ihren Logs auf und nennen Sie sie, wenn Sie den Support kontaktieren. In einem Webhook der Version 2 kennzeichnet request_id stattdessen die Zustellung (whd_…) und bleibt gleich, wenn diese Zustellung wiederholt wird.

Siehe: Fehler · Webhooks

Reservierung, Abrechnung und Freigabe

Die drei Schritte, mit denen ein Task bezahlt wird. Eine Reservierung ist Geld, das zurückgelegt, aber noch nicht ausgegeben ist, so wie ein Hotel einen Betrag auf Ihrer Karte vormerkt.

Bei SpicyAPI:

• Reservierung (hold): Wird ein Task angenommen, werden seine geschätzten Kosten (estimatedCost) in Ihrem Guthaben zurückgelegt und als held angezeigt. Das ist noch keine Belastung, und es ist zugleich der Höchstbetrag, den dieser Task überhaupt kosten kann.
• Abrechnung (settle): Ist der Task erfolgreich, zahlen Sie das, was er tatsächlich verbraucht hat, nie mehr als die Reservierung. Was übrig bleibt, geht in Ihr verfügbares Guthaben zurück. settled: true am Task bedeutet, dass der Betrag in cost endgültig ist.
• Freigabe (release): Bei fehlgeschlagenen oder abgelaufenen Tasks wird die Reservierung normalerweise vollständig freigegeben. Einige Inhaltsablehnungen werden zum angenommenen Angebotspreis berechnet, sofern die Modellseite diese Ausnahme ausdrücklich nennt. Prüfen Sie den endgültigen Betrag anhand von settled und cost.

Siehe: Abrechnung

SDK

Kurz für Software Development Kit: eine fertige Codebibliothek, die Sie in Ihr eigenes Programm einbinden, damit Sie nicht jede Anfrage von Hand bauen müssen.

Bei SpicyAPI: Es gibt fünf offizielle SDKs – @spicyapi/sdk für TypeScript und JavaScript unter Node.js, dazu je eines für Python, Go, PHP und Java. Jedes kümmert sich um den Schlüssel, das Warten auf Tasks, Wiederholungen, Uploads und die Prüfung von Webhooks, sodass wenige Aufrufe einen Task vom Absenden bis zum Ergebnis bringen. Alle laufen nur auf Servern, nicht in Browsern oder mobilen Apps, und keines deckt Chatmodelle ab.

Siehe: TypeScript-SDK · Python-SDK · Go-SDK · PHP-SDK · Java-SDK

Signatur (HMAC)

Ein Code, der aus einer Nachricht und einem gemeinsamen Geheimnis berechnet wird, damit der Empfänger prüfen kann, dass die Nachricht echt ist und unterwegs nicht verändert wurde. HMAC ist das Standardverfahren, um einen solchen Code zu berechnen.

Bei SpicyAPI: Jede Webhook-Zustellung trägt einen Header X-Webhook-Signature: ein HMAC-SHA256 über die Task-ID, den Zustellungszeitpunkt und einen Digest des exakten Bodys, erstellt mit Ihrem Webhook-Signaturschlüssel. Diesen Schlüssel erzeugen oder rotieren Sie in der Konsole auf der Seite Webhooks, und er wird nur in diesem Moment angezeigt; haben Sie ihn nie kopiert, rotieren Sie ihn dort. Prüfen Sie die Signatur, bevor Sie einer Zustellung vertrauen, mit verifyWebhook aus dem SDK oder mit spicyapi webhooks verify, und lehnen Sie Zustellungen ab, deren Zeitstempel mehr als fünf Minuten von der aktuellen Zeit abweicht.

Siehe: Webhooks

Streaming (SSE)

Eine Antwort Stück für Stück über eine offene Verbindung senden, während sie entsteht, statt am Ende alles auf einmal. SSE, kurz für Server-Sent Events, ist das gängige Webformat dafür.

Bei SpicyAPI: Textmodelle können ihre Antwort Wort für Wort über die kompatiblen Endpunkte streamen (zum Beispiel mit stream: true an /v1/chat/completions) oder über das native POST /api/v1/jobs/stream. Jedes Protokoll markiert das Ende eines Streams auf seine eigene Weise. Schließen Sie die Verbindung vorzeitig, empfangen Sie keinen weiteren Text, das Modell arbeitet aber weiter, und die Nutzung wird trotzdem berechnet. Gestreamter Text wird nicht gespeichert und lässt sich später nicht erneut abrufen.

Siehe: Text und Streaming

Task

Eine Arbeitseinheit, die im Hintergrund läuft: Sie geben sie ab und holen das Ergebnis später ab.

Bei SpicyAPI: Jede Bild- oder Videogenerierung ist ein Task. POST /api/v1/jobs/createTask nimmt ihn an und liefert eine Task-ID, die mit job_ beginnt; danach fragen Sie den Task per Polling ab oder erhalten einen Webhook, sobald er fertig ist. Über die API lässt sich ein Task nur mit demselben API-Schlüssel lesen, mit dem er erstellt wurde; die Seite Logs in der Konsole zeigt alle Tasks Ihres Kontos. Ein angenommener Task kann nicht abgebrochen werden.

Siehe: Asynchrone Tasks · Verbindliche Tasks und Wiederholen

Task-Status

Wo sich ein Task in seinem Lebenslauf gerade befindet.

Bei SpicyAPI:

Ältere Datensätze können auch canceled zeigen; neue Tasks erreichen diesen Status nie. Behandeln Sie jeden Status außer queued oder running als Endzustand.

Siehe: Asynchrone Tasks

Terminal

Ein Textfenster, in das Sie Befehle tippen und mit der Eingabetaste ausführen. Unter macOS ist das die App Terminal; unter Windows verwenden Sie PowerShell; die meisten Linux-Desktops öffnen eines mit Strg + Alt + T. Nicht zu verwechseln mit einem Endzustand (englisch „terminal state“).

Bei SpicyAPI: In einem Terminal führen Sie die CLI aus, installieren Node.js-Werkzeuge wie den MCP-Server oder den Skill und probieren die curl-Beispiele dieser Dokumentation aus.

Siehe: CLI: Bevor Sie beginnen

Umgebungsvariable

Ein benannter Wert, den Ihr Terminal an jedes Programm weitergibt, das es startet. So kann ein Programm eine Einstellung lesen, etwa einen geheimen Schlüssel, ohne dass der Wert in einer Datei oder einem Befehl stehen muss.

Bei SpicyAPI: SDK, CLI, MCP-Server und die Codebeispiele dieser Dokumentation lesen Ihren API-Schlüssel aus einer Variable namens SPICY_API_KEY. So setzen Sie sie für das aktuelle Terminalfenster:

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

Diese Einstellung ist vergessen, sobald Sie das Fenster schließen. Die CLI-Seite zeigt, wie Sie sie dauerhaft setzen und prüfen, ohne den ganzen Schlüssel auszugeben.

Siehe: CLI: Bevor Sie beginnen · Konto einrichten

Upload

Eine Datei von Ihrem Computer an einen Server senden, damit sie dort verwendet werden kann.

Bei SpicyAPI: Ein Modell, das ein Bild, ein Video oder Audio als Eingabe nimmt, kann es auf drei Wegen erhalten: als öffentlichen HTTPS-Link zur Datei, als kleines Bild, das als Data-URI direkt in die Anfrage eingebettet ist (bis 1 MiB), oder als hochgeladene Datei. Das Hochladen hat drei Schritte: ein Ticket anfordern (POST /api/v1/common/upload-url), die Datei an die Adresse im Ticket senden und sie anschließend bestätigen (POST /api/v1/files/{fileId}/commit). Die Bestätigung liefert eine spicy://-Adresse, die Sie in das Eingabefeld des Modells schreiben. Sie ist einen Tag lang verwendbar. Bilder dürfen bis zu 10 MiB groß sein, Audio und Video bis zu 90 MiB und 600 Sekunden lang. uploadFile() im SDK, spicyapi files upload und der MCP-Server erledigen alle drei Schritte für Sie.

Siehe: Medien

Webhook

Eine Adresse auf Ihrem eigenen Server, die ein anderer Dienst aufruft, wenn etwas passiert, damit Sie nicht ständig nachfragen müssen. Auch Callback genannt.

Bei SpicyAPI: Tragen Sie beim Erstellen eines Tasks eine öffentliche HTTPS-Adresse in callBackUrl ein. Erreicht der Task einen Endzustand, sendet SpicyAPI dorthin eine POST-Anfrage mit demselben Inhalt, den recordInfo liefern würde, signiert mit Ihrem Webhook-Signaturschlüssel. Antworten Sie innerhalb von 15 Sekunden mit einem beliebigen 2xx-Status; andernfalls wird die Zustellung wiederholt, bis zu acht Versuche über rund neun Stunden, und Sie können sie in der Konsole auf der Seite Webhooks erneut senden. Dass ein Task lediglich startet, wird nicht gemeldet. Lokale Adressen wie http://localhost:3000 können keine Webhooks empfangen; nutzen Sie daher Polling, solange Sie auf Ihrem eigenen Computer entwickeln.

Siehe: Webhooks