> ## 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.
# Strumenti MCP
> Ogni strumento del MCP server di Samsa, con parametri, scope richiesto e costo in credits.
Il server espone **diciotto strumenti**. Nove sono gratuiti — le cinque letture
(`list_models`, `get_model`, `list_image_engines`, `get_job_status`,
`get_credit_balance`), i due strumenti
di gestione dei modelli (`create_model`, `update_model`) e i due strumenti di upload
(`prepare_image_upload`, `complete_image_upload`). Gli altri **nove** costano
[credits](/it/guides/pricing) dal pool della tua organizzazione, alle stesse tariffe
dell'app e della REST API.
**In arrivo:** `improve_prompt`, un diciannovesimo strumento che costa 1 credit per
chiamata. Non è ancora nell'elenco degli strumenti del server; vi compare non appena
il miglioramento dei prompt viene attivato. La sua riga e la sua sezione qui sotto
lo descrivono come sarà al lancio.
| Strumento | Cosa fa | Scope | Costo |
| - | - | - | - |
| `list_models` | Elenca i modelli addestrati pronti della tua organizzazione (id, nome, categoria, thumbnail). | `models.read` | Gratis |
| `get_model` | Dettaglio completo di un modello — stato, immagini di riferimento, prompt predefinito, trigger word. | `models.read` | Gratis |
| `create_model` | Addestra un nuovo modello da 1–10 immagini di riferimento (async). | `models.write` | Gratis |
| `update_model` | Aggiorna nome, prompt predefinito e/o l'istruzione sempre applicata di un modello. | `models.write` | Gratis |
| `list_image_engines` | Elenca gli engine text-to-image accettati da `generate_image`, con i loro limiti e credits. | `images.generate` | Gratuito |
| `improve_prompt` *(in arrivo)* | Riscrive un prompt breve in un prompt dettagliato per la generazione di un'immagine o di un video (sincrono). Non ancora nell'elenco degli strumenti. | uno tra `images.generate`, `images.edit`, `videos.generate` | 1 per chiamata |
| `generate_image` | Genera immagini da un prompt con un engine scelto, componendo facoltativamente i tuoi modelli addestrati. | `images.generate` | 5 × output × risoluzione |
| `edit_image` | Magic Edit — modifica un'immagine da un prompt, con una scelta di cinque engine. | `images.edit` | 5 × output × risoluzione (5 per output su `gemini` / `kontext`) |
| `img2img` | Trasforma 1–14 immagini di riferimento con un prompt. | `images.edit` | 5 × output × risoluzione |
| `create_variations` | Genera variazioni creative di un'immagine. | `images.transform` | 5 × output × risoluzione sorgente |
| `resize_image` | Ridimensiona a un nuovo rapporto d'aspetto per outpainting. | `images.transform` | 5 × output × risoluzione |
| `upscale_image` | Fa l'upscale di un'immagine a una risoluzione più alta (quattro modelli). | `images.transform` | Fascia × moltiplicatore del modello |
| `remove_background` | Rimuove lo sfondo (PNG trasparente). | `images.transform` | 1 (0 con un cache hit) |
| `vectorize_image` | Vettorializza un'immagine in SVG. | `images.transform` | 5 (0 con un cache hit) |
| `generate_video` | Genera video da un frame iniziale, da testo o da testo stilizzato con i tuoi modelli. | `videos.generate` | 5 / secondo × engine × risoluzione × audio |
| `get_job_status` | Interroga un job di immagine, trasformazione, video o modello inviato per stato e risultati. | scope dello strumento che ha inviato | Gratis |
| `get_credit_balance` | Leggi il saldo credits che questa connessione può spendere, i totali dell'organizzazione, il suo scope di budget e il periodo di fatturazione. | `usage.read` | Gratis |
| `prepare_image_upload` | Avvia l'upload di un file immagine locale: ottieni un `image_id` e un URL PUT presigned. | uno qualsiasi tra `images.edit`, `images.transform`, `videos.generate` | Gratis |
| `complete_image_upload` | Completa l'upload: verifica il file e rende il suo `image_id` utilizzabile come sorgente. | uno qualsiasi tra `images.edit`, `images.transform`, `videos.generate` | Gratis |
Una chiamata a uno strumento rifiutata per uno scope mancante restituisce un errore
strutturato dello strumento (non un crash) che nomina lo scope di cui ha bisogno. Le
chiavi vengono create con tutti gli scope per impostazione predefinita; un admin può
restringere o ampliare una chiave in **Settings → API Keys**.
## Parametri
* `category` *(facoltativo)* — filtra a uno tra `style`, `object`, `person`,
`setting`.
Restituisce i modelli **pronti** della tua organizzazione con `id`, `name`,
`category` e un `thumbnail_url` presigned. Usa gli id o i nomi come `style_id` /
`object_ids` / `person_ids` / `setting_ids` in `generate_image` e
`generate_video` — un nome viene risolto a un modello visibile a te. Gli
engine text-to-image generali non sono modelli addestrati —
`list_image_engines` li elenca.
* `model_id` *(obbligatorio)* — l'id del modello.
Restituisce il dettaglio completo: stato, prontezza, URL presigned delle immagini
di riferimento, il prompt predefinito e le trigger word.
* `name` *(obbligatorio)* — il nome del modello.
* `category` *(obbligatorio)* — uno tra `style`, `object`, `person`, `setting`.
* `images` *(obbligatorio)* — 1–10 immagini di riferimento. Ciascuna è **o** un
URL `https` pubblico (≤ 10 MB ciascuna) **oppure** un data URI base64 inline
(`data:image/png;base64,…`) — `image/jpeg`, `image/png` o `image/webp`.
L'intera richiesta MCP è limitata a 1 MB, quindi le immagini base64 inline
possono trasportare solo circa 750 KB di dati **in totale** — invia le immagini
più grandi come URL `https`.
* `instruction` *(facoltativo)* — la guida sempre applicata del modello
(≤ 8000 caratteri), iniettata come direttiva obbligatoria ("MUST FOLLOW") in
ogni generazione che compone il modello. Vedi
[Addestramento di modelli](/it/api-reference/model-training/overview).
* `webhook_url` *(facoltativo)* — un URL `https` notificato una volta quando
l'addestramento raggiunge uno stato terminale.
**Asincrono** — restituisce subito `{ id, status: "pending", estimated_credits }`;
interroga `get_job_status(kind="model", id=…)` (che richiede anche lo scope
`models.read`) finché non è `completed` o `failed`, poi usa l'id del modello in
`generate_image` / `generate_video`.
**Gratis** — la creazione del modello non deduce credits. Gli upload presigned di
modelli con file di grandi dimensioni sono solo REST (non esposti via MCP) — usa
[`POST /models/prepare`](/it/api-reference/model-training/prepare) per quelli. Un
`image_id` di `prepare_image_upload` non è accettato qui.
* `model_id` *(obbligatorio)* — il modello da aggiornare.
* `name` *(facoltativo)* — un nuovo nome del modello.
* `default_prompt` *(facoltativo)* — un nuovo prompt predefinito.
* `instruction` *(facoltativo)* — la guida sempre applicata del modello
(≤ 8000 caratteri). Invia una stringa vuota per cancellarla.
Fornisci **almeno uno** tra `name`, `default_prompt` o `instruction`; i campi
omessi restano invariati. **Sincrono** — restituisce subito il modello aggiornato
completo (stessa forma di `get_model`). **Gratis.**
Nessun parametro. Restituisce `{ data: [...], unavailable_reason }` — una voce
per ogni engine text-to-image che puoi usare, con il predefinito per primo:
`id`, `name`, `is_default`, `provider_family`, `aspect_ratios`,
`default_aspect_ratio`, `resolutions`, `default_resolution`,
`max_num_outputs`, `credits_per_image` (per risoluzione; una richiesta costa
questo valore × `num_outputs`), `supports_trained_refs` e
`supports_color_palette`. Il contenuto è lo stesso di
[`GET /images/models`](/it/api-reference/images/list-engines). Passa l'`id` di
una voce come `engine` a `generate_image`.
Se la tua organizzazione genera solo con i suoi modelli addestrati, `data` è
vuoto e `unavailable_reason` è `organization_restricted`; altrimenti è `null`.
**Gratuito.** Scope `images.generate`.
**In arrivo** — non compare nell'elenco degli strumenti del server finché il
miglioramento dei prompt non viene attivato.
* `prompt` *(obbligatorio)* — il prompt da migliorare: da 3 a 5000 caratteri dopo
la rimozione degli spazi iniziali e finali, con le stesse regole di ogni prompt
Samsa (niente `<` o `>`, niente backslash, niente a capo o tabulazioni).
* `target` *(obbligatorio)* — `image` o `video`: il mezzo a cui è destinato il
prompt migliorato.
* `language` *(facoltativo)* — un tag di lingua BCP-47 come `en` o `de` per la
lingua del prompt migliorato. Omesso: il prompt migliorato mantiene la lingua
del tuo prompt.
* `idempotency_key` *(facoltativo)* — da 1 a 255 caratteri ASCII stampabili. La
stessa chiave con gli stessi argomenti entro 24 ore restituisce il risultato
salvato e non viene mai addebitata due volte; la stessa chiave con altri
argomenti viene rifiutata (`idempotency_key_reused`), e una chiave la cui prima
chiamata è ancora in corso restituisce `idempotency_in_progress`. Una chiave la cui
chiamata è fallita restituisce di nuovo quell'errore: usa una nuova chiave per un
nuovo tentativo a pagamento. Le chiavi valgono per il titolare delle credenziali
(il creatore della chiave API o l'utente OAuth) all'interno dell'organizzazione e
condividono un unico namespace con l'header REST `Idempotency-Key`.
**Sincrono** — restituisce direttamente `{ improved_prompt, target, language,
credits_charged }`; non c'è nessun job da interrogare. Passa `improved_prompt`
come `prompt` a `generate_image` o `generate_video`. **Costo: 1 credit per
chiamata**, addebitato prima che il modello venga eseguito; se il provider di IA
fallisce, il credit viene rimborsato e lo strumento restituisce un
`provider_error`. Gli errori hanno la stessa forma strutturata di errore degli
altri strumenti. Scope: uno tra `images.generate`, `images.edit` o
`videos.generate`. Equivalente REST:
[`POST /prompts/improve`](/it/api-reference/prompts/improve).
* `prompt` *(obbligatorio)* — il prompt testuale.
* `engine` *(facoltativo)* — il modello text-to-image: `nano_banana_pro`
(predefinito), `nano_banana_2_1`, `nano_banana_2`, `nano_banana`, `imagen_4`,
`seedream_4` o `flux_1_pro`. Omettilo per usare `nano_banana_pro`. I limiti
di ogni engine sono in [Engine](/it/api-reference/images/overview#engine),
oppure chiama `list_image_engines`.
* `style_id`, `object_ids`, `person_ids`, `setting_ids` *(facoltativi)* — id o
nomi dei modelli addestrati da `list_models` da comporre (un nome viene
risolto a un modello visibile a te).
* `color_palette` *(facoltativo)* — una palette di colori da applicare, indicata
con il suo **nome o id** (come i riferimenti ai modelli addestrati).
* `num_outputs` (`1`–`4`, predefinito `1`), `aspect_ratio` (predefinito `"1:1"`),
`resolution` (predefinito `"1K"`).
`aspect_ratio` e `resolution` vengono validati rispetto all'engine:
`nano_banana_pro`, `nano_banana_2_1` e `nano_banana_2` accettano `1:1`, `16:9`,
`9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9`, `4:1`, `1:4`, `8:1`,
`1:8` a `1K` / `2K` / `4K`; `nano_banana` i primi dieci di questi a `1K`;
`imagen_4` `1:1`, `16:9`, `9:16`, `4:3`, `3:4` a `1K` / `2K`; `seedream_4` e
`flux_1_pro` `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9` a `1K`. Un engine
sconosciuto o un valore non supportato restituisce un `422` che indica i valori
validi.
I modelli addestrati e `color_palette` funzionano solo con `nano_banana_pro`,
`nano_banana_2_1` e `nano_banana_2`; su qualsiasi altro engine restituiscono
`422` — non vengono mai scartati, e l'engine non viene mai cambiato. Alcune
organizzazioni generano solo con i loro modelli addestrati: lì qualsiasi
`engine` restituisce `422` — ometti `engine` e passa almeno un modello
addestrato o una `color_palette`.
**Asincrono** — restituisce `{ id, status: "pending", estimated_credits }`
immediatamente. Costo: `5 × num_outputs × risoluzione` (`1K` ×1, `2K` ×2, `4K`
×4), dedotto all'invio — uguale su ogni engine.
* `prompt` *(obbligatorio)* — come modificare l'immagine.
* Esattamente **uno** tra `image_id` (un'immagine nel tuo contesto Samsa, per
esempio da `complete_image_upload`) o `image_url` (un URL https pubblico). Il
rapporto d'aspetto della sorgente viene mantenuto.
* `engine` *(facoltativo)* — `nano_banana_pro` (Nano Banana Pro, predefinito),
`nano_banana_2` (Nano Banana 2), `nano_banana_2_1` (Nano Banana 2.1), `gemini`
(Nano Banana via FAL) o `kontext` (Flux Kontext). Un engine sconosciuto
restituisce `422` con i valori validi. Vedi
[Engine e credits](/it/api-reference/edits/overview#engine-e-credits).
* `resolution` *(facoltativo)* — `1K` (predefinito), `2K` o `4K` su
`nano_banana_pro`, `nano_banana_2` e `nano_banana_2_1`. `gemini` e `kontext`
hanno una risoluzione fissa: lì ometti `resolution` (un valore restituisce
`422`).
* `num_images` *(facoltativo)* — `1`–`4`, predefinito `1`.
* `style_id`, `object_ids`, `person_ids`, `setting_ids` *(facoltativi)* — id o
nomi dei modelli addestrati da `list_models` da riusare per modifiche fedeli al
tuo brand (un nome viene risolto a un modello visibile a te), alla pari con
`generate_image`.
* `color_palette` *(facoltativo)* — una palette di colori da applicare, indicata
con il suo **nome o id**.
I modelli addestrati e `color_palette` funzionano solo con `nano_banana_pro`
(anche quando ometti `engine`). Indicare un qualsiasi altro engine insieme a loro
restituisce `422` prima di qualsiasi addebito — l'engine non viene mai cambiato.
Le modifiche con maschera sono solo REST e girano su `nano_banana_pro` o
`gemini`.
**Asincrono** — restituisce `{ id, status: "pending", estimated_credits, engine,
resolution }`. `engine` e `resolution` sono i valori **effettivi** con cui gira
la modifica (`resolution` è `null` su `gemini` e `kontext`). Costo per output: 5
credits × risoluzione sui tre engine Nano Banana (`1K` 5, `2K` 10, `4K` 20), 5
fissi su `gemini` e `kontext`; × `num_images`, dedotto all'invio. Per esempio,
`edit_image(prompt=…, image_id=…, resolution="4K")` restituisce
`estimated_credits: 20`.
* `prompt` *(obbligatorio)* — come trasformare le sorgenti.
* `images` *(obbligatorio)* — **1–14** sorgenti; ogni elemento è **o**
`{ image_id }` **o** `{ image_url }` (un URL https). L'ordine delle sorgenti è
preservato. Nessun base64 su MCP — vedi
[Input immagine](/it/guides/image-inputs).
* `engine` *(facoltativo)* — `nano_banana_pro` (predefinito), `nano_banana_2` o
`nano_banana_2_1` (Nano Banana 2.1).
* `aspect_ratio` *(facoltativo)* — validato rispetto alla lista dell'engine
(`nano_banana_2` e `nano_banana_2_1` consentono anche `4:1`, `1:4`, `8:1`,
`1:8`); se omesso, la forma della sorgente è preservata.
* `resolution` (`1K` predefinito, `2K`, `4K`), `num_outputs` (predefinito `1`).
**Asincrono** — interroga `get_job_status(kind="img2img", id=…)`. Costo:
`5 × num_outputs × risoluzione` (`1K` ×1, `2K` ×2, `4K` ×4). Scope
`images.edit`.
* **Uno** tra `image_id` o `image_url` *(obbligatorio)*.
* `target` *(facoltativo)* — cosa può cambiare: `everything` (predefinito),
`person`, `object`, `scene`.
* `creativity` *(facoltativo)* — `subtle` o `creative` (predefinito).
* `variation_instructions` / `preservation_instructions` *(facoltativi)* — testo
libero, ≤ 2000 caratteri ciascuno.
* `num_outputs` (`1`–`4`, predefinito `1`).
La **risoluzione di output è ereditata dalla sorgente** (nessun argomento
`resolution`). **Asincrono** — interroga
`get_job_status(kind="image_variation", id=…)`. Costo:
`5 × num_outputs × risoluzione sorgente` (`1K` ×1, `2K` ×2, `4K` ×4; una sorgente
senza dimensioni recuperabili è addebitata a `1K`). Scope `images.transform`.
* `aspect_ratio` *(obbligatorio)* — uno tra `21:9`, `16:9`, `3:2`, `4:3`, `5:4`,
`1:1`, `4:5`, `3:4`, `2:3`, `9:16`.
* **Uno** tra `image_id` o `image_url` *(obbligatorio)*.
* `resolution` (`1K` predefinito, `2K`, `4K`), `num_outputs` (`1`–`4`, predefinito
`1`).
* `prompt` *(facoltativo)* — guida per l'area appena esposta.
* `placement` *(facoltativo)* — `{ gravity, scale }` che posiziona la sorgente sul
canvas (`gravity` uno tra `center` \[predefinito], `top`, `bottom`, `left`,
`right`, `top_left`, `top_right`, `bottom_left`, `bottom_right`; `scale` in
`(0, 1]`).
Ridimensiona per outpainting — il server riempie il nuovo canvas con
un'estensione coerente con lo stile. Se non c'è nulla di nuovo da generare e non è
fornito alcun `prompt`, restituisce l'immagine appiattita e rimborsa gli output
inutilizzati. **Asincrono** — interroga
`get_job_status(kind="image_resize", id=…)`. Costo:
`5 × num_outputs × risoluzione`. Scope `images.transform`.
* `target_resolution` *(obbligatorio)* — `2K`, `4K`, `6K`, `8K`, `10K`, `12K`,
`14K`, `16K`, `20K`, `24K`, `28K`, `32K`, `38K` (le classi oltre `16K` sono
**solo `crystal`**).
* **Uno** tra `image_id` o `image_url` *(obbligatorio)*.
* `model` *(facoltativo)* — `seedvr`, `crystal` (predefinito), `magnific-creative`,
`magnific-precision`.
* `options` *(facoltativo)* — per modello, validate rigorosamente:
`options.magnific_creative` (`prompt`, `optimized_for`,
`creativity`/`hdr`/`resemblance`/`fractality` in −10..10, `engine`) o
`options.magnific_precision` (`sharpen`/`smart_grain`/`ultra_detail` in 0..100,
`flavor`). `seedvr`/`crystal` non prendono opzioni.
I limiti di fattore/area per modello sono validati **prima** dell'addebito.
**Asincrono** — interroga `get_job_status(kind="image_upscale", id=…)`. Costo: la
fascia di risoluzione × il moltiplicatore del modello (Magnific ×3); `crystal`
oltre `12K` è addebitato in base ai megapixel di output — vedi
[prezzi](/it/guides/pricing#upscale). Scope `images.transform`.
* **Uno** tra `image_id` o `image_url` *(obbligatorio)*.
Produce un PNG trasparente; non c'è un parametro del modello. **Asincrono** —
interroga `get_job_status(kind="image_background_removal", id=…)`. Costo: **1**
credit su un miss; **0** con un cache hit — un `image_id` che possiedi e che ha già
un risultato di rimozione dello sfondo restituisce subito
`{ status: "completed", estimated_credits: 0 }`. Scope `images.transform`.
* `svg_acceptance` *(obbligatorio)* — deve essere il booleano letterale `true`.
* **Uno** tra `image_id` o `image_url` *(obbligatorio)*.
Produce un **SVG**. Un SVG non può contenere né un manifesto C2PA né una filigrana,
quindi l'output vettoriale è consegnato senza firma — vedi
[Provenienza dei contenuti](/it/guides/content-provenance). Il riconoscimento è una
prova di divulgazione / audit, non una rinuncia alla conformità; senza di esso la
chiamata è rifiutata `422 svg_acceptance_required` e nulla viene addebitato. La
consegna richiede inoltre che la tua organizzazione abbia accettato gli attuali
ToS/AUP (verificato lato server); in caso contrario la chiamata è rifiutata
`403 svg_phase1_scope_out_required` senza addebito. **Asincrono** — interroga
`get_job_status(kind="image_vectorize", id=…)`. Costo: **5** su un miss; **0** con
un cache hit. Scope `images.transform`.
* `mode` *(obbligatorio)* — uno tra:
* `image_to_video` — anima un frame iniziale. Richiede esattamente uno tra
`image_id` / `image_url`; `end_image_url` facoltativo su engine capaci di
gestire il frame finale; `prompt` facoltativo.
* `text_to_video` — richiede `prompt`.
* `text_to_video_styled` — richiede `prompt` **e** `style_id`;
`object_ids` / `person_ids` / `setting_ids` facoltativi, più una
`color_palette` facoltativa (nome o id).
* `engine` *(predefinito `veo_3_1_lite`)*, `duration` *(predefinito: la durata
più breve supportata dall'engine, in secondi)*, `aspect_ratio` *(predefinito
`"16:9"`; anche `9:16`, `1:1`)*.
**Asincrono** — restituisce `{ id, status: "pending", estimated_credits }`. Costo:
moltiplicatori `5 / secondo × engine × risoluzione × audio`; la modalità stilizzata
aggiunge un forfait di 10 per l'immagine intermedia. Consulta
[prezzi](/it/guides/pricing#generazione-di-video).
* `kind` *(obbligatorio)* — uno tra `image_generation`, `image_edit`, `img2img`,
`image_variation`, `image_resize`, `image_upscale`,
`image_background_removal`, `image_vectorize`, `video` o `model`. Usa il kind
che lo strumento di invio ti ha indicato di interrogare.
* `id` *(obbligatorio)* — l'id del job o del modello restituito da uno strumento
di invio.
Restituisce lo stato (`pending` → `processing` → `completed` / `failed`) e, una
volta `completed`, gli URL presigned del risultato validi per 24 ore. Richiede lo
scope dello strumento che ha inviato (`models.read` per `kind: "model"`).
`processing` significa "interroga di nuovo". Per i kind di immagine
`image_generation`, `image_edit`, `img2img`, `image_variation` e `image_resize`:
* Quando **tutti** gli output non hanno superato la pipeline di compliance (per
esempio la firma C2PA), il job è `failed` con `error` impostato a
`delivery_blocked_compliance: ` e nessuna immagine. È uno stato
terminale — smetti di interrogare.
* Quando solo **alcuni** output non l'hanno superata, il job è `completed`:
`images` contiene gli output consegnabili e `blocked_images` elenca gli altri
come `{ id, reason }`. `reason` è `compliance_failed_signing`,
`compliance_failed_storage`, `compliance_failed_watermark` o
`missing_provenance_state`.
Per un job di **immagine raster** completato — ogni kind di immagine **tranne**
`image_vectorize` — la risposta include anche un'**anteprima inline
ridimensionata**, così i client MCP possono visualizzarla direttamente, insieme al
link all'asset a piena risoluzione. `image_vectorize` restituisce un SVG (nessuna
anteprima raster): usa l'URL presigned. L'anteprima è una copia a risoluzione
ridotta per una visualizzazione rapida; recupera il link per l'originale.
Nessun parametro. Restituisce ciò che **questa connessione** può spendere (`available` e
`spendable_plan_credits`), insieme ai `plan_credits` e `topup_credits` a livello di
organizzazione, al periodo di fatturazione corrente e a `scope` — il regime di budget da
cui la connessione attinge. `available` può essere inferiore a `plan_credits` quando
l'organizzazione riserva credits del piano ai team: ecco perché un job può essere
rifiutato per credits insufficienti mentre l'organizzazione mostra ancora un saldo. Vedi
[`GET /credits`](/it/api-reference/account/credits) per la semantica completa dei campi.
Gli argomenti degli strumenti MCP non possono trasportare i byte di un file. Per
usare un file immagine **locale** come sorgente, caricalo in tre passaggi:
1. Chiama `prepare_image_upload` con:
* `filename` *(obbligatorio)* — il nome del file.
* `content_type` *(obbligatorio)* — `image/jpeg`, `image/png` o `image/webp`.
* `size_bytes` *(obbligatorio)* — la dimensione **esatta** del file in byte
(per esempio da `wc -c < photo.png`). È firmata nell'URL, quindi un `PUT` di
qualsiasi altra lunghezza viene rifiutato.
* `width`, `height` *(facoltativi)* — usati solo per rifiutare in anticipo
un'immagine oltre i 32 MP.
Restituisce `{ image_id, upload_url, expires_at, max_bytes,
allowed_content_types }` e una stringa `next_step`.
2. Fai tu il `PUT` dei byte grezzi del file su `upload_url`, fuori da MCP, con lo
stesso `Content-Type` e senza header `Authorization`:
```bash theme={null}
curl -X PUT -H "Content-Type: image/png" --data-binary @photo.png ""
```
3. Chiama `complete_image_upload(image_id)` entro un'ora.
**Limiti:** al massimo 10 MB (10,485,760 byte) e 32 megapixel; `upload_url`
scade dopo **1 ora**; al massimo **20** upload in attesa di completamento per
utente (`too_many_pending_uploads` oltre). L'immagine appartiene all'utente
chiamante (il creatore della chiave API o l'utente OAuth) — gli altri membri
della tua organizzazione non possono usarla. **Gratis.** Scope: uno qualsiasi tra
`images.edit`, `images.transform` o `videos.generate`. Equivalente REST:
[Caricamento di immagini](/it/api-reference/uploads/overview).
* `image_id` *(obbligatorio)* — l'id restituito da `prepare_image_upload`.
Chiamalo **dopo** il `PUT`. Verifica il file salvato (presente, esattamente
`size_bytes`, al massimo 10 MB, un'immagine leggibile del `content_type`
preparato, al massimo 32 megapixel) e restituisce `{ image_id, status:
"completed", filename, content_type, size_bytes, width, height }`.
**Sincrono** — l'`image_id` è subito utilizzabile come sorgente di `edit_image`,
`img2img`, `upscale_image`, `resize_image`, `create_variations`,
`remove_background`, `vectorize_image` e `generate_video`
(`mode: "image_to_video"`). Prima che questa chiamata riesca, l'`image_id` non è
utilizzabile da nessuna parte.
Puoi richiamarlo senza rischi: restituisce lo stesso risultato, e un `PUT`
successivo non modifica l'immagine completata. Un file che non supera un
controllo restituisce un errore di validazione e viene scartato — fai il `PUT` di
un file valido sullo stesso `upload_url` finché è ancora valido e richiama questo
strumento. Un `image_id` sconosciuto, scaduto o di un altro utente restituisce
`not_found`; `upload_in_progress` significa che un'altra chiamata lo sta
completando proprio ora — riprova tra qualche secondo. **Gratis.** Stessi scope
di `prepare_image_upload`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.