# Завантаження файлів

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

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

ID файлу працює з Messages, Responses, генерацією зображень і генерацією відео. З Chat Completions він не працює.

## Перш ніж почати

- API-ключ. Див. [Автентифікація](https://openapi.felo.ai/uk/docs/authentication.md).
- Базова URL-адреса `https://openapi.felo.ai`.
- Модель, яка приймає тип файлу, який ви плануєте надіслати. Див. [Перевірка підтримки моделі](#section-7).

## Швидкий старт

### 1. Завантаження файлу

```bash
curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"
```

Успішне завантаження повертає HTTP `200` з метаданими файлу:

```json
{
  "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. Посилання на файл у запиті

```bash
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:

```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 або новішій версії:

```javascript
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

```json
{
  "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.

### Генерація зображень

```json
{
  "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` та опитування описано в [Генерація зображень](https://openapi.felo.ai/uk/docs/guides/image-generation.md).

### Генерація відео

Перший і останній кадри передаються в `frame_images`:

```json
{
  "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`. Кожен запис використовує локатор, що відповідає його типу медіа:

```json
{
  "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`.
- Запит, який посилається на файл, у разі збою не переноситься на інший канал. Не повторюйте його на іншому каналі, не перевіривши помилку.
- Зберігайте файл, доки кожне завдання, яке на нього посилається, не досягне термінального стану. Якщо видалити його раніше, завдання може завершитися збоєм.

## Перевірка підтримки моделі

Збережений файл не стає автоматично придатним для кожної моделі. Модель має оголошувати відповідну вхідну модальність у публічному каталозі:

```bash
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
```

```json
["text", "image", "file"]
```

| Що надсилаєте | `input_modalities` має містити |
|---|---|
| PDF | `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` частини.

| Тип | Формати | Де можна використати |
|---|---|---|
| PDF | PDF | 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 файлів.

### Отримання списку файлів

```bash
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{
  "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`, щоб отримати наступну сторінку. Серверного пошуку чи фільтра за типом немає.

### Отримання одного файлу

```bash
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

### Видалення файлу

```bash
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{"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` | [Об'єкт файлу](#section-16) |
| `GET` | `/api/v1/files` | [Сторінка файлів](#section-18) |
| `GET` | `/api/v1/files/{file_id}` | [Об'єкт файлу](#section-16) |
| `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:

```json
{
  "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`.

Помилки автентифікації, балансу та обмеження швидкості описано в [Помилки, обмеження та повторні спроби](https://openapi.felo.ai/uk/docs/guides/errors-and-limits.md).

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

- [Протоколи та SDK](https://openapi.felo.ai/uk/docs/guides/protocols.md)
- [Генерація зображень](https://openapi.felo.ai/uk/docs/guides/image-generation.md)
- [Асинхронні завдання](https://openapi.felo.ai/uk/docs/guides/async-tasks.md)
- [Довідка Model API](https://openapi.felo.ai/uk/docs/model-api)
