# Bestanden uploaden

Upload een bestand één keer en verwijs er daarna met de ID naar in Messages-, Responses-, beeld- en videogeneratieverzoeken.

Upload een bestand één keer en verwijs er daarna in modelverzoeken naar met het ID. Dat vervangt het opnieuw verzenden van dezelfde bytes als base64 of het hosten van het bestand op een openbare URL.

Een bestands-ID werkt met Messages, Responses, beeldgeneratie en videogeneratie. Het werkt niet met Chat Completions.

## Voordat je begint

- Een API-sleutel. Zie [Authenticatie](https://openapi.felo.ai/nl/docs/authentication.md).
- De base-URL `https://openapi.felo.ai`.
- Een model dat het bestandstype accepteert dat je wilt verzenden. Zie [Modelondersteuning controleren](#modelondersteuning-controleren).

## Snelstart

### 1. Het bestand uploaden

```bash
curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"
```

Een geslaagde upload retourneert HTTP `200` met de metadata van het bestand:

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

Sla `id` op. Behandel het als een opaque string: stel het niet zelf samen en parseer het niet.

### 2. Ernaar verwijzen in een verzoek

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

Dezelfde twee stappen in 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())
```

En in Node.js 20 of hoger:

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

### Uploadregels

- De body is `multipart/form-data` met precies één deel, met de naam `file`. Elk ander deel, ook `purpose`, wordt geweigerd met `invalid_file`.
- Laat je HTTP-client `Content-Type` instellen. Als je die handmatig instelt, gaat de multipart boundary verloren.
- Voeg geen queryparameters toe aan de upload-URL.
- Upload via HTTP in plaats van met de Files-helper van een SDK. `files.create()` van de OpenAI SDK stuurt altijd `purpose` mee en kan dit endpoint dus niet aanroepen.
- Een upload met een time-out of een verbroken verbinding kan toch zijn opgeslagen. Vraag de lijst met je bestanden op voordat je opnieuw uploadt.

## Waar je een bestands-ID kunt gebruiken

| Endpoint | Bestandstypen | Vereiste invoermodaliteit | Veld |
|---|---|---|---|
| `POST /api/v1/messages` | PDF, afbeelding | `file`, `image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF, afbeelding | `file`, `image` | `input[].content[]` |
| `POST /api/v1/images/generations` | Afbeelding | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | Afbeelding | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | Afbeelding, MP4, audio | `image`, `video`, `audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | Niet ondersteund | | |

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

Gebruik voor een afbeelding `{"type": "image", "source": {"type": "file", "file_id": "..."}}`.

### Responses

| Bestand | Contentblok |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| Afbeelding | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

Een blok met `file_id` mag niet ook een URL of base64-gegevens bevatten.

### Beeldgeneratie

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

De rest van het verzoek, de `202`-respons en het pollen worden beschreven in [Beeldgeneratie](https://openapi.felo.ai/nl/docs/guides/image-generation.md).

### Videogeneratie

Het eerste en het laatste frame gaan in `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..."}
    }
  ]
}
```

Voeg voor een eindframe een tweede vermelding toe met `"frame_type": "last_frame"`. Een laatste frame vereist een eerste frame.

Referentiemateriaal gaat in `input_references`. Elke vermelding gebruikt de locator die bij het mediatype past:

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

Welke combinaties een model accepteert, hangt af van het model en het kanaal. `frame_images` en `input_references` kunnen niet in hetzelfde verzoek worden gebruikt.

### Locatorregels

- In beeld- en videoverzoeken bevat elk `image_url`-, `video_url`- of `audio_url`-object precies één van `file_id` of `url`, en geen ander veld.
- Eén array kan vermeldingen met `file_id` en vermeldingen met `url` combineren.
- Beeld- en videogeneratie accepteren alleen bestanden die je zelf hebt geüpload. Geef de uitvoer-`url` van een gegenereerde afbeelding door om die opnieuw te gebruiken.
- Een verzoek dat naar een bestand verwijst, wordt bij een fout niet naar een ander kanaal verplaatst. Probeer het niet opnieuw op een ander kanaal zonder de fout te controleren.
- Bewaar een bestand totdat elke taak die ernaar verwijst een definitieve status heeft bereikt. Als je het eerder verwijdert, kan de taak mislukken.

## Modelondersteuning controleren

Een opgeslagen bestand is niet automatisch bruikbaar met elk model. Het model moet de bijbehorende invoermodaliteit declareren in de openbare catalogus:

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

| Wat je verzendt | `input_modalities` moet bevatten |
|---|---|
| Een PDF | `file` |
| Een afbeelding | `image` |
| Een MP4 | `video` |
| Een audiobestand | `audio` |

Een lege of ontbrekende lijst betekent dat bestands-ID's voor dat model niet zijn ingeschakeld. Het verzoek mislukt dan met `file_model_unsupported`. Leid ondersteuning niet af uit de modelnaam.

## Limieten

| Limiet | Waarde |
|---|---|
| Uploadgrootte | 100 MiB (104,857,600 bytes) per bestand; lege bestanden worden geweigerd |
| Bytes waarnaar wordt verwezen per modelverzoek | 50,000,000 bytes in totaal |
| Referenties per modelverzoek | 100 |
| Lengte van de bestandsnaam | 255 tekens |

Twee keer naar hetzelfde bestand verwijzen telt twee keer mee voor beide verzoeklimieten. Een bestand tussen 50 MB en 100 MiB kan worden geüpload, maar er kan niet naar worden verwezen in een modelverzoek. Een model of kanaal kan een lagere limiet toepassen.

### Bestandstypen

Het type wordt bepaald aan de hand van de inhoud van het bestand, niet aan de hand van de extensie of de `Content-Type` van het deel.

| Type | Formaten | Verwijzing mogelijk in |
|---|---|---|
| PDF | PDF | Messages, Responses |
| Afbeelding | PNG, JPEG, GIF, WebP | Messages, Responses, beeldgeneratie, videogeneratie |
| Video | MP4 | Videogeneratie |
| Audio | MP3, WAV, FLAC, OGG | Videogeneratie |
| Office | DOCX, XLSX, PPTX | Alleen opslag |
| Tekst | UTF-8-tekst, opgeslagen als `text/plain` | Alleen opslag |

Alle andere inhoud wordt geweigerd met `invalid_file`.

### Bestandsnamen

Een bestandsnaam mag geen `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\` of besturingstekens bevatten. `/` is toegestaan als scheidingsteken, maar lege segmenten, `.` en `..` zijn dat niet.

## Bestanden beheren

Bestanden horen bij je account. Elke API-sleutel van het account ziet dezelfde bestanden; andere accounts kunnen je bestands-ID's niet gebruiken.

### Bestanden opvragen

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

De resultaten zijn gesorteerd van oud naar nieuw. Als `has_more` `true` is, geef je de geretourneerde `cursor` door om de volgende pagina op te halen. Er is geen zoekfunctie of typefilter aan de serverkant.

### Eén bestand ophalen

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

### Een bestand verwijderen

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

Verwijderen gaat direct in en kan niet ongedaan worden gemaakt. Een `503` betekent dat het verwijderen niet is voltooid; stuur de `DELETE` opnieuw.

### Downloads

Geüploade bestanden kunnen niet worden gedownload. `GET /api/v1/files/{file_id}/content` retourneert `400 file_not_downloadable`, en de `Location`-header van de uploadrespons verwijst naar de metadata van het bestand, niet naar de bytes. Bewaar zelf een kopie van alles wat je uploadt.

Gebruik de ondertekende URL's in de `outputs` van de taak om gegenereerde media te downloaden.

## API-referentie

Alle endpoints gebruiken `Authorization: Bearer YOUR_API_KEY`. Geslaagde responsen zijn gewone JSON-objecten zonder envelop.

| Methode | Pad | Retourneert |
|---|---|---|
| `POST` | `/api/v1/files` | Het [bestandsobject](#bestandsobject) |
| `GET` | `/api/v1/files` | Een [pagina met bestanden](#lijstparameters) |
| `GET` | `/api/v1/files/{file_id}` | Het [bestandsobject](#bestandsobject) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`, `DELETE` en de `GET` voor één bestand weigeren elke queryparameter met `invalid_query`.

