Felo API PlatformFelo API Platform

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

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-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

EndpointTipi di fileModalità di input richiestaCampo
POST /api/v1/messagesPDF, immaginefile, imagemessages[].content[]
POST /api/v1/responsesPDF, immaginefile, imageinput[].content[]
POST /api/v1/images/generationsImmagineimageinput_references[]
POST /api/v1/videos/generationsImmagineimageframe_images[]
POST /api/v1/videos/generationsImmagine, MP4, audioimage, video, audioinput_references[]
POST /api/v1/chat/completionsNon 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

FileBlocco 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

{
  "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_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:

curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
["text", "image", "file"]
Per inviareinput_modalities deve includere
Un PDFfile
Un'immagineimage
Un MP4video
Un file audioaudio

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

LimiteValore
Dimensione del caricamento100 MiB (104,857,600 byte) per file; i file vuoti vengono rifiutati
Byte referenziati per richiesta al modello50,000,000 byte in totale
Riferimenti per richiesta al modello100
Lunghezza del nome file255 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.

TipoFormatiPuò essere referenziato in
PDFPDFMessages, Responses
ImmaginePNG, JPEG, GIF, WebPMessages, Responses, generazione di immagini, generazione di video
VideoMP4Generazione di video
AudioMP3, WAV, FLAC, OGGGenerazione di video
OfficeDOCX, XLSX, PPTXSolo archiviazione
TestoTesto UTF-8, salvato come text/plainSolo 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.

MetodoPercorsoRestituisce
POST/api/v1/filesL'oggetto file
GET/api/v1/filesUna 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}/content400 file_not_downloadable

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

Oggetto file

CampoTipoDescrizione
idstringID del file, con prefisso felo_file_. Usalo come file_id
typestringSempre file
sourcestringupload per i file caricati da te, generated per gli output dei modelli
filenamestringIl nome inviato con il caricamento
mime_typestringTipo rilevato dal contenuto
size_bytesintegerDimensione in byte
created_atstringTimestamp UTC in formato ISO 8601
downloadablebooleanfalse per i file caricati

Richiesta di caricamento

ParteObbligatorioDescrizione
fileSì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

ParametroPredefinitoDescrizione
limit100Dimensione della pagina, da 1 a 1000
cursorIl valore cursor della pagina precedente
after, after_idAlias di cursor. Invia solo uno dei tre
orderascÈ supportato solo asc
Campo della rispostaTipoDescrizione
dataarrayOggetti file, dal meno recente
first_idstring o nullID del primo file della pagina
last_idstring o nullID dell'ultimo file della pagina
cursorstring o nullValore da passare come cursor per la pagina successiva
has_morebooleanIndica 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:

HTTPerror.codeSignificato
400invalid_content_typeIl corpo non è multipart/form-data
400invalid_fileNessuna parte file, una parte in più, un file vuoto o un contenuto non supportato
400invalid_filenameIl nome file è troppo lungo o contiene un carattere non ammesso
413file_too_largeIl file supera 100 MiB
400invalid_queryUn parametro di query non supportato, oppure order diverso da asc
400invalid_limitlimit è fuori dall'intervallo da 1 a 1000
400invalid_cursorIl cursore è malformato, oppure è stato inviato più di un cursore
400file_not_downloadableÈ stato richiesto /content
404file_not_foundIl file non esiste, è stato eliminato o appartiene a un altro account
503file_storage_unavailableL'archiviazione dei file è temporaneamente non disponibile; riprova più tardi
503file_upload_expiredIl 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:

HTTPerror.codeSignificato
400invalid_file_inputID malformato, file_id e url entrambi in uno stesso locator, oppure più di 100 riferimenti
400unsupported_file_typeIl tipo del file non corrisponde alla posizione, per esempio un MP4 in un blocco documento
400file_model_unsupportedIl modello non dichiara la modalità di input richiesta
400file_input_too_largeI file referenziati superano 50,000,000 byte in totale
400file_protocol_unsupportedÈ stato inviato un ID di file a Chat Completions
404file_not_foundIl 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?