Kostenschätzungen und Protokollkompatibilität

Eine exakte Anfrage schätzen lassen

Eine Kostenschätzung (englisch quote) nennt Ihnen den Preis genau einer Anfrage, bevor Sie bezahlen. Sie ist kostenlos, legt keinen Task an und reserviert kein Geld. Danach senden Sie dieselbe Anfrage zusammen mit der Kostenschätzung ab, und sie wird nur zu dem Preis angenommen, den Sie gesehen haben.

Die folgenden Befehle sind für ein Terminal unter macOS oder Linux gedacht, mit gesetztem SPICY_API_KEY wie im Schnellstart beschrieben. MODEL_ID_FROM_CATALOG ist ein Platzhalter: Setzen Sie einen model-Wert aus Ihrem Live-Katalog (GET /api/v1/models) ein, und übernehmen Sie jedes Feld in input aus dem Schema dieses Modells.

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" }
}

curl https://api.spicyapi.ai/api/v1/jobs/quote \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

{
  "code": 200,
  "msg": "success",
  "data": {
    "quoteId": "QUOTE_ID_FROM_RESPONSE",
    "model": "MODEL_ID_FROM_CATALOG",
    "estimatedCost": "0.008",
    "maxCharge": "0.008",
    "currency": "USD",
    "quantity": "1",
    "unit": "per_image",
    "expiresAt": "2026-09-17T10:05:00Z"
  },
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" },
  "quoteId": "QUOTE_ID_FROM_RESPONSE",
  "expectedCost": "0.008"
}

SPICY_IDEMPOTENCY_KEY="$(uuidgen)"   # einmal pro neuem Task; nur wiederverwenden, um genau diese Anfrage erneut zu senden

curl https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  --data-binary @submit.json

POST /api/v1/jobs/stream, der native Textstream, nimmt eine Kostenschätzung auf dieselbe Weise an; siehe Text und Streaming.

Nach einer verlorenen Antwort weitermachen

Ist eine Übermittlung in ein Timeout gelaufen oder die Verbindung abgebrochen, wissen Sie nicht, ob sie angenommen wurde. Für createTask, retry und POST /v1/videos gilt:

1. Senden Sie die ursprüngliche Anfrage mit ihrem ursprünglichen Idempotency-Key und demselben API-Schlüssel erneut. Sie erhalten den ursprünglichen Task in seinem aktuellen Zustand zurück und zahlen nicht doppelt.
2. Legen Sie keinen weiteren Task mit einem neuen Idempotenzschlüssel an. Ein neuer Idempotenzschlüssel bedeutet eine neue Generierung und eine neue Belastung.
3. Das erneute Senden einer bereits angenommenen Anfrage bleibt gültig, auch wenn die Kostenschätzung inzwischen abgelaufen ist. Der Ablauf entscheidet nur über die Annahme, nicht über den Task, der bei der Annahme entstanden ist.
4. Ein 409 bedeutet nicht „nicht angelegt“. Entweder hat sich die Anfrage geändert (dann ist es ein neuer Arbeitsauftrag, der einen neuen Idempotenzschlüssel braucht), oder sie wurde mit einem anderen API-Schlüssel desselben Kontos gesendet (dann senden Sie sie mit dem ursprünglichen API-Schlüssel erneut). Siehe Idempotenz.
5. Die endgültige Belastung lesen Sie aus cost und settled in recordInfo.

Kostenschätzungen in den offiziellen Werkzeugen

CLI und MCP-Server holen vor jedem kostenpflichtigen Aufruf eine Kostenschätzung ein und fragen einen Menschen, sodass Sie diesen Schritt nicht selbst bauen müssen:

• CLI: spicyapi tasks quote ermittelt den Preis einer Anfrage; spicyapi tasks create holt erneut eine Kostenschätzung ein, gibt den Betrag aus und fragt vor dem Anlegen nach. Siehe Kosten, Bestätigung und Sicherheit.
• MCP: Der Assistent darf beliebig Kostenschätzungen einholen, doch das Anlegen eines Tasks fragt Sie über Ihren KI-Client, mit dem Preis. Siehe Kosten, Bestätigung und Sicherheit.
• SDK: quoteTask liefert die Kostenschätzung; übergeben Sie deren quoteId und estimatedCost an createTask oder run.

Text- und Videokompatibilität

SpicyAPI versteht für Textmodelle außerdem die Formate von OpenAI, Anthropic und Google Gemini und für Video das Format OpenAI Videos. Die vollständige Liste der Endpunkte steht in der API-Referenz; Anfragen, Streams und Fehler je Protokoll finden Sie unter Text und Streaming.

Basis-URL. Das OpenAI-Format verwendet https://api.spicyapi.ai/v1. Die SDKs von Anthropic und Google GenAI hängen /v1 bzw. /v1beta selbst an; tragen Sie bei ihnen deshalb https://api.spicyapi.ai als Basis-URL ein.

Zugangsdaten. Ein einziger API-Schlüssel für alle, im Header Authorization: Bearer. Der Header x-api-key, den das Anthropic-SDK verwendet, und der Header x-goog-api-key des Google-GenAI-SDK werden ebenfalls akzeptiert. Ein ?key= in der URL dagegen nie.

Modell. Wählen Sie ein exaktes Modell aus dem Live-Katalog. Ob Tools, Bildnachrichten und Generierungsoptionen funktionieren, hängt vom Schema dieses Modells ab, nicht vom gewählten Protokoll.

Antwortform. Jedes Protokoll liefert seine eigene Hülle, nicht den Plattform-Envelope {code, msg, data, request_id}.

Reasoning-Felder

Chatmodelle, die ihren Denkweg als Text ausgeben, können einen optionalen String in message.reasoning_content liefern, beim Streaming in delta.reasoning_content. Setzen Sie nach einem Tool-Aufruf fort, können Sie ihn in der zugehörigen Assistentennachricht mitsenden, sofern das Live-Schema des Modells das unterstützt.

usage.completion_tokens_details.reasoning_tokens beschreibt den Reasoning-Anteil, der in completion_tokens bereits enthalten ist; rechnen Sie ihn nicht noch einmal hinzu. Nicht jedes Modell liefert Reasoning-Text oder diese Token-Details.

Zwei Formen, die Sie vor dem Bauen kennen sollten

• Responses erwartet die vollständige Unterhaltung in input. previous_response_id wird nicht unterstützt.
• Videos nimmt JSON mit model, prompt, input_reference, seconds und size an; diese Felder werden auf die eigenen Felder des Modells abgebildet. Die zurückgegebene Video-id ist zugleich eine Task-ID, die recordInfo akzeptiert. Der Inhalts-Endpunkt des Videos leitet mit HTTP 302 auf eine kurzlebige signierte URL weiter.

Ein Streaming-Chatbeispiel mit den offiziellen Clients von OpenAI, Anthropic und Google finden Sie unter Ein offizielles SDK verwenden. CLI und MCP-Server senden native Tasks ab und verfolgen sie; Chat-Tokens streamen sie nicht.