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.
  • Не додавайте параметри запиту до 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-ключ облікового запису бачить ті самі файли; інші облікові записи не можуть використовувати ваші 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 одного файлу відхиляють будь-який параметр запиту з 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. ID запиту міститься в заголовку відповіді X-Request-Id.

Помилки під час завантаження файлів або керування ними:

HTTPerror.codeЗначення
400invalid_content_typeТіло не є multipart/form-data
400invalid_fileНемає частини file, є зайва частина, файл порожній або вміст не підтримується
400invalid_filenameІм'я файлу задовге або містить недозволений символ
413file_too_largeФайл перевищує 100 MiB
400invalid_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_inputID неправильного формату, 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.

Помилки автентифікації, балансу та обмеження швидкості описано в Помилки, обмеження та повторні спроби.

Пов'язані розділи

Потрібна допомога?