# Caricamento di file

Carica un file una sola volta e fai riferimento al suo ID nelle richieste Messages, Responses, di generazione di immagini e di video.

Carica un file una sola volta, poi fai riferimento al suo ID nelle richieste ai modelli. Questo sostituisce il reinvio degli stessi byte in base64 o l'hosting del file a un URL pubblico.

Un ID di file funziona con Messages, Responses, generazione di immagini e generazione di video. Non funziona con Chat Completions.

## Prima di iniziare

- Una chiave API. Vedi [Autenticazione](https://openapi.felo.ai/it/docs/authentication.md).
- L'URL di base `https://openapi.felo.ai`.
- Un modello che accetta il tipo di file che intendi inviare. Vedi [Verificare il supporto del modello](#verificare-il-supporto-del-modello).

## Avvio rapido

### 1. Caricare il file

```bash
curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"
```

Un caricamento riuscito restituisce HTTP `200` con i metadati del file:

```json
{
  "id": "felo_file_0179...",
  "type": "file",
  "source": "upload",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 482113,
  "created_at": "2026-11-10T02:25:41Z",
  "downloadable": false
}
```

Salva `id`. Trattalo come una stringa opaca: non costruirlo e non analizzarlo.

### 2. Farvi riferimento in una richiesta

```bash
curl "https://openapi.felo.ai/api/v1/responses" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_file", "file_id": "felo_file_0179..."},
          {"type": "input_text", "text": "Summarize the attached report."}
        ]
      }
    ]
  }'
```

Gli stessi due passaggi in Python:

```python
import os

import requests

BASE = "https://openapi.felo.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['FELO_API_KEY']}"}


def upload(path: str) -> str:
    with open(path, "rb") as file:
        response = requests.post(
            f"{BASE}/api/v1/files",
            headers=HEADERS,
            files={"file": file},
            timeout=300,
        )
    response.raise_for_status()
    return response.json()["id"]


file_id = upload("./report.pdf")

response = requests.post(
    f"{BASE}/api/v1/responses",
    headers=HEADERS,
    json={
        "model": "gpt-5.5",
        "input": [
            {
                "role": "user",
                "content": [
                    {"type": "input_file", "file_id": file_id},
                    {"type": "input_text", "text": "Summarize the attached report."},
                ],
            }
        ],
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())
```

E in Node.js 20 o versioni successive:

```javascript
import { openAsBlob } from "node:fs";
import { basename } from "node:path";

const BASE = "https://openapi.felo.ai";
const headers = { Authorization: `Bearer ${process.env.FELO_API_KEY}` };

async function upload(path) {
  const form = new FormData();
  form.append("file", await openAsBlob(path), basename(path));
  const response = await fetch(`${BASE}/api/v1/files`, { method: "POST", headers, body: form });
  if (!response.ok) throw new Error(`Upload failed: ${response.status} ${await response.text()}`);
  return (await response.json()).id;
}

const fileId = await upload("./report.pdf");
```

### Regole di caricamento

- Il corpo è `multipart/form-data` con esattamente una parte, chiamata `file`. Qualsiasi altra parte, incluso `purpose`, viene rifiutata con `invalid_file`.
- Lascia che sia il client HTTP a impostare `Content-Type`. Impostandolo a mano si perde il boundary multipart.
- Non aggiungere parametri di query all'URL di caricamento.
- Carica via HTTP invece di usare l'helper Files di un SDK. `files.create()` dell'SDK OpenAI invia sempre `purpose`, quindi non può chiamare questo endpoint.
- Un caricamento andato in timeout o interrotto da una disconnessione potrebbe essere stato comunque salvato. Elenca i tuoi file prima di caricare di nuovo.

## Dove si può usare un ID di file

| Endpoint | Tipi di file | Modalità di input richiesta | Campo |
|---|---|---|---|
| `POST /api/v1/messages` | PDF, immagine | `file`, `image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF, immagine | `file`, `image` | `input[].content[]` |
| `POST /api/v1/images/generations` | Immagine | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | Immagine | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | Immagine, MP4, audio | `image`, `video`, `audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | Non supportato | | |

### Messages

```json
{
  "model": "claude-haiku-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "document", "source": {"type": "file", "file_id": "felo_file_0179..."}},
        {"type": "text", "text": "Summarize the attached report."}
      ]
    }
  ]
}
```

Per un'immagine, usa `{"type": "image", "source": {"type": "file", "file_id": "..."}}`.

### Responses

| File | Blocco di contenuto |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| Immagine | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

Un blocco che contiene `file_id` non deve contenere anche un URL o dati base64.

### Generazione di immagini

```json
{
  "model": "gemini-3-pro-image",
  "prompt": "Keep the product and framing. Replace the background with a sunlit marble countertop.",
  "input_references": [
    {"type": "image_url", "image_url": {"file_id": "felo_file_0179..."}}
  ]
}
```

Il resto della richiesta, la risposta `202` e il polling sono descritti in [Generazione di immagini](https://openapi.felo.ai/it/docs/guides/image-generation.md).

### Generazione di video

Il primo e l'ultimo fotogramma vanno in `frame_images`:

```json
{
  "model": "YOUR_VIDEO_MODEL",
  "prompt": "The camera slowly pushes in. Keep the colors and composition.",
  "duration": 5,
  "resolution": "720p",
  "frame_images": [
    {
      "type": "image_url",
      "frame_type": "first_frame",
      "image_url": {"file_id": "felo_file_0179..."}
    }
  ]
}
```

Aggiungi una seconda voce con `"frame_type": "last_frame"` per un fotogramma finale. Un ultimo fotogramma richiede un primo fotogramma.

Il materiale di riferimento va in `input_references`. Ogni voce usa il locator corrispondente al proprio tipo di media:

```json
{
  "input_references": [
    {"type": "image_url", "image_url": {"file_id": "felo_file_IMAGE"}},
    {"type": "video_url", "video_url": {"file_id": "felo_file_VIDEO"}},
    {"type": "audio_url", "audio_url": {"file_id": "felo_file_AUDIO"}}
  ]
}
```

Le combinazioni accettate da un modello dipendono dal modello e dal canale. `frame_images` e `input_references` non possono essere usati nella stessa richiesta.

### Regole dei locator

- Nelle richieste di immagini e video, ogni oggetto `image_url`, `video_url` o `audio_url` contiene esattamente uno tra `file_id` e `url`, e nessun altro campo.
- Uno stesso array può combinare voci che usano `file_id` e voci che usano `url`.
- La generazione di immagini e di video accetta solo file caricati da te. Per riutilizzare un'immagine generata, passa il suo `url` di output.
- Una richiesta che fa riferimento a un file non viene spostata su un altro canale in caso di errore. Non riprovarla su un canale diverso senza aver controllato l'errore.
- Conserva un file finché ogni attività che vi fa riferimento non raggiunge uno stato terminale. Eliminarlo prima può far fallire l'attività.

## Verificare il supporto del modello

Un file salvato non è automaticamente utilizzabile con ogni modello. Il modello deve dichiarare la modalità di input corrispondente nel catalogo pubblico:

```bash
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
```

```json
["text", "image", "file"]
```

| Per inviare | `input_modalities` deve includere |
|---|---|
| Un PDF | `file` |
| Un'immagine | `image` |
| Un MP4 | `video` |
| Un file audio | `audio` |

Un elenco vuoto o mancante significa che gli ID di file non sono abilitati per quel modello. La richiesta fallisce quindi con `file_model_unsupported`. Non dedurre il supporto dal nome del modello.

## Limiti

| Limite | Valore |
|---|---|
| Dimensione del caricamento | 100 MiB (104,857,600 byte) per file; i file vuoti vengono rifiutati |
| Byte referenziati per richiesta al modello | 50,000,000 byte in totale |
| Riferimenti per richiesta al modello | 100 |
| Lunghezza del nome file | 255 caratteri |

Fare riferimento due volte allo stesso file conta due volte per entrambi i limiti della richiesta. Un file tra 50 MB e 100 MiB può essere caricato ma non può essere referenziato in una richiesta a un modello. Un modello o un canale può applicare un limite inferiore.

### Tipi di file

Il tipo viene rilevato dal contenuto del file, non dall'estensione né dal `Content-Type` della parte.

| Tipo | Formati | Può essere referenziato in |
|---|---|---|
| PDF | PDF | Messages, Responses |
| Immagine | PNG, JPEG, GIF, WebP | Messages, Responses, generazione di immagini, generazione di video |
| Video | MP4 | Generazione di video |
| Audio | MP3, WAV, FLAC, OGG | Generazione di video |
| Office | DOCX, XLSX, PPTX | Solo archiviazione |
| Testo | Testo UTF-8, salvato come `text/plain` | Solo archiviazione |

Qualsiasi altro contenuto viene rifiutato con `invalid_file`.

### Nomi dei file

Un nome file non può contenere `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\` o caratteri di controllo. `/` è consentito come separatore, ma i segmenti vuoti, `.` e `..` non lo sono.

## Gestire i file

I file appartengono al tuo account. Ogni chiave API dell'account vede gli stessi file; gli altri account non possono usare i tuoi ID di file.

### Elencare i file

```bash
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{
  "data": [
    {
      "id": "felo_file_0179...",
      "type": "file",
      "source": "upload",
      "filename": "report.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 482113,
      "created_at": "2026-11-10T02:25:41Z",
      "downloadable": false
    }
  ],
  "first_id": "felo_file_0179...",
  "last_id": "felo_file_0179...",
  "cursor": "felo_file_0179...",
  "has_more": false
}
```

I risultati sono ordinati dal meno recente al più recente. Quando `has_more` è `true`, passa il `cursor` restituito per ottenere la pagina successiva. Non esistono ricerca né filtro per tipo lato server.

### Ottenere un file

```bash
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

### Eliminare un file

```bash
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{"id": "felo_file_0179...", "type": "file_deleted"}
```

L'eliminazione ha effetto immediato e non può essere annullata. Un `503` significa che l'eliminazione non è stata completata; invia di nuovo la `DELETE`.

### Download

I file caricati non possono essere scaricati. `GET /api/v1/files/{file_id}/content` restituisce `400 file_not_downloadable`, e l'header `Location` della risposta di caricamento punta ai metadati del file, non ai suoi byte. Conserva una tua copia di tutto ciò che carichi.

Per scaricare i media generati, usa gli URL firmati negli `outputs` dell'attività.

## Riferimento API

Tutti gli endpoint usano `Authorization: Bearer YOUR_API_KEY`. Le risposte riuscite sono semplici oggetti JSON, senza envelope.

| Metodo | Percorso | Restituisce |
|---|---|---|
| `POST` | `/api/v1/files` | L'[oggetto file](#oggetto-file) |
| `GET` | `/api/v1/files` | Una [pagina di file](#parametri-di-elenco) |
| `GET` | `/api/v1/files/{file_id}` | L'[oggetto file](#oggetto-file) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`, `DELETE` e la `GET` di un singolo file rifiutano qualsiasi parametro di query con `invalid_query`.

### Oggetto file

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | ID del file, con prefisso `felo_file_`. Usalo come `file_id` |
| `type` | string | Sempre `file` |
| `source` | string | `upload` per i file caricati da te, `generated` per gli output dei modelli |
| `filename` | string | Il nome inviato con il caricamento |
| `mime_type` | string | Tipo rilevato dal contenuto |
| `size_bytes` | integer | Dimensione in byte |
| `created_at` | string | Timestamp UTC in formato ISO 8601 |
| `downloadable` | boolean | `false` per i file caricati |

### Richiesta di caricamento

| Parte | Obbligatorio | Descrizione |
|---|---|---|
| `file` | Sì | Il file, inviato come parte file `multipart/form-data` con un nome file |

La risposta include un header `Location` con l'URL dei metadati del file.

### Parametri di elenco

| Parametro | Predefinito | Descrizione |
|---|---|---|
| `limit` | `100` | Dimensione della pagina, da 1 a 1000 |
| `cursor` | | Il valore `cursor` della pagina precedente |
| `after`, `after_id` | | Alias di `cursor`. Invia solo uno dei tre |
| `order` | `asc` | È supportato solo `asc` |

| Campo della risposta | Tipo | Descrizione |
|---|---|---|
| `data` | array | Oggetti file, dal meno recente |
| `first_id` | string o null | ID del primo file della pagina |
| `last_id` | string o null | ID dell'ultimo file della pagina |
| `cursor` | string o null | Valore da passare come `cursor` per la pagina successiva |
| `has_more` | boolean | Indica se esiste un'altra pagina |

## Errori

Gli endpoint Files, Responses e la generazione di immagini e video usano la struttura di errore OpenAI:

```json
{
  "error": {
    "message": "This model does not accept this attachment type",
    "type": "invalid_request_error",
    "param": "frame_images.0.image_url",
    "code": "file_model_unsupported"
  }
}
```

`param` è `null` per gli errori degli endpoint Files. Messages restituisce il formato di errore Anthropic, che non ha `error.code`. Il request ID si trova nell'header di risposta `X-Request-Id`.

Errori durante il caricamento o la gestione dei file:

| HTTP | `error.code` | Significato |
|---|---|---|
| 400 | `invalid_content_type` | Il corpo non è `multipart/form-data` |
| 400 | `invalid_file` | Nessuna parte `file`, una parte in più, un file vuoto o un contenuto non supportato |
| 400 | `invalid_filename` | Il nome file è troppo lungo o contiene un carattere non ammesso |
| 413 | `file_too_large` | Il file supera 100 MiB |
| 400 | `invalid_query` | Un parametro di query non supportato, oppure `order` diverso da `asc` |
| 400 | `invalid_limit` | `limit` è fuori dall'intervallo da 1 a 1000 |
| 400 | `invalid_cursor` | Il cursore è malformato, oppure è stato inviato più di un cursore |
| 400 | `file_not_downloadable` | È stato richiesto `/content` |
| 404 | `file_not_found` | Il file non esiste, è stato eliminato o appartiene a un altro account |
| 503 | `file_storage_unavailable` | L'archiviazione dei file è temporaneamente non disponibile; riprova più tardi |
| 503 | `file_upload_expired` | Il caricamento non è stato completato in tempo; carica di nuovo il file |

Errori quando si fa riferimento a un file in una richiesta a un modello:

| HTTP | `error.code` | Significato |
|---|---|---|
| 400 | `invalid_file_input` | ID malformato, `file_id` e `url` entrambi in uno stesso locator, oppure più di 100 riferimenti |
| 400 | `unsupported_file_type` | Il tipo del file non corrisponde alla posizione, per esempio un MP4 in un blocco documento |
| 400 | `file_model_unsupported` | Il modello non dichiara la modalità di input richiesta |
| 400 | `file_input_too_large` | I file referenziati superano 50,000,000 byte in totale |
| 400 | `file_protocol_unsupported` | È stato inviato un ID di file a Chat Completions |
| 404 | `file_not_found` | Il file è mancante, eliminato, di proprietà di un altro account, oppure è un file generato inviato alla generazione di immagini o video |

Per la generazione di immagini e video, un file può fallire anche dopo il `202`. L'attività termina quindi come `failed` con uno di questi codici in `error.code`.

Gli errori di autenticazione, saldo e rate limit sono descritti in [Errori, limiti e retry](https://openapi.felo.ai/it/docs/guides/errors-and-limits.md).

## Correlati

- [Protocolli e SDK](https://openapi.felo.ai/it/docs/guides/protocols.md)
- [Generazione di immagini](https://openapi.felo.ai/it/docs/guides/image-generation.md)
- [Attività asincrone](https://openapi.felo.ai/it/docs/guides/async-tasks.md)
- [Riferimento Model API](https://openapi.felo.ai/it/docs/model-api)
