> ## Documentation Index > Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Prompt-Verbesserung > Mach aus einem kurzen Prompt einen detaillierten, generierungsfertigen Prompt für ein Bild oder ein Video — 1 Credit pro Aufruf. Demnächst verfügbar. > [!NOTE] > > **Demnächst verfügbar.** Die Prompt-Verbesserung ist noch nicht aktiviert. Bis dahin > gibt `POST /prompts/improve` > [`503 service_unavailable`](/de/guides/errors#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`](/de/api-reference/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](/de/mcp-server/tools.md). 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: ```bash theme={null} 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" }' ``` ```json 200 OK theme={null} { "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`](/de/api-reference/images/generate) (oder an das MCP-Tool `generate_image`). Für `target: "video"` sende ihn an [`POST /videos/generations`](/de/api-reference/videos/generate). ## 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: 1. **Authentifizierung** — `401` (`invalid_api_key`, oder `invalid_token` bei einem OAuth-Access-Token). 2. **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. 3. **Rate Limit** — `429 rate_limited`. 4. **Scope** — `403 missing_scope`. 5. **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](/de/guides/pricing.md#wenn-dir-die-credits-ausgehen). * Schlägt der KI-Provider fehl, wird der Credit **automatisch erstattet** und der Aufruf gibt [`502 provider_error`](/de/guides/errors#provider_error) zurück. * Im seltenen Fall, dass die Erstattung nicht sofort bestätigt werden kann, gibt der Aufruf [`500 refund_pending`](/de/guides/errors#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`](/de/guides/errors#idempotency_key_reused). Es wird nichts berechnet. | | Gleicher Key, erster Aufruf läuft noch | [`409 idempotency_in_progress`](/de/guides/errors#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`](/de/guides/errors#missing_scope). ## Rate Limits Jeder aktivierte Aufruf zählt gegen die [Request-Rate pro Key](/de/guides/rate-limits.md#request-rate-pro-key) (`429 rate_limited` mit `Retry-After`). Der Aufruf erstellt keinen Job und belegt daher nicht den Concurrency-Cap der Organisation. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.