Felo API PlatformFelo API Platform

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

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

EndpointDateitypenErforderliche EingabemodalitätFeld
POST /api/v1/messagesPDF, Bildfile, imagemessages[].content[]
POST /api/v1/responsesPDF, Bildfile, imageinput[].content[]
POST /api/v1/images/generationsBildimageinput_references[]
POST /api/v1/videos/generationsBildimageframe_images[]
POST /api/v1/videos/generationsBild, MP4, Audioimage, video, audioinput_references[]
POST /api/v1/chat/completionsNicht 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

DateiInhaltsblock
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

{
  "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- 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:

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 sendeninput_modalities muss enthalten
Ein PDFfile
Ein Bildimage
Ein MP4video
Eine Audiodateiaudio

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

LimitWert
Upload-Größe100 MiB (104,857,600 Bytes) pro Datei; leere Dateien werden abgelehnt
Referenzierte Bytes pro ModellanfrageInsgesamt 50,000,000 Bytes
Referenzen pro Modellanfrage100
Länge des Dateinamens255 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.

TypFormateReferenzierbar in
PDFPDFMessages, Responses
BildPNG, JPEG, GIF, WebPMessages, Responses, Bildgenerierung, Videogenerierung
VideoMP4Videogenerierung
AudioMP3, WAV, FLAC, OGGVideogenerierung
OfficeDOCX, XLSX, PPTXNur Speicherung
TextUTF-8-Text, gespeichert als text/plainNur 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.

MethodePfadRückgabe
POST/api/v1/filesDas Dateiobjekt
GET/api/v1/filesEine 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}/content400 file_not_downloadable

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

Dateiobjekt

FeldTypBeschreibung
idstringDatei-ID mit dem Präfix felo_file_. Verwenden Sie sie als file_id
typestringImmer file
sourcestringupload für Dateien, die Sie hochgeladen haben, generated für Modellausgaben
filenamestringDer beim Upload gesendete Name
mime_typestringAnhand des Inhalts erkannter Typ
size_bytesintegerGröße in Bytes
created_atstringUTC-Zeitstempel nach ISO 8601
downloadablebooleanfalse für hochgeladene Dateien

Upload-Anfrage

TeilErforderlichBeschreibung
fileJaDie 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

ParameterStandardBeschreibung
limit100Seitengröße, von 1 bis 1000
cursorDer cursor-Wert der vorherigen Seite
after, after_idAliasse für cursor. Senden Sie nur einen der drei
orderascNur asc wird unterstützt
AntwortfeldTypBeschreibung
dataarrayDateiobjekte, älteste zuerst
first_idstring oder nullID der ersten Datei auf der Seite
last_idstring oder nullID der letzten Datei auf der Seite
cursorstring oder nullWert, der für die nächste Seite als cursor übergeben wird
has_morebooleanOb 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:

HTTPerror.codeBedeutung
400invalid_content_typeDer Body ist nicht multipart/form-data
400invalid_fileKein file-Teil, ein zusätzlicher Teil, eine leere Datei oder nicht unterstützter Inhalt
400invalid_filenameDer Dateiname ist zu lang oder enthält ein unzulässiges Zeichen
413file_too_largeDie Datei überschreitet 100 MiB
400invalid_queryEin nicht unterstützter Query-Parameter oder ein anderer order-Wert als asc
400invalid_limitlimit liegt außerhalb von 1 bis 1000
400invalid_cursorDer Cursor ist fehlerhaft formatiert, oder es wurde mehr als ein Cursor gesendet
400file_not_downloadable/content wurde angefragt
404file_not_foundDie Datei existiert nicht, wurde gelöscht oder gehört zu einem anderen Konto
503file_storage_unavailableDer Dateispeicher ist vorübergehend nicht verfügbar; versuchen Sie es später erneut
503file_upload_expiredDer Upload wurde nicht rechtzeitig abgeschlossen; laden Sie die Datei erneut hoch

Fehler beim Referenzieren einer Datei in einer Modellanfrage:

HTTPerror.codeBedeutung
400invalid_file_inputFehlerhaft formatierte ID, sowohl file_id als auch url in einem Locator oder mehr als 100 Referenzen
400unsupported_file_typeDer Dateityp passt nicht zur Position, zum Beispiel ein MP4 in einem Dokumentblock
400file_model_unsupportedDas Modell deklariert die erforderliche Eingabemodalität nicht
400file_input_too_largeDie referenzierten Dateien überschreiten insgesamt 50,000,000 Bytes
400file_protocol_unsupportedEine Datei-ID wurde an Chat Completions gesendet
404file_not_foundDie 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?