> ## 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. # Migliorare un prompt > Riscrivi un prompt breve in un prompt dettagliato per la generazione di un'immagine o di un video. Sincrona, 1 credit per chiamata. In arrivo. > [!NOTE] > > **In arrivo.** Questo endpoint non è ancora attivato. Fino ad allora, ogni chiamata > autenticata restituisce > [`503 service_unavailable`](/it/guides/errors#service_unavailable) con il messaggio > `Prompt improvement is not available yet.` Non viene addebitato nulla, e la chiamata > non conta nel tuo rate limit. Il comportamento descritto qui sotto vale dal lancio. Migliora un `prompt` per un `target` `image` o `video`. La chiamata è **sincrona** e restituisce **`200 OK`** con il `improved_prompt`. Costa **1 credit**, addebitato prima che il modello di IA venga eseguito e rimborsato automaticamente se il provider fallisce. Richiede **uno qualsiasi** degli scope `images.generate`, `images.edit` o `videos.generate`. Le regole di idempotenza e l'ordine dei controlli sono nella [panoramica](/it/api-reference/prompts/overview.md). ## Esempio ```bash image 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" }' ``` ```bash video, output in tedesco theme={null} curl -X POST https://api.samsa.ai/public/v1/prompts/improve \ -H "Authorization: Bearer $SAMSA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "a red bicycle rolling through a park", "target": "video", "language": "de" }' ``` ```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 } ``` Passa `improved_prompt` come `prompt` a [`POST /images/generations`](/it/api-reference/images/generate) o a [`POST /videos/generations`](/it/api-reference/videos/generate). ## Ripetere con un `Idempotency-Key` Se ripeti la chiamata con lo **stesso** `Idempotency-Key` e lo **stesso** body entro 24 ore, ricevi il risultato salvato — senza un secondo addebito. La ripetizione porta l'header `Idempotency-Replayed: true`: ```http theme={null} HTTP/1.1 200 OK Idempotency-Replayed: true Content-Type: application/json { "improved_prompt": "A glossy red city bicycle …", "target": "image", "language": null, "credits_charged": 1 } ``` `credits_charged` riporta l'addebito della chiamata originale; la ripetizione in sé non costa nulla. Senza l'header, ogni chiamata è un nuovo addebito. Una chiave la cui prima chiamata è fallita restituisce di nuovo quell'errore: usa una nuova chiave per un nuovo tentativo a pagamento. ## Errori Finché l'endpoint non è attivato, una chiamata autenticata restituisce solo `503 service_unavailable`. Dal lancio, la chiamata può restituire: | Stato | Codice | Quando | | - | - | - | | `401` | [`invalid_api_key`](/it/guides/errors#invalid_api_key) / `invalid_token` | API key (`invalid_api_key`) o access token OAuth (`invalid_token`) mancante, sconosciuto, scaduto o revocato. | | `402` | [`insufficient_credits`](/it/guides/errors#insufficient_credits) / [`insufficient_team_credits`](/it/guides/errors#insufficient_team_credits) / [`insufficient_unallocated_credits`](/it/guides/errors#insufficient_unallocated_credits) | Il saldo che queste credenziali possono spendere è inferiore a 1 credit. Non viene addebitato nulla e il modello non viene eseguito. Le organizzazioni con almeno un team attivo ricevono i codici legati ai team (eccetto le organizzazioni di sistema esenti da budget). | | `402` | [`subscription_inactive`](/it/guides/errors#subscription_inactive) | L'organizzazione non ha un abbonamento utilizzabile. | | `403` | [`missing_scope`](/it/guides/errors#missing_scope) | Le credenziali non hanno nessuno tra `images.generate`, `images.edit`, `videos.generate`. | | `409` | [`idempotency_key_reused`](/it/guides/errors#idempotency_key_reused) | L'`Idempotency-Key` è già stato usato con un body diverso. | | `409` | [`idempotency_in_progress`](/it/guides/errors#idempotency_in_progress) | Una chiamata con questo `Idempotency-Key` è ancora in corso. | | `422` | [`validation_error`](/it/guides/errors#validation_error) | `prompt` è più corto di 3 o più lungo di 5000 caratteri o viola una regola dei prompt, `target` non è `image` o `video`, `language` non è un tag di lingua valido, oppure l'header `Idempotency-Key` non è valido. | | `429` | [`rate_limited`](/it/guides/errors#rate_limited) | Finestra di rate per chiave superata. | | `500` | [`refund_pending`](/it/guides/errors#refund_pending) | Il provider è fallito e il rimborso non è ancora stato confermato. Samsa lo ripete automaticamente. | | `502` | [`provider_error`](/it/guides/errors#provider_error) | Il provider di IA è fallito. Il credit è stato rimborsato. | | `503` | [`service_unavailable`](/it/guides/errors#service_unavailable) | Il miglioramento dei prompt non è ancora attivato (oggi, a ogni chiamata). Dal lancio: Samsa non ha potuto confermare lo stato di idempotenza o l'esito dell'addebito. Nessun prompt è stato consegnato, e un credit addebitato viene rimborsato automaticamente. | Un `Idempotency-Key` ripetuto la cui prima chiamata è fallita restituisce di nuovo lo stesso errore, con `Idempotency-Replayed: true`. L'header di risposta `X-Request-ID` identifica la chiamata per il supporto. ## OpenAPI ````yaml api-reference/openapi.json POST /prompts/improve openapi: 3.1.0 info: title: Samsa API description: >- The Samsa public REST API. Authenticate with an organization API key (`Authorization: Bearer samsa_sk_...`) or an OAuth 2.1 access token (`Authorization: Bearer samsa_at_...`). Errors follow a single envelope shape; every response carries an `X-Request-ID`. version: 1.0.0 servers: - url: https://api.samsa.ai/public/v1 security: - BearerAuth: [] paths: /prompts/improve: post: tags: - Prompts summary: Improve a prompt for an image or a video generation (1 credit) description: >- Rewrites ONE prompt into a detailed, generation-ready prompt — the same prompt improver as the Samsa app. `target` is `image` or `video`; `language` (optional, BCP-47 such as `en`, `de`, `fr`) sets the language of the improved prompt, otherwise it keeps the language of the input. **Cost: 1 credit per improved prompt**, charged before the AI call; when the AI provider fails the credit is refunded and the call answers `502 provider_error`. Send an `Idempotency-Key` header (1-255 printable ASCII characters) to retry safely: the same key with the same body within 24 hours returns the same result with `Idempotency-Replayed: true` and is never charged twice (a key that ended in an error replays that error — use a new key for a new attempt); the same key with another body is `409 idempotency_key_reused`; while the first request runs it is `409 idempotency_in_progress`. Keys are scoped to the key's creator in its organization. Common errors: `402` (no credits or no usable subscription — nothing is charged), `422` (validation), `429` (rate limit). Requires any one of the `images.generate`, `images.edit` or `videos.generate` scopes. Not available yet: the endpoint answers `503 service_unavailable` until it is enabled. operationId: improve_prompt_prompts_improve_post parameters: - name: Idempotency-Key in: header required: false schema: anyOf: - type: string maxLength: 255 - type: 'null' description: >- Optional. 1-255 printable ASCII characters; see the operation description. title: Idempotency-Key description: >- Optional. 1-255 printable ASCII characters; see the operation description. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicPromptImproveRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PublicPromptImproveResponse' '401': description: Missing, invalid, expired, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '402': description: Insufficient credits or inactive subscription. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The API key lacks the required scope. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: >- `idempotency_key_reused` (the key was used with another body) or `idempotency_in_progress` (a request with the key is still running — retry). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: >- `refund_pending`: the AI provider failed and the refund of the credit is not confirmed yet (it is retried automatically), or `internal_error`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '502': description: >- `provider_error`: the AI provider failed; the 1 credit charged was refunded. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: >- `service_unavailable`: idempotent requests or the billing outcome could not be confirmed (no prompt was delivered; a credit taken is refunded automatically). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: PublicPromptImproveRequest: properties: prompt: type: string title: Prompt description: >- The prompt to improve: 3 to 5000 characters after trimming (the characters `<` and `>`, line breaks and backslashes are not allowed — the same rules as every Samsa prompt). target: type: string enum: - image - video title: Target description: >- What the improved prompt is for: `image` (text-to-image) or `video` (text-to-video). language: anyOf: - type: string maxLength: 63 - type: 'null' title: Language description: >- Optional BCP-47 / ISO 639-1 language tag of the improved prompt (e.g. `en`, `de`, `fr`). Omitted: the improved prompt keeps the language of the input prompt. examples: - de type: object required: - prompt - target title: PublicPromptImproveRequest description: >- `POST /prompts/improve` body — improve ONE prompt for an image or a video generation. **Cost = 1 credit per improved prompt**, charged before the AI call and refunded automatically when the AI provider fails (`502 provider_error`). Send an `Idempotency-Key` header to retry safely: the same key with the same body within 24 hours returns the same result and never charges twice. examples: - prompt: a red fox in the snow at dawn target: image - language: de prompt: Ein Fuchs läuft durch den Schnee target: video PublicPromptImproveResponse: properties: improved_prompt: type: string title: Improved Prompt description: The improved prompt. target: type: string enum: - image - video title: Target description: The `target` of the request. language: anyOf: - type: string - type: 'null' title: Language description: >- The requested language tag (canonical BCP-47 form), or `null` when none was requested. credits_charged: type: integer title: Credits Charged description: >- Credits charged for this improved prompt (always 1; a replayed idempotent call reports the charge of its key — it is never charged twice). type: object required: - improved_prompt - target - language - credits_charged title: PublicPromptImproveResponse description: '`POST /prompts/improve` 200 body.' ErrorEnvelope: properties: error: $ref: '#/components/schemas/ErrorDetail' type: object required: - error title: ErrorEnvelope description: The complete public error body — an ``error`` object wrapper (ADR §5). ErrorDetail: properties: type: type: string title: Type examples: - authentication_error code: type: string title: Code examples: - invalid_api_key message: type: string title: Message examples: - The provided API key is invalid, expired, or revoked. request_id: type: string title: Request Id examples: - 8f14e45fceea167a5a36dedd4bea2543 param: anyOf: - type: string - type: 'null' title: Param description: Present on validation errors — names the offending field. examples: - aspect_ratio type: object required: - type - code - message - request_id title: ErrorDetail description: The ``error`` object of the public envelope (ADR §5). securitySchemes: BearerAuth: type: http scheme: bearer description: >- Organization API key (`Authorization: Bearer samsa_sk_...`) or OAuth 2.1 access token (`Authorization: Bearer samsa_at_...`). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.