# File

Carica gli input e scarica i risultati.

Fonte: https://scifig.ai/it/docs/api/files

## Carica

`POST /files` accetta `multipart/form-data` e richiede l’ambito `figures:generate`. Restituisce `201` con `file_id`, `purpose`, `content_type`, `size_bytes`, `expires_at` e `created_at`.

| Campo | Tipo | Obbligatorio | Valore predefinito | Regole |
| --- | --- | --- | --- | --- |
| file | file | sì | — | Vedi sotto i limiti per finalità |
| purpose | string | no | `image` | `image`, `mask` o `flowchart_attachment` |

| Finalità | Accettato | Usato per |
| --- | --- | --- |
| image | PNG, JPEG o WebP fino a 20 MB, verificato dal contenuto e non dal nome | Modifiche, rilevamento del testo, ingrandimenti, conversioni, immagini di riferimento |
| mask | PNG fino a 8 MB; il bianco indica la regione da ridisegnare | `POST /images/edits` |
| flowchart_attachment | Formati dello spazio di lavoro FlowChart, fino a 32 MB | `POST /flowcharts/generations` |

I file caricati possono essere usati per 24 ore; dopo, il `file_id` è sconosciuto: `400 INVALID_REQUEST`, `FILE_NOT_FOUND`. Sono solo input: non compaiono mai nelle risposte dei processi e non vengono condivisi con nessuno.

I caricamenti contano per gli stessi limiti del sito. Oltre tali limiti, la risposta è `429 RATE_LIMITED` con `Retry-After` e `details.reason` pari a `UPLOAD_RATE_LIMITED` al minuto o `UPLOAD_DAILY_LIMIT_REACHED` al giorno per gli allegati dei diagrammi di flusso.

Un caricamento può inviare un’intestazione facoltativa `Idempotency-Key` di 1–255 caratteri ASCII visibili. Lo stesso account, chiave e `purpose` corrispondono sempre a un solo `file_id`: una ripetizione restituisce il primo file con `201`, senza ricaricarlo né consumare i limiti. La stessa chiave e `purpose` con byte diversi restituisce `409 IDEMPOTENCY_CONFLICT`. Senza intestazione, ogni caricamento crea un nuovo file. Se il caricamento è scaduto, la ripetizione restituisce `400 INVALID_REQUEST` con `details.reason = FILE_EXPIRED`; caricalo di nuovo con una nuova chiave.

## Scarica

Ogni risultato ha un `download_url` utilizzabile senza credenziali per un’ora; consulta di nuovo il processo per un nuovo link. `GET /files/{file_id}` con le tue credenziali scarica qualsiasi tuo file. I file vengono sempre serviti come allegati.

Un `download_url` firmato restituisce `404 NOT_FOUND` dopo la scadenza o se viene modificato; tutti i link di un account bloccato o in fase di eliminazione smettono di funzionare allo stesso modo.

| Risultato | Può essere passato a |
| --- | --- |
| PNG o JPEG | Ogni endpoint per immagini: modifiche, rilevamento del testo, ingrandimenti, conversioni, immagini di riferimento |
| WebP | Modifiche, rilevamento del testo, ingrandimenti, vettorializzazione SVG e immagini di riferimento; non conversioni PNG, PDF, TIFF o PPTX |
| SVG di diagramma di flusso | `POST /images/conversions` in PNG, PDF, TIFF o PPTX |
| PDF, TIFF, EPS, PPTX e altri SVG | Nessuno: solo download |

Una sorgente di conversione più grande di 20 MB, ad esempio un ingrandimento 8K, viene rifiutata con `400 INVALID_REQUEST` e `FILE_TOO_LARGE`.

## cURL

```bash
curl -X POST https://scifig.ai/api/v1/files \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -F "file=@figure.png" \
  -F "purpose=image"
```

## JavaScript

```javascript
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.set('file', new Blob([await readFile('figure.png')]), 'figure.png');
form.set('purpose', 'image');

const response = await fetch('https://scifig.ai/api/v1/files', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
  },
  body: form,
});
const result = await response.json();
console.log(response.status, result);
```

## Python

```python
import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
}
response = requests.post(
    "https://scifig.ai/api/v1/files",
    headers=headers,
    files={"file": open("figure.png", "rb")},
    data={"purpose": "image"},
    timeout=60,
)
print(response.status_code, response.json())
```