# API SciFig e server MCP

Crea figure scientifiche, grafici e diagrammi di flusso dal codice o dagli assistenti IA. Versione leggibile: https://scifig.ai/it/developers. OpenAPI: https://scifig.ai/api/v1/openapi.json.

## Panoramica

L’API SciFig crea figure scientifiche, grafici e diagrammi di flusso con gli stessi motori, prezzi e crediti del sito. L’URL di base è `https://scifig.ai/api/v1`. Ogni creazione è un’attività: la crei, poi ne consulti lo stato e i file prodotti.

Gli assistenti IA possono usare SciFig tramite il server MCP remoto all’indirizzo `https://mcp.scifig.ai/mcp` (vedi «Server MCP» più avanti).

## Autenticazione

Invia `Authorization: Bearer <credential>` con ogni richiesta, tranne quelle a `/pricing`, `/openapi.json` e `/openapi.yaml`.

- Le chiavi con permessi di scrittura richiedono un abbonamento attivo o un saldo positivo di un pacchetto e scadono dopo 30, 90 o 365 giorni. Quelle di sola lettura possono non scadere.
- Token di accesso OAuth (`sf_at_…`): vengono rilasciati ai client MCP dopo la tua approvazione e sono validi per un’ora. I client che richiedono `offline_access` ricevono anche un token di aggiornamento (`sf_rt_…`) valido per 30 giorni. Revoca un’app in Impostazioni → Chiavi API → App collegate.
- Le otto autorizzazioni si scelgono separatamente. Nessuna ne include un’altra: caricamento, lettura delle attività e lettura del saldo richiedono ciascuno il proprio permesso. `images:generate`, `images:edit`, `images:convert`, `charts:generate`, `flowcharts:generate`, `files:write`, `jobs:read`, `credits:read`
- `GET /api/v1/capabilities` richiede credenziali valide, senza autorizzazioni operative. Restituisce solo `granted_scopes`, senza saldo, piano o dati dell’account.
- Tutte le chiamate autenticate, inclusi errori di permessi e altri errori, conservano metadati per 30 giorni. Nessun prompt, contenuto, nome di file, IP o credenziale. In caso di guasti della piattaforma alcuni dati possono andare persi. Chiavi, cronologia e app collegate mostrano ciascuno 10 righe per pagina. I crediti indicano la contabilizzazione dell’attività associata; non sommare i tentativi ripetuti come spese aggiuntive.
- Solo i client `CIMD` consentiti possono usare `private_key_jwt` con firma a chiave pubblica verificata e protezione dai replay. La registrazione dinamica anonima resta limitata a `none` o `client_secret_basic`.

## Guida rapida

```bash
curl https://scifig.ai/api/v1/images/generations \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=25" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Mitochondrial electron transport chain, labelled", "aspect_ratio": "4:3"}'
```

La risposta contiene l’attività. Se non è ancora conclusa, lo stato è `202` con `Location: /api/v1/jobs/{id}`. Interroga questo URL ogni pochi secondi finché `status` non è `succeeded`, `failed` o `canceled`, poi scarica i risultati da `outputs[].download_url`.

## Convenzioni

- Richieste e risposte usano JSON; i caricamenti di file e i dati dei grafici usano `multipart/form-data`. I nomi dei campi seguono `snake_case`.
- Ogni `POST` che crea un risultato richiede un header `Idempotency-Key` (1–255 caratteri ASCII visibili). Riprovare con la stessa chiave e lo stesso corpo restituisce la stessa attività senza addebiti duplicati; la stessa chiave con un corpo diverso restituisce `409 IDEMPOTENCY_CONFLICT`. Due richieste contemporanee con la stessa chiave restituiscono la stessa attività oppure `409 IDEMPOTENCY_IN_PROGRESS` per quella che arriva mentre l’altra viene ancora accettata. Una richiesta rifiutata (per esempio `INSUFFICIENT_CREDITS`) conserva quella risposta per la sua chiave: dopo una ricarica o un cambio di abbonamento, inviala con una nuova chiave. Una volta creata l’attività, un errore per cui si può riprovare (`429`, `503`, `409 IDEMPOTENCY_IN_PROGRESS`) o `500 INTERNAL_ERROR` include `details.job_id`: riprova con la stessa chiave o interroga `GET /jobs/{job_id}`, senza usare una nuova chiave. Un’attività accettata ma non rileggibile restituisce `202` con stato `queued`.
- `Prefer: wait=N` (1–30 secondi) mantiene la risposta in attesa fino al completamento dell’attività o alla scadenza del tempo.
- Ogni risposta include `X-Request-Id`. Gli errori usano `{"error": {"code", "message", "request_id", "details"}}`.
- L’API non è accessibile dai browser tramite CORS; chiamala da un server o da uno script.

