Prompt-Verbesserung

Demnächst verfügbar. Die Prompt-Verbesserung ist noch nicht aktiviert. Bis dahin gibt POST /prompts/improve 503 service_unavailable mit der Meldung Prompt improvement is not available yet. zurück, und das MCP-Tool improve_prompt erscheint nicht in der Tool-Liste des Servers. Es wird nichts berechnet, und ein deaktivierter Aufruf zählt nicht gegen dein Rate Limit. Das Verhalten zu Credits, Idempotenz und Fehlern auf dieser Seite gilt ab dem Start.

Der Prompt-Verbesserer schreibt einen kurzen Prompt in einen detaillierten Prompt um, der für eine Bild- oder Videogenerierung bereit ist.

POST /prompts/improve — verbessert einen Prompt für das target image oder video.
Der MCP server wird dieselbe Operation als Tool improve_prompt bieten — siehe MCP-Tools.

Der Aufruf ist synchron: Die 200-Antwort enthält den verbesserten Prompt. Es gibt keinen Job zum Abfragen und keinen Webhook.

Beispiel: verbessern, dann generieren

Verbessere a red bicycle in a park für ein Bild:

curl -X POST https://api.samsa.ai/public/v1/prompts/improve \
  -H "Authorization: Bearer $SAMSA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a3e-improve-bicycle" \
  -d '{ "prompt": "a red bicycle in a park", "target": "image" }'

200 OK

{
  "improved_prompt": "A glossy red city bicycle leaning against a wooden bench in a sunlit park, autumn leaves on the path, soft morning light, shallow depth of field, photorealistic",
  "target": "image",
  "language": null,
  "credits_charged": 1
}

Sende dann improved_prompt als prompt an POST /images/generations (oder an das MCP-Tool generate_image). Für target: "video" sende ihn an POST /videos/generations.

Anfrage

Feld	Erforderlich	Beschreibung
`prompt`	Ja	Der zu verbessernde Prompt: 3 bis 5000 Zeichen nach dem Trimmen. Es gelten dieselben Regeln wie für jeden Samsa-Prompt: kein `<` oder `>`, keine Backslashes, keine Zeilenumbrüche oder Tabs. Ein Prompt, der eine Regel verletzt, gibt `422` zurück.
`target`	Ja	`image` (Text-to-Image) oder `video` (Text-to-Video). Der Verbesserer schreibt für dieses Medium.
`language`	Nein	Die Sprache des verbesserten Prompts als BCP-47-Sprach-Tag, zum Beispiel `en`, `de` oder `fr`. Lässt du ihn weg, behält der verbesserte Prompt die Sprache deines Prompts.

Unbekannte Felder im Body werden ignoriert. Die 200-Antwort hat vier Felder:

Feld	Beschreibung
`improved_prompt`	Der verbesserte Prompt.
`target`	Das `target` deiner Anfrage.
`language`	Das Sprach-Tag, das du gesendet hast, in kanonischer BCP-47-Form, oder `null`, wenn du keines gesendet hast.
`credits_charged`	Die für diesen Aufruf abgebuchten Credits: immer `1`. Eine Wiederholung meldet die Abbuchung des ursprünglichen Aufrufs.

Jede Antwort trägt einen X-Request-ID-Header. Nenne ihn, wenn du den Support kontaktierst.

Reihenfolge der Prüfungen

Ein Aufruf wird in dieser Reihenfolge geprüft. Die erste fehlgeschlagene Prüfung bestimmt die Antwort:

Authentifizierung — 401 (invalid_api_key, oder invalid_token bei einem OAuth-Access-Token).
Verfügbarkeit — 503 service_unavailable, solange die Prompt-Verbesserung nicht aktiviert ist. Diese Prüfung läuft vor dem Rate Limiter, daher zählt ein deaktivierter Aufruf nicht gegen dein Rate Limit.
Rate Limit — 429 rate_limited.
Scope — 403 missing_scope.
Validierung — 422 validation_error.

Credits

Ab dem Start kostet jeder Aufruf 1 Credit. Der Credit wird vor dem Lauf des KI-Modells abgebucht:

Reicht der Stand, den diese Zugangsdaten ausgeben können, nicht aus, gibt der Aufruf 402 zurück — es wird nichts berechnet und das Modell läuft nicht. Siehe Wenn dir die Credits ausgehen.
Schlägt der KI-Provider fehl, wird der Credit automatisch erstattet und der Aufruf gibt 502 provider_error zurück.
Im seltenen Fall, dass die Erstattung nicht sofort bestätigt werden kann, gibt der Aufruf 500 refund_pending zurück. Samsa wiederholt die Erstattung automatisch — du musst nichts tun.

Idempotenz

Sende einen optionalen Idempotency-Key-Header (1–255 druckbare ASCII-Zeichen, zum Beispiel eine UUID), um nach einem Timeout oder einem Netzwerkfehler sicher zu wiederholen:

Situation	Ergebnis
Gleicher Key, gleicher Body, innerhalb von 24 Stunden	Dasselbe Ergebnis wie beim ersten Aufruf, mit dem Response-Header `Idempotency-Replayed: true`. Nie eine zweite Abbuchung.
Gleicher Key, erster Aufruf fehlgeschlagen	Derselbe Fehler erneut, mit `Idempotency-Replayed: true`. Für einen neuen bezahlten Versuch verwendest du einen neuen Key.
Gleicher Key, anderer Body	`409 idempotency_key_reused`. Es wird nichts berechnet.
Gleicher Key, erster Aufruf läuft noch	`409 idempotency_in_progress`. Wiederhole nach ein paar Sekunden.
Kein `Idempotency-Key`-Header	Jeder Aufruf ist ein neuer Aufruf und eine neue Abbuchung.

Keys gelten pro Inhaber der Zugangsdaten — Ersteller des API-Keys oder OAuth-User — innerhalb der Organisation. REST-Aufrufe, MCP-Aufrufe und alle Zugangsdaten desselben Inhabers teilen sich einen Key-Namensraum. Zwei verschiedene User können denselben Key-Wert ohne Konflikt verwenden.

Scope

Zugangsdaten mit einem der Scopes images.generate, images.edit oder videos.generate können den Verbesserer aufrufen — die Scopes der Operationen, für die ein verbesserter Prompt gedacht ist. Es gibt keinen eigenen Scope, daher funktionieren bestehende Keys. Ein Key ohne einen dieser drei erhält 403 missing_scope.

Rate Limits

Jeder aktivierte Aufruf zählt gegen die Request-Rate pro Key (429 rate_limited mit Retry-After). Der Aufruf erstellt keinen Job und belegt daher nicht den Concurrency-Cap der Organisation.

Übersicht

Endpunkte

Prompt-Verbesserung

Beispiel: verbessern, dann generieren

Anfrage

Reihenfolge der Prüfungen

Credits

Idempotenz

Scope

Rate Limits

​Beispiel: verbessern, dann generieren

​Anfrage

​Reihenfolge der Prüfungen

​Credits

​Idempotenz

​Scope

​Rate Limits

Beispiel: verbessern, dann generieren

Anfrage

Reihenfolge der Prüfungen

Credits

Idempotenz

Scope

Rate Limits