Leitfäden
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.
- Die Base-URL
https://openapi.felo.ai. - Ein Modell, das den Dateityp akzeptiert, den Sie senden möchten. Siehe Modellunterstützung prüfen.
Schnellstart
1. Datei hochladen
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:
{
"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
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:
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:
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-datamit genau einem Teil namensfile. Jeder weitere Teil, auchpurpose, wird mitinvalid_fileabgelehnt. - Überlassen Sie das Setzen von
Content-TypeIhrem 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 immerpurposeund 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
{
"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 |
|---|---|
{"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
{
"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 beschrieben.
Videogenerierung
Erster und letzter Frame gehören in 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..."}
}
]
}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:
{
"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- oderaudio_url-Objekt genau eines der Felderfile_idoderurlund kein weiteres Feld. - Ein Array kann Einträge mit
file_idund Einträge miturlmischen. - 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:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["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 |
|---|---|---|
| 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
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
}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
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Eine Datei löschen
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"}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 |
GET | /api/v1/files | Eine Seite mit Dateien |
GET | /api/v1/files/{file_id} | Das 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:
{
"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 beschrieben.
Verwandte Themen
Brauchst du Hilfe?
- Bei Fragen zu API, Abrechnung und Konto wende dich an den Support.
- Sprich mit Felo-Entwicklern auf Discord.
- Sieh dir unser Änderungsprotokoll an.
- Brauchst du Mengenpreise oder Hilfe beim Einkauf? Vertrieb kontaktieren.
- Du baust mit einem LLM? Lies llms.txt.