## Endpoint e crediti

| Endpoint | Destinazione | Crediti |
| --- | --- | --- |
| POST /images/generations | Genera un’illustrazione scientifica | 50 / 75 / 100 (standard / advanced / premium) |
| POST /images/edits | Modifica un’immagine: tramite istruzioni, una maschera per ridisegnare una regione, sfondo bianco, proporzioni, cambio di colori o sostituzione del testo | 50 / 75 / 100; con maschera o `replace_text` 100 |
| POST /images/text-detections | Rileva il testo in un’immagine prima di sostituirlo | 0 |
| POST /images/upscales | Ingrandisci a 2K, 4K o 8K | 50 / 100 / 150 |
| POST /images/conversions | Converti in SVG, PNG, PDF, TIFF o PPTX; gli SVG dei diagrammi di flusso in PNG, PDF, TIFF o PPTX | SVG 150; altri formati gratuiti, 200 al giorno |
| POST /charts/generations | Crea un grafico da dati CSV, TSV o Excel | 100 |
| POST /charts/edits | Modifica l’ultima versione di un grafico | 100 |
| POST /flowcharts/generations | Disegna un diagramma di flusso in SVG | 100 |
| POST /flowcharts/edits | Modifica l’ultima versione di un diagramma di flusso | 100 |
| POST /files | Carica un’immagine, una maschera o un allegato per un diagramma di flusso | 0 |
| GET /jobs/{id} | Stato, crediti e link di download di un processo | 0 |
| GET /jobs | I tuoi processi recenti, dal più recente, con paginazione tramite cursore | 0 |
| GET /files/{file_id} | Scarica un file | 0 |
| GET /credits | Saldo, piano e limiti delle attività | 0 |
| GET /pricing | Prezzo in crediti di ogni operazione, senza autenticazione | 0 |
| GET /openapi.json | Descrizione OpenAPI 3.1, senza autenticazione | 0 |
| GET /openapi.yaml | La stessa descrizione in YAML | 0 |

## Campi della richiesta

`POST /images/generations`: `prompt` (obbligatorio), `aspect_ratio` (`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`), `quality` (`standard`, `advanced`, `premium`), `style`, `palette` (ID di una combinazione predefinita o 1–4 colori `#RRGGBB`), `reference_file_ids` (fino a 3). Alcuni modelli e immagini di riferimento richiedono un piano a pagamento; l’errore lo specifica.

`POST /images/edits`: `image` (una `file_id`) e `operation`. `instruct` (predefinita) accetta `instruction` (fino a 2000 caratteri) e una `mask` facoltativa (PNG; il bianco indica l’area modificabile; una maschera usa sempre il modello `premium`). `white_background` sostituisce lo sfondo con bianco pieno. `aspect_ratio` adatta l’immagine a `aspect_ratio`. `recolor` applica `palette` (1–8 colori `#RRGGBB`) o sceglie una combinazione. Tutte queste operazioni accettano `quality`. `replace_text` accetta `text_detection` (l’ID restituito da `POST /images/text-detections` per la stessa immagine) e `replacements` (`[{"index", "text"}]`), e usa sempre il modello `premium` per la modifica del testo.

`POST /images/text-detections`: `image`. Restituisce `id`, le dimensioni `width` e `height` dell’immagine e `texts` (`index`, `text`, `corners`) in ordine di lettura. Gratuito; condivide con il sito il limite di 20 rilevamenti ogni 15 minuti.

`POST /images/upscales`: `image`, `scale` (`2k`; `4k` richiede almeno Starter e `8k` almeno Plus; un saldo del pacchetto crediti superiore a zero equivale a Pro).

`POST /images/conversions`: `image`, `format` (`svg`, `png`, `pdf`, `tiff`, `pptx`). Per SVG, `vector_mode` è `editable_text` (predefinita) o `full_vector`; la sorgente è un’immagine PNG, JPEG o WebP. Per gli altri formati, `dpi` è 300, 600 o 1000. I DPI vengono scritti nei metadati e determinano le dimensioni della pagina; i pixel non vengono ricampionati (per avere più pixel, ingrandisci prima l’immagine). La sorgente è un’immagine PNG o JPEG o l’SVG di un diagramma di flusso; WebP non è accettato e PNG e TIFF richiedono una sorgente PNG. L’SVG di un diagramma di flusso viene renderizzato sul server con Arial e Noto. `width` (256–4096, valore predefinito 2048) imposta il lato lungo in pixel; il testo che questi caratteri non possono visualizzare viene rifiutato. Il PPTX contiene l’immagine renderizzata, non forme modificabili.

