Miglioramento dei prompt

In arrivo. Il miglioramento dei prompt non è ancora attivato. Fino ad allora, POST /prompts/improve restituisce 503 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 — migliora un prompt per il target image o video.
Il MCP server offrirà la stessa operazione con lo strumento improve_prompt — vedi Strumenti MCP.

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:

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
}

Poi invia improved_prompt come prompt a POST /images/generations (o allo strumento MCP generate_image). Per target: "video", invialo a POST /videos/generations.

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:

Autenticazione — 401 (invalid_api_key, oppure invalid_token per un access token OAuth).
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.
Rate limit — 429 rate_limited.
Scope — 403 missing_scope.
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.
Se il provider di IA fallisce, il credit viene rimborsato automaticamente e la chiamata restituisce 502 provider_error.
Nel raro caso in cui il rimborso non possa essere confermato subito, la chiamata restituisce 500 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`. Non viene addebitato nulla.
Stessa chiave, prima chiamata ancora in corso	`409 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.

Rate limit

Ogni chiamata attivata conta nel 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.

Panoramica

Endpoint

Miglioramento dei prompt

Esempio: migliora, poi genera

Richiesta

Ordine dei controlli

Credits

Idempotenza

Scope

Rate limit

​Esempio: migliora, poi genera

​Richiesta

​Ordine dei controlli

​Credits

​Idempotenza

​Scope

​Rate limit

Esempio: migliora, poi genera

Richiesta

Ordine dei controlli

Credits

Idempotenza

Scope

Rate limit