# Datei-Uploads

Laden Sie eine Datei einmal hoch und verweisen Sie in Messages-, Responses-, Bild- und Videogenerierungsanfragen per ID darauf.

Laden Sie eine Datei einmal hoch und verweisen Sie dann in Modellanfragen per ID darauf. Das ersetzt das erneute Senden derselben Bytes als Base64 oder das Hosten der Datei unter einer öffentlichen URL.

Eine Datei-ID funktioniert mit Messages, Responses, der Bildgenerierung und der Videogenerierung. Mit Chat Completions funktioniert sie nicht.

## Bevor Sie beginnen

- Einen API-Schlüssel. Siehe [Authentifizierung](https://openapi.felo.ai/de/docs/authentication.md).
- Die Base-URL `https://openapi.felo.ai`.
- Ein Modell, das den Dateityp akzeptiert, den Sie senden möchten. Siehe [Modellunterstützung prüfen](#modellunterst-tzung-pr-fen).

## Schnellstart

### 1. Datei hochladen

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

Ein erfolgreicher Upload gibt HTTP `200` mit den Metadaten der Datei zurück:

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

Speichern Sie `id`. Behandeln Sie den Wert als opaken String: Setzen Sie ihn nicht selbst zusammen und parsen Sie ihn nicht.

### 2. In einer Anfrage darauf verweisen

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

Dieselben zwei Schritte 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())
```

Und in Node.js 20 oder höher:

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

### Upload-Regeln

- Der Body ist `multipart/form-data` mit genau einem Teil namens `file`. Jeder weitere Teil, auch `purpose`, wird mit `invalid_file` abgelehnt.
- Überlassen Sie das Setzen von `Content-Type` Ihrem HTTP-Client. Wenn Sie den Header von Hand setzen, geht die Multipart-Boundary verloren.
- Hängen Sie keine Query-Parameter an die Upload-URL an.
- Laden Sie per HTTP hoch statt über den Files-Helper eines SDK. `files.create()` des OpenAI SDK sendet immer `purpose` und kann diesen Endpoint daher nicht aufrufen.
- Ein Upload, der in ein Timeout läuft oder dessen Verbindung abbricht, wurde möglicherweise trotzdem gespeichert. Listen Sie Ihre Dateien auf, bevor Sie erneut hochladen.

## Wo eine Datei-ID verwendet werden kann

| Endpoint | Dateitypen | Erforderliche Eingabemodalität | Feld |
|---|---|---|---|
| `POST /api/v1/messages` | PDF, Bild | `file`, `image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF, Bild | `file`, `image` | `input[].content[]` |
| `POST /api/v1/images/generations` | Bild | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | Bild | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | Bild, MP4, Audio | `image`, `video`, `audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | Nicht unterstützt | | |

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

Für ein Bild verwenden Sie `{"type": "image", "source": {"type": "file", "file_id": "..."}}`.

### Responses

| Datei | Inhaltsblock |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| Bild | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

Ein Block, der `file_id` enthält, darf nicht zusätzlich eine URL oder Base64-Daten enthalten.

### Bildgenerierung

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

Der Rest der Anfrage, die `202`-Antwort und das Abfragen werden unter [Bildgenerierung](https://openapi.felo.ai/de/docs/guides/image-generation.md) beschrieben.

### Videogenerierung

Erster und letzter Frame gehören 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..."}
    }
  ]
}
```

Fügen Sie für einen Endframe einen zweiten Eintrag mit `"frame_type": "last_frame"` hinzu. Ein letzter Frame setzt einen ersten Frame voraus.

Referenzmaterial gehört in `input_references`. Jeder Eintrag verwendet den Locator, der zu seinem Medientyp passt:

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

Welche Kombinationen ein Modell akzeptiert, hängt von Modell und Kanal ab. `frame_images` und `input_references` können nicht in derselben Anfrage verwendet werden.

### Locator-Regeln

- In Bild- und Videoanfragen enthält jedes `image_url`-, `video_url`- oder `audio_url`-Objekt genau eines der Felder `file_id` oder `url` und kein weiteres Feld.
- Ein Array kann Einträge mit `file_id` und Einträge mit `url` mischen.
- Bild- und Videogenerierung akzeptieren nur Dateien, die Sie hochgeladen haben. Um ein generiertes Bild wiederzuverwenden, übergeben Sie dessen Ausgabe-`url`.
- Eine Anfrage, die auf eine Datei verweist, wird bei einem Fehler nicht auf einen anderen Kanal verschoben. Wiederholen Sie sie nicht auf einem anderen Kanal, ohne den Fehler zu prüfen.
- Behalten Sie eine Datei, bis jede Aufgabe, die auf sie verweist, einen Endzustand erreicht hat. Wenn Sie sie früher löschen, kann die Aufgabe fehlschlagen.

## Modellunterstützung prüfen

Eine gespeicherte Datei ist nicht automatisch mit jedem Modell nutzbar. Das Modell muss die passende Eingabemodalität im öffentlichen Katalog deklarieren:

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

| Was Sie senden | `input_modalities` muss enthalten |
|---|---|
| Ein PDF | `file` |
| Ein Bild | `image` |
| Ein MP4 | `video` |
| Eine Audiodatei | `audio` |

Eine leere oder fehlende Liste bedeutet, dass Datei-IDs für dieses Modell nicht aktiviert sind. Die Anfrage schlägt dann mit `file_model_unsupported` fehl. Leiten Sie die Unterstützung nicht aus dem Modellnamen ab.

## Limits

| Limit | Wert |
|---|---|
| Upload-Größe | 100 MiB (104,857,600 Bytes) pro Datei; leere Dateien werden abgelehnt |
| Referenzierte Bytes pro Modellanfrage | Insgesamt 50,000,000 Bytes |
| Referenzen pro Modellanfrage | 100 |
| Länge des Dateinamens | 255 Zeichen |

Wird dieselbe Datei zweimal referenziert, zählt sie für beide Anfragelimits doppelt. Eine Datei zwischen 50 MB und 100 MiB kann hochgeladen, aber nicht in einer Modellanfrage referenziert werden. Ein Modell oder Kanal kann ein niedrigeres Limit anwenden.

### Dateitypen

Der Typ wird anhand des Dateiinhalts erkannt, nicht anhand der Dateiendung oder des `Content-Type` des Teils.

| Typ | Formate | Referenzierbar in |
|---|---|---|
| PDF | PDF | Messages, Responses |
| Bild | PNG, JPEG, GIF, WebP | Messages, Responses, Bildgenerierung, Videogenerierung |
| Video | MP4 | Videogenerierung |
| Audio | MP3, WAV, FLAC, OGG | Videogenerierung |
| Office | DOCX, XLSX, PPTX | Nur Speicherung |
| Text | UTF-8-Text, gespeichert als `text/plain` | Nur Speicherung |

Jeder andere Inhalt wird mit `invalid_file` abgelehnt.

### Dateinamen

Ein Dateiname darf weder `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\` noch Steuerzeichen enthalten. `/` ist als Trennzeichen erlaubt, leere Segmente, `.` und `..` sind es nicht.

## Dateien verwalten

Dateien gehören zu Ihrem Konto. Jeder API-Schlüssel des Kontos sieht dieselben Dateien; andere Konten können Ihre Datei-IDs nicht verwenden.

### Dateien auflisten

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

Die Ergebnisse sind von alt nach neu sortiert. Wenn `has_more` den Wert `true` hat, übergeben Sie den zurückgegebenen `cursor`, um die nächste Seite abzurufen. Es gibt weder eine serverseitige Suche noch einen Typfilter.

### Eine Datei abrufen

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

### Eine Datei löschen

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

Das Löschen wird sofort wirksam und kann nicht rückgängig gemacht werden. Ein `503` bedeutet, dass das Löschen nicht abgeschlossen wurde; senden Sie das `DELETE` erneut.

### Downloads

Hochgeladene Dateien können nicht heruntergeladen werden. `GET /api/v1/files/{file_id}/content` gibt `400 file_not_downloadable` zurück, und der `Location`-Header der Upload-Antwort verweist auf die Metadaten der Datei, nicht auf ihre Bytes. Bewahren Sie von allem, was Sie hochladen, eine eigene Kopie auf.

Um generierte Medien herunterzuladen, verwenden Sie die signierten URLs in den `outputs` der Aufgabe.

## API-Referenz

Alle Endpoints verwenden `Authorization: Bearer YOUR_API_KEY`. Erfolgreiche Antworten sind einfache JSON-Objekte ohne Umschlag.

| Methode | Pfad | Rückgabe |
|---|---|---|
| `POST` | `/api/v1/files` | Das [Dateiobjekt](#dateiobjekt) |
| `GET` | `/api/v1/files` | Eine [Seite mit Dateien](#listenparameter) |
| `GET` | `/api/v1/files/{file_id}` | Das [Dateiobjekt](#dateiobjekt) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`, `DELETE` und das `GET` für eine einzelne Datei lehnen jeden Query-Parameter mit `invalid_query` ab.

### Dateiobjekt

| Feld | Typ | Beschreibung |
|---|---|---|
| `id` | string | Datei-ID mit dem Präfix `felo_file_`. Verwenden Sie sie als `file_id` |
| `type` | string | Immer `file` |
| `source` | string | `upload` für Dateien, die Sie hochgeladen haben, `generated` für Modellausgaben |
| `filename` | string | Der beim Upload gesendete Name |
| `mime_type` | string | Anhand des Inhalts erkannter Typ |
| `size_bytes` | integer | Größe in Bytes |
| `created_at` | string | UTC-Zeitstempel nach ISO 8601 |
| `downloadable` | boolean | `false` für hochgeladene Dateien |

### Upload-Anfrage

| Teil | Erforderlich | Beschreibung |
|---|---|---|
| `file` | Ja | Die Datei, gesendet als `multipart/form-data`-Dateiteil mit einem Dateinamen |

Die Antwort enthält einen `Location`-Header mit der URL der Metadaten der Datei.

### Listenparameter

| Parameter | Standard | Beschreibung |
|---|---|---|
| `limit` | `100` | Seitengröße, von 1 bis 1000 |
| `cursor` | | Der `cursor`-Wert der vorherigen Seite |
| `after`, `after_id` | | Aliasse für `cursor`. Senden Sie nur einen der drei |
| `order` | `asc` | Nur `asc` wird unterstützt |

| Antwortfeld | Typ | Beschreibung |
|---|---|---|
| `data` | array | Dateiobjekte, älteste zuerst |
| `first_id` | string oder null | ID der ersten Datei auf der Seite |
| `last_id` | string oder null | ID der letzten Datei auf der Seite |
| `cursor` | string oder null | Wert, der für die nächste Seite als `cursor` übergeben wird |
| `has_more` | boolean | Ob eine weitere Seite existiert |

## Fehler

Die Files-Endpoints, Responses sowie die Bild- und Videogenerierung verwenden das OpenAI-Fehlerformat:

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

Bei Fehlern der Files-Endpoints ist `param` gleich `null`. Messages gibt das Anthropic-Fehlerformat zurück, das kein `error.code` enthält. Die Request-ID steht im Antwort-Header `X-Request-Id`.

Fehler beim Hochladen oder Verwalten von Dateien:

| HTTP | `error.code` | Bedeutung |
|---|---|---|
| 400 | `invalid_content_type` | Der Body ist nicht `multipart/form-data` |
| 400 | `invalid_file` | Kein `file`-Teil, ein zusätzlicher Teil, eine leere Datei oder nicht unterstützter Inhalt |
| 400 | `invalid_filename` | Der Dateiname ist zu lang oder enthält ein unzulässiges Zeichen |
| 413 | `file_too_large` | Die Datei überschreitet 100 MiB |
| 400 | `invalid_query` | Ein nicht unterstützter Query-Parameter oder ein anderer `order`-Wert als `asc` |
| 400 | `invalid_limit` | `limit` liegt außerhalb von 1 bis 1000 |
| 400 | `invalid_cursor` | Der Cursor ist fehlerhaft formatiert, oder es wurde mehr als ein Cursor gesendet |
| 400 | `file_not_downloadable` | `/content` wurde angefragt |
| 404 | `file_not_found` | Die Datei existiert nicht, wurde gelöscht oder gehört zu einem anderen Konto |
| 503 | `file_storage_unavailable` | Der Dateispeicher ist vorübergehend nicht verfügbar; versuchen Sie es später erneut |
| 503 | `file_upload_expired` | Der Upload wurde nicht rechtzeitig abgeschlossen; laden Sie die Datei erneut hoch |

Fehler beim Referenzieren einer Datei in einer Modellanfrage:

| HTTP | `error.code` | Bedeutung |
|---|---|---|
| 400 | `invalid_file_input` | Fehlerhaft formatierte ID, sowohl `file_id` als auch `url` in einem Locator oder mehr als 100 Referenzen |
| 400 | `unsupported_file_type` | Der Dateityp passt nicht zur Position, zum Beispiel ein MP4 in einem Dokumentblock |
| 400 | `file_model_unsupported` | Das Modell deklariert die erforderliche Eingabemodalität nicht |
| 400 | `file_input_too_large` | Die referenzierten Dateien überschreiten insgesamt 50,000,000 Bytes |
| 400 | `file_protocol_unsupported` | Eine Datei-ID wurde an Chat Completions gesendet |
| 404 | `file_not_found` | Die Datei fehlt, wurde gelöscht, gehört einem anderen Konto oder ist eine generierte Datei, die an die Bild- oder Videogenerierung gesendet wurde |

Bei der Bild- und Videogenerierung kann eine Datei auch nach dem `202` fehlschlagen. Die Aufgabe endet dann als `failed` mit einem dieser Codes in `error.code`.

Authentifizierungs-, Guthaben- und Rate-Limit-Fehler werden unter [Fehler, Limits und Wiederholungen](https://openapi.felo.ai/de/docs/guides/errors-and-limits.md) beschrieben.

## Verwandte Themen

- [Protokolle und SDKs](https://openapi.felo.ai/de/docs/guides/protocols.md)
- [Bildgenerierung](https://openapi.felo.ai/de/docs/guides/image-generation.md)
- [Asynchrone Aufgaben](https://openapi.felo.ai/de/docs/guides/async-tasks.md)
- [Model API-Referenz](https://openapi.felo.ai/de/docs/model-api)