`POST /charts/generations` (`multipart`): `data` (CSV, TSV, TXT, XLSX o XLS, fino a 8 MB; il delimitatore dei file di testo viene rilevato), `request` (cosa tracciare, 1–16.000 caratteri), e i campi facoltativi `chart_types` (separati da virgole), `journal_style` (`default`, `nature`, `science`, `cell`, `plos`, `acs`), `figure_width` (`single`, `onehalf`, `double`), `color_palette`, `sheet_name` (foglio di una cartella di lavoro con più fogli). I dati illeggibili restituiscono `400 INVALID_REQUEST`, con `details.field = data` e il codice del parser in `details.reason`. Output: PNG, PDF, TIFF ed EPS.

`POST /charts/edits` e `POST /flowcharts/edits`: `job` (attività precedente di un grafico o diagramma di flusso) e `instruction` (1–16.000 caratteri per i grafici, 1–8000 per i diagrammi di flusso). La modifica riparte dall’output di quell’attività, conservando dati, tipi di grafico e stile della rivista (grafici) o rapporto d’aspetto (diagrammi di flusso). Come nell’area di lavoro, si può modificare solo la versione più recente. Se esiste una versione successiva (anche creata sul sito), la risposta è `409 REVISION_CONFLICT` con `details.reason = NOT_LATEST_REVISION`. Finché l’attività padre è in corso, restituisce un errore per cui si può riprovare, `409 REVISION_CONFLICT` (`PARENT_JOB_RUNNING`, con `Retry-After`); se il padre è fallito, restituisce `400 INVALID_REQUEST` (`JOB_NOT_SUCCEEDED`).

`POST /flowcharts/generations`: `prompt` (1–8000 caratteri), `aspect_ratio` (`auto` o uno dei rapporti sopra indicati) e `attachment_file_ids` facoltativo (fino a 8, caricati con destinazione `flowchart_attachment`). Output: SVG.

## Attività

`status` è `queued`, `processing`, `succeeded`, `failed` o `canceled`. `credits` riporta `reserved`, `charged` e `refunded`, letti dal registro contabile. Un’attività fallita viene rimborsata.

Una generazione o modifica che supera il tempo limite ha stato `failed`, `error.code = TASK_TIMED_OUT` e la scadenza `late_delivery_until`. Fino a quel momento, il risultato può ancora essere consegnato gratuitamente: continua a leggere l’attività anziché crearne un’altra.

Un rifiuto dovuto alle norme sui contenuti restituisce `422 CONTENT_REJECTED` durante la creazione della richiesta oppure un’attività `failed` con `error.code = CONTENT_REJECTED` se avviene durante l’esecuzione. In entrambi i casi i crediti vengono rimborsati.

Ogni output ha una `file_id`, un `format` e una `download_url` valida per un’ora senza credenziali. Gli output PNG includono anche `width` e `height`. I grafici e i diagrammi di flusso includono una `editor_url` che apre il risultato nell’area di lavoro del sito; illustrazioni e conversioni non la hanno.

Le immagini di output (PNG, JPEG, WebP) possono essere passate tramite `file_id` come `image` o riferimento agli endpoint delle immagini. Le conversioni accettano sorgenti fino a 20 MB. Per PNG, PDF, TIFF e PPTX accettano immagini PNG o JPEG e l’SVG di un diagramma di flusso, non WebP.

## File

`POST /files` (`multipart`): `file` e `purpose` (`image`, `mask` o `flowchart_attachment`). Immagini: PNG, JPEG o WebP fino a 20 MB; maschere: PNG fino a 8 MB; allegati di diagrammi di flusso: formati dell’area di lavoro FlowChart, fino a 32 MB. La risposta è `201` con `file_id`, `purpose`, `content_type`, `size_bytes`, `expires_at` e `created_at`. I file caricati sono utilizzabili per 24 ore. Condividono i limiti di caricamento del sito; oltre il limite, la risposta è `429 RATE_LIMITED`. Un `Idempotency-Key` facoltativo (1–255 caratteri ASCII visibili) consente di ripetere il caricamento: lo stesso account, la stessa chiave e lo stesso `purpose` restituiscono il primo file con `201`, senza ricaricarlo né consumare il limite. La stessa chiave e lo stesso `purpose` con byte diversi restituiscono `409 IDEMPOTENCY_CONFLICT`. Ripetere un caricamento scaduto restituisce `400 INVALID_REQUEST` con `details.reason = FILE_EXPIRED`; caricalo di nuovo con una nuova chiave.

