Guides
File Uploads
Upload a file once, then reference it by ID in Messages, Responses, image generation, and video generation requests.
Upload a file once, then reference it by ID in model requests. This replaces resending the same bytes as base64 or hosting the file at a public URL.
A file ID works with Messages, Responses, image generation, and video generation. It does not work with Chat Completions.
Before you start
- An API key. See Authentication.
- The base URL
https://openapi.felo.ai. - A model that accepts the file type you plan to send. See Check model support.
Quick start
1. Upload the file
curl "https://openapi.felo.ai/api/v1/files" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-F "file=@./report.pdf"A successful upload returns HTTP 200 with the file's metadata:
{
"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
}Store id. Treat it as an opaque string: do not build or parse it.
2. Reference it in a request
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."}
]
}
]
}'The same two steps 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())And in Node.js 20 or later:
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 rules
- The body is
multipart/form-datawith exactly one part, namedfile. Any other part, includingpurpose, is rejected withinvalid_file. - Let your HTTP client set
Content-Type. Setting it by hand drops the multipart boundary. - Do not append query parameters to the upload URL.
- Upload over HTTP instead of an SDK's Files helper. The OpenAI SDK's
files.create()always sendspurpose, so it cannot call this endpoint. - An upload that times out or disconnects may still have been stored. List your files before uploading again.
Where a file ID can go
| Endpoint | File types | Required input modality | Field |
|---|---|---|---|
POST /api/v1/messages | PDF, image | file, image | messages[].content[] |
POST /api/v1/responses | PDF, image | file, image | input[].content[] |
POST /api/v1/images/generations | Image | image | input_references[] |
POST /api/v1/videos/generations | Image | image | frame_images[] |
POST /api/v1/videos/generations | Image, MP4, audio | image, video, audio | input_references[] |
POST /api/v1/chat/completions | Not supported |
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."}
]
}
]
}For an image, use {"type": "image", "source": {"type": "file", "file_id": "..."}}.
Responses
| File | Content block |
|---|---|
{"type": "input_file", "file_id": "..."} | |
| Image | {"type": "input_image", "file_id": "...", "detail": "auto"} |
A block that carries file_id must not also carry a URL or base64 data.
Image generation
{
"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..."}}
]
}The rest of the request, the 202 response, and polling are described in Image Generation.
Video generation
First and last frames go 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..."}
}
]
}Add a second entry with "frame_type": "last_frame" for an end frame. A last frame requires a first frame.
Reference material goes in input_references. Each entry uses the locator that matches its media type:
{
"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"}}
]
}Which combinations a model accepts depends on the model and channel. frame_images and input_references cannot be used in the same request.
Locator rules
- In image and video requests, each
image_url,video_url, oraudio_urlobject holds exactly one offile_idorurl, and no other field. - One array can mix entries that use
file_idwith entries that useurl. - Image and video generation accept only files you uploaded. To reuse a generated image, pass its output
url. - A request that references a file is not moved to another channel on failure. Do not retry it on a different channel without checking the error.
- Keep a file until every task that references it reaches a terminal state. Deleting it earlier can fail the task.
Check model support
A stored file is not automatically usable with every model. The model must declare the matching input modality in the public catalog:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| To send | input_modalities must include |
|---|---|
| A PDF | file |
| An image | image |
| An MP4 | video |
| An audio file | audio |
An empty or missing list means file IDs are not enabled for that model. The request then fails with file_model_unsupported. Do not infer support from the model name.
Limits
| Limit | Value |
|---|---|
| Upload size | 100 MiB (104,857,600 bytes) per file; empty files are rejected |
| Referenced bytes per model request | 50,000,000 bytes in total |
| References per model request | 100 |
| Filename length | 255 characters |
Referencing the same file twice counts twice toward both request limits. A file between 50 MB and 100 MiB can be uploaded but cannot be referenced in a model request. A model or channel can apply a lower limit.
File types
The type is detected from the file's content, not from its extension or the Content-Type of the part.
| Type | Formats | Can be referenced in |
|---|---|---|
| Messages, Responses | ||
| Image | PNG, JPEG, GIF, WebP | Messages, Responses, image generation, video generation |
| Video | MP4 | Video generation |
| Audio | MP3, WAV, FLAC, OGG | Video generation |
| Office | DOCX, XLSX, PPTX | Storage only |
| Text | UTF-8 text, stored as text/plain | Storage only |
Any other content is rejected with invalid_file.
Filenames
A filename cannot contain <, >, :, ", |, ?, *, \, or control characters. / is allowed as a separator, but empty segments, ., and .. are not.
Manage files
Files belong to your account. Every API key on the account sees the same files; other accounts cannot use your file IDs.
List files
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
}Results are ordered oldest first. When has_more is true, pass the returned cursor to get the next page. There is no server-side search or type filter.
Get one file
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Delete a file
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"}Deletion takes effect immediately and cannot be undone. A 503 means the deletion did not complete; send the DELETE again.
Downloads
Uploaded files cannot be downloaded. GET /api/v1/files/{file_id}/content returns 400 file_not_downloadable, and the Location header of the upload response points to the file's metadata, not its bytes. Keep your own copy of anything you upload.
To download generated media, use the signed URLs in the task's outputs.
API reference
All endpoints use Authorization: Bearer YOUR_API_KEY. Successful responses are plain JSON objects with no envelope.
| Method | Path | Returns |
|---|---|---|
POST | /api/v1/files | The file object |
GET | /api/v1/files | A page of files |
GET | /api/v1/files/{file_id} | The file object |
DELETE | /api/v1/files/{file_id} | {"id": "...", "type": "file_deleted"} |
GET | /api/v1/files/{file_id}/content | 400 file_not_downloadable |
POST, DELETE, and the single-file GET reject any query parameter with invalid_query.
File object
| Field | Type | Description |
|---|---|---|
id | string | File ID, prefixed felo_file_. Use it as file_id |
type | string | Always file |
source | string | upload for files you uploaded, generated for model outputs |
filename | string | The name sent with the upload |
mime_type | string | Type detected from the content |
size_bytes | integer | Size in bytes |
created_at | string | ISO 8601 UTC timestamp |
downloadable | boolean | false for uploaded files |
Upload request
| Part | Required | Description |
|---|---|---|
file | Yes | The file, sent as a multipart/form-data file part with a filename |
The response includes a Location header with the URL of the file's metadata.
List parameters
| Parameter | Default | Description |
|---|---|---|
limit | 100 | Page size, from 1 to 1000 |
cursor | The cursor value from the previous page | |
after, after_id | Aliases of cursor. Send only one of the three | |
order | asc | Only asc is supported |
| Response field | Type | Description |
|---|---|---|
data | array | File objects, oldest first |
first_id | string or null | ID of the first file on the page |
last_id | string or null | ID of the last file on the page |
cursor | string or null | Value to pass as cursor for the next page |
has_more | boolean | Whether another page exists |
Errors
The Files endpoints, Responses, and image and video generation use the OpenAI error envelope:
{
"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 for errors from the Files endpoints. Messages returns the Anthropic error shape, which has no error.code. The request ID is in the X-Request-Id response header.
Errors when uploading or managing files:
| HTTP | error.code | Meaning |
|---|---|---|
| 400 | invalid_content_type | The body is not multipart/form-data |
| 400 | invalid_file | No file part, an extra part, an empty file, or unsupported content |
| 400 | invalid_filename | The filename is too long or contains a rejected character |
| 413 | file_too_large | The file exceeds 100 MiB |
| 400 | invalid_query | An unsupported query parameter, or order other than asc |
| 400 | invalid_limit | limit is outside 1 to 1000 |
| 400 | invalid_cursor | The cursor is malformed, or more than one cursor was sent |
| 400 | file_not_downloadable | /content was requested |
| 404 | file_not_found | The file does not exist, was deleted, or belongs to another account |
| 503 | file_storage_unavailable | File storage is temporarily unavailable; retry later |
| 503 | file_upload_expired | The upload did not complete in time; upload the file again |
Errors when referencing a file in a model request:
| HTTP | error.code | Meaning |
|---|---|---|
| 400 | invalid_file_input | Malformed ID, both file_id and url in one locator, or more than 100 references |
| 400 | unsupported_file_type | The file's type does not match the position, for example an MP4 in a document block |
| 400 | file_model_unsupported | The model does not declare the required input modality |
| 400 | file_input_too_large | The referenced files exceed 50,000,000 bytes in total |
| 400 | file_protocol_unsupported | A file ID was sent to Chat Completions |
| 404 | file_not_found | The file is missing, deleted, owned by another account, or is a generated file sent to image or video generation |
For image and video generation, a file can also fail after the 202. The task then ends as failed with one of these codes in error.code.
Authentication, balance, and rate-limit errors are described in Errors, Limits, and Retries.
Related
Need help?
- Contact Support for API, billing, and account questions.
- Chat with Felo developers on Discord.
- Check out our changelog.
- Need volume pricing or procurement help? Contact Sales.
- Building with an LLM? Read llms.txt.