Integration für den Produktivbetrieb

Nutzen Sie diese Seite als Checkliste, bevor echte Nutzer oder echtes Geld von Ihrer Integration abhängen. Jeder Abschnitt sagt, was zu tun ist, warum es wichtig ist und wo die Details stehen. Haben Sie noch keinen ersten Aufruf gemacht, beginnen Sie mit Konto einrichten und dem Schnellstart.

Modell und Protokoll auswählen

• Ein Modell wählen, das Ihr Schlüssel tatsächlich aufrufen kann. Rufen Sie GET /api/v1/models mit Ihrem API-Schlüssel auf und verwenden Sie nur Modelle, bei denen enabled und available beide true sind. Lesen Sie das inputSchema des Modells (die Liste der Felder, die es annimmt) und die examples aus derselben Antwort. Eine Modellseite auf der Website zeigt, was ein Modell kann; sie belegt nicht, dass Ihr Schlüssel es gerade aufrufen darf. Siehe Modelle.
• Den richtigen Einstiegspunkt verwenden. Bild-, Video- und andere Medien-Tasks laufen über die Task-API unter /api/v1 (createTask, danach recordInfo oder ein Callback). Textmodelle lassen sich zusätzlich über OpenAI- oder Anthropic-kompatible Clients unter /v1 aufrufen oder über Gemini-kompatible Clients unter /v1beta. Siehe Text und Streaming.
• Nur mit einem API-Schlüssel authentifizieren. Ein Anmelde-Cookie der Konsole ist kein Zugangsnachweis für die API und darf nie in Code kopiert werden.

Schlüssel und Guthaben schützen

• Den Schlüssel auf Ihrem Server halten. Legen Sie ihn in Ihrem Backend in einer Umgebungsvariable (SPICY_API_KEY) ab, niemals in Browser-Code, mobilen Apps oder einem öffentlichen Repository. Siehe Authentifizierung.
• Ein Schlüssel pro Umgebung und Dienst. Benennen Sie jeden Schlüssel nach dem, was ihn nutzt (zum Beispiel „production-worker“), damit Sie einen sperren können, ohne die anderen zu stoppen.
• Limits für den Produktivschlüssel setzen: ein Tageslimit, das auf einen schlechten Tag ausgelegt ist, ein Monatsbudget, erlaubte Modelle und, für serverseitige Aufrufe, eine IP-Freigabeliste. Siehe Einschränkungen pro Schlüssel. Denken Sie beim Bearbeiten eines Schlüssels daran, dass ein leeres Limitfeld kein Limit bedeutet.
• Ablaufdaten prüfen. Ein Schlüssel mit Ablaufdatum hört am Ende dieses Tages (UTC) auf zu funktionieren und liefert dieselbe 401 wie ein gesperrter Schlüssel. Tragen Sie das Datum in Ihren Kalender ein, oder setzen Sie für ein langlebiges Backend gar keines.
• Nicht mitten in einer Serie von Tasks ohne Geld dastehen. Ein wegen des Guthabens abgelehnter Task liefert 40201 und kommt nie in die Warteschlange. Schalten Sie unter Benachrichtigungen die Warnung bei niedrigem Guthaben ein und ziehen Sie das automatische Aufladen in Betracht.
• Auch Team-Limits gelten. Gehört Ihr Schlüssel zu einem Team, können die Tages- und Monatslimits des Teams Tasks mit 40202 stoppen, selbst wenn die Limits des Schlüssels noch nicht erreicht sind, und jeder Task wird aus dem Guthaben des Team-Inhabers bezahlt. Siehe Ausgabenlimits.
• Die Rotation des Webhook-Signaturschlüssels planen. Das Rotieren des Schlüssels in der Konsole hat keine Übergangszeit: Der alte Schlüssel signiert ab sofort nicht mehr. Zustellungen, die noch wiederholt werden, werden mit dem neuen Schlüssel signiert. Rotieren Sie in einer ruhigen Phase, spielen Sie den neuen Schlüssel sofort bei Ihrem Empfänger ein und holen Sie Verpasstes mit recordInfo nach. Siehe Webhooks.

Eingaben auf Ihrem Server vorbereiten

• Gegen das aktuelle Schema validieren. Halten Sie sich an Feldtypen, erlaubte Werte und bedingte Pflichtfelder im inputSchema, und validieren Sie nach einem Modellwechsel erneut, denn jedes Modell hat sein eigenes Schema.
• Medien auf unterstützte Weise senden. Verwenden Sie eine öffentlich erreichbare https://-URL oder eine unterstützte Base64-Eingabe. Für lokale Dateien fordern Sie eine Upload-URL an, laden die Bytes per PUT hoch, rufen files/{fileId}/commit auf und übergeben dann die zurückgegebene spicy://-URI im Eingabefeld des Modells. Siehe Medien.
• Jede hochgeladene Datei innerhalb ihrer Lebensdauer verwenden. Eine spicy://-URI funktioniert bis zu dem expiresAt aus der Antwort auf den Commit (standardmäßig 1 Tag). Fordern Sie nicht massenhaft Upload-URLs an, die Sie dann nie nutzen: Ungenutzte zählen gegen ein Limit. Siehe Rate Limits.

Vor einer Belastung eine Kostenschätzung einholen

