OpenAPI und Endpunktübersicht
Herunterladbarer OpenAPI-3.1-Vertrag, öffentliche Endpunkte mit passenden Leitfäden, gemeinsame Anfrageheader und produktiver API-Ursprung.
Der maschinenlesbare öffentliche Vertrag ist als OpenAPI-3.1-YAML verfügbar. Erzeugen Sie damit einen Client oder prüfen Sie Ihre Integration gegen die aktuellen öffentlichen Endpunkte.
Produktiver API-Ursprung
https://api.spicyapi.ai ist der einzige unter OpenAPI servers[0].url deklarierte produktive Ursprung. Task-APIs verwenden /api/v1, Protokollkompatibilität /v1 und /v1beta.
Diese Plattform-APIs unterstützen Modellwahl, Kostenschätzung und Ausgabenüberwachung ohne Öffnen der Konsole. Der Modellkatalog enthält Kontopreise; bei parameterabhängigen Preisen verwenden Sie eine Preisabfrage für die exakte Eingabe. Taskverlauf und Nutzung sind auf den verwendeten API-Key beschränkt. Erstellung, Rotation und Budgeteinstellungen von Keys bleiben in der Konsole. Jede Tabelle verlinkt den vollständigen Endpunktleitfaden.
Modellübersicht, Preise und Konto-APIs
| Methode | Pfad | Zweck | Leitfaden |
|---|---|---|---|
GET | /console/v1/catalog/models | Öffentlicher Bewertungskatalog: ohne API-Key, Standardpreise, anhand der Quelladresse begrenzt | Schnellstart |
GET | /api/v1/models | Aufrufbare Modelle, Kontopreise und optionale Schemas lesen | Modellkatalog |
GET | /api/v1/models/{model} | Ein Modell mit vollständigem JSON Schema lesen | Modellkatalog |
POST | /api/v1/jobs/quote | Exakte Anfrage für fünf Minuten bepreisen, ohne Task oder Guthabenreservierung | Preisabfragen |
GET | /api/v1/chat/credit | Verfügbares, reserviertes und gesamtes Guthaben lesen | Abrechnung |
GET | /api/v1/usage | Aufrufe und abgerechnete USD-Ausgaben des aktuellen Keys nach Datum und Modell lesen | Abrechnung |
Generierungs- und Task-APIs
| Methode | Pfad | Zweck | Leitfaden |
|---|---|---|---|
GET | /api/v1/jobs | Taskverlauf des aktuellen API-Keys mit Cursor-Paginierung auflisten | Tasks |
POST | /api/v1/jobs/createTask | Asynchronen Generierungsauftrag erstellen | Tasks |
GET | /api/v1/jobs/recordInfo | Mit dem aufrufenden API-Key erstellten Task lesen | Tasks |
POST | /api/v1/jobs/retry | Neuen Task aus fehlgeschlagenem oder abgelaufenem erstellen; historische Abbruchdatensätze bleiben kompatibel | Taskaktionen |
POST | /api/v1/jobs/purge | Dateien und Prompt eines abgeschlossenen Tasks vernichten; Abrechnung unverändert | Aufbewahrung |
POST | /api/v1/jobs/stream | Textmodell ausführen und Antwort über SSE streamen | Text und Streaming |
Medien-APIs
| Methode | Pfad | Zweck | Leitfaden |
|---|---|---|---|
POST | /api/v1/common/upload-url | Ticket für direkten Medienupload ausstellen | Medien |
POST | /api/v1/files/{fileId}/commit | Direkten Upload prüfen und bestätigen; taskbereite spicy://-URI zurückgeben | Medien |
POST | /api/v1/files/import | LoRA-Gewichtsdatei über einen Link importieren, optional mit einem Zugriffstoken, das nur einmal verwendet und nie gespeichert wird; gibt eine taskbereite spicy://-URI zurück | Adapter-Gewichte |
POST | /api/v1/common/download-url | Kurzlebige Taskausgabe-Download-URL ausstellen (optional: abgeschlossene Tasks enthalten bereits eine) | Medien |
POST | /api/v1/assets | Datei in der Asset-Bibliothek speichern (Idempotency-Key erforderlich) | Medien |
GET | /api/v1/assets | Gespeicherte Assets auflisten (Filter favorite, collectionId, q; Sortierung mit sort) | Medien |
GET | /api/v1/assets/usage | Plan, Nutzung und Limits der Asset-Bibliothek abrufen | Medien |
GET | /api/v1/assets/{assetId} | Ein Asset mit frischem privatem Vorschaulink abrufen | Medien |
PATCH | /api/v1/assets/{assetId} | Asset umbenennen oder sein Flag favorite ändern | Medien |
DELETE | /api/v1/assets/{assetId} | Asset löschen | Medien |
GET | /api/v1/assets/entities | Figuren Ihrer Asset-Bibliothek auflisten (nur lesend) | Medien |
GET | /api/v1/assets/entities/{entityId} | Eine Figur mit ihren Bildern in Reihenfolge abrufen (nur lesend) | Medien |
Authentifizierung und Antwortstruktur
Außer dem öffentlichen Katalog benötigt jeder Endpunkt Ihren API-Key als Authorization: Bearer sk-spicy-…. Kompatibilitätsendpunkte (/v1, /v1beta) akzeptieren außerdem x-api-key aus Anthropic-SDKs und x-goog-api-key aus Google-GenAI-SDKs. Ein Key im URL-Abfragestring wird nie akzeptiert. Tasks, Wiederholungen, Vernichtung und Downloadlinks sind nur für den erstellenden API-Key sichtbar. Siehe Authentifizierung.
JSON-Antworten der Task-API verwenden {code,msg,data,request_id}; Kompatibilitätsendpunkte verwenden die eigene Protokollstruktur. Das Taskergebnis steht in data.state, nicht im umschließenden code. Siehe Fehler.
Endpunktübergreifende Anfrageheader
| Header | Ziel | Zweck |
|---|---|---|
Authorization: Bearer … | Alles außer öffentlichem Katalog | Ihr API-Key |
Idempotency-Key | jobs/createTask, jobs/retry, jobs/stream, POST /v1/videos sowie /v1- und /v1beta-Textendpunkte | Sichere Wiederholung nach Netzwerkfehler. Taskendpunkte liefern ursprünglichen Task; Textendpunkte verhindern zweite Belastung, stellen verlorene Antwort aber nicht wieder her. Siehe Idempotenz |
X-Spicy-Retention | jobs/createTask, jobs/stream | Verkürzt die Aufbewahrung von Ausgaben und Prompt dieses Tasks, in Sekunden. Siehe Aufbewahrung |
Accept-Language | Beliebig | Fehlermeldungssprache; Codes bleiben gleich. Siehe Fehler |
OpenAPI-Datei verwenden
- Anfragen ohne eigenen Code ausprobieren: Importieren Sie die oben verlinkte OpenAPI-Datei in einen API-Client wie Postman, Insomnia oder Bruno und setzen den Bearer-Token auf Ihren API-Key. Taskerstellung kostet Geld.
- Client erzeugen: Verwenden Sie dieselbe Datei mit einem OpenAPI-3.1-Codegenerator Ihrer Sprache.
Vertragsänderungen
- Bewahren Sie Modellparameter nicht als dauerhafte fest codierte Kopie auf; lesen Sie
inputSchemaaus/models/{model}. - Akzeptieren Sie unbekannte Antwortfelder, erfinden aber keine unbekannten Anfragefelder.
- Verwenden Sie die OpenAPI-YAML vor Veröffentlichung zur Codegenerierung oder für Vertragstests.
Kompatibilitätsendpunkte
| Methode | Pfad | Protokoll |
|---|---|---|
GET | /v1/models | Models |
POST | /v1/chat/completions | Chat Completions |
POST | /v1/responses | Responses |
POST | /v1/messages | Messages |
POST | /v1beta/models/{model}:generateContent | Gemini generateContent |
POST | /v1beta/models/{model}:streamGenerateContent | Gemini streamGenerateContent |
POST | /v1/videos | Videos |
GET | /v1/videos/{videoId} | Videostatus |
GET | /v1/videos/{videoId}/content | Videoinhalt |
Textendpunkte beschreibt Text und Streaming; die Abrechnung erklärt Preisabfragen und Kompatibilität.
Das offizielle TypeScript-Paket ist @spicyapi/sdk. Für Python und Go oder ohne zusätzliche Abhängigkeit rufen die kopierbaren Referenzclients unten die Endpunkte allein mit der Sprachlaufzeit auf. Der Python-Client führt einen vollständigen Medienjob aus: Referenz hochladen und bestätigen, Preis abfragen, Task erstellen und bis zum Endzustand abfragen, Datei- oder Textergebnis lesen, abgelaufenen Ausgabelink erneuern, gespeicherten Inhalt anschließend vernichten und Webhook-Signatur prüfen. Der Go-Client deckt dieselbe Pipeline mit Kontext bei jedem Aufruf und typisiertem, über errors.As abrufbarem Fehler ab. Der TypeScript-Client unterstützt Taskerstellung, Wiederholung, Statusabfragen und begrenztes Warten; für Uploads und weitere Node.js-Funktionen verwenden Sie das SDK.
Kopierbare Referenz-Clients
Abhängigkeitsfreie Beispiele für Modellsuche, Task-Erstellung, Wiederholung fehlgeschlagener Tasks, Statusabfragen, alle Endzustände, begrenztes Warten, Idempotenz und Fehler. Angenommene Tasks können nicht abgebrochen werden.
Dokumentationsbeispiele, keine veröffentlichten npm-, PyPI- oder Go-Module. Zehn Minuten sind ein lokales Limit, kein Produktions-SLA.