Felo API PlatformFelo API Platform

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

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-data with exactly one part, named file. Any other part, including purpose, is rejected with invalid_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 sends purpose, 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

EndpointFile typesRequired input modalityField
POST /api/v1/messagesPDF, imagefile, imagemessages[].content[]
POST /api/v1/responsesPDF, imagefile, imageinput[].content[]
POST /api/v1/images/generationsImageimageinput_references[]
POST /api/v1/videos/generationsImageimageframe_images[]
POST /api/v1/videos/generationsImage, MP4, audioimage, video, audioinput_references[]
POST /api/v1/chat/completionsNot 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

FileContent block
PDF{"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, or audio_url object holds exactly one of file_id or url, and no other field.
  • One array can mix entries that use file_id with entries that use url.
  • 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 sendinput_modalities must include
A PDFfile
An imageimage
An MP4video
An audio fileaudio

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

LimitValue
Upload size100 MiB (104,857,600 bytes) per file; empty files are rejected
Referenced bytes per model request50,000,000 bytes in total
References per model request100
Filename length255 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.

TypeFormatsCan be referenced in
PDFPDFMessages, Responses
ImagePNG, JPEG, GIF, WebPMessages, Responses, image generation, video generation
VideoMP4Video generation
AudioMP3, WAV, FLAC, OGGVideo generation
OfficeDOCX, XLSX, PPTXStorage only
TextUTF-8 text, stored as text/plainStorage 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.

MethodPathReturns
POST/api/v1/filesThe file object
GET/api/v1/filesA 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}/content400 file_not_downloadable

POST, DELETE, and the single-file GET reject any query parameter with invalid_query.

File object

FieldTypeDescription
idstringFile ID, prefixed felo_file_. Use it as file_id
typestringAlways file
sourcestringupload for files you uploaded, generated for model outputs
filenamestringThe name sent with the upload
mime_typestringType detected from the content
size_bytesintegerSize in bytes
created_atstringISO 8601 UTC timestamp
downloadablebooleanfalse for uploaded files

Upload request

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

ParameterDefaultDescription
limit100Page size, from 1 to 1000
cursorThe cursor value from the previous page
after, after_idAliases of cursor. Send only one of the three
orderascOnly asc is supported
Response fieldTypeDescription
dataarrayFile objects, oldest first
first_idstring or nullID of the first file on the page
last_idstring or nullID of the last file on the page
cursorstring or nullValue to pass as cursor for the next page
has_morebooleanWhether 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:

HTTPerror.codeMeaning
400invalid_content_typeThe body is not multipart/form-data
400invalid_fileNo file part, an extra part, an empty file, or unsupported content
400invalid_filenameThe filename is too long or contains a rejected character
413file_too_largeThe file exceeds 100 MiB
400invalid_queryAn unsupported query parameter, or order other than asc
400invalid_limitlimit is outside 1 to 1000
400invalid_cursorThe cursor is malformed, or more than one cursor was sent
400file_not_downloadable/content was requested
404file_not_foundThe file does not exist, was deleted, or belongs to another account
503file_storage_unavailableFile storage is temporarily unavailable; retry later
503file_upload_expiredThe upload did not complete in time; upload the file again

Errors when referencing a file in a model request:

HTTPerror.codeMeaning
400invalid_file_inputMalformed ID, both file_id and url in one locator, or more than 100 references
400unsupported_file_typeThe file's type does not match the position, for example an MP4 in a document block
400file_model_unsupportedThe model does not declare the required input modality
400file_input_too_largeThe referenced files exceed 50,000,000 bytes in total
400file_protocol_unsupportedA file ID was sent to Chat Completions
404file_not_foundThe 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.

Need help?