# 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](https://openapi.felo.ai/fr/docs/authentication.md).
- 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](#v-rifier-la-prise-en-charge-par-le-mod-le).

## Démarrage rapide

### 1. Téléverser le fichier

```bash
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 :

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

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

```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."}
        ]
      }
    ]
  }'
```

Les deux mêmes étapes en 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())
```

Et avec Node.js 20 ou une version ultérieure :

```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");
```

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

| 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

```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."}
      ]
    }
  ]
}
```

Pour une image, utilisez `{"type": "image", "source": {"type": "file", "file_id": "..."}}`.

### Responses

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

```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..."}}
  ]
}
```

Le reste de la requête, la réponse `202` et l'interrogation sont décrits dans [Génération d'images](https://openapi.felo.ai/fr/docs/guides/image-generation.md).

### Génération vidéo

La première et la dernière image se placent dans `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..."}
    }
  ]
}
```

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 :

```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"}}
  ]
}
```

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 :

```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"]
```

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

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

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

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

### Supprimer un fichier

```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"}
```

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](#objet-fichier) |
| `GET` | `/api/v1/files` | Une [page de fichiers](#param-tres-de-liste) |
| `GET` | `/api/v1/files/{file_id}` | L'[objet fichier](#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 :

```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` 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](https://openapi.felo.ai/fr/docs/guides/errors-and-limits.md).

## Voir aussi

- [Protocoles et SDKs](https://openapi.felo.ai/fr/docs/guides/protocols.md)
- [Génération d'images](https://openapi.felo.ai/fr/docs/guides/image-generation.md)
- [Tâches asynchrones](https://openapi.felo.ai/fr/docs/guides/async-tasks.md)
- [Référence API de modèle](https://openapi.felo.ai/fr/docs/model-api)
