Felo API PlatformFelo API Platform

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

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-data avec exactement une partie, nommée file. Toute autre partie, y compris purpose, est rejetée avec invalid_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 toujours purpose et 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

EndpointTypes de fichiersModalité d'entrée requiseChamp
POST /api/v1/messagesPDF, imagefile, imagemessages[].content[]
POST /api/v1/responsesPDF, imagefile, imageinput[].content[]
POST /api/v1/images/generationsImageimageinput_references[]
POST /api/v1/videos/generationsImageimageframe_images[]
POST /api/v1/videos/generationsImage, MP4, audioimage, video, audioinput_references[]
POST /api/v1/chat/completionsNon 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

FichierBloc de contenu
PDF{"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_url ou audio_url contient exactement l'un des champs file_id ou url, et aucun autre champ.
  • Un même tableau peut mélanger des entrées qui utilisent file_id et des entrées qui utilisent url.
  • 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 url de 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 envoyerinput_modalities doit inclure
Un PDFfile
Une imageimage
Un MP4video
Un fichier audioaudio

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

LimiteValeur
Taille de téléversement100 MiB (104,857,600 octets) par fichier ; les fichiers vides sont rejetés
Octets référencés par requête de modèle50,000,000 octets au total
Références par requête de modèle100
Longueur du nom de fichier255 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.

TypeFormatsPeut être référencé dans
PDFPDFMessages, Responses
ImagePNG, JPEG, GIF, WebPMessages, Responses, génération d'images, génération vidéo
VidéoMP4Génération vidéo
AudioMP3, WAV, FLAC, OGGGénération vidéo
OfficeDOCX, XLSX, PPTXStockage uniquement
TexteTexte UTF-8, stocké en text/plainStockage 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éthodeCheminRenvoie
POST/api/v1/filesL'objet fichier
GET/api/v1/filesUne 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}/content400 file_not_downloadable

POST, DELETE et le GET d'un seul fichier rejettent tout paramètre de requête avec invalid_query.

Objet fichier

ChampTypeDescription
idstringID de fichier, préfixé par felo_file_. Utilisez-le comme file_id
typestringToujours file
sourcestringupload pour les fichiers que vous avez téléversés, generated pour les sorties de modèle
filenamestringLe nom envoyé lors du téléversement
mime_typestringType détecté à partir du contenu
size_bytesintegerTaille en octets
created_atstringHorodatage UTC au format ISO 8601
downloadablebooleanfalse pour les fichiers téléversés

Requête de téléversement

PartieRequisDescription
fileOuiLe 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ètreValeur par défautDescription
limit100Taille de page, de 1 à 1000
cursorLa valeur cursor de la page précédente
after, after_idAlias de cursor. N'envoyez qu'un seul des trois
orderascSeul asc est pris en charge
Champ de réponseTypeDescription
dataarrayObjets fichier, du plus ancien au plus récent
first_idstring ou nullID du premier fichier de la page
last_idstring ou nullID du dernier fichier de la page
cursorstring ou nullValeur à passer comme cursor pour la page suivante
has_morebooleanIndique 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 :

HTTPerror.codeSignification
400invalid_content_typeLe corps n'est pas en multipart/form-data
400invalid_fileAucune partie file, une partie supplémentaire, un fichier vide ou un contenu non pris en charge
400invalid_filenameLe nom de fichier est trop long ou contient un caractère refusé
413file_too_largeLe fichier dépasse 100 MiB
400invalid_queryUn paramètre de requête non pris en charge, ou order différent de asc
400invalid_limitlimit est en dehors de la plage de 1 à 1000
400invalid_cursorLe curseur est mal formé, ou plusieurs curseurs ont été envoyés
400file_not_downloadable/content a été demandé
404file_not_foundLe fichier n'existe pas, a été supprimé ou appartient à un autre compte
503file_storage_unavailableLe stockage de fichiers est temporairement indisponible ; réessayez plus tard
503file_upload_expiredLe 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 :

HTTPerror.codeSignification
400invalid_file_inputID mal formé, file_id et url à la fois dans un même localisateur, ou plus de 100 références
400unsupported_file_typeLe type du fichier ne correspond pas à l'emplacement, par exemple un MP4 dans un bloc document
400file_model_unsupportedLe modèle ne déclare pas la modalité d'entrée requise
400file_input_too_largeLes fichiers référencés dépassent 50,000,000 octets au total
400file_protocol_unsupportedUn ID de fichier a été envoyé à Chat Completions
404file_not_foundLe 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 ?