Посібники
Завантаження файлів
Завантажте файл один раз і посилайтеся на нього за ID у запитах Messages, Responses, генерування зображень і відео.
Завантажте файл один раз, а потім посилайтеся на нього за ID у запитах до моделей. Це замінює повторне надсилання тих самих байтів у base64 або розміщення файлу за публічною URL-адресою.
ID файлу працює з Messages, Responses, генерацією зображень і генерацією відео. З Chat Completions він не працює.
Перш ніж почати
- API-ключ. Див. Автентифікація.
- Базова 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. - Не додавайте параметри запиту до 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-ключ облікового запису бачить ті самі файли; інші облікові записи не можуть використовувати ваші 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 одного файлу відхиляють будь-який параметр запиту з 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. 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 | Непідтримуваний параметр запиту або 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.