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

Presigned URL для входных файлов

Базовый адрес — `https://api.iskragen.ru`. Общие правила — в [обзоре справочника](/docs/api-reference).

## POST /v1/files/

**Загрузить файл напрямую.** Принимает `multipart/form-data` с ровно одним полем `file`, сверяет содержимое с заявленным типом и каждый раз сохраняет новый файл с новым `url`, без дедупликации; пределы — 10 МБ для изображений, 50 МБ для аудио и 100 МБ для видео. Действует лимит 20 запросов в минуту и не более 3 одновременных загрузок на аккаунт, при превышении возвращается `429`; успешный ответ — `201` с `url` для генерации и `durationMs` — длительностью видео в миллисекундах по заголовку файла (`null` у изображений, аудио и видео, длительность которого определить не удалось). Требуется API-ключ; без него возвращается `401 AUTHENTICATION_ERROR`.

**Авторизация:** заголовок `Authorization: Bearer <ключ>` — API-ключ, выданный в личном кабинете (`isk_live_<prefix>_<secret>`).

### Пример вызова

```bash
curl -X POST "https://api.iskragen.ru/v1/files/" \
  -H "Authorization: Bearer $ISKRAGEN_API_KEY" \
  -F "file=@<путь к файлу>"
```

### Структура ответа `201`

Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — `object`.

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `contentType` | `string` | да | — |
| `createdAt` | `string` | да | — |
| `durationMs` | `integer \| null` | да | — |
| `id` | `string` | да | формат uuid |
| `originalFilename` | `string \| null` | да | — |
| `sizeBytes` | `integer` | да | ≥ 1 |
| `url` | `string` | да | — |

### Коды ошибок

- `401 AUTHENTICATION_ERROR` — ключ отсутствует, невалиден или отозван.
- `429` — Превышен лимит — см. [Rate limits](/docs/rate-limits)

## POST /v1/uploads/presign

**Ссылка для загрузки к генерации.** Выдаёт новую presigned `PUT`-ссылку на 900 секунд для существующей своей генерации с ролью `input` или `mask`; действуют те же типы и пределы 10 МБ для изображений, 50 МБ для аудио и 100 МБ для видео. Чужая генерация возвращает `404`. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает `429 RATE_LIMIT_ERROR` с `retryAfter`, а отсутствие ключа — `401 AUTHENTICATION_ERROR`.

**Авторизация:** заголовок `Authorization: Bearer <ключ>` — API-ключ, выданный в личном кабинете (`isk_live_<prefix>_<secret>`).

### Тело запроса (`application/json`)

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `contentType` | `string` | да | — |
| `generationId` | `string` | да | формат uuid |
| `role` | `string` | да | значения: `input`, `mask` |
| `size` | `integer` | да | ≥ 1; ≤ 100000000 |

### Пример вызова

```bash
curl -X POST "https://api.iskragen.ru/v1/uploads/presign" \
  -H "Authorization: Bearer $ISKRAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"generationId":"<generationId>","role":"input","contentType":"<contentType>","size":1}'
```

### Структура ответа `200`

Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — `object`.

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `expiresIn` | `number` | да | — |
| `key` | `string` | да | — |
| `url` | `string` | да | — |

### Коды ошибок

- `401 AUTHENTICATION_ERROR` — ключ отсутствует, невалиден или отозван.
- `404` — Ресурс не существует или принадлежит другому пользователю
- `429 RATE_LIMIT_ERROR` — превышен лимит запросов либо число одновременных генераций (по умолчанию 5).

## POST /v1/uploads/presign-input

**Ссылка для загрузки референса.** Выдаёт новую presigned `PUT`-ссылку на 900 секунд (15 минут) и `finalUrl` для `params` будущей генерации; поддерживаются `image/png`, `image/jpeg`, `image/webp`, `video/mp4`, `video/quicktime`, `audio/mpeg`, `audio/mp3`, `audio/wav`, `audio/x-wav`. Размер ограничен 10 МБ для изображений, 50 МБ для аудио и 100 МБ для видео, иначе возвращается `400`; каждый вызов создаёт новый ключ. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает `429 RATE_LIMIT_ERROR` с `retryAfter`, а отсутствие ключа — `401 AUTHENTICATION_ERROR`.

**Авторизация:** заголовок `Authorization: Bearer <ключ>` — API-ключ, выданный в личном кабинете (`isk_live_<prefix>_<secret>`).

### Тело запроса (`application/json`)

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `contentType` | `string` | да | — |
| `size` | `integer` | да | ≥ 1; ≤ 100000000 |

### Пример вызова

```bash
curl -X POST "https://api.iskragen.ru/v1/uploads/presign-input" \
  -H "Authorization: Bearer $ISKRAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contentType":"<contentType>","size":1}'
```

### Структура ответа `200`

Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — `object`.

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `expiresIn` | `number` | да | — |
| `finalUrl` | `string` | да | — |
| `key` | `string` | да | — |
| `url` | `string` | да | — |

### Коды ошибок

- `400` — Неверные параметры запроса (см. `code`)
- `401 AUTHENTICATION_ERROR` — ключ отсутствует, невалиден или отозван.
- `429 RATE_LIMIT_ERROR` — превышен лимит запросов либо число одновременных генераций (по умолчанию 5).