# Modifica di immagini

Modifica un’immagine tramite istruzioni o una regione, sostituisci lo sfondo, cambia proporzioni o colori oppure sostituisci il testo.

Fonte: https://scifig.ai/it/docs/api/image-edits

## Operazioni

`POST /images/edits` con un corpo JSON. Ambito richiesto: `figures:generate`. `image` è un `file_id` di un caricamento o risultato precedente; `operation` sceglie la modifica e vale `instruct` per impostazione predefinita. Gli stessi strumenti sono nella barra dei risultati del sito.

| operation | Funzione | Campi | Crediti |
| --- | --- | --- | --- |
| instruct | Modifica l’intera immagine secondo le istruzioni; con una maschera, ridisegna solo la regione mascherata | `instruction` di 1–2.000 caratteri, `mask` facoltativa, `quality` | 50 / 75 / 100 in base alla qualità; con maschera 100 |
| white_background | Sostituisce lo sfondo con bianco uniforme, senza trasparenza | `quality` | 50 / 75 / 100 |
| aspect_ratio | Adatta l’intera figura a nuove proporzioni, estendendo lo sfondo | `aspect_ratio` (`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`), `quality` | 50 / 75 / 100 |
| recolor | Applica una palette all’illustrazione mantenendo i colori delle etichette | `palette` facoltativa di 1–8 colori `#RRGGBB`; se omessa, viene scelta una palette; `quality` | 50 / 75 / 100 |
| replace_text | Modifica le etichette nella loro posizione, mantenendo carattere e collocazione | `text_detection`, `replacements` | 100 |

Una maschera è un PNG caricato con finalità `mask`, delle stesse dimensioni dell’immagine, bianco dove l’immagine può cambiare. La modifica di una regione usa sempre il modello `premium`, indipendentemente da `quality`. `replace_text` non accetta `quality`: usa sempre il modello di modifica del testo al prezzo `premium`.

## Sostituzione del testo

- Chiama [`POST /images/text-detections`](/it/docs/api/text-detections) sulla stessa immagine. È gratuito e restituisce un `id` e i `texts` con il relativo `index`.
- Invia `operation: "replace_text"`, `text_detection: <id>` e `replacements: [{"index": 0, "text": "Figure 1"}]`. I testi non elencati rimangono invariati.
- Un indice assente nel rilevamento restituisce `400 INVALID_REQUEST` con `details.reason = TEXT_INDEX_OUT_OF_RANGE` senza addebiti.

## Crediti

I crediti vengono riservati alla creazione del processo, addebitati una sola volta se riesce e restituiti integralmente se fallisce. La risposta è un processo; consulta [Processi e attesa limitata](/it/docs/api/jobs) per i campi e gli stati. Gli errori sono elencati in [Errori](/it/docs/api/errors).

## cURL

```bash
curl -X POST https://scifig.ai/api/v1/images/edits \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=25" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<file_id>",
    "operation": "aspect_ratio",
    "aspect_ratio": "16:9"
  }'
```

## JavaScript

```javascript
const response = await fetch('https://scifig.ai/api/v1/images/edits', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    Prefer: 'wait=25',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "image": "<file_id>",
    "operation": "aspect_ratio",
    "aspect_ratio": "16:9"
  }),
});
const result = await response.json();
console.log(response.status, result);
```

## Python

```python
import os
import uuid

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
    "Idempotency-Key": str(uuid.uuid4()),
    "Prefer": "wait=25",
}
response = requests.post(
    "https://scifig.ai/api/v1/images/edits",
    headers=headers,
    json={
        "image": "<file_id>",
        "operation": "aspect_ratio",
        "aspect_ratio": "16:9"
    },
    timeout=60,
)
print(response.status_code, response.json())
```