Guide
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.
- 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.
Avvio rapido
1. Caricare il file
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:
{
"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
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:
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:
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-datacon esattamente una parte, chiamatafile. Qualsiasi altra parte, inclusopurpose, viene rifiutata coninvalid_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 semprepurpose, 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
{
"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 |
|---|---|
{"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
{
"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.
Generazione di video
Il primo e l'ultimo fotogramma vanno in frame_images:
{
"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:
{
"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_urloaudio_urlcontiene esattamente uno trafile_ideurl, e nessun altro campo. - Uno stesso array può combinare voci che usano
file_ide voci che usanourl. - La generazione di immagini e di video accetta solo file caricati da te. Per riutilizzare un'immagine generata, passa il suo
urldi 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:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["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 |
|---|---|---|
| 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
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
-H "Authorization: Bearer ${FELO_API_KEY}"{
"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
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Eliminare un file
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"{"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 |
GET | /api/v1/files | Una pagina di file |
GET | /api/v1/files/{file_id} | L'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:
{
"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.
Correlati
Serve aiuto?
- Per domande su API, fatturazione e account scrivi a supporto.
- Parla con gli sviluppatori Felo su Discord.
- Dai un'occhiata al nostro registro delle modifiche.
- Ti servono prezzi per volumi o aiuto con gli acquisti? Contatta le vendite.
- Stai sviluppando con un LLM? Leggi llms.txt.