`GET /files/{file_id}` scarica il tuo file con le tue credenziali o tramite la `download_url` firmata di un’attività. Un link firmato scaduto o alterato restituisce `404`, così come tutti i link di un account bloccato o in fase di eliminazione.

## Errori

| Codice | HTTP | Significato |
| --- | --- | --- |
| UNAUTHORIZED | 401 | Credenziali mancanti o non valide. |
| ACCOUNT_UNAVAILABLE | 401 | Questo account non può usare l’API. |
| SCOPE_DENIED | 403 | Le credenziali non concedono questa autorizzazione. |
| INVALID_REQUEST | 400 | La richiesta non è valida. |
| IDEMPOTENCY_KEY_REQUIRED | 400 | È richiesta un’intestazione Idempotency-Key con 1–255 caratteri ASCII visibili. |
| IDEMPOTENCY_CONFLICT | 409 | Questo Idempotency-Key è già stato usato con una richiesta diversa. |
| IDEMPOTENCY_IN_PROGRESS | 409 | È ancora in elaborazione una richiesta con questo Idempotency-Key. |
| NOT_FOUND | 404 | Non trovato. |
| REVISION_CONFLICT | 409 | Il processo del grafico o diagramma di flusso non può essere modificato ora: `NOT_LATEST_REVISION`, `EDIT_IN_PROGRESS` oppure `PARENT_JOB_RUNNING` finché il processo padre è in esecuzione. |
| PAYLOAD_TOO_LARGE | 413 | Il corpo della richiesta è troppo grande. |
| INSUFFICIENT_CREDITS | 402 | Crediti insufficienti. |
| CONTENT_REJECTED | 422 | La politica sui contenuti ha rifiutato la richiesta. Il rifiuto viene restituito come `422` alla creazione della richiesta o come `error.code` di un processo non riuscito se avviene durante l’esecuzione; i crediti vengono rimborsati in entrambi i casi. |
| PLAN_REQUIRED | 403 | Il tuo piano non include questa opzione. |
| RATE_LIMITED | 429 | Troppe richieste, attività per ora, conversioni al giorno o caricamenti; `details.reason` indica la causa. |
| CONCURRENCY_LIMITED | 429 | Sono in esecuzione troppe attività per questo account. |
| SERVICE_UNAVAILABLE | 503 | Il servizio è temporaneamente non disponibile. Riprova con lo stesso Idempotency-Key. |
| TASK_FAILED | 502 | L’attività non è riuscita e i crediti sono stati restituiti. Invia una nuova richiesta con un nuovo Idempotency-Key per riprovare. |
| INTERNAL_ERROR | 500 | Errore interno. |

`details.reason` indica la causa precisa di `INVALID_REQUEST`, `PLAN_REQUIRED` ed errori analoghi. Solo `INSUFFICIENT_CREDITS` include `details.top_up_url`; il suo `utm_source` è `api` o `mcp`, in base al canale della richiesta.

Codici presenti solo in un’attività fallita:

| error.code | Significato | Cosa fare |
| --- | --- | --- |
| TASK_TIMED_OUT | L’attività ha superato il tempo limite e i crediti sono stati rimborsati. Una generazione o modifica di illustrazione può includere `late_delivery_until`: fino a quel momento il risultato può ancora arrivare gratuitamente. | Continua a consultare il processo fino a `late_delivery_until`; altrimenti invia una nuova richiesta con una nuova chiave |
| CONTENT_REJECTED | La politica sui contenuti ha rifiutato il risultato durante l’esecuzione; i crediti sono stati rimborsati. Lo stesso codice viene restituito come `422` quando la richiesta stessa viene rifiutata alla creazione. | Modifica la descrizione o l’input e usa una nuova chiave |
| ADMISSION_INCOMPLETE | Il processo non è mai stato avviato perché un errore che consente un nuovo tentativo lo ha impedito. Nessun credito è stato usato. | Invia la stessa richiesta con lo stesso Idempotency-Key |
| TASK_NOT_FOUND | Il processo è stato ammesso, ma la relativa attività non è più reperibile. | Invia una nuova richiesta con una nuova chiave |
| TASK_FAILED | L’attività non è riuscita e i crediti sono stati rimborsati. Ogni errore del motore senza un codice pubblico proprio diventa `TASK_FAILED`; il codice del motore è in `details.reason`. | Invia una nuova richiesta con una nuova chiave |
| INTERNAL_ERROR | L’attività non è riuscita senza indicare il motivo; i crediti sono stati rimborsati. | Invia una nuova richiesta con una nuova chiave |

