> ## 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. # Miglioramento dei prompt > Trasforma un prompt breve in un prompt dettagliato, pronto per la generazione di un'immagine o di un video — 1 credit per chiamata. In arrivo. > [!NOTE] > > **In arrivo.** Il miglioramento dei prompt non è ancora attivato. Fino ad allora, > `POST /prompts/improve` restituisce > [`503 service_unavailable`](/it/guides/errors#service_unavailable) con il messaggio > `Prompt improvement is not available yet.`, e lo strumento MCP `improve_prompt` non > compare nell'elenco degli strumenti del server. Non viene addebitato nulla, e una > chiamata disattivata non conta nel tuo rate limit. Il comportamento di credits, > idempotenza ed errori descritto in questa pagina vale dal lancio. Il miglioratore di prompt riscrive un prompt breve in un prompt dettagliato, pronto per la generazione di un'immagine o di un video. * [`POST /prompts/improve`](/it/api-reference/prompts/improve) — migliora un prompt per il `target` `image` o `video`. * Il MCP server offrirà la stessa operazione con lo strumento `improve_prompt` — vedi [Strumenti MCP](/it/mcp-server/tools.md). La chiamata è **sincrona**: la risposta `200` contiene il prompt migliorato. Non c'è nessun job da interrogare e nessun webhook. ## Esempio: migliora, poi genera Migliora `a red bicycle in a park` per un'immagine: ```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 } ``` Poi invia `improved_prompt` come `prompt` a [`POST /images/generations`](/it/api-reference/images/generate) (o allo strumento MCP `generate_image`). Per `target: "video"`, invialo a [`POST /videos/generations`](/it/api-reference/videos/generate). ## Richiesta | Campo | Obbligatorio | Descrizione | | - | - | - | | `prompt` | Sì | Il prompt da migliorare: **da 3 a 5000 caratteri** dopo la rimozione degli spazi iniziali e finali. Valgono le stesse regole di ogni prompt Samsa: niente `<` o `>`, niente backslash, niente a capo o tabulazioni. Un prompt che viola una regola restituisce `422`. | | `target` | Sì | `image` (text-to-image) o `video` (text-to-video). Il miglioratore scrive per quel mezzo. | | `language` | No | La lingua del prompt migliorato, come tag di lingua BCP-47, per esempio `en`, `de` o `fr`. Se lo ometti, il prompt migliorato mantiene la lingua del tuo prompt. | I campi sconosciuti del body vengono ignorati. La risposta `200` ha quattro campi: | Campo | Descrizione | | - | - | | `improved_prompt` | Il prompt migliorato. | | `target` | Il `target` della tua richiesta. | | `language` | Il tag di lingua che hai inviato, in forma BCP-47 canonica, oppure `null` se non ne hai inviato uno. | | `credits_charged` | I credits addebitati per questa chiamata: sempre `1`. Una ripetizione riporta l'addebito della chiamata originale. | Ogni risposta contiene un header `X-Request-ID`. Citalo quando contatti il supporto. ## Ordine dei controlli Una chiamata viene controllata in quest'ordine. Il primo controllo che fallisce determina la risposta: 1. **Autenticazione** — `401` (`invalid_api_key`, oppure `invalid_token` per un access token OAuth). 2. **Disponibilità** — `503 service_unavailable` finché il miglioramento dei prompt non è attivato. Questo controllo avviene prima del rate limiter, quindi una chiamata disattivata non conta nel tuo rate limit. 3. **Rate limit** — `429 rate_limited`. 4. **Scope** — `403 missing_scope`. 5. **Validazione** — `422 validation_error`. ## Credits Dal lancio, ogni chiamata costa **1 credit**. Il credit viene addebitato **prima** che il modello di IA venga eseguito: * Se il saldo che queste credenziali possono spendere è troppo basso, la chiamata restituisce `402` — non viene addebitato nulla e il modello non viene eseguito. Vedi [Quando finisci i credits](/it/guides/pricing.md#quando-finisci-i-credits). * Se il provider di IA fallisce, il credit viene **rimborsato automaticamente** e la chiamata restituisce [`502 provider_error`](/it/guides/errors#provider_error). * Nel raro caso in cui il rimborso non possa essere confermato subito, la chiamata restituisce [`500 refund_pending`](/it/guides/errors#refund_pending). Samsa ripete il rimborso automaticamente — non devi fare nulla. ## Idempotenza Invia un header `Idempotency-Key` facoltativo (da 1 a 255 caratteri ASCII stampabili, per esempio un UUID) per ripetere in sicurezza dopo un timeout o un errore di rete: | Situazione | Risultato | | - | - | | Stessa chiave, stesso body, entro **24 ore** | Lo **stesso risultato** della prima chiamata, con l'header di risposta `Idempotency-Replayed: true`. Mai un secondo addebito. | | Stessa chiave, prima chiamata fallita | Lo **stesso errore** di nuovo, con `Idempotency-Replayed: true`. Per un nuovo tentativo a pagamento, usa una nuova chiave. | | Stessa chiave, body diverso | [`409 idempotency_key_reused`](/it/guides/errors#idempotency_key_reused). Non viene addebitato nulla. | | Stessa chiave, prima chiamata ancora in corso | [`409 idempotency_in_progress`](/it/guides/errors#idempotency_in_progress). Riprova dopo qualche secondo. | | Nessun header `Idempotency-Key` | Ogni chiamata è una nuova chiamata e un nuovo addebito. | Le chiavi valgono per il **titolare** delle credenziali — il creatore della API key o l'utente OAuth — all'interno dell'organizzazione. Le chiamate REST, le chiamate MCP e tutte le credenziali dello stesso titolare condividono un unico namespace di chiavi. Due utenti diversi possono usare lo stesso valore di chiave senza conflitto. ## Scope Le credenziali con **uno qualsiasi** degli scope `images.generate`, `images.edit` o `videos.generate` possono chiamare il miglioratore — gli scope delle operazioni a cui è destinato un prompt migliorato. Non esiste uno scope separato, quindi le chiavi esistenti funzionano. Una chiave senza nessuno dei tre riceve [`403 missing_scope`](/it/guides/errors#missing_scope). ## Rate limit Ogni chiamata attivata conta nel [rate di richieste per chiave](/it/guides/rate-limits.md#rate-di-richieste-per-chiave) (`429 rate_limited` con `Retry-After`). La chiamata non crea alcun job, quindi non usa il tetto di concorrenza dell'organizzazione. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.