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
- Een API-sleutel. Zie Authenticatie.
- De base-URL
https://openapi.felo.ai. - Een model dat het bestandstype accepteert dat je wilt verzenden. Zie Modelondersteuning controleren.
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-datamet precies één deel, met de naamfile. Elk ander deel, ookpurpose, wordt geweigerd metinvalid_file. - Laat je HTTP-client
Content-Typeinstellen. 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 altijdpurposemee 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
{
"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 |
|---|---|
{"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- ofaudio_url-object precies één vanfile_idofurl, en geen ander veld. - Eén array kan vermeldingen met
file_iden vermeldingen meturlcombineren. - Beeld- en videogeneratie accepteren alleen bestanden die je zelf hebt geüpload. Geef de uitvoer-
urlvan 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 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 |
|---|---|---|
| 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
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.
| Methode | Pad | Retourneert |
|---|---|---|
POST | /api/v1/files | Het bestandsobject |
GET | /api/v1/files | Een 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}/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:
{
"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.
Gerelateerd
Hulp nodig?
- Neem voor vragen over API, facturering en account contact op met support.
- Praat met Felo-ontwikkelaars op Discord.
- Bekijk ons wijzigingslogboek.
- Hulp nodig bij volumeprijzen of inkoop? Neem contact op met sales.
- Bouw je met een LLM? Lees llms.txt.