## Limiti di frequenza

- Creazione: 20 richieste al minuto per credenziale e 40 al minuto per account. Le credenziali OAuth vengono conteggiate per client e account.
- Lettura: 120 richieste al minuto per credenziale.
- Le attività simultanee dipendono dal tuo piano; ne possono iniziare al massimo 200 all’ora. Entrambi i limiti sono condivisi con il sito.
- Le risposte che superano l’autenticazione e il controllo dell’ambito includono `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`; una risposta `429` include `Retry-After`.
- `429 RATE_LIMITED` ha diverse cause; consulta `details.reason` e la [pagina dei limiti di frequenza](/it/docs/api/rate-limits).

## Installa il plugin ufficiale SciFig

Aggiungi il marketplace SciFig in Claude Code per installare la connessione MCP remota e quattro skill per la configurazione, le figure, i grafici e l’esportazione.

```text
/plugin marketplace add lilingm963/scifig-plugins
/plugin install scifig@scifig-plugins
```

- [Panoramica di API e MCP](/it/developers)
- [Guida all’installazione MCP](/it/developers/mcp/install.md)
- [Riferimento API](/it/docs/api)
- [Scopri il plugin ufficiale](https://github.com/lilingm963/scifig-plugins)
- [Scheda nel MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.lilingm963%2Fscifig/versions/1.0.0)

## Server MCP

URL del server: `https://mcp.scifig.ai/mcp`, Streamable HTTP. I client che supportano OAuth si collegano accedendo a SciFig e autorizzando l’accesso; quelli che inviano intestazioni possono usare una chiave API come `Authorization: Bearer sk_live_…`.

| Strumento | Funzione |
| --- | --- |
| generate_figure | Crea un’illustrazione scientifica da una descrizione |
| edit_figure | Modifica un’immagine: istruzioni, eventualmente una regione mascherata, sfondo bianco, proporzioni, cambio di colori o sostituzione del testo |
| detect_text | Rileva il testo in un’immagine prima di sostituirlo |
| upscale_figure | Ingrandisci a 2K, 4K o 8K |
| convert_figure | Converti in SVG, PNG, PDF, TIFF o PPTX |
| generate_chart | Crea un grafico da testo CSV o TSV o righe JSON, fino a 1 MB |
| edit_chart | Modifica l’ultima versione di un grafico |
| generate_flowchart | Disegna un diagramma di flusso in SVG, eventualmente da un massimo di 8 allegati |
| edit_flowchart | Modifica l’ultima versione di un diagramma di flusso |
| get_job | Stato, crediti e link di download di un processo |
| list_figures | Processi recenti |
| get_credit_balance | Saldo crediti, piano e limiti |

Gli strumenti di creazione attendono fino a 25 secondi. Se un processo è ancora in esecuzione, chiama `get_job` più tardi; richiamare lo strumento di creazione crea e addebita un nuovo processo. I risultati elencano tutti i link di download e, per grafici e diagrammi di flusso, il link che apre il risultato nell’editor SciFig.

L’inizializzazione usa `/capabilities` senza `credits:read`. Ogni strumento richiede il proprio permesso. Caricare da URL esterni o data URL richiede anche `files:write`, verificato prima del download; riutilizzare un `file_id` non lo richiede. Download integrati e `get_job` richiedono `jobs:read`. Se manca, conserva il risultato e spiega il limite senza ampliare i permessi senza consenso.

## Collega il tuo client

Claude, su claude.ai e in Claude Desktop: Impostazioni → Connettori → Aggiungi connettore personalizzato. Inserisci l’URL del server, accedi a SciFig e consenti l’accesso.

Apri `Plugins` in ChatGPT e aggiungi una connessione MCP personalizzata privata. I menu dipendono dall’account.

Claude Code:

```bash
claude mcp add --transport http scifig https://mcp.scifig.ai/mcp
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.scifig]
url = "https://mcp.scifig.ai/mcp"
```

Apri Cursor `Customize` → MCP e modifica `mcp.json` mantenendo i server esistenti. Poi seleziona `Authenticate` e autorizza SciFig nel browser.

```json
{
  "mcpServers": {
    "scifig": {
      "url": "https://mcp.scifig.ai/mcp"
    }
  }
}
```

I client senza OAuth possono aggiungere l’intestazione `Authorization: Bearer sk_live_…` con una chiave API creata in Impostazioni → Chiavi API.