Guides
Téléversement de fichiers
Téléversez un fichier une seule fois, puis référencez-le par son ID dans les requêtes Messages, Responses, de génération d'images et de vidéos.
Téléversez un fichier une seule fois, puis référencez-le par son ID dans les requêtes de modèle. Cela remplace le renvoi des mêmes octets en base64 ou l'hébergement du fichier à une URL publique.
Un ID de fichier fonctionne avec Messages, Responses, la génération d'images et la génération vidéo. Il ne fonctionne pas avec Chat Completions.
Avant de commencer
- Une clé API. Consultez Authentification.
- L'URL de base
https://openapi.felo.ai. - Un modèle qui accepte le type de fichier que vous prévoyez d'envoyer. Consultez Vérifier la prise en charge par le modèle.
Démarrage rapide
1. Téléverser le fichier
curl "https://openapi.felo.ai/api/v1/files" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-F "file=@./report.pdf"Un téléversement réussi renvoie le code HTTP 200 avec les métadonnées du fichier :
{
"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
}Conservez id. Traitez-le comme une chaîne opaque : ne le construisez pas et ne l'analysez pas.
2. Le référencer dans une requête
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."}
]
}
]
}'Les deux mêmes étapes en 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())Et avec Node.js 20 ou une version ultérieure :
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");Règles de téléversement
- Le corps est en
multipart/form-dataavec exactement une partie, nomméefile. Toute autre partie, y comprispurpose, est rejetée avecinvalid_file. - Laissez votre client HTTP définir
Content-Type. Le définir à la main fait disparaître la boundary multipart. - N'ajoutez pas de paramètres de requête à l'URL de téléversement.
- Téléversez en HTTP plutôt qu'avec le helper Files d'un SDK. La méthode
files.create()du SDK OpenAI envoie toujourspurposeet ne peut donc pas appeler cet endpoint. - Un téléversement qui expire ou dont la connexion est coupée peut tout de même avoir été stocké. Listez vos fichiers avant de téléverser à nouveau.
Où utiliser un ID de fichier
| Endpoint | Types de fichiers | Modalité d'entrée requise | Champ |
|---|---|---|---|
POST /api/v1/messages | PDF, image | file, image | messages[].content[] |
POST /api/v1/responses | PDF, image | file, image | input[].content[] |
POST /api/v1/images/generations | Image | image | input_references[] |
POST /api/v1/videos/generations | Image | image | frame_images[] |
POST /api/v1/videos/generations | Image, MP4, audio | image, video, audio | input_references[] |
POST /api/v1/chat/completions | Non pris en charge |
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."}
]
}
]
}Pour une image, utilisez {"type": "image", "source": {"type": "file", "file_id": "..."}}.
Responses
| Fichier | Bloc de contenu |
|---|---|
{"type": "input_file", "file_id": "..."} | |
| Image | {"type": "input_image", "file_id": "...", "detail": "auto"} |
Un bloc qui contient file_id ne doit pas contenir en plus une URL ou des données base64.
Génération d'images
{
"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..."}}
]
}Le reste de la requête, la réponse 202 et l'interrogation sont décrits dans Génération d'images.
Génération vidéo
La première et la dernière image se placent dans 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..."}
}
]
}Ajoutez une seconde entrée avec "frame_type": "last_frame" pour une image de fin. Une dernière image nécessite une première image.
Les éléments de référence se placent dans input_references. Chaque entrée utilise le localisateur correspondant à son type de média :
{
"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"}}
]
}Les combinaisons qu'un modèle accepte dépendent du modèle et du canal. frame_images et input_references ne peuvent pas être utilisés dans la même requête.
Règles des localisateurs
- Dans les requêtes d'image et de vidéo, chaque objet
image_url,video_urlouaudio_urlcontient exactement l'un des champsfile_idouurl, et aucun autre champ. - Un même tableau peut mélanger des entrées qui utilisent
file_idet des entrées qui utilisenturl. - La génération d'images et la génération vidéo n'acceptent que les fichiers que vous avez téléversés. Pour réutiliser une image générée, passez son
urlde sortie. - Une requête qui référence un fichier n'est pas basculée vers un autre canal en cas d'échec. Ne la réessayez pas sur un autre canal sans avoir vérifié l'erreur.
- Conservez un fichier jusqu'à ce que chaque tâche qui le référence atteigne un état terminal. Le supprimer plus tôt peut faire échouer la tâche.
Vérifier la prise en charge par le modèle
Un fichier stocké n'est pas automatiquement utilisable avec tous les modèles. Le modèle doit déclarer la modalité d'entrée correspondante dans le catalogue public :
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| Pour envoyer | input_modalities doit inclure |
|---|---|
| Un PDF | file |
| Une image | image |
| Un MP4 | video |
| Un fichier audio | audio |
Une liste vide ou absente signifie que les ID de fichier ne sont pas activés pour ce modèle. La requête échoue alors avec file_model_unsupported. Ne déduisez pas la prise en charge du nom du modèle.
Limites
| Limite | Valeur |
|---|---|
| Taille de téléversement | 100 MiB (104,857,600 octets) par fichier ; les fichiers vides sont rejetés |
| Octets référencés par requête de modèle | 50,000,000 octets au total |
| Références par requête de modèle | 100 |
| Longueur du nom de fichier | 255 caractères |
Référencer deux fois le même fichier compte deux fois dans les deux limites par requête. Un fichier entre 50 MB et 100 MiB peut être téléversé, mais ne peut pas être référencé dans une requête de modèle. Un modèle ou un canal peut appliquer une limite inférieure.
Types de fichiers
Le type est détecté à partir du contenu du fichier, et non de son extension ou du Content-Type de la partie.
| Type | Formats | Peut être référencé dans |
|---|---|---|
| Messages, Responses | ||
| Image | PNG, JPEG, GIF, WebP | Messages, Responses, génération d'images, génération vidéo |
| Vidéo | MP4 | Génération vidéo |
| Audio | MP3, WAV, FLAC, OGG | Génération vidéo |
| Office | DOCX, XLSX, PPTX | Stockage uniquement |
| Texte | Texte UTF-8, stocké en text/plain | Stockage uniquement |
Tout autre contenu est rejeté avec invalid_file.
Noms de fichiers
Un nom de fichier ne peut pas contenir <, >, :, ", |, ?, *, \ ni de caractères de contrôle. / est autorisé comme séparateur, mais les segments vides, . et .. ne le sont pas.
Gérer les fichiers
Les fichiers appartiennent à votre compte. Toutes les clés API du compte voient les mêmes fichiers ; les autres comptes ne peuvent pas utiliser vos ID de fichier.
Lister les fichiers
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
}Les résultats sont triés du plus ancien au plus récent. Lorsque has_more vaut true, passez le cursor renvoyé pour obtenir la page suivante. Il n'y a ni recherche ni filtre par type côté serveur.
Obtenir un fichier
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Supprimer un fichier
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"}La suppression prend effet immédiatement et ne peut pas être annulée. Un 503 signifie que la suppression n'a pas abouti ; renvoyez le DELETE.
Téléchargements
Les fichiers téléversés ne peuvent pas être téléchargés. GET /api/v1/files/{file_id}/content renvoie 400 file_not_downloadable, et l'en-tête Location de la réponse de téléversement pointe vers les métadonnées du fichier, pas vers ses octets. Conservez votre propre copie de tout ce que vous téléversez.
Pour télécharger des médias générés, utilisez les URL signées dans les outputs de la tâche.
Référence de l'API
Tous les endpoints utilisent Authorization: Bearer YOUR_API_KEY. Les réponses réussies sont de simples objets JSON, sans enveloppe.
| Méthode | Chemin | Renvoie |
|---|---|---|
POST | /api/v1/files | L'objet fichier |
GET | /api/v1/files | Une page de fichiers |
GET | /api/v1/files/{file_id} | L'objet fichier |
DELETE | /api/v1/files/{file_id} | {"id": "...", "type": "file_deleted"} |
GET | /api/v1/files/{file_id}/content | 400 file_not_downloadable |
POST, DELETE et le GET d'un seul fichier rejettent tout paramètre de requête avec invalid_query.
Objet fichier
| Champ | Type | Description |
|---|---|---|
id | string | ID de fichier, préfixé par felo_file_. Utilisez-le comme file_id |
type | string | Toujours file |
source | string | upload pour les fichiers que vous avez téléversés, generated pour les sorties de modèle |
filename | string | Le nom envoyé lors du téléversement |
mime_type | string | Type détecté à partir du contenu |
size_bytes | integer | Taille en octets |
created_at | string | Horodatage UTC au format ISO 8601 |
downloadable | boolean | false pour les fichiers téléversés |
Requête de téléversement
| Partie | Requis | Description |
|---|---|---|
file | Oui | Le fichier, envoyé comme partie fichier multipart/form-data avec un nom de fichier |
La réponse inclut un en-tête Location contenant l'URL des métadonnées du fichier.
Paramètres de liste
| Paramètre | Valeur par défaut | Description |
|---|---|---|
limit | 100 | Taille de page, de 1 à 1000 |
cursor | La valeur cursor de la page précédente | |
after, after_id | Alias de cursor. N'envoyez qu'un seul des trois | |
order | asc | Seul asc est pris en charge |
| Champ de réponse | Type | Description |
|---|---|---|
data | array | Objets fichier, du plus ancien au plus récent |
first_id | string ou null | ID du premier fichier de la page |
last_id | string ou null | ID du dernier fichier de la page |
cursor | string ou null | Valeur à passer comme cursor pour la page suivante |
has_more | boolean | Indique s'il existe une autre page |
Erreurs
Les endpoints Files, Responses ainsi que la génération d'images et la génération vidéo utilisent l'enveloppe d'erreur 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 vaut null pour les erreurs des endpoints Files. Messages renvoie le format d'erreur Anthropic, qui n'a pas de error.code. L'ID de requête se trouve dans l'en-tête de réponse X-Request-Id.
Erreurs lors du téléversement ou de la gestion des fichiers :
| HTTP | error.code | Signification |
|---|---|---|
| 400 | invalid_content_type | Le corps n'est pas en multipart/form-data |
| 400 | invalid_file | Aucune partie file, une partie supplémentaire, un fichier vide ou un contenu non pris en charge |
| 400 | invalid_filename | Le nom de fichier est trop long ou contient un caractère refusé |
| 413 | file_too_large | Le fichier dépasse 100 MiB |
| 400 | invalid_query | Un paramètre de requête non pris en charge, ou order différent de asc |
| 400 | invalid_limit | limit est en dehors de la plage de 1 à 1000 |
| 400 | invalid_cursor | Le curseur est mal formé, ou plusieurs curseurs ont été envoyés |
| 400 | file_not_downloadable | /content a été demandé |
| 404 | file_not_found | Le fichier n'existe pas, a été supprimé ou appartient à un autre compte |
| 503 | file_storage_unavailable | Le stockage de fichiers est temporairement indisponible ; réessayez plus tard |
| 503 | file_upload_expired | Le téléversement n'a pas abouti à temps ; téléversez à nouveau le fichier |
Erreurs lors du référencement d'un fichier dans une requête de modèle :
| HTTP | error.code | Signification |
|---|---|---|
| 400 | invalid_file_input | ID mal formé, file_id et url à la fois dans un même localisateur, ou plus de 100 références |
| 400 | unsupported_file_type | Le type du fichier ne correspond pas à l'emplacement, par exemple un MP4 dans un bloc document |
| 400 | file_model_unsupported | Le modèle ne déclare pas la modalité d'entrée requise |
| 400 | file_input_too_large | Les fichiers référencés dépassent 50,000,000 octets au total |
| 400 | file_protocol_unsupported | Un ID de fichier a été envoyé à Chat Completions |
| 404 | file_not_found | Le fichier est introuvable, supprimé, détenu par un autre compte, ou est un fichier généré envoyé à la génération d'images ou à la génération vidéo |
Pour la génération d'images et la génération vidéo, un fichier peut aussi échouer après le 202. La tâche se termine alors en failed avec l'un de ces codes dans error.code.
Les erreurs d'authentification, de solde et de limite de débit sont décrites dans Erreurs, limites et nouvelles tentatives.
Voir aussi
Besoin d'aide ?
- Pour toute question sur l'API, la facturation ou le compte, contactez le support.
- Échangez avec les développeurs Felo sur Discord.
- Consultez notre journal des modifications.
- Besoin de tarifs dégressifs ou d'aide à l'achat ? Contacter les ventes.
- Vous développez avec un LLM ? Lisez llms.txt.