Agents & Automatisierung

Dieser Leitfaden richtet sich an KI-Coding-Agents und automatisierte Backends, die SpicyAPI integrieren. Er macht aus der API-Referenz einen begrenzten, wiederaufnehmbaren und prüfbaren Ablauf: Vertrag finden, Eingabe validieren, genau einmal anlegen, sicher warten, Abschluss prüfen und Ausgaben rechtzeitig sichern.

Maschinenlesbare Einstiegspunkte

Lesen Sie zuerst das kleinste Artefakt, das die aktuelle Frage beantwortet. Das spart Kontext und reduziert veraltete Annahmen.

OpenAPI und der aktuelle Modellkatalog sind der Vertrag. Marketingbeispiele sind keine Schema-Quelle. Aktualisieren Sie zwischengespeicherte Discovery-Dateien vor der Codegenerierung und sobald neue Validierungsfehler auftreten.

Offizielle npm-Integrationen

SDK, CLI, MCP und der portable Agent Skill sind vier unabhängige npm-Pakete unter MIT-Lizenz. Installieren Sie nur die benötigte Oberfläche. @spicyapi/skill folgt dem portablen Agent-Skills-Format und ist nicht auf Codex beschränkt.

npm install @spicyapi/sdk
npx --yes --package=@spicyapi/cli spicyapi --help
npx --yes --package=@spicyapi/mcp spicyapi-mcp
npx --yes --package=@spicyapi/skill spicyapi-skill install

Der Skill wird standardmäßig nach ~/.agents/skills/spicyapi installiert. Für Agents mit einem anderen Skills-Verzeichnis geben Sie mit --target /exakter/pfad/spicyapi das genaue Ziel an.

Im Coding-Agent verwenden

Der MCP-Server läuft lokal über stdio und gibt dem Agent Modellkatalog, Preisangebote, Task-Erstellung und Ergebnisabruf. Jede kostenpflichtige Aktion hält für eine Bestätigung an, die der Agent nicht überspringen kann. Unten steht die Form, die jeder Client derzeit empfiehlt; Ort und Format der Konfiguration legt der Client fest und ändern sich zwischen Versionen — maßgeblich ist die jeweilige Herstellerdokumentation.

Claude Code

claude mcp add spicyapi \
  -e SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

npx --yes --package=@spicyapi/skill spicyapi-skill install \
  --target ~/.claude/skills/spicyapi

Codex CLI

codex mcp add spicyapi \
  --env SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

npx --yes --package=@spicyapi/skill spicyapi-skill install \
  --target ~/.codex/skills/spicyapi

Beide Befehle schreiben SPICY_API_KEY aus Ihrer aktuellen Shell in die lokale Konfiguration des Clients. Führen Sie sie in einem Terminal aus, in dem der Schlüssel bereits exportiert ist. Er bleibt lokal — niemals einchecken.

Cursor, Windsurf und Gemini CLI

Ihre Konfigurationsdateien sind ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json und ~/.gemini/settings.json; der Aufbau ist identisch:

{
  "mcpServers": {
    "spicyapi": {
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "YOUR_SERVER_SIDE_KEY" }
    }
  }
}

Das sind Dateien auf Benutzerebene außerhalb Ihres Repositorys. Sobald YOUR_SERVER_SIDE_KEY einen echten Schlüssel enthält, kopieren Sie den Block nie in eine eingecheckte Projektdatei.

VS Code

.vscode/mcp.json wird mit dem Repository eingecheckt, der Schlüssel darf also nicht darin stehen. Lassen Sie VS Code den Wert beim ersten Start abfragen und im eigenen Secret-Storage ablegen:

{
  "inputs": [
    {
      "id": "spicyapi-key",
      "type": "promptString",
      "description": "SpicyAPI key",
      "password": true
    }
  ],
  "servers": {
    "spicyapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "${input:spicyapi-key}" }
    }
  }
}

Nach dem Verbinden

Geben Sie dem Agent direkt eine echte Aufgabe:

Liste mit SpicyAPI die Bildmodelle auf, die ich aufrufen kann, wähle ein günstiges, erzeuge ein filmisches Nachtporträt und gib mir am Ende den Ergebnislink.

Der Agent liest den Katalog, holt das Schema des Modells und ein exaktes Angebot und hält vor jeder Belastung für Ihre Bestätigung an. Mit installiertem Skill verwendet er außerdem durchgehend denselben Idempotency-Key und liest fertige Ergebnis-URLs, statt wiederholt zu pollen.

Ablauf für den Produktivbetrieb

