Authentifizierung

Jeder API-Aufruf, der etwas erstellt, liest oder abrechnet, sendet Ihren API-Key im Authorization-Header. Einzige Ausnahme ist der öffentliche Modellkatalog zur Bewertung: Er benötigt keinen Key.

Authorization: Bearer sk-spicy-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Die native API (/api/v1/*) akzeptiert nur Bearer-Keys, keine Cookies oder Abfrageparameter.

Die Text- und Videokompatibilitätsendpunkte (/v1, /v1beta) verwenden denselben Key und akzeptieren zusätzlich x-api-key aus Anthropic-SDKs und x-goog-api-key aus Google-GenAI-SDKs. Die offiziellen SDKs funktionieren so mit lediglich geänderter Basis-URL. Siehe Text und Streaming. Diese beiden Header haben unter /api/v1 keine Wirkung; kein Endpunkt akzeptiert Keys im URL-Abfragestring.

API-Keys und Konsole sind getrennt

Nur /api/v1, /v1 und /v1beta akzeptieren API-Keys. Die Webkonsole verwendet eine eigene Browsersitzung. Eine Konsolenanmeldung ist daher kein API-Key; ein offengelegter Key ermöglicht keine Konsolenanmeldung. Falsche Zugangsdatenart führt immer zu 401, nie zu einem Berechtigungsfehler.

Wie ein Key aussieht

Festes Präfix sk-spicy-, gefolgt von 48 kleinen Hexadezimalzeichen.

Das Präfix ist bewusst gewählt: Eine Erkennung mit Benachrichtigung ist besser, als erst fremde Guthabenausgaben zu bemerken.

Einen Key erstellen

1. Öffnen Sie Konsole → API-Keys und klicken auf Key erstellen.
2. Benennen Sie ihn nach dem nutzenden Dienst, etwa production backend oder staging worker. Beim Widerruf müssen Sie ihn erkennen.
3. Optional legen Sie unter Erweitert Ausgabenlimits, Modellfreigabeliste, IP-Freigabeliste und Ablaufdatum fest. Alles ist später änderbar.
4. Kopieren Sie den Key oder klicken auf Als Datei speichern und bestätigen die Speicherung. Nach Dialogende wird er nicht erneut angezeigt.

Die Erstellung benötigt die Teamrolle Inhaber, Administrator oder Entwickler. Der Key gehört zum oben links gewählten Team; Nutzung und Limits zählen für dieses Team. Jedes Team darf bis zu 50 aktive Keys haben. Für bezahlte Arbeit benötigt Ihr Konto außerdem bestätigte E-Mail und Guthaben. Siehe Kontoeinrichtung.

Wo Sie den Key aufbewahren

• Am eigenen Rechner zum Testen: export SPICY_API_KEY="…" im Terminal, gültig bis zum Fensterschließen, oder eine vom Code geladene .env-Datei. Fügen Sie .env vor dem ersten Commit zur .gitignore hinzu.
• Auf Server oder Hostingplattform: Verwenden Sie Geheimnis- oder Umgebungsvariableneinstellungen und lesen im Code SPICY_API_KEY aus der Umgebung.
• Niemals in Quellcode, Chat, Screenshot, Supportticket oder Prompt eines KI-Assistenten einfügen.

Liefern Sie einen Key niemals an Clients aus

Dasselbe gilt für mobile Binärdateien, Desktopclients, öffentliche Notebooks, CI-Logs und Inhalte eines ins Supportticket kopierten curl -v-Dumps.

Eigene Werkzeuge im eigenen Browser sind ein anderer Fall. Die API akzeptiert Browseraufrufe. Selbst genutzte Werkzeuge wie die SillyTavern-Erweiterung oder eine Rollenspiel-App, in die Sie Ihren eigenen Key einfügen, dürfen direkt aufrufen. Die Regel oben betrifft Keys in etwas, das andere laden. Geben Sie jedem Werkzeug einen eigenen Key mit Tageslimit, um Ausgaben zuzuordnen und separat zu widerrufen.

Einschränkungen je Key

Konfigurieren Sie diese bei Erstellung oder später in der Konsole. Sie werden serverseitig durchgesetzt.

Die Karte jedes Keys zeigt aktuelle Limits, die Sie jederzeit ändern können.

Limits zählen für laufende Tasks reserviertes Geld und bereits ausgegebenes Geld. Ein Key kann das Limit deshalb bei noch laufenden Tasks erreichen. msg nennt das erreichte Limit. Nennt msg bei 40202 ein Plattformkontingent, liegt es nicht am Key: Ein weiterer Key hilft nicht; versuchen Sie es später.

Die IP-Freigabeliste prüft Ihre tatsächliche öffentliche Adresse aus Sicht des Edge-Netzwerks, nicht die Adresse des letzten Proxys. Ihre Ausgangsadresse ist die öffentliche IP Ihrer Serveranfragen. Hostingplattformen nennen sie meist in Netzwerkeinstellungen; am eigenen Rechner zeigt curl https://ifconfig.me sie an.

Tasks gehören dem erstellenden Key

Ein Task ist über die API nur für den erstellenden API-Key sichtbar. Bei jedem anderen Key, auch desselben Teams:

Zwei Dinge sind nicht keygebunden. Webhooks werden auch nach Widerruf des erstellenden Keys ausgeliefert. Und alle Teamtasks sind unabhängig vom Key unter Konsole → Logs aufgeführt; die Detailansicht zeigt Verwendeter Key.

Rotation

• Ein Key je Umgebung – Produktion, Staging, lokal – erlaubt separaten Widerruf.
• Geplante Rotation: Erstellen Sie den neuen Key und senden damit nur neue Tasks. Halten Sie den alten aktiv, bis alle seine Tasks abgeschlossen sind, spätestens bis zum jeweiligen deadlineAt, und Ergebnisse eingesammelt wurden. Widerrufen Sie ihn dann. Diese Reihenfolge gilt nur für weiterhin vertrauenswürdige alte Keys.
• Widerruf wirkt sofort und ist endgültig. Es gibt keinen abzuwartenden Cache und keine Reaktivierung; Sie erstellen einen neuen Key.

Nach einer Offenlegung

Bei unerwarteten Ausgaben kontaktieren Sie uns über Konsole → Support mit Task-IDs oder request_id-Werten.

Wie ein Fehler aussieht

{
  "code": 401,
  "msg": "Credentials are invalid or expired",
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

Auch der HTTP-Status ist 401. Jeder Authentifizierungsfehler liefert code: 401; msg nennt die Art:

Verzweigen Sie anhand von code, nicht anhand des Textes: Formulierungen können sich ändern und folgen Ihrer Fehlersprache. Weitere Unterscheidungen unter Fehler.

Kann das Konto selbst nicht aufrufen, etwa wegen unbestätigter E-Mail oder Sperrung, erhalten Sie stattdessen 403. Key-Wechsel hilft dabei nicht.