### Bestandsobject

| Veld | Type | Beschrijving |
|---|---|---|
| `id` | string | Bestands-ID met het voorvoegsel `felo_file_`. Gebruik het als `file_id` |
| `type` | string | Altijd `file` |
| `source` | string | `upload` voor bestanden die je hebt geüpload, `generated` voor modeluitvoer |
| `filename` | string | De naam die bij de upload is meegestuurd |
| `mime_type` | string | Type dat uit de inhoud is bepaald |
| `size_bytes` | integer | Grootte in bytes |
| `created_at` | string | UTC-tijdstempel in ISO 8601 |
| `downloadable` | boolean | `false` voor geüploade bestanden |

### Uploadverzoek

| Deel | Verplicht | Beschrijving |
|---|---|---|
| `file` | Ja | Het bestand, verzonden als `multipart/form-data`-bestandsdeel met een bestandsnaam |

De respons bevat een `Location`-header met de URL van de metadata van het bestand.

### Lijstparameters

| Parameter | Standaard | Beschrijving |
|---|---|---|
| `limit` | `100` | Paginagrootte, van 1 tot en met 1000 |
| `cursor` | | De `cursor`-waarde van de vorige pagina |
| `after`, `after_id` | | Aliassen van `cursor`. Stuur slechts één van de drie |
| `order` | `asc` | Alleen `asc` wordt ondersteund |

