Felo API PlatformFelo API Platform

Handleidingen

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

Snelstart

1. Het bestand uploaden

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:

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

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:

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:

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

EndpointBestandstypenVereiste invoermodaliteitVeld
POST /api/v1/messagesPDF, afbeeldingfile, imagemessages[].content[]
POST /api/v1/responsesPDF, afbeeldingfile, imageinput[].content[]
POST /api/v1/images/generationsAfbeeldingimageinput_references[]
POST /api/v1/videos/generationsAfbeeldingimageframe_images[]
POST /api/v1/videos/generationsAfbeelding, MP4, audioimage, video, audioinput_references[]
POST /api/v1/chat/completionsNiet ondersteund

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

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

Responses

BestandContentblok
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

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

Videogeneratie

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

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:

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

curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
["text", "image", "file"]
Wat je verzendtinput_modalities moet bevatten
Een PDFfile
Een afbeeldingimage
Een MP4video
Een audiobestandaudio

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

LimietWaarde
Uploadgrootte100 MiB (104,857,600 bytes) per bestand; lege bestanden worden geweigerd
Bytes waarnaar wordt verwezen per modelverzoek50,000,000 bytes in totaal
Referenties per modelverzoek100
Lengte van de bestandsnaam255 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.

TypeFormatenVerwijzing mogelijk in
PDFPDFMessages, Responses
AfbeeldingPNG, JPEG, GIF, WebPMessages, Responses, beeldgeneratie, videogeneratie
VideoMP4Videogeneratie
AudioMP3, WAV, FLAC, OGGVideogeneratie
OfficeDOCX, XLSX, PPTXAlleen opslag
TekstUTF-8-tekst, opgeslagen als text/plainAlleen 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

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
}

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

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

Een bestand verwijderen

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

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.

MethodePadRetourneert
POST/api/v1/filesHet bestandsobject
GET/api/v1/filesEen pagina met bestanden
GET/api/v1/files/{file_id}Het bestandsobject
DELETE/api/v1/files/{file_id}{"id": "...", "type": "file_deleted"}
GET/api/v1/files/{file_id}/content400 file_not_downloadable

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

Bestandsobject

VeldTypeBeschrijving
idstringBestands-ID met het voorvoegsel felo_file_. Gebruik het als file_id
typestringAltijd file
sourcestringupload voor bestanden die je hebt geüpload, generated voor modeluitvoer
filenamestringDe naam die bij de upload is meegestuurd
mime_typestringType dat uit de inhoud is bepaald
size_bytesintegerGrootte in bytes
created_atstringUTC-tijdstempel in ISO 8601
downloadablebooleanfalse voor geüploade bestanden

Uploadverzoek

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

ParameterStandaardBeschrijving
limit100Paginagrootte, van 1 tot en met 1000
cursorDe cursor-waarde van de vorige pagina
after, after_idAliassen van cursor. Stuur slechts één van de drie
orderascAlleen asc wordt ondersteund
ResponsveldTypeBeschrijving
dataarrayBestandsobjecten, oudste eerst
first_idstring of nullID van het eerste bestand op de pagina
last_idstring of nullID van het laatste bestand op de pagina
cursorstring of nullWaarde om als cursor door te geven voor de volgende pagina
has_morebooleanOf er nog een pagina is

Fouten

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

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

HTTPerror.codeBetekenis
400invalid_content_typeDe body is geen multipart/form-data
400invalid_fileGeen file-deel, een extra deel, een leeg bestand of niet-ondersteunde inhoud
400invalid_filenameDe bestandsnaam is te lang of bevat een niet-toegestaan teken
413file_too_largeHet bestand is groter dan 100 MiB
400invalid_queryEen niet-ondersteunde queryparameter, of een andere order dan asc
400invalid_limitlimit ligt buiten 1 tot en met 1000
400invalid_cursorDe cursor is ongeldig opgemaakt, of er is meer dan één cursor gestuurd
400file_not_downloadable/content is opgevraagd
404file_not_foundHet bestand bestaat niet, is verwijderd of hoort bij een ander account
503file_storage_unavailableBestandsopslag is tijdelijk niet beschikbaar; probeer het later opnieuw
503file_upload_expiredDe upload is niet op tijd voltooid; upload het bestand opnieuw

Fouten bij het verwijzen naar een bestand in een modelverzoek:

HTTPerror.codeBetekenis
400invalid_file_inputOngeldig opgemaakt ID, zowel file_id als url in één locator, of meer dan 100 referenties
400unsupported_file_typeHet bestandstype past niet bij de positie, bijvoorbeeld een MP4 in een documentblok
400file_model_unsupportedHet model declareert de vereiste invoermodaliteit niet
400file_input_too_largeDe bestanden waarnaar wordt verwezen zijn samen groter dan 50,000,000 bytes
400file_protocol_unsupportedEr is een bestands-ID naar Chat Completions gestuurd
404file_not_foundHet 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.

Gerelateerd

Hulp nodig?