Felo API PlatformFelo API Platform

Руководства

Загрузка файлов

Загрузите файл один раз и ссылайтесь на него по ID в запросах Messages, Responses, генерации изображений и видео.

Загрузите файл один раз, а затем ссылайтесь на него по ID в запросах к моделям. Это заменяет повторную отправку тех же байтов в base64 и размещение файла по публичному URL.

ID файла работает с Messages, Responses, генерацией изображений и генерацией видео. С Chat Completions он не работает.

Перед началом

Быстрый старт

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/messagesPDF, изображениеfile, imagemessages[].content[]
POST /api/v1/responsesPDF, изображениеfile, imageinput[].content[]
POST /api/v1/images/generationsИзображениеimageinput_references[]
POST /api/v1/videos/generationsИзображениеimageframe_images[]
POST /api/v1/videos/generationsИзображение, MP4, аудиоimage, video, audioinput_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

ФайлБлок контента
PDF{"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 должен содержать
PDFfile
Изображениеimage
An MP4video
Аудиофайлaudio

Пустой или отсутствующий список означает, что ID файлов для этой модели не включены. Тогда запрос завершается ошибкой file_model_unsupported. Не судите о поддержке по названию модели.

Лимиты

ЛимитЗначение
Размер загрузки100 MiB (104,857,600 байт) на файл; пустые файлы отклоняются
Объём файлов по ссылкам в одном запросе к модели50,000,000 байт суммарно
Ссылок на файлы в одном запросе к модели100
Длина имени файла255 символов

Две ссылки на один и тот же файл учитываются дважды в обоих лимитах запроса. Файл размером от 50 MB до 100 MiB можно загрузить, но на него нельзя сослаться в запросе к модели. Модель или канал могут применять более низкий лимит.

Типы файлов

Тип определяется по содержимому файла, а не по расширению или Content-Type части.

ТипФорматыГде можно использовать
PDFPDFMessages, Responses
ИзображениеPNG, JPEG, GIF, WebPMessages, Responses, генерация изображений, генерация видео
ВидеоMP4Генерация видео
АудиоMP3, WAV, FLAC, OGGГенерация видео
OfficeDOCX, 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}/content400 file_not_downloadable

POST, DELETE и GET одного файла отклоняют любой query-параметр с ошибкой invalid_query.

Объект файла

ПолеТипОписание
idstringID файла с префиксом felo_file_. Используйте его как file_id
typestringВсегда file
sourcestringupload для файлов, которые загрузили вы, generated для результатов модели
filenamestringИмя, отправленное при загрузке
mime_typestringТип, определённый по содержимому
size_bytesintegerРазмер в байтах
created_atstringМетка времени ISO 8601 в UTC
downloadablebooleanfalse для загруженных файлов

Запрос на загрузку

ЧастьОбязательноОписание
fileДаФайл, отправленный как файловая часть multipart/form-data с именем файла

Ответ содержит заголовок Location с URL метаданных файла.

Параметры списка

ПараметрПо умолчаниюОписание
limit100Размер страницы, от 1 до 1000
cursorЗначение cursor с предыдущей страницы
after, after_idПсевдонимы cursor. Отправляйте только один из трёх
orderascПоддерживается только asc
Поле ответаТипОписание
dataarrayОбъекты файлов, от старых к новым
first_idstring или nullID первого файла на странице
last_idstring или nullID последнего файла на странице
cursorstring или nullЗначение, которое нужно передать как cursor для следующей страницы
has_morebooleanЕсть ли следующая страница

Ошибки

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.

Ошибки при загрузке файлов и управлении ими:

HTTPerror.codeЗначение
400invalid_content_typeТело запроса не является multipart/form-data
400invalid_fileНет части file, есть лишняя часть, файл пуст или содержимое не поддерживается
400invalid_filenameИмя файла слишком длинное или содержит недопустимый символ
413file_too_largeФайл превышает 100 MiB
400invalid_queryНеподдерживаемый query-параметр или order, отличный от asc
400invalid_limitlimit вне диапазона от 1 до 1000
400invalid_cursorКурсор некорректен или отправлено больше одного курсора
400file_not_downloadableЗапрошен /content
404file_not_foundФайл не существует, удалён или принадлежит другому аккаунту
503file_storage_unavailableХранилище файлов временно недоступно; повторите позже
503file_upload_expiredЗагрузка не завершилась вовремя; загрузите файл заново

Ошибки при ссылке на файл в запросе к модели:

HTTPerror.codeЗначение
400invalid_file_inputНекорректный ID, file_id и url в одном локаторе или больше 100 ссылок
400unsupported_file_typeТип файла не соответствует позиции, например MP4 в блоке документа
400file_model_unsupportedМодель не объявляет требуемую входную модальность
400file_input_too_largeФайлы по ссылкам суммарно превышают 50,000,000 байт
400file_protocol_unsupportedID файла отправлен в Chat Completions
404file_not_foundФайл отсутствует, удалён, принадлежит другому аккаунту или это сгенерированный файл, отправленный в генерацию изображений или видео

При генерации изображений и видео сбой из-за файла возможен и после 202. Тогда задача завершается со статусом failed и одним из этих кодов в error.code.

Ошибки аутентификации, баланса и лимитов запросов описаны в разделе Ошибки, лимиты и повторные попытки.

Связанные разделы

Нужна помощь?