| Responsveld | Type | Beschrijving |
|---|---|---|
| `data` | array | Bestandsobjecten, oudste eerst |
| `first_id` | string of null | ID van het eerste bestand op de pagina |
| `last_id` | string of null | ID van het laatste bestand op de pagina |
| `cursor` | string of null | Waarde om als `cursor` door te geven voor de volgende pagina |
| `has_more` | boolean | Of er nog een pagina is |

## Fouten

De Files-endpoints, Responses en beeld- en videogeneratie gebruiken het OpenAI-foutformaat:

```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` is `null` bij fouten van de Files-endpoints. Messages retourneert het Anthropic-foutformaat, dat geen `error.code` heeft. De request-ID staat in de `X-Request-Id`-responsheader.

Fouten bij het uploaden of beheren van bestanden:

| HTTP | `error.code` | Betekenis |
|---|---|---|
| 400 | `invalid_content_type` | De body is geen `multipart/form-data` |
| 400 | `invalid_file` | Geen `file`-deel, een extra deel, een leeg bestand of niet-ondersteunde inhoud |
| 400 | `invalid_filename` | De bestandsnaam is te lang of bevat een niet-toegestaan teken |
| 413 | `file_too_large` | Het bestand is groter dan 100 MiB |
| 400 | `invalid_query` | Een niet-ondersteunde queryparameter, of een andere `order` dan `asc` |
| 400 | `invalid_limit` | `limit` ligt buiten 1 tot en met 1000 |
| 400 | `invalid_cursor` | De cursor is ongeldig opgemaakt, of er is meer dan één cursor gestuurd |
| 400 | `file_not_downloadable` | `/content` is opgevraagd |
| 404 | `file_not_found` | Het bestand bestaat niet, is verwijderd of hoort bij een ander account |
| 503 | `file_storage_unavailable` | Bestandsopslag is tijdelijk niet beschikbaar; probeer het later opnieuw |
| 503 | `file_upload_expired` | De upload is niet op tijd voltooid; upload het bestand opnieuw |

Fouten bij het verwijzen naar een bestand in een modelverzoek:

| HTTP | `error.code` | Betekenis |
|---|---|---|
| 400 | `invalid_file_input` | Ongeldig opgemaakt ID, zowel `file_id` als `url` in één locator, of meer dan 100 referenties |
| 400 | `unsupported_file_type` | Het bestandstype past niet bij de positie, bijvoorbeeld een MP4 in een documentblok |
| 400 | `file_model_unsupported` | Het model declareert de vereiste invoermodaliteit niet |
| 400 | `file_input_too_large` | De bestanden waarnaar wordt verwezen zijn samen groter dan 50,000,000 bytes |
| 400 | `file_protocol_unsupported` | Er is een bestands-ID naar Chat Completions gestuurd |
| 404 | `file_not_found` | Het bestand ontbreekt, is verwijderd, is van een ander account, of is een gegenereerd bestand dat naar beeld- of videogeneratie is gestuurd |

Bij beeld- en videogeneratie kan een bestand ook na de `202` mislukken. De taak eindigt dan als `failed` met een van deze codes in `error.code`.

Authenticatie-, saldo- en rate-limit-fouten worden beschreven in [Fouten, limieten en nieuwe pogingen](https://openapi.felo.ai/nl/docs/guides/errors-and-limits.md).

## Gerelateerd

- [Protocollen en SDK's](https://openapi.felo.ai/nl/docs/guides/protocols.md)
- [Beeldgeneratie](https://openapi.felo.ai/nl/docs/guides/image-generation.md)
- [Asynchrone taken](https://openapi.felo.ai/nl/docs/guides/async-tasks.md)
- [Model API-verwijzing](https://openapi.felo.ai/nl/docs/model-api)