1. Modell und Eingabe festlegen. Wählen Sie den Endpunkt für die gewünschte Modalität und validieren Sie gegen dessen aktuelles Schema. Feldnamen werden nicht geraten; unbekannte Felder werden nicht still verworfen.
2. Genau einmal anlegen. Erzeugen und speichern Sie pro logischer Generierung vor dem ersten Aufruf einen stabilen Idempotency-Key. Bei erneuter Übermittlung derselben Anfrage innerhalb von 24 Stunden verwenden Sie denselben Wert. Für eine neue Generierung verwenden Sie einen neuen Schlüssel. Siehe Idempotenz.
3. taskId sofort speichern. Sie ist die dauerhafte Identität für Status, Webhook-Abgleich, Support und Abrechnung. Liefert ein Retry dieselbe ID, darf kein zweiter lokaler Datensatz entstehen.
4. Begrenzt warten. Bevorzugen Sie signierte Webhooks. Polling beginnt beispielsweise bei 2 Sekunden, wächst um den Faktor 1,5, ist bei 15 Sekunden gedeckelt und besitzt zusätzlich eine Gesamtlaufzeit. succeeded, failed, canceled und expired sind Endzustände.
5. Callback vor Verarbeitung prüfen. Prüfen Sie X-Webhook-Timestamp, den Digest des rohen Request-Bodys und die HMAC-Signatur. Deduplizieren Sie anhand der Liefer-request_id, antworten Sie schnell mit 2xx und verarbeiten Sie anschließend in einer Queue. Details unter Webhooks.
6. Ausgabe rechtzeitig kopieren. Verwenden Sie die signierte URL aus output.assets[].url direkt und kopieren Sie benötigte Ergebnisse in Ihren eigenen Speicher. Ein zusätzlicher Aufruf zum Umwandeln eines Objekt-Keys ist optional. Die URL läuft derzeit nach 20 Minuten ab. Beachten Sie außerdem Medien und Aufbewahrung.

POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Content-Type: application/json
Idempotency-Key: project-42-scene-07-v1

const deadline = Date.now() + 10 * 60_000;
let delay = 2_000;
while (Date.now() < deadline) {
  await sleep(delay);
  const task = await recordInfo(taskId);
  if (['succeeded', 'failed', 'canceled', 'expired'].includes(task.state)) return task;
  delay = Math.min(Math.round(delay * 1.5), 15_000);
}
throw new Error(`task ${taskId} exceeded the polling deadline`);

Ein lokaler Timeout beweist nicht, dass die Generierung gescheitert ist. Bewahren Sie die taskId für den späteren Abgleich auf. HTTP 200 allein bedeutet ebenfalls keinen Erfolg – maßgeblich ist data.state.

Minimaler dauerhafter Datensatz

Speichern Sie localRequestId, idempotencyKey, taskId, model, state, lastCheckedAt, webhookDeliveryId und outputKeys, damit ein Neustart sicher fortsetzen kann. Eine ablaufende Download-URL ist keine dauerhafte Asset-ID.

Mock und Abnahmetests

Erstellen Sie anhand von Tasks, Webhooks und Fehlern einen lokalen Contract-Mock. Er muss mindestens Folgendes abdecken:

• queued → running → succeeded sowie einen Endfehler mit code: 200 und data.state: "failed";
• doppelte Erstellung, die dieselbe taskId zurückgibt;
• gültige Signatur, ungültige Signatur und erneute Webhook-Zustellung;
• 429, 503, Transport-Timeout und Überschreitung der Polling-Frist;
• Neuausstellung einer abgelaufenen Download-URL.

Mocks prüfen die Orchestrierung, nicht die Modellqualität. Führen Sie vor dem Release einen kleinen echten Task mit exakt dem vorgesehenen Modell und Eingabeschema aus.

Checkliste für die Freigabe

• Secrets liegen nur im serverseitigen Secret Store und werden in Logs maskiert.
• Die Integration liest das aktuelle Modellschema, statt Felder zu erraten.
• Pro logischem Request existiert genau ein persistierter Idempotency-Key.
• taskId wird vor der Weiterverarbeitung gespeichert und übersteht Neustarts.
• Polling besitzt Backoff, Maximalintervall und Gesamtlaufzeit.
• Webhooks prüfen Zeitstempel, Rohdaten-Digest und HMAC und deduplizieren Liefer-IDs.
• Der Endzustand kommt aus data.state, nicht aus HTTP-Status oder Envelope-code.
• Ausgaben werden vor Ablauf kopiert; Objekt-Keys bleiben die dauerhafte Referenz.
• Logs enthalten request_id, taskId, Modell und Versuchszahl, aber keine Secrets oder vollständigen Prompts.

Der Abschlussbericht eines Agents sollte Modellendpunkt, Schema-Abrufzeit, Idempotenzstrategie, Polling-Frist, Webhook-Prüfung und die ausgefüllte Checkliste enthalten.