# Файлы

> Референсы по ссылке, загрузка своих файлов и скачивание результатов.

## <a id="references"></a>Файлы по ссылке

Поля-списки ссылок (например image_urls) принимают прямые https-ссылки на файлы: сервер скачает их сам. Ссылка должна отдавать файл без входа, а не страницу просмотра. Какие поля есть у модели, сколько файлов и каких форматов, сказано на её странице.

```json
{
  "prompt": "Make the background blue",
  "image_urls": [
    "https://example.com/reference.jpg"
  ]
}
```

## <a id="upload"></a>Загрузить свой файл

Если публичной ссылки нет, загрузите файл в POST /v1/files (multipart/form-data, поле file) и передайте url из ответа в нужное поле настроек.

```bash
curl -X POST "https://api.cyhub.ai/v1/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@reference.jpg"
```

```python
import requests

API = "https://api.cyhub.ai/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

with open("reference.jpg", "rb") as handle:
    response = requests.post(f"{API}/files", files={"file": handle}, headers=HEADERS, timeout=120)
response.raise_for_status()
uploaded = response.json()
print(uploaded["url"], uploaded["expires_at"])
```

В ответе id, kind (image, audio, video), size, url и expires_at. Загруженный файл хранится 7 дней, ставьте задачу сразу после загрузки.

| Вид | Форматы | Размер до |
|---|---|---|
| Картинка | jpg, jpeg, png, webp | 30 МБ |
| Аудио | mp3, wav, ogg, m4a, flac, aac | 20 МБ |
| Видео | mp4, mov, webm | 200 МБ |

Это общий потолок загрузки. У модели пределы могут быть строже, они на её странице и проверяются при постановке задачи.

## <a id="download"></a>Скачать результат

Файлы результата скачиваются по download_path из задачи с тем же ключом. Вместо 0 подставьте index нужного файла.

```bash
curl "https://api.cyhub.ai/v1/tasks/TASK_ID/artifacts/0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o result.png
```

```python
import requests

API = "https://api.cyhub.ai/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(f"{API}/tasks/TASK_ID/artifacts/0", headers=HEADERS, timeout=300)
response.raise_for_status()
with open("result.png", "wb") as handle:
    handle.write(response.content)
```

> Результаты хранятся 7 дней после завершения задачи. Потом files_expired становится true, download_path null, а история задачи остаётся. Сохраняйте файлы у себя.