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

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

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

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

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

- API key. См. [Аутентификация](https://openapi.felo.ai/ru/docs/authentication.md).
- Base 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.
- Не добавляйте 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

```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/ru/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 key аккаунта видят одни и те же файлы; другие аккаунты не могут использовать ваши 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` одного файла отклоняют любой 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:

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

Ошибки аутентификации, баланса и лимитов запросов описаны в разделе [Ошибки, лимиты и повторные попытки](https://openapi.felo.ai/ru/docs/guides/errors-and-limits.md).

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

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