curl --request POST \
--url https://api.samsa.ai/public/v1/prompts/improve \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "a red fox in the snow at dawn",
"target": "image"
}
'import requests
url = "https://api.samsa.ai/public/v1/prompts/improve"
payload = {
"prompt": "a red fox in the snow at dawn",
"target": "image"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({prompt: 'a red fox in the snow at dawn', target: 'image'})
};
fetch('https://api.samsa.ai/public/v1/prompts/improve', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.samsa.ai/public/v1/prompts/improve",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'a red fox in the snow at dawn',
'target' => 'image'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.samsa.ai/public/v1/prompts/improve"
payload := strings.NewReader("{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.samsa.ai/public/v1/prompts/improve")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/prompts/improve")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}"
response = http.request(request)
puts response.read_body{
"improved_prompt": "<string>",
"target": "image",
"language": "<string>",
"credits_charged": 123
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}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.
curl --request POST \
--url https://api.samsa.ai/public/v1/prompts/improve \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "a red fox in the snow at dawn",
"target": "image"
}
'import requests
url = "https://api.samsa.ai/public/v1/prompts/improve"
payload = {
"prompt": "a red fox in the snow at dawn",
"target": "image"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({prompt: 'a red fox in the snow at dawn', target: 'image'})
};
fetch('https://api.samsa.ai/public/v1/prompts/improve', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.samsa.ai/public/v1/prompts/improve",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'a red fox in the snow at dawn',
'target' => 'image'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.samsa.ai/public/v1/prompts/improve"
payload := strings.NewReader("{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.samsa.ai/public/v1/prompts/improve")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/prompts/improve")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}"
response = http.request(request)
puts response.read_body{
"improved_prompt": "<string>",
"target": "image",
"language": "<string>",
"credits_charged": 123
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}503 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.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.
Esempio
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" }'
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" }'
{
"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
}
improved_prompt come prompt a
POST /images/generations o a
POST /videos/generations.
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/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 solo503 service_unavailable. Dal lancio, la chiamata può restituire:
| Stato | Codice | Quando |
|---|---|---|
401 | invalid_api_key / invalid_token | API key (invalid_api_key) o access token OAuth (invalid_token) mancante, sconosciuto, scaduto o revocato. |
402 | insufficient_credits / insufficient_team_credits / 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 | L’organizzazione non ha un abbonamento utilizzabile. |
403 | missing_scope | Le credenziali non hanno nessuno tra images.generate, images.edit, videos.generate. |
409 | idempotency_key_reused | L’Idempotency-Key è già stato usato con un body diverso. |
409 | idempotency_in_progress | Una chiamata con questo Idempotency-Key è ancora in corso. |
422 | 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 | Finestra di rate per chiave superata. |
500 | refund_pending | Il provider è fallito e il rimborso non è ancora stato confermato. Samsa lo ripete automaticamente. |
502 | provider_error | Il provider di IA è fallito. Il credit è stato rimborsato. |
503 | 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. |
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.Autorizzazioni
Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).
Intestazioni
Optional. 1-255 printable ASCII characters; see the operation description.
255Corpo
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.
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).
What the improved prompt is for: image (text-to-image) or video (text-to-video).
image, video 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.
63"de"
Risposta
Successful Response
POST /prompts/improve 200 body.
The improved prompt.
The target of the request.
image, video The requested language tag (canonical BCP-47 form), or null when none was requested.
Credits charged for this improved prompt (always 1; a replayed idempotent call reports the charge of its key — it is never charged twice).