# Файлы

Любой файл — результат, референс из запроса, ваша загрузка — объект `file` (схема `File`)
со **сроком жизни 1 день** (`retention.files_days` в `GET /v1/key`). Нужен дольше — скачайте.

## Ссылка на файл

`url` подписан до конца срока и не меняется — можно отдать пользователю или встроить
на страницу (`media.souz.ai`, CORS `*`, работают `Range` и `?download=1`).
После срока байты удаляются: у объекта `expired: true` без `url`, ссылка отвечает
`410 file_expired`. Неверная подпись — `403 invalid_signature`.

## Загрузка — `POST /v1/files`

`multipart/form-data`, часть `file` (`purpose` SDK OpenAI принимается и ни на что не
влияет). Полученный `file_…` подставляйте в поля запроса вместо байтов.

| Тип | Форматы | Предел |
|---|---|---|
| картинки | `png`, `jpeg`, `webp` | 50 МиБ; JPEG до 300 Мп, остальные — см. [референсы](https://souz.ai/docs/images.md#референсы); хранятся как есть, без метаданных |
| видео | `mp4`, `mov` | 200 МиБ; сохраняются как есть |
| звук | `wav`, `mp3` | 15 МиБ; сохраняются как есть |

Отвергнутый файл — `400 invalid_input` (`413` — слишком большой) с `detail[]`.

```bash tab="cURL"
curl https://api.souz.ai/v1/files \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -F file=@reference.png
```

```python tab="Python"
with open("reference.png", "rb") as f:
    uploaded = client.files.create(file=f, purpose="user_data")
print(uploaded.id)
```

## Список и удаление

`GET /v1/files`, `GET /v1/files/{id}`, `DELETE /v1/files/{id}` — как `files.list`,
`files.retrieve` и `files.delete` SDK OpenAI; удаление отвечает
`{"id", "object": "file", "deleted": true}`. Чужой файл неотличим от несуществующего:
`404 file_not_found`.

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.