• Den Preis zeigen, bevor Geld ausgegeben wird. Senden Sie model, input und callBackUrl vollständig an POST /api/v1/jobs/quote. Zeigen Sie der zahlenden Person estimatedCost, maxCharge, die Währung (USD) und expiresAt. Eine Kostenschätzung ist kostenlos: Sie legt keinen Task an und reserviert kein Guthaben.
• Genau das absenden, was bestätigt wurde. Eine Kostenschätzung gilt fünf Minuten. Senden Sie nach der Bestätigung dieselbe Anfrage an createTask, ergänzt um quoteId und expectedCost.
• 40901 behandeln. Dieser Code bedeutet, dass die Kostenschätzung abgelaufen ist, sich die Eingabe geändert hat oder sich der Preis seit der Schätzung geändert hat. Holen Sie eine neue Kostenschätzung ein und zeigen Sie den neuen Betrag; akzeptieren Sie nie stillschweigend einen höheren. Siehe Kostenschätzungen.
• Geldbeträge exakt halten. Beträge sind Dezimalzeichenketten wie "0.008". Speichern und addieren Sie sie mit Dezimalarithmetik, nicht mit Gleitkommazahlen. Siehe Abrechnung.

Den Geschäftsvorgang dauerhaft speichern

Ihre eigenen Aufzeichnungen sind das, womit Sie wieder aufsetzen können, wenn ein Netzwerkaufruf auf halbem Weg scheitert.

• Vor dem Senden speichern: Ihre eigene Auftrags- oder Vorgangs-ID, eine kurze Beschreibung der Anfrage ohne Geheimnisse und ohne vollständige Prompts (genug, um sie später wiederzuerkennen) und den Idempotency-Key, den Sie senden werden.
• Nach der Annahme speichern: taskId und request_id aus der Antwort.
• Den Idempotenzschlüssel für dieselbe Übermittlung wiederverwenden. Senden Sie den ursprünglichen Idempotency-Key innerhalb von 24 Stunden erneut, für dasselbe Konto, denselben API-Schlüssel und dieselbe Anfrage; Sie erhalten dann den ursprünglichen Task zurück statt einer zweiten Belastung. Siehe Idempotenz.
• Eine Zeitüberschreitung als „unbekannt“ behandeln, nicht als „fehlgeschlagen“. Stellen Sie die ursprüngliche Übermittlung mit ihrem Idempotenzschlüssel wieder her, bevor Sie entscheiden, eine neue anzulegen. Siehe Fehlerdiagnose und Wiederherstellung.
• Wissen, was eine Wiederholung kostet. Die Wiederholung eines bereits fehlgeschlagenen Tasks legt einen neuen Task zu den dann geltenden Bedingungen und Preisen an.

Callbacks und Ergebnisse zuverlässig verarbeiten

• Jeden Callback prüfen. Prüfen Sie Signatur und Zeitstempel anhand der unveränderten Bytes der Anfrage, bevor Sie parsen; entfernen Sie danach Duplikate und speichern Sie das Ereignis. Siehe Webhooks.
• Schnell bestätigen. Antworten Sie sofort mit einem 2xx und erledigen Sie langsame Arbeit in Ihrer eigenen Warteschlange.
• Mit Duplikaten und Verzögerungen rechnen. Entscheiden Sie anhand des state des Tasks, was zu tun ist, nicht anhand der Reihenfolge, in der Callbacks eintreffen.
• Polling als Rückfallebene behalten. Kommt ein Callback verspätet, lesen Sie recordInfo mit wachsenden Pausen statt jede Sekunde.
• Das richtige Signal lesen. HTTP 202 von createTask heißt, dass der Task angenommen wurde. state: "succeeded" heißt, dass die Generierung fertig ist. settled: true heißt, dass die Belastung endgültig ist.

Parallelität begrenzen und Ergebnisse sichern

• Gleichzeitig laufende Tasks begrenzen, pro Konto, und Ihren eigenen Anfragen Fristen setzen. Jeder angenommene Task hält Guthaben reserviert, bis er abgerechnet ist.
• Bei 429 den Wert von Retry-After befolgen und vermeiden, dass viele Clients im Gleichschritt jede Sekunde pollen. Siehe Rate Limits.
• Katalogdaten nur kurz und privat cachen, und eine Kostenschätzung nie als dauerhafte Preisliste behandeln.
• Benötigte Ergebnisse archivieren. Download-Links gelten 20 Minuten; erzeugte Medien werden höchstens etwa 14 Tage aufbewahrt, Uploads einen Tag. Sie können diese Fristen verkürzen oder die Inhalte eines Tasks mit POST /api/v1/jobs/purge früher löschen. Das Verkürzen einer Aufbewahrungseinstellung kann auch Ergebnisse von Tasks entfernen, die Sie bereits ausgeführt haben; siehe Aufbewahrung.
• Sich nicht darauf verlassen, dass ein Verbindungsabbruch die Arbeit stoppt. Ein angenommener Task läuft weiter und kann nicht abgebrochen werden.

Vor dem Livegang prüfen

Beginnen Sie mit den kostenlosen Aufrufen: dem Katalog (GET /api/v1/models), Ihrem Guthaben (GET /api/v1/chat/credit) und einer Kostenschätzung. Führen Sie danach eine kleine echte Generierung über Ihren eigenen Ablauf zur Kostenbestätigung aus; sie wird wie jeder andere Task abgerechnet. Prüfen Sie, dass Ihre Integration jeden dieser Fälle bewältigt:

Protokollieren Sie request_id, taskId, die Uhrzeit, den state und die Beträge. Halten Sie API-Schlüssel und vollständige Prompts aus allgemeinen Logs heraus.

Verwandte Abläufe

Kostenschätzungen und Protokollkompatibilität · Modellkatalog und Schemas · Medien · Webhooks · Fehler · Fehlerdiagnose und Wiederherstellung · Abrechnung · Aufbewahrung