Руководства
Загрузка файлов
Загрузите файл один раз и ссылайтесь на него по ID в запросах Messages, Responses, генерации изображений и видео.
Загрузите файл один раз, а затем ссылайтесь на него по ID в запросах к моделям. Это заменяет повторную отправку тех же байтов в base64 и размещение файла по публичному URL.
ID файла работает с Messages, Responses, генерацией изображений и генерацией видео. С Chat Completions он не работает.
Перед началом
- API key. См. Аутентификация.
- Base URL:
https://openapi.felo.ai. - Модель, принимающая тот тип файла, который вы собираетесь отправить. См. Проверить поддержку модели.
Быстрый старт
1. Загрузить файл
curl "https://openapi.felo.ai/api/v1/files" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-F "file=@./report.pdf"Успешная загрузка возвращает HTTP 200 с метаданными файла:
{
"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
}Сохраните id. Считайте его непрозрачной строкой: не формируйте и не разбирайте его.
2. Указать файл в запросе
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."}
]
}
]
}'Те же два шага на 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())И на Node.js 20 или новее:
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");Правила загрузки
- Тело запроса —
multipart/form-dataровно с одной частью с именемfile. Любая другая часть, включаяpurpose, отклоняется с ошибкойinvalid_file. - Пусть
Content-Typeзадаст ваш HTTP-клиент. Если задать его вручную, потеряется multipart boundary. - Не добавляйте query-параметры к URL загрузки.
- Загружайте по HTTP, а не через Files-хелпер SDK.
files.create()в OpenAI SDK всегда отправляетpurpose, поэтому не может вызвать этот endpoint. - Загрузка, которая завершилась тайм-аутом или обрывом соединения, всё равно могла сохраниться. Перед повторной загрузкой запросите список своих файлов.
Где можно указать ID файла
| Endpoint | Типы файлов | Требуемая входная модальность | Поле |
|---|---|---|---|
POST /api/v1/messages | PDF, изображение | file, image | messages[].content[] |
POST /api/v1/responses | PDF, изображение | file, image | input[].content[] |
POST /api/v1/images/generations | Изображение | image | input_references[] |
POST /api/v1/videos/generations | Изображение | image | frame_images[] |
POST /api/v1/videos/generations | Изображение, MP4, аудио | image, video, audio | input_references[] |
POST /api/v1/chat/completions | Не поддерживается |
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."}
]
}
]
}Для изображения используйте {"type": "image", "source": {"type": "file", "file_id": "..."}}.
Responses
| Файл | Блок контента |
|---|---|
{"type": "input_file", "file_id": "..."} | |
| Изображение | {"type": "input_image", "file_id": "...", "detail": "auto"} |
Блок, в котором есть file_id, не должен одновременно содержать URL или данные base64.
Генерация изображений
{
"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..."}}
]
}Остальная часть запроса, ответ 202 и опрос описаны в разделе Генерация изображений.
Генерация видео
Первый и последний кадры передаются в 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..."}
}
]
}Для конечного кадра добавьте вторую запись с "frame_type": "last_frame". Последний кадр требует первого кадра.
Референсные материалы передаются в input_references. Каждая запись использует локатор, соответствующий её типу медиа:
{
"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"}}
]
}Какие сочетания принимает модель, зависит от модели и канала. frame_images и input_references нельзя использовать в одном запросе.
Правила для локаторов
- В запросах на изображения и видео каждый объект
image_url,video_urlилиaudio_urlсодержит ровно одно из полейfile_idилиurlи никаких других полей. - В одном массиве можно смешивать записи с
file_idи записи сurl. - Генерация изображений и видео принимает только файлы, которые загрузили вы. Чтобы повторно использовать сгенерированное изображение, передайте его выходной
url. - Запрос, который ссылается на файл, при сбое не переносится на другой канал. Не повторяйте его на другом канале, не проверив ошибку.
- Храните файл, пока каждая задача, которая на него ссылается, не достигнет терминального состояния. Если удалить его раньше, задача может завершиться ошибкой.
Проверить поддержку модели
Сохранённый файл не становится автоматически пригодным для любой модели. Модель должна объявлять соответствующую входную модальность в публичном каталоге:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| Что отправляете | input_modalities должен содержать |
|---|---|
file | |
| Изображение | image |
| An MP4 | video |
| Аудиофайл | audio |
Пустой или отсутствующий список означает, что ID файлов для этой модели не включены. Тогда запрос завершается ошибкой file_model_unsupported. Не судите о поддержке по названию модели.
Лимиты
| Лимит | Значение |
|---|---|
| Размер загрузки | 100 MiB (104,857,600 байт) на файл; пустые файлы отклоняются |
| Объём файлов по ссылкам в одном запросе к модели | 50,000,000 байт суммарно |
| Ссылок на файлы в одном запросе к модели | 100 |
| Длина имени файла | 255 символов |
Две ссылки на один и тот же файл учитываются дважды в обоих лимитах запроса. Файл размером от 50 MB до 100 MiB можно загрузить, но на него нельзя сослаться в запросе к модели. Модель или канал могут применять более низкий лимит.
Типы файлов
Тип определяется по содержимому файла, а не по расширению или Content-Type части.
| Тип | Форматы | Где можно использовать |
|---|---|---|
| Messages, Responses | ||
| Изображение | PNG, JPEG, GIF, WebP | Messages, Responses, генерация изображений, генерация видео |
| Видео | MP4 | Генерация видео |
| Аудио | MP3, WAV, FLAC, OGG | Генерация видео |
| Office | DOCX, XLSX, PPTX | Только хранение |
| Текст | Текст UTF-8, сохраняется как text/plain | Только хранение |
Любое другое содержимое отклоняется с ошибкой invalid_file.
Имена файлов
Имя файла не может содержать <, >, :, ", |, ?, *, \ и управляющие символы. / допускается как разделитель, но пустые сегменты, . и .. — нет.
Управление файлами
Файлы принадлежат вашему аккаунту. Все API key аккаунта видят одни и те же файлы; другие аккаунты не могут использовать ваши ID файлов.
Получить список файлов
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
}Результаты отсортированы от старых к новым. Если has_more равно true, передайте полученный cursor, чтобы получить следующую страницу. Поиска и фильтра по типу на стороне сервера нет.
Получить один файл
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Удалить файл
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"}Удаление вступает в силу сразу, и отменить его нельзя. 503 означает, что удаление не завершилось; отправьте DELETE ещё раз.
Скачивание
Загруженные файлы нельзя скачать. GET /api/v1/files/{file_id}/content возвращает 400 file_not_downloadable, а заголовок Location в ответе на загрузку указывает на метаданные файла, а не на его байты. Храните собственную копию всего, что загружаете.
Чтобы скачать сгенерированные медиа, используйте подписанные URL из outputs задачи.
Справочник API
Все endpoint'ы используют Authorization: Bearer YOUR_API_KEY. Успешные ответы — обычные JSON-объекты без конверта.
| Метод | Путь | Возвращает |
|---|---|---|
POST | /api/v1/files | Объект файла |
GET | /api/v1/files | Страница файлов |
GET | /api/v1/files/{file_id} | Объект файла |
DELETE | /api/v1/files/{file_id} | {"id": "...", "type": "file_deleted"} |
GET | /api/v1/files/{file_id}/content | 400 file_not_downloadable |
POST, DELETE и GET одного файла отклоняют любой query-параметр с ошибкой invalid_query.
Объект файла
| Поле | Тип | Описание |
|---|---|---|
id | string | ID файла с префиксом felo_file_. Используйте его как file_id |
type | string | Всегда file |
source | string | upload для файлов, которые загрузили вы, generated для результатов модели |
filename | string | Имя, отправленное при загрузке |
mime_type | string | Тип, определённый по содержимому |
size_bytes | integer | Размер в байтах |
created_at | string | Метка времени ISO 8601 в UTC |
downloadable | boolean | false для загруженных файлов |
Запрос на загрузку
| Часть | Обязательно | Описание |
|---|---|---|
file | Да | Файл, отправленный как файловая часть multipart/form-data с именем файла |
Ответ содержит заголовок Location с URL метаданных файла.
Параметры списка
| Параметр | По умолчанию | Описание |
|---|---|---|
limit | 100 | Размер страницы, от 1 до 1000 |
cursor | Значение cursor с предыдущей страницы | |
after, after_id | Псевдонимы cursor. Отправляйте только один из трёх | |
order | asc | Поддерживается только asc |
| Поле ответа | Тип | Описание |
|---|---|---|
data | array | Объекты файлов, от старых к новым |
first_id | string или null | ID первого файла на странице |
last_id | string или null | ID последнего файла на странице |
cursor | string или null | Значение, которое нужно передать как cursor для следующей страницы |
has_more | boolean | Есть ли следующая страница |
Ошибки
Endpoint'ы Files, Responses, а также генерация изображений и видео используют конверт ошибок OpenAI:
{
"error": {
"message": "This model does not accept this attachment type",
"type": "invalid_request_error",
"param": "frame_images.0.image_url",
"code": "file_model_unsupported"
}
}Для ошибок от endpoint'ов Files param равен null. Messages возвращает формат ошибок Anthropic, в котором нет error.code. Request ID находится в заголовке ответа X-Request-Id.
Ошибки при загрузке файлов и управлении ими:
| HTTP | error.code | Значение |
|---|---|---|
| 400 | invalid_content_type | Тело запроса не является multipart/form-data |
| 400 | invalid_file | Нет части file, есть лишняя часть, файл пуст или содержимое не поддерживается |
| 400 | invalid_filename | Имя файла слишком длинное или содержит недопустимый символ |
| 413 | file_too_large | Файл превышает 100 MiB |
| 400 | invalid_query | Неподдерживаемый query-параметр или order, отличный от asc |
| 400 | invalid_limit | limit вне диапазона от 1 до 1000 |
| 400 | invalid_cursor | Курсор некорректен или отправлено больше одного курсора |
| 400 | file_not_downloadable | Запрошен /content |
| 404 | file_not_found | Файл не существует, удалён или принадлежит другому аккаунту |
| 503 | file_storage_unavailable | Хранилище файлов временно недоступно; повторите позже |
| 503 | file_upload_expired | Загрузка не завершилась вовремя; загрузите файл заново |
Ошибки при ссылке на файл в запросе к модели:
| HTTP | error.code | Значение |
|---|---|---|
| 400 | invalid_file_input | Некорректный ID, file_id и url в одном локаторе или больше 100 ссылок |
| 400 | unsupported_file_type | Тип файла не соответствует позиции, например MP4 в блоке документа |
| 400 | file_model_unsupported | Модель не объявляет требуемую входную модальность |
| 400 | file_input_too_large | Файлы по ссылкам суммарно превышают 50,000,000 байт |
| 400 | file_protocol_unsupported | ID файла отправлен в Chat Completions |
| 404 | file_not_found | Файл отсутствует, удалён, принадлежит другому аккаунту или это сгенерированный файл, отправленный в генерацию изображений или видео |
При генерации изображений и видео сбой из-за файла возможен и после 202. Тогда задача завершается со статусом failed и одним из этих кодов в error.code.
Ошибки аутентификации, баланса и лимитов запросов описаны в разделе Ошибки, лимиты и повторные попытки.
Связанные разделы
Нужна помощь?
- По вопросам API, оплаты и аккаунта пишите в поддержку.
- Общайтесь с разработчиками Felo в Discord.
- Загляните в наш журнал изменений.
- Нужны цены за объём или помощь с закупкой? Связаться с отделом продаж.
- Создаёте на LLM? Прочитайте llms.txt.