# CyHUB API

> Генерация картинок, видео и аудио через HTTP API теми же моделями и по тем же ценам, что в ботах Cyber AI. Один ключ на все модели, оплата с баланса кабинета.

Адрес API: https://api.cyhub.ai/v1. В каждом запросе заголовок `Authorization: Bearer <ключ>`. Ключ создаётся в кабинете (https://cyhub.ai/cabinet/keys) после подтверждения почты.

Порядок работы: выбрать модель (GET /v1/models), узнать поля её настроек (GET /v1/models/{model_key}), при желании узнать цену (POST /v1/price), поставить задачу (POST /v1/tasks), опрашивать её (GET /v1/tasks/{id}) до статуса succeeded и скачать файлы результата.

Ошибка приходит в виде `{"error": {"code", "message"}}`: ветвиться нужно по code, а message показывать человеку. Язык текстов: ?lang=ru или ?lang=en либо заголовок Accept-Language, без них русский.

У каждой страницы документации есть версия в Markdown: добавьте .md к её адресу, например https://api.cyhub.ai/docs/tasks.md.

Этот файл на английском: https://api.cyhub.ai/llms.txt?lang=en

---

# Старт

> Первый запрос к API CyHUB.

## <a id="begin"></a>С чего начать

Один ключ открывает все модели CyHUB, доступные через API. Выберите модель, отправьте задачу и заберите результат: те же модели и цены, что у ботов.

1. [Создайте ключ](https://cyhub.ai/cabinet/keys): В кабинете, после подтверждения почты.
2. [Выберите модель](https://api.cyhub.ai/models): Параметры и примеры на странице модели.
3. [Отправьте задачу](https://api.cyhub.ai/docs/generations.md?lang=ru): Модель и её настройки в POST /v1/tasks.
4. [Заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): Статус задачи и файлы, они хранятся 7 дней.

## <a id="first-request"></a>Первый запрос

Замените YOUR_API_KEY своим ключом. Запрос проверяет ключ и показывает баланс, генерацию не запускает.

```bash
curl "https://api.cyhub.ai/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import requests

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

response = requests.get(f"{API}/me", headers=HEADERS, timeout=30)
response.raise_for_status()
me = response.json()
for wallet in me["wallets"]:
    print(wallet["currency"], wallet["available_minor"])
```

В ответе wallets: доступная новым задачам сумма в available_minor, для RUB в копейках.

## <a id="next"></a>Дальше

Общие разделы описывают подключение, запуск, задачи, файлы и ошибки. У каждой модели своя страница с параметрами, правилами файлов и примером запроса. Формальное описание (OpenAPI) и консоль для запросов: /v1/docs.

Для ИИ-агентов: оглавление документации лежит в /llms.txt, а у каждой страницы есть версия в Markdown, достаточно добавить .md к адресу. Схемы всех моделей одним запросом отдаёт GET /v1/models/schemas.

[Настроить подключение](https://api.cyhub.ai/docs/connection.md?lang=ru)

---

# Подключение

> Ключ API, адрес запросов и баланс.

## <a id="key"></a>Ключ доступа

Ключ создаётся в кабинете в разделе «Ключи доступа» после подтверждения почты. Секрет показывается один раз: храните его на своём сервере, в браузер и в открытый код не кладите.

[Открыть ключи доступа](https://cyhub.ai/cabinet/keys)

Ключ потерян или мог утечь: отзовите его в кабинете и создайте новый. Отозванный ключ перестаёт работать сразу.

## <a id="address"></a>Адрес и заголовки

```
https://api.cyhub.ai/v1
```

В каждом запросе заголовок Authorization. Тело запросов это JSON в UTF-8 с Content-Type: application/json.

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Язык текстов в ответах (сообщения об ошибках, описания моделей): заголовок Accept-Language: ru или en, либо ?lang=ru в адресе. Без них русский.

## <a id="balance"></a>Баланс

```bash
curl "https://api.cyhub.ai/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import requests

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

response = requests.get(f"{API}/me", headers=HEADERS, timeout=30)
response.raise_for_status()
me = response.json()
for wallet in me["wallets"]:
    print(wallet["currency"], wallet["available_minor"])
```

В ответе id (номер кабинета), platform, key (каким ключом сделан запрос) и wallets. У кошелька balance_minor (всё на балансе), reserved_minor (удержано задачами в работе) и available_minor (доступно новым задачам). Суммы в минорных единицах: 15000 это 150 ₽.

Баланс общий с Telegram и MAX, если кабинеты связаны. Пополнение сейчас в RUB, на странице «Баланс» в кабинете.

[Пополнить баланс](https://cyhub.ai/balance)

---

# Запуск генерации

> Модель и настройки в одном запросе, цена и безопасные повторы.

## <a id="models"></a>Список моделей

Те же модели отдаёт GET /v1/models, а GET /v1/models/{model_key} даёт JSON Schema настроек и документацию на языке запроса. Все модели с их схемами одним запросом: GET /v1/models/schemas.

```bash
curl "https://api.cyhub.ai/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import requests

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

response = requests.get(f"{API}/models", headers=HEADERS, timeout=30)
response.raise_for_status()
for model in response.json()["models"]:
    print(model["model_key"], model["title"], model["available"])
```

[Все нейросети и их API](https://api.cyhub.ai/models)

## <a id="submit"></a>Запустить задачу

Задача создаётся одним запросом: ключ модели и её настройки. Какие поля есть у модели, сказано на её странице. Заголовок Idempotency-Key необязателен, но с ним повтор запроса безопасен (ниже).

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  --data '{
  "model": "veo",
  "settings": {
    "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
    "mode": "text_to_video",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}'
```

```python
import requests

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

body = {
  "model": "veo",
  "settings": {
    "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
    "mode": "text_to_video",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}
headers = {**HEADERS, "Idempotency-Key": "order-1042"}
response = requests.post(f"{API}/tasks", json=body, headers=headers, timeout=60)
response.raise_for_status()
task = response.json()
print(task["id"], task["status"], task["amount_minor"])
```

Ответ 201 с задачей: id, status (сначала queued), amount_minor и currency (цена). Цена считается при приёме и резервируется на балансе, списывается после успешной генерации; при ошибке или отмене резерв возвращается.

Если денег не хватает, ответ 402 insufficient_funds: задача не создаётся, деньги не трогаются. Незнакомое поле в settings это 422 unknown_setting, неподходящее значение 422 invalid_settings.

[Проверить статус и получить результат](https://api.cyhub.ai/docs/tasks.md?lang=ru)

## <a id="price"></a>Узнать цену заранее

Те же модель и настройки в POST /v1/price: задача не создаётся, деньги не трогаются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "veo",
  "settings": {
    "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
    "mode": "text_to_video",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}'
```

```python
import requests

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

body = {
  "model": "veo",
  "settings": {
    "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
    "mode": "text_to_video",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}
headers = HEADERS
response = requests.post(f"{API}/price", json=body, headers=headers, timeout=60)
response.raise_for_status()
price = response.json()
print(price["amount_minor"], price["currency"], price["available_minor"])
```

В ответе credits (внутренние единицы модели), amount_minor и currency (цена в деньгах), regular_minor и discount (цена без скидки и скидка, ниже) и available_minor (сколько доступно). Цена справочная: у новой задачи она считается заново при приёме.

## <a id="discounts"></a>Скидки

Если у кабинета есть скидка, amount_minor в POST /v1/price и у задачи уже с ней: столько и будет зарезервировано и списано. Рядом regular_minor (цена без скидки) и процент скидки: discount.percent у цены, discount_percent у задачи. Без скидки regular_minor равен amount_minor, а процент 0.

Уровень скидки кабинета, оборот и цены моделей на каждом уровне отдаёт GET /v1/discounts. Пока скидки у кабинета нет, ответ {"active": false}.

```bash
curl "https://api.cyhub.ai/v1/discounts" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import requests

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

response = requests.get(f"{API}/discounts", headers=HEADERS, timeout=30)
response.raise_for_status()
view = response.json()
if view["active"]:
    print(view["tier_no"], view["turnover_minor"], view["remaining_minor"])
```

## <a id="retries"></a>Повторные запросы

Idempotency-Key это метка одной генерации, которую придумывает ваша программа: UUID или свой номер, например order-1042. Передаётся заголовком или полем idempotency_key в теле запроса.

```http
Idempotency-Key: order-1042
```

Ответ не дошёл (обрыв связи, таймаут): повторите тот же запрос с той же меткой. Вернётся уже созданная задача, второй генерации и второго резерва не будет. Для следующей генерации нужна новая метка, даже если настройки те же.

Та же метка с другими настройками это 409 idempotency_conflict.

Повторы с одной меткой можно слать и одновременно: задачу ставит первый, остальные дожидаются его и получают ту же задачу. Если первый ещё не закончил за 40 секунд, ответ 409 request_in_progress: повторите чуть позже.

---

# Плагин MCP

> Генерации CyHUB в Claude и ChatGPT: адрес и подключение.

## <a id="address"></a>Адрес плагина

Плагин MCP CyberAI запускает генерации прямо из чата с Claude или ChatGPT и тратит тот же баланс, что сайт и боты. Подключается он по этому адресу:

```
https://mcp.cyhub.ai/mcp
```

Ключ API плагину не нужен. При подключении откроется наш сайт: войдите в кабинет, проверьте, что просит плагин, и нажмите «Разрешить». Пароль от кабинета плагин не получает.

Готовые картинки, видео и звук плагин показывает прямо в чате, в своём окне с плеером и кнопкой «Скачать». В Claude Code и Codex такого окна нет, там результат приходит ссылками.

## <a id="claude"></a>Claude

- Откройте в Claude раздел коннекторов (Connectors) и добавьте свой коннектор (Add custom connector).
- Название CyberAI, адрес плагина из раздела выше.
- Нажмите Connect, войдите в кабинет на нашем сайте и нажмите «Разрешить».
- Чтобы Claude не спрашивал подтверждение перед каждым запуском, откройте коннектор CyberAI в разделе Connectors, в разрешениях инструментов (Tool permissions) нажмите Custom и выберите Always allow. Траты при этом ограничивают лимиты в кабинете.
- В чате включите коннектор CyberAI и попросите, например, нарисовать картинку.

Коннектор работает в Claude на сайте, в приложении и на телефоне.

## <a id="chatgpt"></a>ChatGPT

CyberAI есть в каталоге плагинов ChatGPT.

[Открыть CyberAI в ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6ab7a35807d48191970dd1bdb063b785)

- Откройте страницу плагина по ссылке выше и подключите его.
- Войдите в кабинет на нашем сайте и нажмите «Разрешить».
- Выберите плагин CyberAI в чате: без этого ChatGPT его не использует.

В ChatGPT доступны все модели, кроме режима 18+ у Grok Video.

Если плагина нет в каталоге вашей страны, подключите его по адресу в режиме разработчика:

- В настройках ChatGPT откройте раздел «Плагины» и включите режим разработчика (Developer mode).
- Создайте приложение: откройте Настройки > Плагины > Посмотреть каталог > Добавить > Создать MCP-Приложение. Напишите название «CyberAI», вставьте адрес плагина из раздела выше, поставьте галочку «Я понимаю и хочу продолжить» и нажмите «Создать».
- Войдите в кабинет на нашем сайте и нажмите «Разрешить», затем выберите CyberAI в чате.

## <a id="programs"></a>Программы на компьютере

Claude Code и Codex подключают плагин командой. Вход тот же: через наш сайт и кнопку «Разрешить». В Claude Code после команды выполните /mcp и выберите CyberAI.

```
claude mcp add --transport http cyberai https://mcp.cyhub.ai/mcp
```

```
codex mcp add cyberai --url https://mcp.cyhub.ai/mcp
```

## <a id="access"></a>Доступ и траты

- Без галочки «Разрешить платные генерации» плагин только смотрит модели, баланс и историю генераций.
- С галочкой он запускает генерации за деньги с баланса кабинета в пределах лимитов: за одну генерацию и за сутки.
- Лимиты, платные генерации и отключение плагина в кабинете, во вкладке «Плагин MCP». Отключённый плагин сразу теряет доступ.

[Открыть плагины MCP в кабинете](https://cyhub.ai/cabinet/connections)

---

# Задачи и результаты

> Статусы, результат и история задач.

## <a id="status"></a>Проверить статус

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

```python
import requests

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

response = requests.get(f"{API}/tasks/TASK_ID", headers=HEADERS, timeout=30)
response.raise_for_status()
task = response.json()
print(task["status"], task.get("stage"))
```

Замените TASK_ID на id принятой задачи. Пока задача в работе, спрашивайте статус раз в несколько секунд. В stage текст того, что модель делает сейчас.

| Статус | Значение |
|---|---|
| `queued` | Задача принята и ждёт очереди. |
| `running` | Генерация выполняется. |
| `succeeded` | Результат готов, деньги списаны. |
| `failed` | Генерация не удалась, резерв возвращён. Причина в error. |
| `cancelled` | Задача отменена, резерв возвращён. |

## <a id="result"></a>Получить результат

У succeeded в result: caption (описание результата), texts (тексты, например слова песни) и artifacts, файлы с index, kind (image, video, audio, document), filename, size и download_path.

У failed причина в error, на языке кабинета. Резерв уже возвращён, повторный запуск это новая задача.

У черновика Seedance (задача с draft: true) есть поле draft: можно ли пересобрать его в высоком качестве (upscale_status), до какого времени (upscale_until) и готовый запрос для этого (upscale_request). Пересобрать черновик можно один раз, режимом upscale_draft той же модели. У остальных задач draft равно null.

[Скачать файлы результата](https://api.cyhub.ai/docs/files.md?lang=ru#download)

[Пересборка черновика Seedance](https://api.cyhub.ai/models/seedance-2-5/api.md#upscale_draft)

## <a id="history"></a>История

```bash
curl "https://api.cyhub.ai/v1/tasks?limit=30" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import requests

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

response = requests.get(f"{API}/tasks?limit=30", headers=HEADERS, timeout=30)
response.raise_for_status()
page = response.json()
for task in page["tasks"]:
    print(task["id"], task["model_key"], task["status"])
print("next:", page["next_cursor"])
```

Фильтры status и model (ключ модели), limit от 1 до 100. Следующая страница: next_cursor из ответа в параметр before.

---

# Файлы

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

## <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, а история задачи остаётся. Сохраняйте файлы у себя.

---

# Ошибки и лимиты

> Что делать, если запрос не выполнился.

## <a id="format"></a>Формат ошибки

Любой ответ с ошибкой устроен одинаково: code для программы, message для человека на языке запроса (Accept-Language или ?lang).

```json
{
  "error": {
    "code": "insufficient_funds",
    "message": "Не хватает средств: нужно ещё 2500 в минорных единицах. Пополните баланс в кабинете."
  }
}
```

## <a id="codes"></a>Коды ответов

| HTTP | Код | Что делать |
|---|---|---|
| `401` | invalid_api_key | Проверьте ключ. Отозванный или отсутствующий ключ замените новым из кабинета. |
| `402` | insufficient_funds | Пополните баланс, задача не создана. |
| `403` | model_not_allowed_for_key | Ключу не разрешена эта модель: набор моделей ключа меняется в кабинете, раздел «Ключи доступа». |
| `403` | key_daily_limit_exceeded | Лимит трат ключа на сутки исчерпан, задача не создана. Сутки по Москве; лимит меняется в кабинете. |
| `404` | model_not_found, task_not_found | Проверьте ключ модели (GET /v1/models) или id задачи. |
| `404` | artifact_expired | Срок хранения файлов результата вышел. |
| `404` | not_found | Такого адреса нет. В ответе поля docs, openapi и llms со ссылками на описание API. |
| `405` | method_not_allowed | Адрес не принимает этот метод запроса: разрешённые в заголовке Allow, ссылки на описание API в ответе. |
| `409` | idempotency_conflict | Под этой меткой уже есть задача с другими настройками, возьмите новую метку. |
| `409` | request_in_progress | Задача под этой меткой ещё создаётся: повторите тот же запрос через несколько секунд. |
| `413` | request_too_large, file_too_large | Уменьшите тело запроса или файл. |
| `422` | invalid_settings, unknown_setting | Сверьте settings со страницей модели: подробности в message. |
| `422` | invalid_request, file_type, file_empty | Проверьте форму запроса, формат и содержимое файла. |
| `429` | rate_limited, too_many_active | Подождите: превышен лимит запросов или одновременных задач модели. |
| `503` | model_unavailable, sg_unavailable | Модель на обслуживании или сервер генераций недоступен, повторите позже. |
| `500` | internal_error | Ошибка на нашей стороне, повторите позже; если повторяется, напишите в поддержку. |

## <a id="limits"></a>Лимиты

- 120 запросов в минуту на кабинет; ключи одного кабинета делят лимит.
- 30 запросов с неверным ключом в минуту с одного адреса.
- Тело JSON у задач и цены до 64 КБ, у остальных запросов до 16 КБ.
- Одновременных задач одной модели столько же, сколько у бота: при превышении 429 too_many_active.
- До 10 активных ключей в кабинете.
- Ключу можно оставить только нужные модели и лимит трат в сутки (по умолчанию все модели и без лимита). Свои права ключ видит в GET /v1/me, а GET /v1/models с таким ключом показывает только его модели.

Модель может быть временно выключена: available в GET /v1/models показывает это заранее, постановка задачи отвечает 503 model_unavailable.

---

# Seedance 2.5 API

> Видео Seedance 2.5 от ByteDance со звуком: по описанию, по первому и последнему кадру или по референсам, до 30 секунд. Референсы: фото, видео и аудио, качество до 1080p. Своё видео можно отредактировать описанием или продлить вперёд или назад. Два канала: обычный и, как правило, подешевле. На Канале 2 можно сначала снять черновик в 480p, а понравившийся один раз пересобрать в 1080p.

Разработчик: ByteDance
Ключ модели в API: `seedance`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2_5",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "seedance",
    "settings": {
        "mode": "text_to_video",
        "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
        "model": "seedance_2_5",
        "quality": "720p",
        "duration": 8,
        "aspect_ratio": "16:9",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2_5",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2_5",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_video"></a>По описанию

> Видео только по тексту, файлы не передаются.

Значение поля mode: `text_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_5` (2.5)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `aspect_ratio` (Необязательно)

Пропорции видео. adaptive есть только у версии 2.5: пропорции подбирает сама модель по описанию.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `adaptive` (Подбирает модель)
- По умолчанию: `"16:9"`

#### `web_search` (Необязательно)

Онлайн-поиск: модель подтянет свежие сведения из интернета. Только на Канале 1.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2_5",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
}
```

Черновик 480p, чтобы проверить сцену

```json
{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Бармен подбрасывает шейкер, ловит его за спиной и подмигивает в камеру",
    "model": "seedance_2_5",
    "channel": "channel_2",
    "draft": true,
    "duration": 5,
    "aspect_ratio": "16:9"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_video"></a>По кадрам

> Первый кадр или первый и последний: модель оживляет их по описанию.

Значение поля mode: `image_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_5` (2.5)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `image_urls` (Обязательно)

Одна ссылка: первый кадр. Две ссылки: первый и последний кадры.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

#### `aspect_ratio` (Необязательно)

Пропорции видео, работают только у семейства 2.0 на Канале 1. У версии 2.5 и на Канале 2 у любой версии размер ролика задаёт первый кадр, и выбранное значение не учитывается: у 2.5 выбор здесь один, adaptive.

- Тип: Строка
- Допустимые значения: `adaptive` (Как у первого кадра)
- По умолчанию: `"16:9"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- На Канале 2 размер ролика задаёт кадр у любой версии.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 2 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить кадр

```json
{
  "model": "seedance",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Девушка поворачивается к камере и улыбается, волосы развеваются на ветру",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "duration": 5
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="multimodal"></a>По референсам

> Персонажи, стиль, движение и звук с ваших фото, видео и аудио в новом ролике. Нужно хотя бы одно фото или видео.

Значение поля mode: `multimodal`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_5` (2.5)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `aspect_ratio` (Необязательно)

Пропорции видео. adaptive есть только у версии 2.5: пропорции подбирает сама модель по описанию и референсам. На Канале 2 с видео-референсами так у любой версии, и выбранное значение не учитывается.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `adaptive` (Подбирает модель)
- По умолчанию: `"16:9"`

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `video_urls` (Необязательно)

Ссылки на видео-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Каждое видео уходит в модель целиком, и его секунды добавляются к цене.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Видео передаются ссылками на MP4, MOV: у версии 2.5 до 200 МБ каждое и вместе не длиннее 30 секунд, у семейства 2.0 до 50 МБ и вместе не длиннее 15 секунд. Каждое от 2 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Файлы уходят в модель как есть и целиком. К длине ролика в цене добавляются секунды всех видео-референсов, неполная секунда каждого видео считается целой. На Канале 2 цена с видео не ниже порога, который растёт с длиной ролика.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании на файлы можно ссылаться по порядку ссылок каждого вида: @image1, @video1, @audio1 и так далее.
- На Канале 2 с видео-референсами пропорции подбирает сама модель у любой версии.
- Изменить или продлить само видео: режимы video_edit и video_extend. Здесь видео только образец, но у версии 2.5 на Канале 1 описание правки модель может принять за правку и отказать: тогда выберите video_edit.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `video_urls` | Видео | mp4, mov | 10 | 200 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Персонаж и движение камеры

```json
{
  "model": "seedance",
  "settings": {
    "mode": "multimodal",
    "prompt": "Девушка с @image1 идёт по ночному городу под дождём, камера движется как в @video1",
    "image_urls": [
      "https://example.com/girl.png"
    ],
    "video_urls": [
      "https://example.com/camera-move.mp4"
    ],
    "duration": 8
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_edit"></a>Правка видео

> Модель меняет ваше видео по описанию: заменить предмет или персонажа, фон, стиль. Остальное остаётся как было, длина и пропорции как у видео.

Значение поля mode: `video_edit`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что поменять в видео: от 3 до 20 000 символов, можно на разных языках. Остальное в видео останется как было.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_5` (2.5)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Не действует: ролик выходит той же длины, что ваше видео.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

В правке и продлении видео черновика нет: оставьте false.

- Тип: Да/нет
- По умолчанию: `false`

#### `video_urls` (Обязательно)

Ссылка на видео, которое нужно изменить. От 4 до 30 секунд у версии 2.5, до 15 у семейства 2.0. В описании это @video1.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Видео передаётся ссылкой на MP4, MOV: у версии 2.5 до 200 МБ и не длиннее 30 секунд, у семейства 2.0 до 50 МБ и не длиннее 15 секунд. От 4 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Видео уходит в модель как есть и целиком: нужен другой кусок, обрежьте файл заранее. Цена считается по длине видео: столько же секунд у нового ролика, и ещё столько же добавляет само видео на входе, неполная секунда считается целой.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании ваше видео это @video1, а фото и звук идут по порядку ссылок: @image1, @audio1 и так далее.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4, mov | 1 | 200 МБ |
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Заменить предмет в видео

```json
{
  "model": "seedance",
  "settings": {
    "mode": "video_edit",
    "prompt": "Замени красный кораблик в @video1 на жёлтую резиновую уточку",
    "video_urls": [
      "https://example.com/boat.mp4"
    ]
  }
}
```

Другой человек с фото

```json
{
  "model": "seedance",
  "settings": {
    "mode": "video_edit",
    "prompt": "Замени девушку в @video1 на женщину с @image1, движения и фон те же",
    "video_urls": [
      "https://example.com/dance.mp4"
    ],
    "image_urls": [
      "https://example.com/woman.jpg"
    ],
    "quality": "1080p"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- Ролик той же длины и с теми же пропорциями, что ваше видео. У версии 2.5 длина точно как у видео, у семейства 2.0 до целой секунды вверх.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_extend"></a>Продление видео

> Модель продолжает ваше видео новым куском заданной длины, после ролика или перед ним. Приходят два ролика: новый кусок и он же, склеенный с вашим видео.

Значение поля mode: `video_extend`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в новом куске: от 3 до 20 000 символов, можно на разных языках. Напишите и то, что видео нужно продлить, и в какую сторону.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_5` (2.5)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина нового куска в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду, и к ней добавляются секунды вашего видео.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

В правке и продлении видео черновика нет: оставьте false.

- Тип: Да/нет
- По умолчанию: `false`

#### `video_urls` (Обязательно)

Ссылка на видео, которое нужно продлить. От 2 до 30 секунд у версии 2.5, до 15 у семейства 2.0. В описании это @video1.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `extend_direction` (Необязательно)

С какой стороны приклеить новый кусок к вашему видео: forward после ролика, backward перед ним. Модель направление берёт из описания, поэтому напишите его и там.

- Тип: Строка
- Допустимые значения: `forward` (После ролика), `backward` (Перед роликом)
- По умолчанию: `"forward"`

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Видео передаётся ссылкой на MP4, MOV: у версии 2.5 до 200 МБ и не длиннее 30 секунд, у семейства 2.0 до 50 МБ и не длиннее 15 секунд. От 2 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Направление модель понимает из описания: напишите, что видео нужно продлить, и что происходит дальше, а для продления назад «продли назад» и что было до начала. extend_direction задаёт только, с какой стороны мы приклеим новый кусок к вашему видео.
- На Канале 1 продлевать умеет только версия 2.5: для семейства 2.0 выберите Канал 2.
- Видео уходит в модель как есть и целиком: нужен другой кусок, обрежьте файл заранее. К длине нового куска в цене добавляются секунды вашего видео, неполная секунда считается целой. На Канале 2 цена не ниже порога, который растёт с длиной куска.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании ваше видео это @video1, а фото и звук идут по порядку ссылок: @image1, @audio1 и так далее.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4, mov | 1 | 200 МБ |
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Что было дальше

```json
{
  "model": "seedance",
  "settings": {
    "mode": "video_extend",
    "prompt": "Продли @video1: кораблик проплывает под мостиком и скрывается за поворотом",
    "video_urls": [
      "https://example.com/boat.mp4"
    ],
    "duration": 5,
    "channel": "channel_2"
  }
}
```

Что было до начала

```json
{
  "model": "seedance",
  "settings": {
    "mode": "video_extend",
    "prompt": "Продли @video1 назад: рука опускает бумажный кораблик на воду",
    "video_urls": [
      "https://example.com/boat.mp4"
    ],
    "duration": 4,
    "extend_direction": "backward"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- Первым приходит новый кусок, вторым он же, склеенный с вашим видео в сторону extend_direction. Склейка той же высоты и ширины, что новый кусок, звук вашего видео сохраняется.
- Если склеить не вышло, приходит только новый кусок, а в texts пояснение. Оплата та же: кусок готов.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 | Новый кусок. |
| `video` | mp4 | 0 или 1 | Ваше видео и новый кусок одним роликом. Нет, если склеить не вышло. |

`result.texts`: Пояснение, если склеить не вышло.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="upscale_draft"></a>Пересборка черновика

> Пересобрать готовый черновик в 1080p: тот же ролик, сцена, движение и звук те же. Один раз на черновик и только в течение 7 дней после его создания.

Значение поля mode: `upscale_draft`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `draft_task_id` (Обязательно)

id задачи-черновика из /v1/tasks: готовой задачи Seedance 2.5 на Канале 2 с draft: true из вашего кабинета.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 36

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Других настроек у пересборки нет: описание, файлы, длительность, пропорции и звук модель берёт у черновика.
- Качество пересборки всегда 1080p. Цена как у обычного ролика 1080p с настройками черновика; узнать её заранее можно через /v1/price с этими же settings.
- Пересобрать черновик можно один раз и только в течение 7 дней после его создания. Точный срок и можно ли пересобрать сейчас, видно в поле draft задачи-черновика.
- Черновик, который ещё не готов, не удался, уже пересобран или пересобирается сейчас, чужой или просроченный, получает отказ с кодом ошибки, и деньги при этом не резервируются.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Пересобрать черновик в 1080p

```json
{
  "model": "seedance",
  "settings": {
    "mode": "upscale_draft",
    "draft_task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- Видео в 1080p. Неудачная пересборка не оплачивается.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Seedance 2.5: возможности и цены](https://api.cyhub.ai/models/seedance-2-5)
- Другие версии: [Seedance 2.0 API](https://api.cyhub.ai/models/seedance-2/api.md), [Seedance 2.0 Fast API](https://api.cyhub.ai/models/seedance-2-fast/api.md), [Seedance 2.0 Mini API](https://api.cyhub.ai/models/seedance-2-mini/api.md)
- Похожие модели: [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Seedance 2.0 API

> Видео Seedance 2.0 от ByteDance со звуком: по описанию, по первому и последнему кадру или по референсам, до 15 секунд. Референсы: фото, видео и аудио. Своё видео можно отредактировать описанием, а на Канале 2 и продлить вперёд или назад. Единственная версия Seedance с 4K. Два канала: обычный и, как правило, подешевле.

Разработчик: ByteDance
Ключ модели в API: `seedance`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "seedance",
    "settings": {
        "mode": "text_to_video",
        "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
        "model": "seedance_2",
        "quality": "720p",
        "duration": 8,
        "aspect_ratio": "16:9",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_video"></a>По описанию

> Видео только по тексту, файлы не передаются.

Значение поля mode: `text_to_video`

На этой странице версия Seedance 2.0: передайте model = seedance_2. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2` (Pro 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`, `4k`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `aspect_ratio` (Необязательно)

Пропорции видео. adaptive есть только у версии 2.5: пропорции подбирает сама модель по описанию.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`
- По умолчанию: `"16:9"`

#### `web_search` (Необязательно)

Онлайн-поиск: модель подтянет свежие сведения из интернета. Только на Канале 1.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_video"></a>По кадрам

> Первый кадр или первый и последний: модель оживляет их по описанию.

Значение поля mode: `image_to_video`

На этой странице версия Seedance 2.0: передайте model = seedance_2. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2` (Pro 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`, `4k`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `image_urls` (Обязательно)

Одна ссылка: первый кадр. Две ссылки: первый и последний кадры.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

#### `aspect_ratio` (Необязательно)

Пропорции видео, работают только у семейства 2.0 на Канале 1. У версии 2.5 и на Канале 2 у любой версии размер ролика задаёт первый кадр, и выбранное значение не учитывается: у 2.5 выбор здесь один, adaptive.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`
- По умолчанию: `"16:9"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- На Канале 2 размер ролика задаёт кадр у любой версии.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 2 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

От первого кадра к последнему

```json
{
  "model": "seedance",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Бутон медленно раскрывается в цветок, мягкий утренний свет",
    "model": "seedance_2",
    "quality": "1080p",
    "aspect_ratio": "9:16",
    "image_urls": [
      "https://example.com/bud.jpg",
      "https://example.com/flower.jpg"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="multimodal"></a>По референсам

> Персонажи, стиль, движение и звук с ваших фото, видео и аудио в новом ролике. Нужно хотя бы одно фото или видео.

Значение поля mode: `multimodal`

На этой странице версия Seedance 2.0: передайте model = seedance_2. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2` (Pro 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`, `4k`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `aspect_ratio` (Необязательно)

Пропорции видео. adaptive есть только у версии 2.5: пропорции подбирает сама модель по описанию и референсам. На Канале 2 с видео-референсами так у любой версии, и выбранное значение не учитывается.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`
- По умолчанию: `"16:9"`

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `video_urls` (Необязательно)

Ссылки на видео-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Каждое видео уходит в модель целиком, и его секунды добавляются к цене.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Видео передаются ссылками на MP4, MOV: у версии 2.5 до 200 МБ каждое и вместе не длиннее 30 секунд, у семейства 2.0 до 50 МБ и вместе не длиннее 15 секунд. Каждое от 2 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Файлы уходят в модель как есть и целиком. К длине ролика в цене добавляются секунды всех видео-референсов, неполная секунда каждого видео считается целой. На Канале 2 цена с видео не ниже порога, который растёт с длиной ролика.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании на файлы можно ссылаться по порядку ссылок каждого вида: @image1, @video1, @audio1 и так далее.
- На Канале 2 с видео-референсами пропорции подбирает сама модель у любой версии.
- Изменить или продлить само видео: режимы video_edit и video_extend. Здесь видео только образец, но у версии 2.5 на Канале 1 описание правки модель может принять за правку и отказать: тогда выберите video_edit.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `video_urls` | Видео | mp4, mov | 10 | 200 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Голос из аудио

```json
{
  "model": "seedance",
  "settings": {
    "mode": "multimodal",
    "prompt": "Мужчина с @image1 рассказывает историю у камина голосом с @audio1",
    "model": "seedance_2",
    "quality": "1080p",
    "image_urls": [
      "https://example.com/man.jpg"
    ],
    "audio_urls": [
      "https://example.com/voice.mp3"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_edit"></a>Правка видео

> Модель меняет ваше видео по описанию: заменить предмет или персонажа, фон, стиль. Остальное остаётся как было, длина и пропорции как у видео.

Значение поля mode: `video_edit`

На этой странице версия Seedance 2.0: передайте model = seedance_2. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что поменять в видео: от 3 до 20 000 символов, можно на разных языках. Остальное в видео останется как было.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2` (Pro 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`, `4k`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Не действует: ролик выходит той же длины, что ваше видео.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

В правке и продлении видео черновика нет: оставьте false.

- Тип: Да/нет
- По умолчанию: `false`

#### `video_urls` (Обязательно)

Ссылка на видео, которое нужно изменить. От 4 до 30 секунд у версии 2.5, до 15 у семейства 2.0. В описании это @video1.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Видео передаётся ссылкой на MP4, MOV: у версии 2.5 до 200 МБ и не длиннее 30 секунд, у семейства 2.0 до 50 МБ и не длиннее 15 секунд. От 4 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Видео уходит в модель как есть и целиком: нужен другой кусок, обрежьте файл заранее. Цена считается по длине видео: столько же секунд у нового ролика, и ещё столько же добавляет само видео на входе, неполная секунда считается целой.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании ваше видео это @video1, а фото и звук идут по порядку ссылок: @image1, @audio1 и так далее.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4, mov | 1 | 200 МБ |
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Заменить предмет в видео

```json
{
  "model": "seedance",
  "settings": {
    "mode": "video_edit",
    "prompt": "Замени красный кораблик в @video1 на жёлтую резиновую уточку",
    "video_urls": [
      "https://example.com/boat.mp4"
    ],
    "model": "seedance_2"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- Ролик той же длины и с теми же пропорциями, что ваше видео. У версии 2.5 длина точно как у видео, у семейства 2.0 до целой секунды вверх.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_extend"></a>Продление видео

> Модель продолжает ваше видео новым куском заданной длины, после ролика или перед ним. Приходят два ролика: новый кусок и он же, склеенный с вашим видео.

Значение поля mode: `video_extend`

На этой странице версия Seedance 2.0: передайте model = seedance_2. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в новом куске: от 3 до 20 000 символов, можно на разных языках. Напишите и то, что видео нужно продлить, и в какую сторону.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2` (Pro 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`, `4k`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина нового куска в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду, и к ней добавляются секунды вашего видео.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

В правке и продлении видео черновика нет: оставьте false.

- Тип: Да/нет
- По умолчанию: `false`

#### `video_urls` (Обязательно)

Ссылка на видео, которое нужно продлить. От 2 до 30 секунд у версии 2.5, до 15 у семейства 2.0. В описании это @video1.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `extend_direction` (Необязательно)

С какой стороны приклеить новый кусок к вашему видео: forward после ролика, backward перед ним. Модель направление берёт из описания, поэтому напишите его и там.

- Тип: Строка
- Допустимые значения: `forward` (После ролика), `backward` (Перед роликом)
- По умолчанию: `"forward"`

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Видео передаётся ссылкой на MP4, MOV: у версии 2.5 до 200 МБ и не длиннее 30 секунд, у семейства 2.0 до 50 МБ и не длиннее 15 секунд. От 2 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Направление модель понимает из описания: напишите, что видео нужно продлить, и что происходит дальше, а для продления назад «продли назад» и что было до начала. extend_direction задаёт только, с какой стороны мы приклеим новый кусок к вашему видео.
- На Канале 1 продлевать умеет только версия 2.5: для семейства 2.0 выберите Канал 2.
- Видео уходит в модель как есть и целиком: нужен другой кусок, обрежьте файл заранее. К длине нового куска в цене добавляются секунды вашего видео, неполная секунда считается целой. На Канале 2 цена не ниже порога, который растёт с длиной куска.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании ваше видео это @video1, а фото и звук идут по порядку ссылок: @image1, @audio1 и так далее.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4, mov | 1 | 200 МБ |
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Что было дальше

```json
{
  "model": "seedance",
  "settings": {
    "mode": "video_extend",
    "prompt": "Продли @video1: кораблик проплывает под мостиком и скрывается за поворотом",
    "video_urls": [
      "https://example.com/boat.mp4"
    ],
    "duration": 5,
    "channel": "channel_2",
    "model": "seedance_2"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- Первым приходит новый кусок, вторым он же, склеенный с вашим видео в сторону extend_direction. Склейка той же высоты и ширины, что новый кусок, звук вашего видео сохраняется.
- Если склеить не вышло, приходит только новый кусок, а в texts пояснение. Оплата та же: кусок готов.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 | Новый кусок. |
| `video` | mp4 | 0 или 1 | Ваше видео и новый кусок одним роликом. Нет, если склеить не вышло. |

`result.texts`: Пояснение, если склеить не вышло.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Seedance 2.0: возможности и цены](https://api.cyhub.ai/models/seedance-2)
- Другие версии: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Seedance 2.0 Fast API](https://api.cyhub.ai/models/seedance-2-fast/api.md), [Seedance 2.0 Mini API](https://api.cyhub.ai/models/seedance-2-mini/api.md)
- Похожие модели: [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Seedance 2.0 Fast API

> Видео Seedance 2.0 Fast от ByteDance со звуком: по описанию, по первому и последнему кадру или по референсам, до 15 секунд. Быстрая версия, качество 480p или 720p. Референсы: фото, видео и аудио. Своё видео можно отредактировать описанием, а на Канале 2 и продлить вперёд или назад. Два канала: обычный и, как правило, подешевле.

Разработчик: ByteDance
Ключ модели в API: `seedance`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Бумажный кораблик плывёт по весеннему ручью, крупный план",
    "model": "seedance_2_fast",
    "quality": "480p",
    "duration": 5,
    "aspect_ratio": "9:16",
    "channel": "channel_2"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "seedance",
    "settings": {
        "mode": "text_to_video",
        "prompt": "Бумажный кораблик плывёт по весеннему ручью, крупный план",
        "model": "seedance_2_fast",
        "quality": "480p",
        "duration": 5,
        "aspect_ratio": "9:16",
        "channel": "channel_2",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Бумажный кораблик плывёт по весеннему ручью, крупный план",
    "model": "seedance_2_fast",
    "quality": "480p",
    "duration": 5,
    "aspect_ratio": "9:16",
    "channel": "channel_2"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Бумажный кораблик плывёт по весеннему ручью, крупный план",
    "model": "seedance_2_fast",
    "quality": "480p",
    "duration": 5,
    "aspect_ratio": "9:16",
    "channel": "channel_2"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_video"></a>По описанию

> Видео только по тексту, файлы не передаются.

Значение поля mode: `text_to_video`

На этой странице версия Seedance 2.0 Fast: передайте model = seedance_2_fast. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_fast` (Fast 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `aspect_ratio` (Необязательно)

Пропорции видео. adaptive есть только у версии 2.5: пропорции подбирает сама модель по описанию.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`
- По умолчанию: `"16:9"`

#### `web_search` (Необязательно)

Онлайн-поиск: модель подтянет свежие сведения из интернета. Только на Канале 1.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Подешевле, через Канал 2

```json
{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Бумажный кораблик плывёт по весеннему ручью, крупный план",
    "model": "seedance_2_fast",
    "quality": "480p",
    "duration": 5,
    "aspect_ratio": "9:16",
    "channel": "channel_2"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_video"></a>По кадрам

> Первый кадр или первый и последний: модель оживляет их по описанию.

Значение поля mode: `image_to_video`

На этой странице версия Seedance 2.0 Fast: передайте model = seedance_2_fast. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_fast` (Fast 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `image_urls` (Обязательно)

Одна ссылка: первый кадр. Две ссылки: первый и последний кадры.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

#### `aspect_ratio` (Необязательно)

Пропорции видео, работают только у семейства 2.0 на Канале 1. У версии 2.5 и на Канале 2 у любой версии размер ролика задаёт первый кадр, и выбранное значение не учитывается: у 2.5 выбор здесь один, adaptive.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`
- По умолчанию: `"16:9"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- На Канале 2 размер ролика задаёт кадр у любой версии.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 2 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить кадр

```json
{
  "model": "seedance",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Девушка поворачивается к камере и улыбается, волосы развеваются на ветру",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "duration": 5,
    "model": "seedance_2_fast"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="multimodal"></a>По референсам

> Персонажи, стиль, движение и звук с ваших фото, видео и аудио в новом ролике. Нужно хотя бы одно фото или видео.

Значение поля mode: `multimodal`

На этой странице версия Seedance 2.0 Fast: передайте model = seedance_2_fast. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_fast` (Fast 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `aspect_ratio` (Необязательно)

Пропорции видео. adaptive есть только у версии 2.5: пропорции подбирает сама модель по описанию и референсам. На Канале 2 с видео-референсами так у любой версии, и выбранное значение не учитывается.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`
- По умолчанию: `"16:9"`

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `video_urls` (Необязательно)

Ссылки на видео-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Каждое видео уходит в модель целиком, и его секунды добавляются к цене.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Видео передаются ссылками на MP4, MOV: у версии 2.5 до 200 МБ каждое и вместе не длиннее 30 секунд, у семейства 2.0 до 50 МБ и вместе не длиннее 15 секунд. Каждое от 2 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Файлы уходят в модель как есть и целиком. К длине ролика в цене добавляются секунды всех видео-референсов, неполная секунда каждого видео считается целой. На Канале 2 цена с видео не ниже порога, который растёт с длиной ролика.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании на файлы можно ссылаться по порядку ссылок каждого вида: @image1, @video1, @audio1 и так далее.
- На Канале 2 с видео-референсами пропорции подбирает сама модель у любой версии.
- Изменить или продлить само видео: режимы video_edit и video_extend. Здесь видео только образец, но у версии 2.5 на Канале 1 описание правки модель может принять за правку и отказать: тогда выберите video_edit.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `video_urls` | Видео | mp4, mov | 10 | 200 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Персонаж и движение камеры

```json
{
  "model": "seedance",
  "settings": {
    "mode": "multimodal",
    "prompt": "Девушка с @image1 идёт по ночному городу под дождём, камера движется как в @video1",
    "image_urls": [
      "https://example.com/girl.png"
    ],
    "video_urls": [
      "https://example.com/camera-move.mp4"
    ],
    "duration": 8,
    "model": "seedance_2_fast"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_edit"></a>Правка видео

> Модель меняет ваше видео по описанию: заменить предмет или персонажа, фон, стиль. Остальное остаётся как было, длина и пропорции как у видео.

Значение поля mode: `video_edit`

На этой странице версия Seedance 2.0 Fast: передайте model = seedance_2_fast. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что поменять в видео: от 3 до 20 000 символов, можно на разных языках. Остальное в видео останется как было.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_fast` (Fast 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Не действует: ролик выходит той же длины, что ваше видео.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

В правке и продлении видео черновика нет: оставьте false.

- Тип: Да/нет
- По умолчанию: `false`

#### `video_urls` (Обязательно)

Ссылка на видео, которое нужно изменить. От 4 до 30 секунд у версии 2.5, до 15 у семейства 2.0. В описании это @video1.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Видео передаётся ссылкой на MP4, MOV: у версии 2.5 до 200 МБ и не длиннее 30 секунд, у семейства 2.0 до 50 МБ и не длиннее 15 секунд. От 4 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Видео уходит в модель как есть и целиком: нужен другой кусок, обрежьте файл заранее. Цена считается по длине видео: столько же секунд у нового ролика, и ещё столько же добавляет само видео на входе, неполная секунда считается целой.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании ваше видео это @video1, а фото и звук идут по порядку ссылок: @image1, @audio1 и так далее.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4, mov | 1 | 200 МБ |
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Заменить предмет в видео

```json
{
  "model": "seedance",
  "settings": {
    "mode": "video_edit",
    "prompt": "Замени красный кораблик в @video1 на жёлтую резиновую уточку",
    "video_urls": [
      "https://example.com/boat.mp4"
    ],
    "model": "seedance_2_fast"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- Ролик той же длины и с теми же пропорциями, что ваше видео. У версии 2.5 длина точно как у видео, у семейства 2.0 до целой секунды вверх.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_extend"></a>Продление видео

> Модель продолжает ваше видео новым куском заданной длины, после ролика или перед ним. Приходят два ролика: новый кусок и он же, склеенный с вашим видео.

Значение поля mode: `video_extend`

На этой странице версия Seedance 2.0 Fast: передайте model = seedance_2_fast. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в новом куске: от 3 до 20 000 символов, можно на разных языках. Напишите и то, что видео нужно продлить, и в какую сторону.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_fast` (Fast 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина нового куска в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду, и к ней добавляются секунды вашего видео.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

В правке и продлении видео черновика нет: оставьте false.

- Тип: Да/нет
- По умолчанию: `false`

#### `video_urls` (Обязательно)

Ссылка на видео, которое нужно продлить. От 2 до 30 секунд у версии 2.5, до 15 у семейства 2.0. В описании это @video1.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `extend_direction` (Необязательно)

С какой стороны приклеить новый кусок к вашему видео: forward после ролика, backward перед ним. Модель направление берёт из описания, поэтому напишите его и там.

- Тип: Строка
- Допустимые значения: `forward` (После ролика), `backward` (Перед роликом)
- По умолчанию: `"forward"`

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Видео передаётся ссылкой на MP4, MOV: у версии 2.5 до 200 МБ и не длиннее 30 секунд, у семейства 2.0 до 50 МБ и не длиннее 15 секунд. От 2 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Направление модель понимает из описания: напишите, что видео нужно продлить, и что происходит дальше, а для продления назад «продли назад» и что было до начала. extend_direction задаёт только, с какой стороны мы приклеим новый кусок к вашему видео.
- На Канале 1 продлевать умеет только версия 2.5: для семейства 2.0 выберите Канал 2.
- Видео уходит в модель как есть и целиком: нужен другой кусок, обрежьте файл заранее. К длине нового куска в цене добавляются секунды вашего видео, неполная секунда считается целой. На Канале 2 цена не ниже порога, который растёт с длиной куска.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании ваше видео это @video1, а фото и звук идут по порядку ссылок: @image1, @audio1 и так далее.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4, mov | 1 | 200 МБ |
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Что было дальше

```json
{
  "model": "seedance",
  "settings": {
    "mode": "video_extend",
    "prompt": "Продли @video1: кораблик проплывает под мостиком и скрывается за поворотом",
    "video_urls": [
      "https://example.com/boat.mp4"
    ],
    "duration": 5,
    "channel": "channel_2",
    "model": "seedance_2_fast"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- Первым приходит новый кусок, вторым он же, склеенный с вашим видео в сторону extend_direction. Склейка той же высоты и ширины, что новый кусок, звук вашего видео сохраняется.
- Если склеить не вышло, приходит только новый кусок, а в texts пояснение. Оплата та же: кусок готов.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 | Новый кусок. |
| `video` | mp4 | 0 или 1 | Ваше видео и новый кусок одним роликом. Нет, если склеить не вышло. |

`result.texts`: Пояснение, если склеить не вышло.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Seedance 2.0 Fast: возможности и цены](https://api.cyhub.ai/models/seedance-2-fast)
- Другие версии: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Seedance 2.0 API](https://api.cyhub.ai/models/seedance-2/api.md), [Seedance 2.0 Mini API](https://api.cyhub.ai/models/seedance-2-mini/api.md)
- Похожие модели: [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Seedance 2.0 Mini API

> Видео Seedance 2.0 Mini от ByteDance со звуком: по описанию, по первому и последнему кадру или по референсам, до 15 секунд. Самая дешёвая версия Seedance, качество 480p или 720p. Референсы: фото, видео и аудио. Своё видео можно отредактировать описанием, а на Канале 2 и продлить вперёд или назад. Два канала: обычный и, как правило, подешевле.

Разработчик: ByteDance
Ключ модели в API: `seedance`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2_mini",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "seedance",
    "settings": {
        "mode": "text_to_video",
        "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
        "model": "seedance_2_mini",
        "quality": "720p",
        "duration": 8,
        "aspect_ratio": "16:9",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2_mini",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2_mini",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_video"></a>По описанию

> Видео только по тексту, файлы не передаются.

Значение поля mode: `text_to_video`

На этой странице версия Seedance 2.0 Mini: передайте model = seedance_2_mini. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_mini` (Mini 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `aspect_ratio` (Необязательно)

Пропорции видео. adaptive есть только у версии 2.5: пропорции подбирает сама модель по описанию.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`
- По умолчанию: `"16:9"`

#### `web_search` (Необязательно)

Онлайн-поиск: модель подтянет свежие сведения из интернета. Только на Канале 1.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "seedance",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот в очках играет на баяне на летней веранде, камера медленно наезжает",
    "model": "seedance_2_mini",
    "quality": "720p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_video"></a>По кадрам

> Первый кадр или первый и последний: модель оживляет их по описанию.

Значение поля mode: `image_to_video`

На этой странице версия Seedance 2.0 Mini: передайте model = seedance_2_mini. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_mini` (Mini 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `image_urls` (Обязательно)

Одна ссылка: первый кадр. Две ссылки: первый и последний кадры.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

#### `aspect_ratio` (Необязательно)

Пропорции видео, работают только у семейства 2.0 на Канале 1. У версии 2.5 и на Канале 2 у любой версии размер ролика задаёт первый кадр, и выбранное значение не учитывается: у 2.5 выбор здесь один, adaptive.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`
- По умолчанию: `"16:9"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- На Канале 2 размер ролика задаёт кадр у любой версии.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 2 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить кадр

```json
{
  "model": "seedance",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Девушка поворачивается к камере и улыбается, волосы развеваются на ветру",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "duration": 5,
    "model": "seedance_2_mini"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="multimodal"></a>По референсам

> Персонажи, стиль, движение и звук с ваших фото, видео и аудио в новом ролике. Нужно хотя бы одно фото или видео.

Значение поля mode: `multimodal`

На этой странице версия Seedance 2.0 Mini: передайте model = seedance_2_mini. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: от 3 до 20 000 символов, можно на разных языках.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_mini` (Mini 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

Черновик: недорогой ролик в 480p, чтобы до дорогого качества проверить сцену, движение и звук. Стоит как обычный ролик 480p, поле quality для него не действует. Есть только у версии 2.5 на Канале 2: с другой версией или каналом задача не принимается. Если черновик понравился, его можно один раз пересобрать в 1080p режимом upscale_draft в течение 7 дней после создания: сцена, движение и звук останутся теми же, а пересборка стоит как обычный ролик 1080p.

- Тип: Да/нет
- По умолчанию: `false`

#### `aspect_ratio` (Необязательно)

Пропорции видео. adaptive есть только у версии 2.5: пропорции подбирает сама модель по описанию и референсам. На Канале 2 с видео-референсами так у любой версии, и выбранное значение не учитывается.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`
- По умолчанию: `"16:9"`

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `video_urls` (Необязательно)

Ссылки на видео-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Каждое видео уходит в модель целиком, и его секунды добавляются к цене.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Видео передаются ссылками на MP4, MOV: у версии 2.5 до 200 МБ каждое и вместе не длиннее 30 секунд, у семейства 2.0 до 50 МБ и вместе не длиннее 15 секунд. Каждое от 2 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Файлы уходят в модель как есть и целиком. К длине ролика в цене добавляются секунды всех видео-референсов, неполная секунда каждого видео считается целой. На Канале 2 цена с видео не ниже порога, который растёт с длиной ролика.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании на файлы можно ссылаться по порядку ссылок каждого вида: @image1, @video1, @audio1 и так далее.
- На Канале 2 с видео-референсами пропорции подбирает сама модель у любой версии.
- Изменить или продлить само видео: режимы video_edit и video_extend. Здесь видео только образец, но у версии 2.5 на Канале 1 описание правки модель может принять за правку и отказать: тогда выберите video_edit.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `video_urls` | Видео | mp4, mov | 10 | 200 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Персонаж и движение камеры

```json
{
  "model": "seedance",
  "settings": {
    "mode": "multimodal",
    "prompt": "Девушка с @image1 идёт по ночному городу под дождём, камера движется как в @video1",
    "image_urls": [
      "https://example.com/girl.png"
    ],
    "video_urls": [
      "https://example.com/camera-move.mp4"
    ],
    "duration": 8,
    "model": "seedance_2_mini"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- С draft: true приходит черновик в 480p. У такой задачи есть поле draft: до какого времени её можно пересобрать в 1080p, можно ли сейчас и готовый запрос для пересборки.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_edit"></a>Правка видео

> Модель меняет ваше видео по описанию: заменить предмет или персонажа, фон, стиль. Остальное остаётся как было, длина и пропорции как у видео.

Значение поля mode: `video_edit`

На этой странице версия Seedance 2.0 Mini: передайте model = seedance_2_mini. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что поменять в видео: от 3 до 20 000 символов, можно на разных языках. Остальное в видео останется как было.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_mini` (Mini 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Не действует: ролик выходит той же длины, что ваше видео.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

В правке и продлении видео черновика нет: оставьте false.

- Тип: Да/нет
- По умолчанию: `false`

#### `video_urls` (Обязательно)

Ссылка на видео, которое нужно изменить. От 4 до 30 секунд у версии 2.5, до 15 у семейства 2.0. В описании это @video1.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Видео передаётся ссылкой на MP4, MOV: у версии 2.5 до 200 МБ и не длиннее 30 секунд, у семейства 2.0 до 50 МБ и не длиннее 15 секунд. От 4 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Видео уходит в модель как есть и целиком: нужен другой кусок, обрежьте файл заранее. Цена считается по длине видео: столько же секунд у нового ролика, и ещё столько же добавляет само видео на входе, неполная секунда считается целой.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании ваше видео это @video1, а фото и звук идут по порядку ссылок: @image1, @audio1 и так далее.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4, mov | 1 | 200 МБ |
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Заменить предмет в видео

```json
{
  "model": "seedance",
  "settings": {
    "mode": "video_edit",
    "prompt": "Замени красный кораблик в @video1 на жёлтую резиновую уточку",
    "video_urls": [
      "https://example.com/boat.mp4"
    ],
    "model": "seedance_2_mini"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- Ролик той же длины и с теми же пропорциями, что ваше видео. У версии 2.5 длина точно как у видео, у семейства 2.0 до целой секунды вверх.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_extend"></a>Продление видео

> Модель продолжает ваше видео новым куском заданной длины, после ролика или перед ним. Приходят два ролика: новый кусок и он же, склеенный с вашим видео.

Значение поля mode: `video_extend`

На этой странице версия Seedance 2.0 Mini: передайте model = seedance_2_mini. Без поля model запустится seedance_2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в новом куске: от 3 до 20 000 символов, можно на разных языках. Напишите и то, что видео нужно продлить, и в какую сторону.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `model` (Необязательно)

Версия. 2.5 новее всех и делает ролики до 30 секунд, Pro 2.0 единственная с 4K, Fast 2.0 быстрая, Mini 2.0 самая дешёвая.

- Тип: Строка
- Допустимые значения: `seedance_2_mini` (Mini 2.0)
- По умолчанию: `"seedance_2_5"`

#### `quality` (Необязательно)

Качество видео, от него зависит цена. 1080p есть у 2.5 и Pro 2.0, 4K только у Pro 2.0. У черновика (draft) качество всегда 480p, это поле для него не действует.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длина нового куска в секундах: от 4 до 30 у версии 2.5, до 15 у семейства 2.0. Цена за каждую секунду, и к ней добавляются секунды вашего видео.

- Тип: Целое число
- Минимум: 4
- Максимум: 30
- По умолчанию: `5`

#### `generate_audio` (Необязательно)

Сгенерировать звук вместе с видео.

- Тип: Да/нет
- По умолчанию: `true`

#### `channel` (Необязательно)

Через какой канал пойдёт генерация: модель та же, отличаются цена и проверки. Канал 1 обычный и принимает фото людей. Канал 2 обычно дешевле, но отклоняет фотографии реальных людей и запрещённые сюжеты, и онлайн-поиска у него нет. С видео на входе у Канала 2 есть нижний порог цены, растущий с длиной ролика, и с коротким видео он может выйти дороже. Отказ канала не оплачивается.

- Тип: Строка
- Допустимые значения: `channel_1` (Канал 1), `channel_2` (Канал 2)
- По умолчанию: `"channel_1"`

#### `draft` (Необязательно)

В правке и продлении видео черновика нет: оставьте false.

- Тип: Да/нет
- По умолчанию: `false`

#### `video_urls` (Обязательно)

Ссылка на видео, которое нужно продлить. От 2 до 30 секунд у версии 2.5, до 15 у семейства 2.0. В описании это @video1.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `extend_direction` (Необязательно)

С какой стороны приклеить новый кусок к вашему видео: forward после ролика, backward перед ним. Модель направление берёт из описания, поэтому напишите его и там.

- Тип: Строка
- Допустимые значения: `forward` (После ролика), `backward` (Перед роликом)
- По умолчанию: `"forward"`

#### `image_urls` (Необязательно)

Ссылки на фото-референсы: до 30 у версии 2.5, до 9 у семейства 2.0.

- Тип: Список (Строка, uri)
- Максимум элементов: 30

#### `audio_urls` (Необязательно)

Ссылки на аудио-референсы: до 10 у версии 2.5, до 3 у семейства 2.0. Аудио только вместе с фото или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Видео передаётся ссылкой на MP4, MOV: у версии 2.5 до 200 МБ и не длиннее 30 секунд, у семейства 2.0 до 50 МБ и не длиннее 15 секунд. От 2 секунд, от 24 до 60 кадров в секунду и не меньше 407 696 точек в кадре (например, 640×640 или 480×854).
- Картинки передаются ссылками на JPEG, PNG, WEBP, BMP, TIFF, GIF до 30 МБ каждая, стороны от 300 до 6 000 пикселей.
- Аудио передаётся ссылками на WAV, MP3 до 15 МБ каждое: у версии 2.5 от 2 до 30 секунд и все вместе не длиннее 30, у семейства 2.0 от 2 до 15 секунд и все вместе не длиннее 15.
- У семейства 2.0 не больше 12 файлов всех видов вместе.
- Направление модель понимает из описания: напишите, что видео нужно продлить, и что происходит дальше, а для продления назад «продли назад» и что было до начала. extend_direction задаёт только, с какой стороны мы приклеим новый кусок к вашему видео.
- На Канале 1 продлевать умеет только версия 2.5: для семейства 2.0 выберите Канал 2.
- Видео уходит в модель как есть и целиком: нужен другой кусок, обрежьте файл заранее. К длине нового куска в цене добавляются секунды вашего видео, неполная секунда считается целой. На Канале 2 цена не ниже порога, который растёт с длиной куска.
- Длину видео для цены мы узнаём, скачав его по ссылке, поэтому ссылка должна вести прямо на файл, без переадресации, и отдавать его быстро. Иначе цену не посчитать, и задача не принимается.
- В описании ваше видео это @video1, а фото и звук идут по порядку ссылок: @image1, @audio1 и так далее.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4, mov | 1 | 200 МБ |
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, gif | 30 | 30 МБ |
| `audio_urls` | Аудио | wav, mp3 | 10 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Что было дальше

```json
{
  "model": "seedance",
  "settings": {
    "mode": "video_extend",
    "prompt": "Продли @video1: кораблик проплывает под мостиком и скрывается за поворотом",
    "video_urls": [
      "https://example.com/boat.mp4"
    ],
    "duration": 5,
    "channel": "channel_2",
    "model": "seedance_2_mini"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Видео MP4.
- Генерация обычно занимает несколько минут, длинные ролики и высокое качество дольше.
- Первым приходит новый кусок, вторым он же, склеенный с вашим видео в сторону extend_direction. Склейка той же высоты и ширины, что новый кусок, звук вашего видео сохраняется.
- Если склеить не вышло, приходит только новый кусок, а в texts пояснение. Оплата та же: кусок готов.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 | Новый кусок. |
| `video` | mp4 | 0 или 1 | Ваше видео и новый кусок одним роликом. Нет, если склеить не вышло. |

`result.texts`: Пояснение, если склеить не вышло.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Seedance 2.0 Mini: возможности и цены](https://api.cyhub.ai/models/seedance-2-mini)
- Другие версии: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Seedance 2.0 API](https://api.cyhub.ai/models/seedance-2/api.md), [Seedance 2.0 Fast API](https://api.cyhub.ai/models/seedance-2-fast/api.md)
- Похожие модели: [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Suno V6 API

> Песни и звуки Suno V6 с нуля по описанию или со своим текстом: за один запуск два варианта трека в MP3. По вашему аудио: добавить вокал или музыку, кавер, продолжение, замена куска, ремикс двух треков. Есть ещё версии V6 Mini и V6 Wild.

Разработчик: Suno
Ключ модели в API: `suno`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "suno",
  "settings": {
    "mode": "generate",
    "model": "V6",
    "customMode": false,
    "songDescription": "Лёгкая летняя песня о дороге к морю, акустическая гитара, женский вокал"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "suno",
    "settings": {
        "mode": "generate",
        "model": "V6",
        "customMode": False,
        "songDescription": "Лёгкая летняя песня о дороге к морю, акустическая гитара, женский вокал",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "suno",
  "settings": {
    "mode": "generate",
    "model": "V6",
    "customMode": false,
    "songDescription": "Лёгкая летняя песня о дороге к морю, акустическая гитара, женский вокал"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "suno",
  "settings": {
    "mode": "generate",
    "model": "V6",
    "customMode": false,
    "songDescription": "Лёгкая летняя песня о дороге к морю, акустическая гитара, женский вокал"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="generate"></a>Песня с нуля

> Песня по короткому описанию или со своим текстом, стилем и названием.

Значение поля mode: `generate`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model` (Необязательно)

Версия модели.

- Тип: Строка
- Допустимые значения: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild)
- По умолчанию: `"V6"`

#### `customMode` (Необязательно)

Расширенный режим: свой текст песни, стиль, название и длительность. Выключен: достаточно описания песни.

- Тип: Да/нет
- По умолчанию: `false`

#### `songDescription` (Необязательно)

Описание песни для простого режима: о чём она, настроение, жанр. Обязательно, когда customMode выключен.

- Тип: Строка
- Максимум символов: 3000

#### `title` (Необязательно)

Название песни. Обязательно в расширенном режиме, в простом не задаётся.

- Тип: Строка
- Максимум символов: 80

#### `style` (Необязательно)

Стиль и жанр словами. Обязательно в расширенном режиме, в простом не задаётся.

- Тип: Строка
- Максимум символов: 1000

#### `prompt` (Необязательно)

Текст песни для расширенного режима. Обязателен, если песня не инструментальная. В простом режиме не задаётся: там песню задаёт описание.

- Тип: Строка
- Максимум символов: 5000

#### `instrumental` (Необязательно)

Без вокала.

- Тип: Да/нет
- По умолчанию: `false`

#### `vocalGender` (Необязательно)

Голос исполнителя, только в расширенном режиме.

- Тип: Строка
- Допустимые значения: `m` (Мужской), `f` (Женский)
- По умолчанию: `"m"`

#### `duration` (Необязательно)

Длительность в секундах, только в расширенном режиме.

- Тип: Целое число
- Минимум: 10
- Максимум: 360
- По умолчанию: `20`

#### `styleWeight` (Необязательно)

Насколько строго держаться заданного стиля: 0 свободно, 1 строго, не точнее сотых. Только в расширенном режиме.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `weirdnessConstraint` (Необязательно)

Насколько смелым выйдет результат: 0 предсказуемо, 1 экспериментально, не точнее сотых. Только в расширенном режиме.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `audioWeight` (Необязательно)

Вес звуковых особенностей в результате: 0 слабо, 1 сильно, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Простой режим: описание песни, остальное придумает модель. Название, стиль и текст песни в нём не задаются.
- Расширенный режим: название и стиль обязательны, текст песни обязателен, если она не инструментальная.
- Голос, длительность, вес стиля и необычность действуют только в расширенном режиме: в простом они не отправляются.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Песня по описанию

```json
{
  "model": "suno",
  "settings": {
    "mode": "generate",
    "model": "V6",
    "customMode": false,
    "songDescription": "Лёгкая летняя песня о дороге к морю, акустическая гитара, женский вокал"
  }
}
```

Песня со своим текстом

```json
{
  "model": "suno",
  "settings": {
    "mode": "generate",
    "model": "V6",
    "customMode": true,
    "title": "Дорога к морю",
    "style": "акустический поп, лето",
    "prompt": "Куплет 1: ...\nПрипев: ...",
    "instrumental": false,
    "vocalGender": "f",
    "duration": 120
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- За один запуск две версии трека в MP3, а текстом название и слова, если они есть.
- Песня создаётся от 5 до 10 минут, звук около минуты.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` | mp3 | 2 | Две версии трека. |

`result.texts`: Название и слова песни, если они есть.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="sounds"></a>Звук или фон

> Не песня, а звук: шум дождя, гул города, эффект для игры. Можно зациклить, задать темп и тональность.

Значение поля mode: `sounds`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model` (Необязательно)

Версия модели.

- Тип: Строка
- Допустимые значения: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild)
- По умолчанию: `"V6"`

#### `soundDescription` (Обязательно)

Что должно звучать, например шум дождя по крыше или шаги по снегу. Слов в звуке не будет.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 500

#### `soundLoop` (Необязательно)

Свести звук так, чтобы конец без щелчка переходил в начало: для фона, который играет по кругу.

- Тип: Да/нет
- По умолчанию: `false`

#### `soundTempo` (Необязательно)

Темп в ударах в минуту. Не задан: темп выберет модель.

- Тип: Целое число
- Минимум: 1
- Максимум: 300

#### `soundKey` (Необязательно)

Тональность: буква это мажор, буква с m это минор (Am это ля минор). Пустая строка: любая.

- Тип: Строка
- Допустимые значения: `""` (Любая), `C`, `C#`, `D`, `D#`, `E`, `F`, `F#`, `G`, `G#`, `A`, `A#`, `B`, `Cm`, `C#m`, `Dm`, `D#m`, `Em`, `Fm`, `F#m`, `Gm`, `G#m`, `Am`, `A#m`, `Bm`
- По умолчанию: `""`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Фон для ролика

```json
{
  "model": "suno",
  "settings": {
    "mode": "sounds",
    "soundDescription": "Шум дождя по жестяной крыше, далёкие раскаты грома",
    "soundLoop": true
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- За один запуск две версии трека в MP3, а текстом название и слова, если они есть.
- Песня создаётся от 5 до 10 минут, звук около минуты.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` | mp3 | 2 | Две версии трека. |

`result.texts`: Название и слова песни, если они есть.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="add_vocals"></a>Добавить вокал

> Вокал поверх вашей музыки без голоса: модель споёт ваш текст в заданном стиле.

Значение поля mode: `add_vocals`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model` (Необязательно)

Версия модели.

- Тип: Строка
- Допустимые значения: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild)
- По умолчанию: `"V6"`

#### `audio` (Обязательно)

Одна ссылка на вашу музыку без вокала.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `title` (Обязательно)

Название трека. Обязательно.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 80

#### `style` (Обязательно)

Стиль и жанр словами. Обязательно.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1000

#### `prompt` (Обязательно)

Слова, которые споёт вокал.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `negativeTags` (Обязательно)

Каких стилей в результате быть не должно, через запятую. Обязательно.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 500

#### `vocalGender` (Необязательно)

Пол вокалиста: m мужской, f женский. Только повышает вероятность, не гарантирует. Не задан: решает модель.

- Тип: Строка
- Допустимые значения: `""` (Не задан), `m` (Мужской), `f` (Женский)
- По умолчанию: `""`

#### `styleWeight` (Необязательно)

Насколько строго держаться заданного стиля: 0 свободно, 1 строго, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `weirdnessConstraint` (Необязательно)

Насколько смелым выйдет результат: 0 предсказуемо, 1 экспериментально, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `audioWeight` (Необязательно)

Насколько результат держится звучания исходника: 0 слабо, 1 сильно, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Аудио передаётся ссылкой на MP3, WAV, OGG, M4A, FLAC или AAC до 20 МБ.
- Только своё аудио: известные чужие песни Suno узнаёт и отказывается обрабатывать.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio` | Аудио | mp3, wav, ogg, m4a, flac, aac | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Вокал на свою музыку

```json
{
  "model": "suno",
  "settings": {
    "mode": "add_vocals",
    "audio": [
      "https://example.com/my-instrumental.mp3"
    ],
    "title": "Ночной город",
    "style": "синти-поп, мягкий женский вокал",
    "prompt": "Куплет 1: ...\nПрипев: ...",
    "negativeTags": "хеви-метал, рэп"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- За один запуск две версии трека в MP3, а текстом название и слова, если они есть.
- Песня создаётся от 5 до 10 минут, звук около минуты.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` | mp3 | 2 | Две версии трека. |

`result.texts`: Название и слова песни, если они есть.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="add_instrumental"></a>Добавить инструментал

> Музыка под ваш вокал, записанный без аккомпанемента.

Значение поля mode: `add_instrumental`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model` (Необязательно)

Версия модели.

- Тип: Строка
- Допустимые значения: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild)
- По умолчанию: `"V6"`

#### `audio` (Обязательно)

Одна ссылка на ваш вокал без музыки.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `title` (Обязательно)

Название трека. Обязательно.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 80

#### `tags` (Обязательно)

Стиль музыки словами: жанр, инструменты, настроение. Обязательно.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 500

#### `negativeTags` (Обязательно)

Каких стилей в результате быть не должно, через запятую. Обязательно.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 500

#### `vocalGender` (Необязательно)

Пол вокалиста: m мужской, f женский. Только повышает вероятность, не гарантирует. Не задан: решает модель.

- Тип: Строка
- Допустимые значения: `""` (Не задан), `m` (Мужской), `f` (Женский)
- По умолчанию: `""`

#### `styleWeight` (Необязательно)

Насколько строго держаться заданного стиля: 0 свободно, 1 строго, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `weirdnessConstraint` (Необязательно)

Насколько смелым выйдет результат: 0 предсказуемо, 1 экспериментально, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `audioWeight` (Необязательно)

Насколько результат держится звучания исходника: 0 слабо, 1 сильно, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Аудио передаётся ссылкой на MP3, WAV, OGG, M4A, FLAC или AAC до 20 МБ.
- Только своё аудио: известные чужие песни Suno узнаёт и отказывается обрабатывать.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio` | Аудио | mp3, wav, ogg, m4a, flac, aac | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Музыка под свой голос

```json
{
  "model": "suno",
  "settings": {
    "mode": "add_instrumental",
    "audio": [
      "https://example.com/my-vocals.mp3"
    ],
    "title": "Колыбельная",
    "tags": "нежное фортепиано, струнные",
    "negativeTags": "барабаны, электроника"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- За один запуск две версии трека в MP3, а текстом название и слова, если они есть.
- Песня создаётся от 5 до 10 минут, звук около минуты.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` | mp3 | 2 | Две версии трека. |

`result.texts`: Название и слова песни, если они есть.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="cover_upload"></a>Кавер вашего аудио

> Мелодия вашего трека остаётся, стиль меняется. Как у песни с нуля: по описанию или со своим текстом, стилем и названием.

Значение поля mode: `cover_upload`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model` (Необязательно)

Версия модели.

- Тип: Строка
- Допустимые значения: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild)
- По умолчанию: `"V6"`

#### `audio` (Обязательно)

Одна ссылка на ваш трек.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `customMode` (Необязательно)

Расширенный режим: свой текст песни, стиль, название и длительность. Выключен: достаточно описания песни.

- Тип: Да/нет
- По умолчанию: `false`

#### `songDescription` (Необязательно)

Описание песни для простого режима: о чём она, настроение, жанр. Обязательно, когда customMode выключен.

- Тип: Строка
- Максимум символов: 3000

#### `title` (Необязательно)

Название песни. Обязательно в расширенном режиме, в простом не задаётся.

- Тип: Строка
- Максимум символов: 80

#### `style` (Необязательно)

Стиль и жанр словами. Обязательно в расширенном режиме, в простом не задаётся.

- Тип: Строка
- Максимум символов: 1000

#### `prompt` (Необязательно)

Текст песни для расширенного режима. Обязателен, если песня не инструментальная. В простом режиме не задаётся: там песню задаёт описание.

- Тип: Строка
- Максимум символов: 5000

#### `instrumental` (Необязательно)

Без вокала.

- Тип: Да/нет
- По умолчанию: `false`

#### `negativeTags` (Необязательно)

Каких стилей в результате быть не должно, через запятую. Только в расширенном режиме.

- Тип: Строка
- Максимум символов: 500

#### `duration` (Необязательно)

Длительность в секундах, только в расширенном режиме.

- Тип: Целое число
- Минимум: 10
- Максимум: 360
- По умолчанию: `20`

#### `styleWeight` (Необязательно)

Насколько строго держаться заданного стиля: 0 свободно, 1 строго, не точнее сотых. Только в расширенном режиме.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `weirdnessConstraint` (Необязательно)

Насколько смелым выйдет результат: 0 предсказуемо, 1 экспериментально, не точнее сотых. Только в расширенном режиме.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `audioWeight` (Необязательно)

Насколько результат держится звучания исходника: 0 слабо, 1 сильно, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Аудио передаётся ссылкой на MP3, WAV, OGG, M4A, FLAC или AAC до 20 МБ.
- Только своё аудио: известные чужие песни Suno узнаёт и отказывается обрабатывать.
- Трек не длиннее 8 минут.
- Простой режим: описание песни, остальное придумает модель. Название, стиль и текст песни в нём не задаются.
- Расширенный режим: название и стиль обязательны, текст песни обязателен, если она не инструментальная.
- Длительность, вес стиля и необычность действуют только в расширенном режиме: в простом они не отправляются.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio` | Аудио | mp3, wav, ogg, m4a, flac, aac | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Кавер в другом стиле

```json
{
  "model": "suno",
  "settings": {
    "mode": "cover_upload",
    "audio": [
      "https://example.com/my-song.mp3"
    ],
    "customMode": false,
    "songDescription": "Та же мелодия в стиле лёгкого джаза, женский вокал"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- За один запуск две версии трека в MP3, а текстом название и слова, если они есть.
- Песня создаётся от 5 до 10 минут, звук около минуты.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` | mp3 | 2 | Две версии трека. |

`result.texts`: Название и слова песни, если они есть.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="extend"></a>Продолжение вашего аудио

> Трек продолжается с нужной секунды. Секунда продолжения обязательна, стиль и название по желанию: без них продолжение держится звучания самого трека.

Значение поля mode: `extend`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model` (Необязательно)

Версия модели.

- Тип: Строка
- Допустимые значения: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild)
- По умолчанию: `"V6"`

#### `audio` (Обязательно)

Одна ссылка на ваш трек.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `title` (Необязательно)

Название трека. По желанию.

- Тип: Строка
- Максимум символов: 100

#### `style` (Необязательно)

Стиль и жанр словами. По желанию.

- Тип: Строка
- Максимум символов: 1000

#### `prompt` (Необязательно)

Слова продолжения. Обязательны, если продолжение не инструментальное.

- Тип: Строка
- Максимум символов: 5000

#### `instrumental` (Необязательно)

Продолжение без вокала.

- Тип: Да/нет
- По умолчанию: `false`

#### `continueAt` (Обязательно)

С какой секунды трека начать продолжение. Раньше конца файла.

- Тип: Число
- Минимум: 1
- Максимум: 480

#### `negativeTags` (Необязательно)

Каких стилей в результате быть не должно, через запятую.

- Тип: Строка
- Максимум символов: 500

#### `vocalGender` (Необязательно)

Пол вокалиста: m мужской, f женский. Только повышает вероятность, не гарантирует. Не задан: решает модель.

- Тип: Строка
- Допустимые значения: `""` (Не задан), `m` (Мужской), `f` (Женский)
- По умолчанию: `""`

#### `styleWeight` (Необязательно)

Насколько строго держаться заданного стиля: 0 свободно, 1 строго, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `weirdnessConstraint` (Необязательно)

Насколько смелым выйдет результат: 0 предсказуемо, 1 экспериментально, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `audioWeight` (Необязательно)

Насколько результат держится звучания исходника: 0 слабо, 1 сильно, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `defaultParamFlag` = `true`

### Входные данные

- Аудио передаётся ссылкой на MP3, WAV, OGG, M4A, FLAC или AAC до 20 МБ.
- Только своё аудио: известные чужие песни Suno узнаёт и отказывается обрабатывать.
- Трек не длиннее 8 минут.
- Секунда продолжения раньше конца трека.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio` | Аудио | mp3, wav, ogg, m4a, flac, aac | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Продолжить свой трек

```json
{
  "model": "suno",
  "settings": {
    "mode": "extend",
    "audio": [
      "https://example.com/my-song.mp3"
    ],
    "title": "Дорога к морю",
    "style": "акустический поп, лето",
    "prompt": "Куплет 3: ...\nПрипев: ...",
    "continueAt": 60
  }
}
```

Продолжить без слов, в звучании трека

```json
{
  "model": "suno",
  "settings": {
    "mode": "extend",
    "audio": [
      "https://example.com/my-song.mp3"
    ],
    "instrumental": true,
    "continueAt": 90
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- За один запуск две версии трека в MP3, а текстом название и слова, если они есть.
- Песня создаётся от 5 до 10 минут, звук около минуты.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` | mp3 | 2 | Две версии трека. |

`result.texts`: Название и слова песни, если они есть.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="replace_upload"></a>Переписать кусок вашего аудио

> Переписывается только выбранный отрезок трека, остальное остаётся и сшивается с новым куском.

Значение поля mode: `replace_upload`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model` (Необязательно)

Версия модели.

- Тип: Строка
- Допустимые значения: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild)
- По умолчанию: `"V6"`

#### `audio` (Обязательно)

Одна ссылка на ваш трек.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `infillStartS` (Обязательно)

Начало куска в секундах, не точнее сотых, например 45.25.

- Тип: Число
- Минимум: 0

#### `infillEndS` (Обязательно)

Конец куска в секундах, не точнее сотых. Кусок не короче 10 секунд и не длиннее половины трека.

- Тип: Число
- Минимум: 0

#### `prompt` (Обязательно)

Новые слова для этого куска.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `fullLyrics` (Обязательно)

Слова всей песни целиком, уже с поправленным куском. Если слов нет, опишите по порядку, что звучит.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `tags` (Обязательно)

Стиль нового куска словами. Обязательно.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 500

#### `title` (Обязательно)

Название трека. Обязательно.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 80

#### `negativeTags` (Необязательно)

Каких стилей в результате быть не должно, через запятую.

- Тип: Строка
- Максимум символов: 500

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Аудио передаётся ссылкой на MP3, WAV, OGG, M4A, FLAC или AAC до 20 МБ.
- Только своё аудио: известные чужие песни Suno узнаёт и отказывается обрабатывать.
- Кусок не короче 10 секунд и не длиннее половины трека.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio` | Аудио | mp3, wav, ogg, m4a, flac, aac | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Новый припев

```json
{
  "model": "suno",
  "settings": {
    "mode": "replace_upload",
    "audio": [
      "https://example.com/my-song.mp3"
    ],
    "infillStartS": 45,
    "infillEndS": 70,
    "prompt": "Новый припев: ...",
    "fullLyrics": "Куплет 1: ...\nНовый припев: ...\nКуплет 2: ...",
    "tags": "поп-рок, энергично",
    "title": "Дорога к морю"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- За один запуск две версии трека в MP3, а текстом название и слова, если они есть.
- Песня создаётся от 5 до 10 минут, звук около минуты.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` | mp3 | 2 | Две версии трека. |

`result.texts`: Название и слова песни, если они есть.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="mashup"></a>Ремикс из двух треков

> Два ваших трека сводятся в один, первый задаёт основу. По описанию или со своим текстом, стилем и названием.

Значение поля mode: `mashup`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model` (Необязательно)

Версия модели.

- Тип: Строка
- Допустимые значения: `V6`, `V6_MINI` (V6 Mini), `V6_WILD` (V6 Wild)
- По умолчанию: `"V6"`

#### `audio` (Обязательно)

Ссылка на первый трек: он задаёт основу.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `audio2` (Обязательно)

Ссылка на второй трек.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `customMode` (Необязательно)

Расширенный режим: свой текст песни, стиль, название и длительность. Выключен: достаточно описания песни.

- Тип: Да/нет
- По умолчанию: `false`

#### `songDescription` (Необязательно)

Описание песни для простого режима: о чём она, настроение, жанр. Обязательно, когда customMode выключен.

- Тип: Строка
- Максимум символов: 3000

#### `title` (Необязательно)

Название песни. Обязательно в расширенном режиме, в простом не задаётся.

- Тип: Строка
- Максимум символов: 80

#### `style` (Необязательно)

Стиль и жанр словами. Обязательно в расширенном режиме, в простом не задаётся.

- Тип: Строка
- Максимум символов: 1000

#### `prompt` (Необязательно)

Текст песни для расширенного режима, по желанию. В простом режиме не задаётся: там песню задаёт описание.

- Тип: Строка
- Максимум символов: 5000

#### `instrumental` (Необязательно)

Без вокала.

- Тип: Да/нет
- По умолчанию: `false`

#### `duration` (Необязательно)

Длительность в секундах, только в расширенном режиме.

- Тип: Целое число
- Минимум: 10
- Максимум: 360
- По умолчанию: `20`

#### `styleWeight` (Необязательно)

Насколько строго держаться заданного стиля: 0 свободно, 1 строго, не точнее сотых. Только в расширенном режиме.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `weirdnessConstraint` (Необязательно)

Насколько смелым выйдет результат: 0 предсказуемо, 1 экспериментально, не точнее сотых. Только в расширенном режиме.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

#### `audioWeight` (Необязательно)

Насколько результат держится звучания исходника: 0 слабо, 1 сильно, не точнее сотых.

- Тип: Число
- Минимум: 0.0
- Максимум: 1.0
- По умолчанию: `0.65`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Аудио передаётся ссылкой на MP3, WAV, OGG, M4A, FLAC или AAC до 20 МБ.
- Только своё аудио: известные чужие песни Suno узнаёт и отказывается обрабатывать.
- Простой режим: описание песни, остальное придумает модель. Название, стиль и текст песни в нём не задаются.
- Расширенный режим: название и стиль обязательны, текст песни по желанию.
- Длительность, вес стиля и необычность действуют только в расширенном режиме: в простом они не отправляются.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio` | Аудио | mp3, wav, ogg, m4a, flac, aac | 1 | 20 МБ |
| `audio2` | Аудио | mp3, wav, ogg, m4a, flac, aac | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Ремикс по описанию

```json
{
  "model": "suno",
  "settings": {
    "mode": "mashup",
    "audio": [
      "https://example.com/track-1.mp3"
    ],
    "audio2": [
      "https://example.com/track-2.mp3"
    ],
    "customMode": false,
    "songDescription": "Танцевальный ремикс, быстрый темп, яркий припев"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- За один запуск две версии трека в MP3, а текстом название и слова, если они есть.
- Песня создаётся от 5 до 10 минут, звук около минуты.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` | mp3 | 2 | Две версии трека. |

`result.texts`: Название и слова песни, если они есть.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Suno V6: возможности и цены](https://api.cyhub.ai/models/suno)
- Похожие модели: [Eleven Music API](https://api.cyhub.ai/models/eleven-music/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# GPT Image 2.5 API

> Картинки GPT Image 2.5 от OpenAI по описанию и по референсам (до 16), до 4K и с прозрачным фоном. Два варианта, Flare и Sunburst, с одинаковыми настройками: тринадцать пропорций и три ступени качества. Описание обязательно.

Разработчик: OpenAI
Ключ модели в API: `images_chatgpt`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-2-5-sunburst",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "images_chatgpt",
    "settings": {
        "model": "gpt-image-2-5-sunburst",
        "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
        "aspect_ratio": "1:1",
        "resolution": "2K",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-2-5-sunburst",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-2-5-sunburst",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="gpt-image-2-5-flare"></a>GPT Image 2.5

> Два варианта версии 2.5 с одинаковыми настройками: тринадцать пропорций, до 4K, три ступени качества, прозрачный фон, до 16 референсов. Описание обязательно.

Значение поля model: `gpt-image-2-5-flare` `gpt-image-2-5-sunburst`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Описание картинки. Обязательно даже с референсами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `quality` (Необязательно)

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

- Тип: Строка
- Допустимые значения: `high` (Высокое), `xhigh` (Очень высокое), `max` (Максимальное)
- По умолчанию: `"high"`

#### `background` (Необязательно)

Фон картинки: авто, прозрачный (PNG) или непрозрачный. С прозрачным фоном цена считается иначе и зависит ещё от числа референсов.

- Тип: Строка
- Допустимые значения: `auto` (Авто), `transparent` (Прозрачный), `opaque` (Непрозрачный)
- По умолчанию: `"auto"`

#### `aspect_ratio` (Необязательно)

Пропорции картинки. Набор зависит от качества и фона.

- Тип: Строка
- Допустимые значения: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`, `27:16`, `16:27`, `9:8`, `8:9`
- Набор зависит от `quality`, `background`.
- Исключения:

  | `quality` | `background` | `aspect_ratio` |
  |---|---|---|
  | `high` | `auto`, `opaque` | и ещё `auto` |
- По умолчанию: `"9:16"`

#### `resolution` (Необязательно)

Разрешение картинки: 1K, 2K или 4K. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `1K`, `2K`, `4K`
- Набор зависит от `quality`, `aspect_ratio`.
- Исключения:

  | `quality` | `aspect_ratio` | `resolution` |
  |---|---|---|
  | `high` | `27:16`, `16:27`, `9:8`, `8:9` | только `1K` |
- По умолчанию: `"1K"`

#### `image_urls` (Необязательно)

Ссылки на референсы, до 16.

- Тип: Список (Строка, uri)
- Максимум элементов: 16

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Референсы передаются ссылками на картинки JPEG, PNG или WebP до 10 МБ каждая.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 16 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Квадратная картинка в 2K

```json
{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-2-5-sunburst",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }
}
```

Наклейка без фона

```json
{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-2-5-flare",
    "prompt": "Рыжий кот в очках, вырезать предмет, фон прозрачный",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  }
}
```

Максимальное качество

```json
{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-2-5-sunburst",
    "prompt": "Витрина ювелирного магазина, отражения и блики на стекле",
    "aspect_ratio": "16:9",
    "resolution": "4K",
    "quality": "max"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка PNG за запуск.
- 4K занимает заметно дольше, до нескольких минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть GPT Image 2.5: возможности и цены](https://api.cyhub.ai/models/gpt-image-2-5)
- Другие версии: [GPT Image 2 API](https://api.cyhub.ai/models/gpt-image-2/api.md), [GPT Image 1.5 API](https://api.cyhub.ai/models/gpt-image-1-5/api.md)
- Похожие модели: [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# GPT Image 2 API

> Картинки GPT Image 2 от OpenAI по описанию и по референсам (до 14), до 4K. Шесть пропорций, результат PNG. Описание можно не давать, если есть референсы.

Разработчик: OpenAI
Ключ модели в API: `images_chatgpt`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-2",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "images_chatgpt",
    "settings": {
        "model": "gpt-image-2",
        "prompt": "Горный хребет на рассвете, туман в долинах",
        "aspect_ratio": "16:9",
        "resolution": "2K",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-2",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-2",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="gpt-image-2"></a>GPT Image 2

> Шесть пропорций, до 4K, до 14 референсов. Описание можно не давать, если есть референсы.

Значение поля model: `gpt-image-2`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Необязательно)

Описание картинки. Можно оставить пустым, если есть референсы.

- Тип: Строка
- Максимум символов: 3000

#### `aspect_ratio` (Необязательно)

Пропорции картинки.

- Тип: Строка
- Допустимые значения: `auto` (Авто), `1:1`, `9:16`, `16:9`, `4:3`, `3:4`
- По умолчанию: `"9:16"`

#### `resolution` (Необязательно)

Разрешение картинки: 1K, 2K или 4K. Часть пропорций даёт не все разрешения. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `1K`, `2K`, `4K`
- Набор зависит от `aspect_ratio`.
- Исключения:

  | `aspect_ratio` | `resolution` |
  |---|---|
  | `auto` | только `1K` |
  | `1:1` | кроме `4K` |
- По умолчанию: `"1K"`

#### `image_urls` (Необязательно)

Ссылки на референсы, до 14.

- Тип: Список (Строка, uri)
- Максимум элементов: 14

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Референсы передаются ссылками на картинки JPEG, PNG или WebP до 10 МБ каждая.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 14 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Широкая картинка в 2K

```json
{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-2",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка PNG за запуск.
- 4K занимает заметно дольше, до нескольких минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть GPT Image 2: возможности и цены](https://api.cyhub.ai/models/gpt-image-2)
- Другие версии: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [GPT Image 1.5 API](https://api.cyhub.ai/models/gpt-image-1-5/api.md)
- Похожие модели: [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# GPT Image 1.5 API

> Картинки GPT Image 1.5 от OpenAI по описанию и по референсам (до 14). Три пропорции и одно разрешение, результат PNG. Описание можно не давать, если есть референсы.

Разработчик: OpenAI
Ключ модели в API: `images_chatgpt`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-1.5",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "1:1"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "images_chatgpt",
    "settings": {
        "model": "gpt-image-1.5",
        "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
        "aspect_ratio": "1:1",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-1.5",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "1:1"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-1.5",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "1:1"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="gpt-image-1.5"></a>GPT Image 1.5

> Три пропорции, одно разрешение, до 14 референсов. Описание можно не давать, если есть референсы.

Значение поля model: `gpt-image-1.5`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Необязательно)

Описание картинки. Можно оставить пустым, если есть референсы.

- Тип: Строка
- Максимум символов: 3000

#### `aspect_ratio` (Необязательно)

Пропорции картинки.

- Тип: Строка
- Допустимые значения: `1:1`, `2:3`, `3:2`
- По умолчанию: `"1:1"`

#### `image_urls` (Необязательно)

Ссылки на референсы, до 14.

- Тип: Список (Строка, uri)
- Максимум элементов: 14

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Референсы передаются ссылками на картинки JPEG, PNG или WebP до 10 МБ каждая.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 14 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Квадратная картинка

```json
{
  "model": "images_chatgpt",
  "settings": {
    "model": "gpt-image-1.5",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "1:1"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка PNG за запуск.
- 4K занимает заметно дольше, до нескольких минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть GPT Image 1.5: возможности и цены](https://api.cyhub.ai/models/gpt-image-1-5)
- Другие версии: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [GPT Image 2 API](https://api.cyhub.ai/models/gpt-image-2/api.md)
- Похожие модели: [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# ElevenLabs API

> Голоса ElevenLabs: озвучка текста и диалогов готовыми голосами, смена голоса в своей записи и дубляж записи на другой язык.

Разработчик: ElevenLabs
Ключ модели в API: `elevenlabs`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "elevenlabs",
  "settings": {
    "mode": "text_to_dialogue",
    "text": "Привет! Сегодня расскажу, как за пять минут сварить идеальный кофе дома.",
    "voice": "cgSgspJ2msm6clMCkdW9",
    "language_code": "ru"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "elevenlabs",
    "settings": {
        "mode": "text_to_dialogue",
        "text": "Привет! Сегодня расскажу, как за пять минут сварить идеальный кофе дома.",
        "voice": "cgSgspJ2msm6clMCkdW9",
        "language_code": "ru",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "elevenlabs",
  "settings": {
    "mode": "text_to_dialogue",
    "text": "Привет! Сегодня расскажу, как за пять минут сварить идеальный кофе дома.",
    "voice": "cgSgspJ2msm6clMCkdW9",
    "language_code": "ru"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "elevenlabs",
  "settings": {
    "mode": "text_to_dialogue",
    "text": "Привет! Сегодня расскажу, как за пять минут сварить идеальный кофе дома.",
    "voice": "cgSgspJ2msm6clMCkdW9",
    "language_code": "ru"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_dialogue"></a>Озвучка текста

> Текст читается выбранным голосом. Для диалога у каждой реплики свой текст и голос.

Значение поля mode: `text_to_dialogue`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `text` (Обязательно)

Текст, который нужно озвучить. Подачу можно подсказать тегами на английском в квадратных скобках, например [whispering] или [laughing]. В диалоге это первая реплика, следующие передаются полями text_2, text_3 и так далее до text_20: по порядку, без пропусков, по тем же правилам.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `voice` (Обязательно)

Голос, которым читается текст (в диалоге голос первой реплики). Готовые голоса ElevenLabs, в подписи имя и характер голоса. У каждой следующей реплики свой голос: voice_2 для text_2, voice_3 для text_3 и так далее до voice_20, значения те же, что у voice.

- Тип: Строка
- Допустимые значения: `BIvP0GN1cAtSRTxNHnWS` (Ellen - Serious, Direct and Confident), `aMSt68OGf4xUZAnLpTU8` (Juniper - Grounded and Professional), `RILOU7YmBhvwJGDGjNmP` (Jane - Professional Audiobook Reader), `EkK5I93UQWFDigLMpZcX` (James - Husky, Engaging and Bold), `Z3R5wn05IrDiVCyEkUrK` (Arabella - Mysterious and Emotive), `tnSpp4vdxKPjI9w0GnoV` (Hope - upbeat and clear), `NNl6r8mD7vthiJatiJt1` (Bradford - Expressive and Articulate), `YOq2y2Up4RgXP2HyXjE5` (Xavier - Dominating, Metalic Announcer), `Bj9UqZbhQsanLzgalpEG` (Austin - Deep, Raspy and Authentic), `c6SfcYrb2t09NHXiT80T` (Jarnathan - Confident and Versatile), `B8gJV1IhpuegLxdpXFOE` (Kuon - Cheerful, Clear and Steady), `exsUS4vynmxd379XN4yO` (Blondie - Conversational), `BpjGufoPiobT79j2vtj4` (Priyanka - Calm, Neutral and Relaxed), `2zRM7PkgwBPiau2jvVXc` (Monika Sogam - Deep and Natural), `1SM7GgM6IMuvQlz2BwM3` (Mark - Casual, Relaxed and Light), `ouL9IsyrSnUkCmfnD02u` (Grimblewood Thornwhisker - Snarky Gnome & Magical Maintainer), `5l5f8iK3YPeGga21rQIX` (Adeline - Feminine and Conversational), `scOwDtmlUjD3prqpp97I` (Sam - Support Agent), `NOpBlnGInO9m6vDvFkFC` (Spuds Oxley - Wise and Approachable), `BZgkqPqms7Kj9ulSkVzn` (Eve - Authentic, Energetic and Happy), `wo6udizrrtpIxWGp2qJk` (Northern Terry), `yjJ45q8TVCrtMhEKurxY` (Dr. Von - Quirky, Mad Scientist), `gU0LNdkMOQCOrPrwtbee` (British Football Announcer), `DGzg6RaUqxGRTHSBjfgF` (Brock - Commanding and Loud Sergeant), `DGTOOUoGpoP6UZ9uSWfA` (Célian - Documentary Narrator), `x70vRnQBMBu4FAYhjJbO` (Nathan - Virtual Radio Host), `Sm1seazb4gs7RSlUVw7c` (Anika - Animated, Friendly and Engaging), `P1bg08DkjqiVEzOn76yG` (Viraj - Rich and Soft), `qDuRKMlYmrm8trt5QyBn` (Taksh - Calm, Serious and Smooth), `kUUTqKQ05NMGulF08DDf` (Guadeloupe Merryweather - Emotional), `qXpMhyvQqiRxWQs4qSSB` (Horatius - Energetic Character Voice), `TX3LPaxmHKxFdv7VOQHJ` (Liam - Energetic, Social Media Creator), `iP95p4xoKVk53GoZ742B` (Chris - Charming, Down-to-Earth), `SOYHLrjzK2X1ezoPC6cr` (Harry - Fierce Warrior), `N2lVS1w4EtoT3dr4eOWO` (Callum - Husky Trickster), `FGY2WhTYpPnrIDTdsKH5` (Laura - Enthusiast, Quirky Attitude), `XB0fDUnXU5powFXDhCwa` (Charlotte), `cgSgspJ2msm6clMCkdW9` (Jessica - Playful, Bright, Warm), `LG95yZDEHg6fCZdQjLqj` (Phil - Explosive, Passionate Announcer), `CeNX9CMwmxDxUF5Q2Inm` (Johnny Dynamite - Vintage Radio DJ), `st7NwhTPEzqo2riw7qWC` (Blondie - Radio Host), `aD6riP1btT197c6dACmy` (Rachel M - Pro British Radio Presenter), `FF7KdobWPaiR0vkcALHF` (David - Movie Trailer Narrator), `mtrellq69YZsNwzUSyXh` (Rex Thunder - Deep N Tough), `dHd5gvgSOzSfduK4CvEg` (Ed - Late Night Announcer), `cTNP6ZM2mLTKj2BFhxEh` (Paul French - Podcaster), `ZF6FPAbjXT4488VcRRnw` (Amelia - Enthusiastic and Expressive), `8JVbfL6oEdmuxKn5DK2C` (Johnny Kid - Serious and Calm Narrator), `iCrDUkL56s3C8sCRl7wb` (Hope - Poetic, Romantic and Captivating), `1hlpeD1ydbI2ow0Tt3EW` (Olivia - Smooth, Warm and Engaging), `wJqPPQ618aTW29mptyoc` (Ana Rita - Smooth, Expressive and Bright), `EiNlNiXeDU1pqqOPrYMO` (John Doe - Deep), `FUfBrNit0NNZAwb58KWH` (Angela - Conversational and Friendly), `4YYIPFl9wE5c4L2eu2Gb` (Burt Reynolds™ - Deep, Smooth and clear), `OYWwCdDHouzDwiZJWOOu` (David - Gruff Cowboy), `6F5Zhi321D3Oq7v1oNT4` (Hank - Deep and Engaging Narrator), `qNkzaJoHLLdpvgh5tISm` (Carter - Rich, Smooth and Rugged), `YXpFCvM1S3JbWEJhoskW` (Wyatt- Wise Rustic Cowboy), `KTPVrSVAEUSJRClDzBw7` (Bob - Rugged and Warm Cowboy), `9PVP7ENhDskL0KYHAKtD` (Jerry B. - Southern/Cowboy), `vfaqCOvlrKi4Zp7C2IAm` (Malyx - Echoey, Menacing and Deep Demon), `piI8Kku0DcvcL6TTSeQt` (Flicker - Cheerful Fairy & Sparkly Sweetness), `flHkNRp1BlvT73UL6gyz` (Jessica Anne Bogart - Eloquent Villain), `9yzdeviXkFddZ4Oz8Mok` (Lutz - Chuckling, Giggly and Cheerful), `pPdl9cQBQq4p6mRkZy2Z` (Emma - Adorable and Upbeat), `0SpgpJ4D3MpHCiWdyTg3` (Matthew Schmitz - Elitist, Arrogant, Conniving Tyrant), `UFO0Yv86wqRxAt1DmXUu` (Sarcastic and Sultry Villain), `oR4uRy4fHDUGGISL0Rev` (Myrrdin - Wise and Magical Narrator), `zYcjlYFOd3taleS0gkk3` (Edward - Loud, Confident and Cocky), `nzeAacJi50IvxcyDnMXa` (Marshal - Friendly, Funny Professor), `ruirxsoakN0GWmGNIo04` (John Morgan - Gritty, Rugged Cowboy), `1KFdM0QCwQn4rmn5nn9C` (Parasyte - Whispers from the Deep Dark), `TC0Zp7WVFzhA8zpTlRqV` (Aria - Sultry Villain), `ljo9gAlSqKOvF6D8sOsX` (Viking Bjorn - Epic Medieval Raider), `PPzYpIqttlTYA83688JI` (Pirate Marshal), `eVItLK1UvXctxuaRV2Oq` (Jean - Alluring and Playful Femme Fatale), `U1Vk2oyatMdYs096Ety7` (Michael - Deep, Dark and Urban), `esy0r39YPLQjOczyOib8` (Britney - Calm and Calculative Villain), `bwCXcoVxWNYMlC6Esa8u` (Matthew Schmitz - Gravel, Deep Anti-Hero), `D2jw4N9m4xePLTQ3IHjU` (Ian - Strange and Distorted Alien), `Tsns2HvNFKfGiNjllgqo` (Sven - Emotional and Nice), `MnUw1cSnpiLoLhpd3Hqp` (Heather Rey - Rushed and Friendly), `kPzsL2i3teMYv0FxEYQ6` (Brittney - Social Media Voice - Fun, Youthful & Informative), `UgBBYS2sOqTuMpoF3BR0` (Mark - Natural Conversations), `IjnA9kwZJHJ20Fp7Vmy6` (Matthew - Casual, Friendly and Smooth), `KoQQbl9zjAdLgKZjm8Ol` (Pro Narrator - Convincing story teller), `hpp4J3VqNfWAUOO0d1Us` (Bella - Professional, Bright, Warm), `pNInz6obpgDQGcFmaJgB` (Adam - Dominant, Firm), `nPczCjzI2devNBz1zQrb` (Brian - Deep, Resonant and Comforting), `Atp5cNFg1Wj5gyKD7HWV` (Natasha - Gentle Meditation), `1cxc5c3E9K6F1wlqOJGV` (Emily - Gentile, Soft and Meditative), `1U02n4nD6AdIZ9CjF053` (Viraj - Smooth and Gentle), `HgyIHe81F3nXywNwkraY` (Nate - Sultry, Whispery and Seductive), `AeRdCCKzvd23BpJoofzx` (Nathaniel - Engaging, British and Calm), `LruHrtVF6PSyGItzMNHS` (Benjamin - Deep, Warm, Calming), `Qggl4b0xRMiqOwhPtVWT` (Clara - Relaxing, Calm and Soothing), `zA6D7RyKdc2EClouEMkP` (AImee - Tranquil ASMR and Meditation), `1wGbFxmAM3Fgw63G1zZJ` (Allison - Calm, Soothing and Meditative), `hqfrgApggtO1785R4Fsn` (Theodore HQ - Serene and Grounded), `sH0WdfE5fsKuM2otdQZr` (Koraly - Soft-spoken and Gentle), `MJ0RnG71ty4LH3dvNfSd` (Leon - Soothing and Grounded), `L0Dsvb3SLTyegXwtm47J` (Archer), `uYXf8XasLslADfZ2MB4u` (Hope - Bubbly, Gossipy and Girly), `gs0tAILXbY5DNrJrsM6F` (Jeff - Classy, Resonating and Strong), `DTKMou8ccj1ZaWGBiotd` (Jamahal - Young, Vibrant, and Natural), `vBKc2FfBKJfcZNyEt1n6` (Finn - Youthful, Eager and Energetic), `TmNe0cCqkZBMwPWOd3RD` (Smith - Mellow, Spontaneous, and Bassy), `DYkrAHD8iwork3YSUBbs` (Tom - Conversations & Books), `56AoDkrOh6qfVPDXZ7Pt` (Cassidy - Crisp, Direct and Clear), `eR40ATw9ArzDf9h3v7t7` (Addison 2.0 - Australian Audiobook & Podcast), `g6xIsTj2HwM6VR4iXFCw` (Jessica Anne Bogart - Chatty and Friendly), `lcMyyd2HUfFzxdCaC4Ta` (Lucy - Fresh & Casual), `6aDn1KB0hjpdcocrUkmq` (Tiffany - Natural and Welcoming), `Sq93GQT4X1lKDXsQcixO` (Felix - Warm, positive & contemporary RP)

#### `tts_version` (Необязательно)

Версия модели. v4 новая: точнее передаёт эмоции из тегов в квадратных скобках и знает больше языков. v3 прежняя: голоса на ней звучат как в прошлых озвучках, на v4 могут звучать немного иначе.

- Тип: Строка
- Допустимые значения: `v4`, `v3`
- По умолчанию: `"v4"`

#### `stability` (Необязательно)

Насколько ровно звучит голос: 0 выразительнее, но менее предсказуемо, 0.5 баланс, 1 ровно и предсказуемо.

- Тип: Строка
- Допустимые значения: `0` (Динамичный), `0.5` (Сбалансированный), `1` (Стабильный)
- По умолчанию: `"0.5"`

#### `language_code` (Необязательно)

Язык озвучки. auto: определяется по тексту. Лучше задать язык текста явно. Список зависит от версии: у v4 он больше.

- Тип: Строка
- Допустимые значения: `auto`, `ru`, `en`, `af`, `ar`, `hy`, `as`, `az`, `be`, `bn`, `bs`, `bg`, `ca`, `ceb`, `ny`, `hr`, `cs`, `da`, `nl`, `et`, `fil`, `fi`, `fr`, `gl`, `ka`, `de`, `el`, `gu`, `ha`, `he`, `hi`, `hu`, `is`, `id`, `ga`, `it`, `ja`, `jv`, `kn`, `kk`, `ky`, `ko`, `lv`, `ln`, `lt`, `lb`, `mk`, `ms`, `ml`, `zh`, `mr`, `ne`, `no`, `ps`, `fa`, `pl`, `pt`, `pa`, `ro`, `sr`, `sd`, `sk`, `sl`, `so`, `es`, `sw`, `sv`, `ta`, `te`, `th`, `tr`, `uk`, `ur`, `vi`, `cy`
- Набор зависит от `tts_version`.
- Исключения:

  | `tts_version` | `language_code` |
  |---|---|
  | `v4` | и ещё `ast`, `my`, `yue`, `mt`, `mi`, `mn`, `oc`, `or`, `tg`, `uz`, `yo` |
- По умолчанию: `"auto"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- До 20 реплик и до 5000 знаков во всём тексте вместе, до 10 разных голосов.
- ElevenLabs надёжно озвучивает до 2000 знаков за раз: длинный текст может оборваться или не пройти, его лучше делить на несколько запусков.
- Цена по числу знаков текста и по голосам: за часть голосов их владельцы в библиотеке ElevenLabs берут доплату, и знаки таким голосом стоят дороже.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Озвучка текста одним голосом

```json
{
  "model": "elevenlabs",
  "settings": {
    "mode": "text_to_dialogue",
    "text": "Привет! Сегодня расскажу, как за пять минут сварить идеальный кофе дома.",
    "voice": "cgSgspJ2msm6clMCkdW9",
    "language_code": "ru"
  }
}
```

Диалог двух голосов

```json
{
  "model": "elevenlabs",
  "settings": {
    "mode": "text_to_dialogue",
    "text": "[cheerfully] Привет! Ты уже видел новый парк у реки?",
    "voice": "cgSgspJ2msm6clMCkdW9",
    "text_2": "[curious] Ещё нет. Там правда так красиво?",
    "voice_2": "iP95p4xoKVk53GoZ742B",
    "stability": "0.5",
    "language_code": "ru"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Один файл MP3 с озвучкой.
- Озвучка занимает от нескольких секунд до минуты в зависимости от длины текста.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` | mp3 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="voice_change"></a>Смена голоса

> Та же запись, но другим голосом: интонации, паузы и темп остаются как в исходнике. Звук или видео до 5 минут.

Значение поля mode: `voice_change`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `audio_url` (Необязательно)

Ссылка на звук, в котором нужно сменить голос. Нужна она или video_url.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `video_url` (Необязательно)

Ссылка на видео, в котором нужно сменить голос: придёт то же видео с новым голосом. Нужна она или audio_url.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `voice` (Обязательно)

Голос, которым зазвучит запись. Готовые голоса ElevenLabs, в подписи имя и характер голоса.

- Тип: Строка
- Допустимые значения: `BIvP0GN1cAtSRTxNHnWS` (Ellen - Serious, Direct and Confident), `aMSt68OGf4xUZAnLpTU8` (Juniper - Grounded and Professional), `RILOU7YmBhvwJGDGjNmP` (Jane - Professional Audiobook Reader), `EkK5I93UQWFDigLMpZcX` (James - Husky, Engaging and Bold), `Z3R5wn05IrDiVCyEkUrK` (Arabella - Mysterious and Emotive), `tnSpp4vdxKPjI9w0GnoV` (Hope - upbeat and clear), `NNl6r8mD7vthiJatiJt1` (Bradford - Expressive and Articulate), `YOq2y2Up4RgXP2HyXjE5` (Xavier - Dominating, Metalic Announcer), `Bj9UqZbhQsanLzgalpEG` (Austin - Deep, Raspy and Authentic), `c6SfcYrb2t09NHXiT80T` (Jarnathan - Confident and Versatile), `B8gJV1IhpuegLxdpXFOE` (Kuon - Cheerful, Clear and Steady), `exsUS4vynmxd379XN4yO` (Blondie - Conversational), `BpjGufoPiobT79j2vtj4` (Priyanka - Calm, Neutral and Relaxed), `2zRM7PkgwBPiau2jvVXc` (Monika Sogam - Deep and Natural), `1SM7GgM6IMuvQlz2BwM3` (Mark - Casual, Relaxed and Light), `ouL9IsyrSnUkCmfnD02u` (Grimblewood Thornwhisker - Snarky Gnome & Magical Maintainer), `5l5f8iK3YPeGga21rQIX` (Adeline - Feminine and Conversational), `scOwDtmlUjD3prqpp97I` (Sam - Support Agent), `NOpBlnGInO9m6vDvFkFC` (Spuds Oxley - Wise and Approachable), `BZgkqPqms7Kj9ulSkVzn` (Eve - Authentic, Energetic and Happy), `wo6udizrrtpIxWGp2qJk` (Northern Terry), `yjJ45q8TVCrtMhEKurxY` (Dr. Von - Quirky, Mad Scientist), `gU0LNdkMOQCOrPrwtbee` (British Football Announcer), `DGzg6RaUqxGRTHSBjfgF` (Brock - Commanding and Loud Sergeant), `DGTOOUoGpoP6UZ9uSWfA` (Célian - Documentary Narrator), `x70vRnQBMBu4FAYhjJbO` (Nathan - Virtual Radio Host), `Sm1seazb4gs7RSlUVw7c` (Anika - Animated, Friendly and Engaging), `P1bg08DkjqiVEzOn76yG` (Viraj - Rich and Soft), `qDuRKMlYmrm8trt5QyBn` (Taksh - Calm, Serious and Smooth), `kUUTqKQ05NMGulF08DDf` (Guadeloupe Merryweather - Emotional), `qXpMhyvQqiRxWQs4qSSB` (Horatius - Energetic Character Voice), `TX3LPaxmHKxFdv7VOQHJ` (Liam - Energetic, Social Media Creator), `iP95p4xoKVk53GoZ742B` (Chris - Charming, Down-to-Earth), `SOYHLrjzK2X1ezoPC6cr` (Harry - Fierce Warrior), `N2lVS1w4EtoT3dr4eOWO` (Callum - Husky Trickster), `FGY2WhTYpPnrIDTdsKH5` (Laura - Enthusiast, Quirky Attitude), `XB0fDUnXU5powFXDhCwa` (Charlotte), `cgSgspJ2msm6clMCkdW9` (Jessica - Playful, Bright, Warm), `LG95yZDEHg6fCZdQjLqj` (Phil - Explosive, Passionate Announcer), `CeNX9CMwmxDxUF5Q2Inm` (Johnny Dynamite - Vintage Radio DJ), `st7NwhTPEzqo2riw7qWC` (Blondie - Radio Host), `aD6riP1btT197c6dACmy` (Rachel M - Pro British Radio Presenter), `FF7KdobWPaiR0vkcALHF` (David - Movie Trailer Narrator), `mtrellq69YZsNwzUSyXh` (Rex Thunder - Deep N Tough), `dHd5gvgSOzSfduK4CvEg` (Ed - Late Night Announcer), `cTNP6ZM2mLTKj2BFhxEh` (Paul French - Podcaster), `ZF6FPAbjXT4488VcRRnw` (Amelia - Enthusiastic and Expressive), `8JVbfL6oEdmuxKn5DK2C` (Johnny Kid - Serious and Calm Narrator), `iCrDUkL56s3C8sCRl7wb` (Hope - Poetic, Romantic and Captivating), `1hlpeD1ydbI2ow0Tt3EW` (Olivia - Smooth, Warm and Engaging), `wJqPPQ618aTW29mptyoc` (Ana Rita - Smooth, Expressive and Bright), `EiNlNiXeDU1pqqOPrYMO` (John Doe - Deep), `FUfBrNit0NNZAwb58KWH` (Angela - Conversational and Friendly), `4YYIPFl9wE5c4L2eu2Gb` (Burt Reynolds™ - Deep, Smooth and clear), `OYWwCdDHouzDwiZJWOOu` (David - Gruff Cowboy), `6F5Zhi321D3Oq7v1oNT4` (Hank - Deep and Engaging Narrator), `qNkzaJoHLLdpvgh5tISm` (Carter - Rich, Smooth and Rugged), `YXpFCvM1S3JbWEJhoskW` (Wyatt- Wise Rustic Cowboy), `KTPVrSVAEUSJRClDzBw7` (Bob - Rugged and Warm Cowboy), `9PVP7ENhDskL0KYHAKtD` (Jerry B. - Southern/Cowboy), `vfaqCOvlrKi4Zp7C2IAm` (Malyx - Echoey, Menacing and Deep Demon), `piI8Kku0DcvcL6TTSeQt` (Flicker - Cheerful Fairy & Sparkly Sweetness), `flHkNRp1BlvT73UL6gyz` (Jessica Anne Bogart - Eloquent Villain), `9yzdeviXkFddZ4Oz8Mok` (Lutz - Chuckling, Giggly and Cheerful), `pPdl9cQBQq4p6mRkZy2Z` (Emma - Adorable and Upbeat), `0SpgpJ4D3MpHCiWdyTg3` (Matthew Schmitz - Elitist, Arrogant, Conniving Tyrant), `UFO0Yv86wqRxAt1DmXUu` (Sarcastic and Sultry Villain), `oR4uRy4fHDUGGISL0Rev` (Myrrdin - Wise and Magical Narrator), `zYcjlYFOd3taleS0gkk3` (Edward - Loud, Confident and Cocky), `nzeAacJi50IvxcyDnMXa` (Marshal - Friendly, Funny Professor), `ruirxsoakN0GWmGNIo04` (John Morgan - Gritty, Rugged Cowboy), `1KFdM0QCwQn4rmn5nn9C` (Parasyte - Whispers from the Deep Dark), `TC0Zp7WVFzhA8zpTlRqV` (Aria - Sultry Villain), `ljo9gAlSqKOvF6D8sOsX` (Viking Bjorn - Epic Medieval Raider), `PPzYpIqttlTYA83688JI` (Pirate Marshal), `eVItLK1UvXctxuaRV2Oq` (Jean - Alluring and Playful Femme Fatale), `U1Vk2oyatMdYs096Ety7` (Michael - Deep, Dark and Urban), `esy0r39YPLQjOczyOib8` (Britney - Calm and Calculative Villain), `bwCXcoVxWNYMlC6Esa8u` (Matthew Schmitz - Gravel, Deep Anti-Hero), `D2jw4N9m4xePLTQ3IHjU` (Ian - Strange and Distorted Alien), `Tsns2HvNFKfGiNjllgqo` (Sven - Emotional and Nice), `MnUw1cSnpiLoLhpd3Hqp` (Heather Rey - Rushed and Friendly), `kPzsL2i3teMYv0FxEYQ6` (Brittney - Social Media Voice - Fun, Youthful & Informative), `UgBBYS2sOqTuMpoF3BR0` (Mark - Natural Conversations), `IjnA9kwZJHJ20Fp7Vmy6` (Matthew - Casual, Friendly and Smooth), `KoQQbl9zjAdLgKZjm8Ol` (Pro Narrator - Convincing story teller), `hpp4J3VqNfWAUOO0d1Us` (Bella - Professional, Bright, Warm), `pNInz6obpgDQGcFmaJgB` (Adam - Dominant, Firm), `nPczCjzI2devNBz1zQrb` (Brian - Deep, Resonant and Comforting), `Atp5cNFg1Wj5gyKD7HWV` (Natasha - Gentle Meditation), `1cxc5c3E9K6F1wlqOJGV` (Emily - Gentile, Soft and Meditative), `1U02n4nD6AdIZ9CjF053` (Viraj - Smooth and Gentle), `HgyIHe81F3nXywNwkraY` (Nate - Sultry, Whispery and Seductive), `AeRdCCKzvd23BpJoofzx` (Nathaniel - Engaging, British and Calm), `LruHrtVF6PSyGItzMNHS` (Benjamin - Deep, Warm, Calming), `Qggl4b0xRMiqOwhPtVWT` (Clara - Relaxing, Calm and Soothing), `zA6D7RyKdc2EClouEMkP` (AImee - Tranquil ASMR and Meditation), `1wGbFxmAM3Fgw63G1zZJ` (Allison - Calm, Soothing and Meditative), `hqfrgApggtO1785R4Fsn` (Theodore HQ - Serene and Grounded), `sH0WdfE5fsKuM2otdQZr` (Koraly - Soft-spoken and Gentle), `MJ0RnG71ty4LH3dvNfSd` (Leon - Soothing and Grounded), `L0Dsvb3SLTyegXwtm47J` (Archer), `uYXf8XasLslADfZ2MB4u` (Hope - Bubbly, Gossipy and Girly), `gs0tAILXbY5DNrJrsM6F` (Jeff - Classy, Resonating and Strong), `DTKMou8ccj1ZaWGBiotd` (Jamahal - Young, Vibrant, and Natural), `vBKc2FfBKJfcZNyEt1n6` (Finn - Youthful, Eager and Energetic), `TmNe0cCqkZBMwPWOd3RD` (Smith - Mellow, Spontaneous, and Bassy), `DYkrAHD8iwork3YSUBbs` (Tom - Conversations & Books), `56AoDkrOh6qfVPDXZ7Pt` (Cassidy - Crisp, Direct and Clear), `eR40ATw9ArzDf9h3v7t7` (Addison 2.0 - Australian Audiobook & Podcast), `g6xIsTj2HwM6VR4iXFCw` (Jessica Anne Bogart - Chatty and Friendly), `lcMyyd2HUfFzxdCaC4Ta` (Lucy - Fresh & Casual), `6aDn1KB0hjpdcocrUkmq` (Tiffany - Natural and Welcoming), `Sq93GQT4X1lKDXsQcixO` (Felix - Warm, positive & contemporary RP)

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Файл передаётся ссылкой, ровно один: звук (mp3, wav, m4a, ogg, oga, flac) до 20 МБ в audio_url или видео (mp4, mov, webm, mkv) до 100 МБ в video_url. В видео должна быть звуковая дорожка.
- Годится и ссылка без расширения в адресе, например на файл прошлой генерации: формат определяется по самому файлу.
- Длину записи для цены сервер измеряет по самому файлу, скачав его по ссылке, и ждёт недолго: большой файл с медленного сервера может не успеть скачаться, тогда цену не посчитать и запрос не примут. Для больших файлов нужна ссылка на быстрый сервер.
- Ссылка должна отдавать один и тот же файл до конца генерации: при запуске файл скачивается заново, и если он окажется другим, генерация может не начаться.
- Запись до 5 минут: столько ElevenLabs меняет за один раз. Цена по длине записи, за каждую минуту, и по голосу: за часть голосов их владельцы в библиотеке ElevenLabs берут доплату, и минута таким голосом стоит дороже.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio_url` | Аудио | mp3, wav, m4a, ogg, oga, flac | 1 | 20 МБ |
| `video_url` | Видео | mp4, mov, webm, mkv | 1 | 100 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Другой голос в записи

```json
{
  "model": "elevenlabs",
  "settings": {
    "mode": "voice_change",
    "audio_url": [
      "https://example.com/voice.mp3"
    ],
    "voice": "iP95p4xoKVk53GoZ742B"
  }
}
```

Другой голос в видео

```json
{
  "model": "elevenlabs",
  "settings": {
    "mode": "voice_change",
    "video_url": [
      "https://example.com/clip.mp4"
    ],
    "voice": "cgSgspJ2msm6clMCkdW9"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Звук MP3, а если на входе видео, то же видео с новым голосом.
- Смена голоса занимает до минуты в зависимости от длины записи.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` или `video` | mp3, mp4 | 1 | Звук на audio_url, видео на video_url. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="dubbing"></a>Дубляж на другой язык

> Речь в записи переводится на другой язык и звучит похожими голосами. Звук или видео до 30 минут.

Значение поля mode: `dubbing`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `audio_url` (Необязательно)

Ссылка на звук, который нужно перевести. Нужна она или video_url.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `video_url` (Необязательно)

Ссылка на видео, которое нужно перевести: придёт то же видео с переведённой речью. Нужна она или audio_url.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `dubbing_version` (Необязательно)

Версия дубляжа. v1 дешевле, с тонкими настройками. v2 дороже, переводит и озвучивает точнее и знает диалекты, но ElevenLabs называет её альфа-версией: возможны шероховатости.

- Тип: Строка
- Допустимые значения: `v1`, `v2`
- По умолчанию: `"v1"`

#### `dubbing_target_lang` (Обязательно)

Язык, на который переводится и озвучивается запись. Список зависит от версии: у v2 есть диалекты, но нет части редких языков v1.

- Тип: Строка
- Допустимые значения: `ru`, `en`, `ar`, `bg`, `hr`, `cs`, `da`, `nl`, `fil`, `fi`, `fr`, `de`, `el`, `hi`, `hu`, `id`, `it`, `ja`, `ko`, `ms`, `zh`, `no`, `pl`, `pt`, `ro`, `sk`, `es`, `sv`, `ta`, `tr`, `uk`, `vi`
- Набор зависит от `dubbing_version`.
- Исключения:

  | `dubbing_version` | `dubbing_target_lang` |
  |---|---|
  | `v2` | и ещё `en-US`, `en-GB`, `en-AU`, `en-CA`, `af`, `ak`, `sq`, `am`, `ar-EG`, `hy`, `as`, `az`, `eu`, `be`, `bs`, `my`, `yue`, `ca`, `ceb`, `zh-TW`, `cmn`, `dgo`, `et`, `fr-FR`, `fr-CA`, `gl`, `ka`, `gu`, `ha`, `he`, `is`, `jv`, `kn`, `kk`, `ki`, `rw`, `rn`, `ky`, `lv`, `lt`, `lg`, `mk`, `ml`, `mr`, `mn`, `ne`, `fa`, `pt-BR`, `pt-PT`, `pa`, `nso`, `st`, `sd`, `sl`, `es-ES`, `es-MX`, `es-AR`, `es-CL`, `su`, `sw`, `ss`, `tg`, `te`, `th`, `bo`, `ts`, `tn`, `ur`, `ug`, `uz`, `ve`, `war`, `cy`, `wo`, `yo`, `zu` |

#### `dubbing_source_lang` (Необязательно)

Язык оригинала. auto: ElevenLabs определит сам.

- Тип: Строка
- Допустимые значения: `auto`, `ru`, `en`, `af`, `ar`, `hy`, `as`, `az`, `be`, `bn`, `bs`, `bg`, `ca`, `ceb`, `ny`, `hr`, `cs`, `da`, `nl`, `et`, `fil`, `fi`, `fr`, `gl`, `ka`, `de`, `el`, `gu`, `ha`, `he`, `hi`, `hu`, `is`, `id`, `ga`, `it`, `ja`, `jv`, `kn`, `kk`, `ky`, `ko`, `lv`, `ln`, `lt`, `lb`, `mk`, `ms`, `ml`, `zh`, `mr`, `ne`, `no`, `ps`, `fa`, `pl`, `pt`, `pa`, `ro`, `sr`, `sd`, `sk`, `sl`, `so`, `es`, `sw`, `sv`, `ta`, `te`, `th`, `tr`, `uk`, `ur`, `vi`, `cy`
- Набор зависит от `dubbing_version`.
- Исключения:

  | `dubbing_version` | `dubbing_source_lang` |
  |---|---|
  | `v2` | `auto`, `ru`, `en`, `af`, `ak`, `sq`, `am`, `ar`, `hy`, `as`, `az`, `eu`, `be`, `bs`, `bg`, `my`, `yue`, `ca`, `ceb`, `zh`, `cmn`, `hr`, `cs`, `da`, `dgo`, `nl`, `et`, `fil`, `fi`, `fr`, `gl`, `ka`, `de`, `el`, `gu`, `ha`, `he`, `hi`, `hu`, `is`, `id`, `it`, `ja`, `jv`, `kn`, `kk`, `ki`, `rw`, `rn`, `ko`, `ky`, `lv`, `lt`, `lg`, `mk`, `ms`, `ml`, `mr`, `mn`, `ne`, `no`, `fa`, `pl`, `pt`, `pa`, `ro`, `nso`, `st`, `sd`, `sk`, `sl`, `es`, `su`, `sw`, `ss`, `sv`, `tg`, `ta`, `te`, `th`, `bo`, `ts`, `tn`, `tr`, `uk`, `ur`, `ug`, `uz`, `ve`, `vi`, `war`, `cy`, `wo`, `yo`, `zu` |
- По умолчанию: `"auto"`

#### `dubbing_num_speakers` (Необязательно)

Сколько разных голосов в записи. 0: определить само. Только v1.

- Тип: Целое число
- Минимум: 0
- Максимум: 9
- По умолчанию: `0`

#### `dubbing_drop_background_audio` (Необязательно)

Убрать музыку и фоновые звуки, оставить только переведённую речь. Для лекций и интервью, не для клипов. Только v1.

- Тип: Да/нет
- По умолчанию: `false`

#### `dubbing_disable_voice_cloning` (Необязательно)

Не повторять тембр исходного голоса, а взять похожий голос из библиотеки ElevenLabs. Помогает на шумных записях. Только v1.

- Тип: Да/нет
- По умолчанию: `false`

#### `dubbing_use_profanity_filter` (Необязательно)

Заменять ругательства на [censored]. Может пропустить слово или сработать зря. Только v1.

- Тип: Да/нет
- По умолчанию: `false`

#### `dubbing_highest_resolution` (Необязательно)

Сохранить исходное разрешение видео, обработка чуть дольше. Только для видео. Только v1.

- Тип: Да/нет
- По умолчанию: `false`

#### `dubbing_target_accent` (Необязательно)

Подсказка по акценту озвучки на английском, например british или american. Может не сработать. Только v1.

- Тип: Строка

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Файл передаётся ссылкой, ровно один: звук (mp3, wav, m4a, ogg, oga, flac) до 50 МБ в audio_url или видео (mp4, mov, webm, mkv) до 500 МБ в video_url. В видео должна быть звуковая дорожка.
- Годится и ссылка без расширения в адресе, например на файл прошлой генерации: формат определяется по самому файлу.
- Длину записи для цены сервер измеряет по самому файлу, скачав его по ссылке, и ждёт недолго: большой файл с медленного сервера может не успеть скачаться, тогда цену не посчитать и запрос не примут. Для больших файлов нужна ссылка на быстрый сервер.
- Ссылка должна отдавать один и тот же файл до конца генерации: при запуске файл скачивается заново, и если он окажется другим, генерация может не начаться.
- Запись до 30 минут, дубляж идёт по всей записи. Цена по длине записи, за каждую минуту, у v2 дороже.
- Тонкие настройки (число голосов, фон, клонирование, цензура, разрешение, акцент) есть только у v1: с v2 запрос с ними не принимается.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio_url` | Аудио | mp3, wav, m4a, ogg, oga, flac | 1 | 50 МБ |
| `video_url` | Видео | mp4, mov, webm, mkv | 1 | 500 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео на английский

```json
{
  "model": "elevenlabs",
  "settings": {
    "mode": "dubbing",
    "video_url": [
      "https://example.com/lecture.mp4"
    ],
    "dubbing_target_lang": "en"
  }
}
```

Интервью на испанский Мексики, v2

```json
{
  "model": "elevenlabs",
  "settings": {
    "mode": "dubbing",
    "audio_url": [
      "https://example.com/interview.mp3"
    ],
    "dubbing_version": "v2",
    "dubbing_target_lang": "es-MX",
    "dubbing_source_lang": "ru"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Звуковая дорожка на новом языке, а если на входе видео, то же видео с переведённой речью.
- Дубляж занимает от 1 до 15 минут в зависимости от длины записи.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` или `video` | mp3, mp4 | 1 | Звук на audio_url, видео на video_url. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть ElevenLabs: возможности и цены](https://api.cyhub.ai/models/elevenlabs)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Nano Banana Pro API

> Картинки Nano Banana Pro от Google по описанию и правка ваших картинок: до 8 референсов, качество до 4K. Десять пропорций, результат PNG или JPG.

Разработчик: Google
Ключ модели в API: `banana_pro`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-pro",
    "prompt": "Маяк на скале в шторм, кинематографичный свет",
    "size": "16:9",
    "resolution": "2K"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "banana_pro",
    "settings": {
        "model": "nano-banana-pro",
        "prompt": "Маяк на скале в шторм, кинематографичный свет",
        "size": "16:9",
        "resolution": "2K",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-pro",
    "prompt": "Маяк на скале в шторм, кинематографичный свет",
    "size": "16:9",
    "resolution": "2K"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-pro",
    "prompt": "Маяк на скале в шторм, кинематографичный свет",
    "size": "16:9",
    "resolution": "2K"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="nano-banana-pro"></a>Nano Banana Pro

> Версия высокого качества: десять пропорций, до 4K, до 8 референсов.

Значение поля model: `nano-banana-pro`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Описание картинки или что сделать с референсами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `resolution` (Необязательно)

Качество: 1K, 2K или 4K. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `1K`, `2K`, `4K`
- По умолчанию: `"1K"`

#### `output_format` (Необязательно)

Формат файла результата.

- Тип: Строка
- Допустимые значения: `png`, `jpg`
- По умолчанию: `"png"`

#### `google_search` (Необязательно)

Только у Banana 2: разрешить модели искать в Google, когда нужны актуальные факты или реальные места.

- Тип: Да/нет
- По умолчанию: `false`

#### `size` (Необязательно)

Пропорции картинки.

- Тип: Строка
- Допустимые значения: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
- По умолчанию: `"1:1"`

#### `image_urls` (Необязательно)

Ссылки на референсы, до 8 штук.

- Тип: Список (Строка, uri)
- Максимум элементов: 8

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Референсы передаются ссылками на картинки JPEG, PNG или WebP до 30 МБ каждая.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 8 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Картинка по описанию

```json
{
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-pro",
    "prompt": "Маяк на скале в шторм, кинематографичный свет",
    "size": "16:9",
    "resolution": "2K"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка за запуск в выбранном формате.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg | 1 | Формат задаёт output_format. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Nano Banana Pro: возможности и цены](https://api.cyhub.ai/models/nano-banana-pro)
- Другие версии: [Nano Banana 2.1 API](https://api.cyhub.ai/models/nano-banana-2-1/api.md), [Nano Banana 2 API](https://api.cyhub.ai/models/nano-banana-2/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Nano Banana 2.1 API

> Картинки Nano Banana 2.1 от Google по описанию и правка ваших картинок: до 10 референсов, качество до 4K. Четырнадцать пропорций, включая вытянутые 1:4, 4:1, 1:8 и 8:1, и «Авто», результат PNG или JPG.

Разработчик: Google
Ключ модели в API: `banana_pro`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-2-1",
    "prompt": "Постер кофейни в стиле ретро, крупная надпись «Доброе утро»",
    "size": "3:4",
    "resolution": "2K"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "banana_pro",
    "settings": {
        "model": "nano-banana-2-1",
        "prompt": "Постер кофейни в стиле ретро, крупная надпись «Доброе утро»",
        "size": "3:4",
        "resolution": "2K",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-2-1",
    "prompt": "Постер кофейни в стиле ретро, крупная надпись «Доброе утро»",
    "size": "3:4",
    "resolution": "2K"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-2-1",
    "prompt": "Постер кофейни в стиле ретро, крупная надпись «Доброе утро»",
    "size": "3:4",
    "resolution": "2K"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="nano-banana-2-1"></a>Nano Banana 2.1

> Новейшая версия, она по умолчанию: четырнадцать пропорций, включая вытянутые 1:4, 4:1, 1:8 и 8:1, и auto, до 4K, до 10 референсов.

Значение поля model: `nano-banana-2-1`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Описание картинки или что сделать с референсами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `resolution` (Необязательно)

Качество: 1K, 2K или 4K. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `1K`, `2K`, `4K`
- По умолчанию: `"1K"`

#### `output_format` (Необязательно)

Формат файла результата.

- Тип: Строка
- Допустимые значения: `png`, `jpg`
- По умолчанию: `"png"`

#### `google_search` (Необязательно)

Только у Banana 2: разрешить модели искать в Google, когда нужны актуальные факты или реальные места.

- Тип: Да/нет
- По умолчанию: `false`

#### `size` (Необязательно)

Пропорции картинки. auto: пропорции выбирает модель, с референсом обычно как у него.

- Тип: Строка
- Допустимые значения: `auto` (Авто), `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9`
- По умолчанию: `"1:1"`

#### `image_urls` (Необязательно)

Ссылки на референсы, до 10 штук.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Референсы передаются ссылками на картинки JPEG, PNG или WebP до 30 МБ каждая.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 10 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Плакат с надписью

```json
{
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-2-1",
    "prompt": "Постер кофейни в стиле ретро, крупная надпись «Доброе утро»",
    "size": "3:4",
    "resolution": "2K"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка за запуск в выбранном формате.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg | 1 | Формат задаёт output_format. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Nano Banana 2.1: возможности и цены](https://api.cyhub.ai/models/nano-banana-2-1)
- Другие версии: [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 API](https://api.cyhub.ai/models/nano-banana-2/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Nano Banana 2 API

> Картинки Nano Banana 2 от Google с широким выбором пропорций, включая вытянутые 1:4, 4:1, 1:8 и 8:1. По описанию и правка ваших картинок (до 10 референсов), качество до 4K. Можно разрешить модели искать в Google актуальные факты и реальные места.

Разработчик: Google
Ключ модели в API: `banana_pro`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-2",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "size": "21:9",
    "resolution": "2K"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "banana_pro",
    "settings": {
        "model": "nano-banana-2",
        "prompt": "Горный хребет на рассвете, туман в долинах",
        "size": "21:9",
        "resolution": "2K",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-2",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "size": "21:9",
    "resolution": "2K"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-2",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "size": "21:9",
    "resolution": "2K"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="nano-banana-2"></a>Nano Banana 2

> Версия с широким выбором пропорций, включая вытянутые 1:4, 4:1, 1:8 и 8:1, и до 10 референсов.

Значение поля model: `nano-banana-2`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Описание картинки или что сделать с референсами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `resolution` (Необязательно)

Качество: 1K, 2K или 4K. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `1K`, `2K`, `4K`
- По умолчанию: `"1K"`

#### `output_format` (Необязательно)

Формат файла результата.

- Тип: Строка
- Допустимые значения: `png`, `jpg`
- По умолчанию: `"png"`

#### `google_search` (Необязательно)

Только у Banana 2: разрешить модели искать в Google, когда нужны актуальные факты или реальные места.

- Тип: Да/нет
- По умолчанию: `false`

#### `size` (Необязательно)

Пропорции картинки.

- Тип: Строка
- Допустимые значения: `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9`
- По умолчанию: `"1:1"`

#### `image_urls` (Необязательно)

Ссылки на референсы, до 10 штук.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Референсы передаются ссылками на картинки JPEG, PNG или WebP до 30 МБ каждая.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 10 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Широкий баннер

```json
{
  "model": "banana_pro",
  "settings": {
    "model": "nano-banana-2",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "size": "21:9",
    "resolution": "2K"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка за запуск в выбранном формате.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg | 1 | Формат задаёт output_format. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="banana"></a>Упрощённый вызов: модель banana

> Картинки Banana 2 по описанию, можно с картинками-образцами: правка фото, смена стиля, сборка сцены из нескольких фото.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Описание картинки или что сделать с картинками-образцами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `image_urls` (Необязательно)

Ссылки на картинки-образцы, до 10 штук. Без них картинка создаётся только по описанию.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

#### `aspect_ratio` (Необязательно)

Пропорции картинки. adaptive: их выбирает сама модель, по описанию или по картинке-образцу.

- Тип: Строка
- Допустимые значения: `adaptive` (Адаптивные), `1:1`, `9:16`, `3:4`, `4:3`, `16:9`
- По умолчанию: `"adaptive"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинки-образцы передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая. Ссылка должна открываться без входа и без переадресации. Если картинка не подошла, задача завершится ошибкой, деньги не спишутся.
- Пропорции задаёт aspect_ratio: 1:1, 9:16, 3:4, 4:3 или 16:9. По умолчанию adaptive: пропорции выбирает сама модель, по описанию или по картинке-образцу, и их можно описать словами в описании: «вертикально», «горизонтально» или «квадрат».

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 10 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Картинка по описанию

```json
{
  "model": "banana",
  "settings": {
    "prompt": "Маяк на скале в шторм, кинематографичный свет",
    "aspect_ratio": "16:9"
  }
}
```

Правка своей картинки

```json
{
  "model": "banana",
  "settings": {
    "prompt": "Посади этого кота на подоконник, за окном дождь",
    "image_urls": [
      "https://example.com/cat.jpg"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка за запуск.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Nano Banana 2: возможности и цены](https://api.cyhub.ai/models/nano-banana-2)
- Другие версии: [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2.1 API](https://api.cyhub.ai/models/nano-banana-2-1/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Nano Banana 2 Lite API

> Быстрые картинки Banana 2 Lite по описанию, можно с картинками-образцами для правки или стиля. Разрешение всегда 1K.

Разработчик: Google
Ключ модели в API: `banana2_lite`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "banana2_lite",
  "settings": {
    "prompt": "Уютная кофейня в дождливый вечер, тёплый свет из окон",
    "size": "16:9"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "banana2_lite",
    "settings": {
        "prompt": "Уютная кофейня в дождливый вечер, тёплый свет из окон",
        "size": "16:9",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "banana2_lite",
  "settings": {
    "prompt": "Уютная кофейня в дождливый вечер, тёплый свет из окон",
    "size": "16:9"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "banana2_lite",
  "settings": {
    "prompt": "Уютная кофейня в дождливый вечер, тёплый свет из окон",
    "size": "16:9"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="parameters"></a>Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

### `prompt` (Обязательно)

Описание картинки или что сделать с картинками-образцами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

### `size` (Необязательно)

Пропорции картинки. Авто: модель выберет сама.

- Тип: Строка
- Допустимые значения: `auto` (Авто), `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9`
- По умолчанию: `"9:16"`

### `image_urls` (Необязательно)

Ссылки на картинки-образцы, до 10 штук. Без них картинка создаётся только по описанию.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

## <a id="input"></a>Входные данные

- Картинки-образцы передаются ссылками на JPEG, PNG или WebP до 30 МБ каждая.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 10 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

## <a id="example"></a>Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Картинка по описанию

```json
{
  "model": "banana2_lite",
  "settings": {
    "prompt": "Уютная кофейня в дождливый вечер, тёплый свет из окон",
    "size": "16:9"
  }
}
```

Правка своей картинки

```json
{
  "model": "banana2_lite",
  "settings": {
    "prompt": "Замени фон на летний луг, человека оставь как есть",
    "size": "auto",
    "image_urls": [
      "https://example.com/photo.jpg"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

## <a id="output"></a>Результат

- Одна картинка за запуск, разрешение 1K.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Nano Banana 2 Lite: возможности и цены](https://api.cyhub.ai/models/nano-banana-2-lite)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Kling 3.0 API

> Видео Kling 3.0 по описанию или по первому и последнему кадру: от 3 до 15 секунд, до 4K, с озвучкой. Ролик можно разбить на несколько сцен, модель сама поделит описание.

Разработчик: Kuaishou
Ключ модели в API: `kling_pro`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v3.0",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется следом",
    "quality": "1080p",
    "length": 8,
    "aspect_ratio": "16:9"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "kling_pro",
    "settings": {
        "model_version": "v3.0",
        "prompt": "Лиса бежит по заснеженному лесу, камера движется следом",
        "quality": "1080p",
        "length": 8,
        "aspect_ratio": "16:9",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "kling_pro",
  "settings": {
    "model_version": "v3.0",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется следом",
    "quality": "1080p",
    "length": 8,
    "aspect_ratio": "16:9"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v3.0",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется следом",
    "quality": "1080p",
    "length": 8,
    "aspect_ratio": "16:9"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="v3.0"></a>Kling 3.0

> Новейшая версия: от 3 до 15 секунд, до 4K, озвучка, деление на сцены, первый и последний кадр.

Значение поля model_version: `v3.0`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: действие, движение камеры, настроение сцены.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `start_frame` (Необязательно)

Одна ссылка на картинку, с которой начнётся видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `end_frame` (Необязательно)

Одна ссылка на картинку, которой закончится видео. Можно и без первого кадра.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `quality` (Необязательно)

Качество: 720p, 1080p или 4K. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`, `4K`
- По умолчанию: `"720p"`

#### `length` (Необязательно)

Длительность видео в секундах, от 3 до 15. Цена растёт с каждой секундой.

- Тип: Целое число
- Минимум: 3
- Максимум: 15
- По умолчанию: `5`

#### `aspect_ratio` (Необязательно)

Пропорции видео без кадров. С первым или последним кадром видео берёт пропорции кадра.

- Тип: Строка
- Допустимые значения: `16:9`, `1:1`, `9:16`
- По умолчанию: `"16:9"`

#### `native_audio` (Необязательно)

Озвучка: звуковая дорожка под содержание видео, голоса, звуки и музыка. Цена выше.

- Тип: Да/нет
- По умолчанию: `true`

#### `multi_shot` (Необязательно)

Разбить видео на несколько сцен: модель сама делит описание на сцены. Сцены удобно описать в описании по порядку.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `api_request` = `true`

### Входные данные

- Кадры передаются ссылками на JPG или PNG до 10 МБ: сторона не меньше 300 пикселей, пропорции от 1:2,5 до 2,5:1.
- Кадры мы скачиваем сами: ссылка должна открываться без входа и вести прямо на файл, без переадресации.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `start_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |
| `end_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "kling_pro",
  "settings": {
    "model_version": "v3.0",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется следом",
    "quality": "1080p",
    "length": 8,
    "aspect_ratio": "16:9"
  }
}
```

Переход от первого кадра к последнему

```json
{
  "model": "kling_pro",
  "settings": {
    "model_version": "v3.0",
    "prompt": "Бутон медленно раскрывается в цветок",
    "start_frame": [
      "https://example.com/bud.jpg"
    ],
    "end_frame": [
      "https://example.com/flower.jpg"
    ],
    "length": 5,
    "native_audio": false
  }
}
```

Несколько сцен

```json
{
  "model": "kling_pro",
  "settings": {
    "model_version": "v3.0",
    "prompt": "Сначала мальчик находит на чердаке старую карту. Потом он бежит с ней через поле к маяку.",
    "multi_shot": true,
    "length": 12
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4, со звуком, если он включён.
- Генерация обычно занимает 3-5 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Kling 3.0: возможности и цены](https://api.cyhub.ai/models/kling-3)
- Другие версии: [Kling 2.6 API](https://api.cyhub.ai/models/kling-2-6/api.md), [Kling 2.5 Turbo API](https://api.cyhub.ai/models/kling-2-5-turbo/api.md), [Kling 2.1 Master API](https://api.cyhub.ai/models/kling-2-1-master/api.md), [Kling 2.1 API](https://api.cyhub.ai/models/kling-2-1/api.md), [Kling 1.6 API](https://api.cyhub.ai/models/kling-1-6/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Kling 2.6 API

> Видео Kling 2.6 с озвучкой: голоса, звуки и музыка под видео. По описанию или по первому и последнему кадру, 5 или 10 секунд, 720p или 1080p.

Разработчик: Kuaishou
Ключ модели в API: `kling_pro`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.6",
    "prompt": "Ведущий говорит: «Добро пожаловать на наш канал», и улыбается",
    "start_frame": [
      "https://example.com/host.png"
    ],
    "length": 5
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "kling_pro",
    "settings": {
        "model_version": "v2.6",
        "prompt": "Ведущий говорит: «Добро пожаловать на наш канал», и улыбается",
        "start_frame": [
            "https://example.com/host.png",
        ],
        "length": 5,
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.6",
    "prompt": "Ведущий говорит: «Добро пожаловать на наш канал», и улыбается",
    "start_frame": [
      "https://example.com/host.png"
    ],
    "length": 5
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.6",
    "prompt": "Ведущий говорит: «Добро пожаловать на наш канал», и улыбается",
    "start_frame": [
      "https://example.com/host.png"
    ],
    "length": 5
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="v2.6"></a>Kling 2.6

> Версия с озвучкой: голоса, звуки и музыка под видео. 5 или 10 секунд.

Значение поля model_version: `v2.6`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: действие, движение камеры, настроение сцены.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `start_frame` (Необязательно)

Одна ссылка на картинку, с которой начнётся видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `end_frame` (Необязательно)

Одна ссылка на картинку, которой закончится видео. Только вместе с первым кадром и без озвучки.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `quality` (Необязательно)

Качество: 720p или 1080p, цена зависит от него. С озвучкой или последним кадром только 1080p.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"1080p"`

#### `length` (Необязательно)

Длительность видео: 5 или 10 секунд. 10 секунд стоят вдвое дороже.

- Тип: Целое число
- Минимум: 5
- Максимум: 10
- По умолчанию: `5`

#### `aspect_ratio` (Необязательно)

Пропорции видео без кадров. С первым или последним кадром видео берёт пропорции кадра.

- Тип: Строка
- Допустимые значения: `16:9`, `1:1`, `9:16`
- По умолчанию: `"16:9"`

#### `native_audio` (Необязательно)

Озвучка: звуковая дорожка под содержание видео, голоса, звуки и музыка. Цена выше. Только в 1080p и без последнего кадра.

- Тип: Да/нет
- По умолчанию: `true`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `api_request` = `true`

### Входные данные

- Кадры передаются ссылками на JPG или PNG до 10 МБ: сторона не меньше 300 пикселей, пропорции от 1:2,5 до 2,5:1.
- Кадры мы скачиваем сами: ссылка должна открываться без входа и вести прямо на файл, без переадресации.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `start_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |
| `end_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить картинку со звуком

```json
{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.6",
    "prompt": "Ведущий говорит: «Добро пожаловать на наш канал», и улыбается",
    "start_frame": [
      "https://example.com/host.png"
    ],
    "length": 5
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4, со звуком, если он включён.
- Генерация обычно занимает 3-5 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Kling 2.6: возможности и цены](https://api.cyhub.ai/models/kling-2-6)
- Другие версии: [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling 2.5 Turbo API](https://api.cyhub.ai/models/kling-2-5-turbo/api.md), [Kling 2.1 Master API](https://api.cyhub.ai/models/kling-2-1-master/api.md), [Kling 2.1 API](https://api.cyhub.ai/models/kling-2-1/api.md), [Kling 1.6 API](https://api.cyhub.ai/models/kling-1-6/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Kling 2.5 Turbo API

> Видео Kling 2.5 Turbo: быстрая версия с реалистичной физикой и звуковыми эффектами. По описанию или по первому и последнему кадру, 5 или 10 секунд, 720p или 1080p.

Разработчик: Kuaishou
Ключ модели в API: `kling_pro`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.5t",
    "prompt": "Машина проезжает мимо камеры и скрывается за поворотом",
    "start_frame": [
      "https://example.com/start.jpg"
    ],
    "end_frame": [
      "https://example.com/end.jpg"
    ],
    "quality": "1080p"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "kling_pro",
    "settings": {
        "model_version": "v2.5t",
        "prompt": "Машина проезжает мимо камеры и скрывается за поворотом",
        "start_frame": [
            "https://example.com/start.jpg",
        ],
        "end_frame": [
            "https://example.com/end.jpg",
        ],
        "quality": "1080p",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.5t",
    "prompt": "Машина проезжает мимо камеры и скрывается за поворотом",
    "start_frame": [
      "https://example.com/start.jpg"
    ],
    "end_frame": [
      "https://example.com/end.jpg"
    ],
    "quality": "1080p"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.5t",
    "prompt": "Машина проезжает мимо камеры и скрывается за поворотом",
    "start_frame": [
      "https://example.com/start.jpg"
    ],
    "end_frame": [
      "https://example.com/end.jpg"
    ],
    "quality": "1080p"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="v2.5t"></a>Kling 2.5 Turbo

> Быстрая версия с реалистичной физикой, 5 или 10 секунд, звуковые эффекты.

Значение поля model_version: `v2.5t`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: действие, движение камеры, настроение сцены.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `start_frame` (Необязательно)

Одна ссылка на картинку, с которой начнётся видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `end_frame` (Необязательно)

Одна ссылка на картинку, которой закончится видео. Только вместе с первым кадром.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `quality` (Необязательно)

Качество: 720p или 1080p, цена зависит от него. С последним кадром только 1080p.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `length` (Необязательно)

Длительность видео: 5 или 10 секунд. 10 секунд стоят вдвое дороже.

- Тип: Целое число
- Минимум: 5
- Максимум: 10
- По умолчанию: `5`

#### `aspect_ratio` (Необязательно)

Пропорции видео без кадров. С первым или последним кадром видео берёт пропорции кадра.

- Тип: Строка
- Допустимые значения: `16:9`, `1:1`, `9:16`
- По умолчанию: `"16:9"`

#### `sound_effects` (Необязательно)

Звуковые эффекты синхронно с видео. Не работают с последним кадром.

- Тип: Да/нет
- По умолчанию: `false`

#### `sfx_sound` (Необязательно)

Какие нужны звуки, например шум волн. Только со звуковыми эффектами.

- Тип: Строка
- Максимум символов: 200

#### `sfx_music` (Необязательно)

Какая нужна фоновая музыка, например мелодичная флейта. Только со звуковыми эффектами.

- Тип: Строка
- Максимум символов: 200

#### `sfx_asmr` (Необязательно)

Режим ASMR: звуки подробнее и объёмнее. Только со звуковыми эффектами.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `api_request` = `true`, `native_audio` = `false`

### Входные данные

- Кадры передаются ссылками на JPG или PNG до 10 МБ: сторона не меньше 300 пикселей, пропорции от 1:2,5 до 2,5:1.
- Кадры мы скачиваем сами: ссылка должна открываться без входа и вести прямо на файл, без переадресации.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `start_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |
| `end_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Первый и последний кадр

```json
{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.5t",
    "prompt": "Машина проезжает мимо камеры и скрывается за поворотом",
    "start_frame": [
      "https://example.com/start.jpg"
    ],
    "end_frame": [
      "https://example.com/end.jpg"
    ],
    "quality": "1080p"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4, со звуком, если он включён.
- Генерация обычно занимает 3-5 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Kling 2.5 Turbo: возможности и цены](https://api.cyhub.ai/models/kling-2-5-turbo)
- Другие версии: [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling 2.6 API](https://api.cyhub.ai/models/kling-2-6/api.md), [Kling 2.1 Master API](https://api.cyhub.ai/models/kling-2-1-master/api.md), [Kling 2.1 API](https://api.cyhub.ai/models/kling-2-1/api.md), [Kling 1.6 API](https://api.cyhub.ai/models/kling-1-6/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Kling 2.1 Master API

> Видео Kling 2.1 Master с кинематографичным движением и звуковыми эффектами, только 1080p. По описанию или из вашей картинки, 5 или 10 секунд, последнего кадра нет.

Разработчик: Kuaishou
Ключ модели в API: `kling_pro`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.1m",
    "prompt": "Дождливая улица ночного города, неоновые вывески отражаются в лужах",
    "aspect_ratio": "9:16"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "kling_pro",
    "settings": {
        "model_version": "v2.1m",
        "prompt": "Дождливая улица ночного города, неоновые вывески отражаются в лужах",
        "aspect_ratio": "9:16",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.1m",
    "prompt": "Дождливая улица ночного города, неоновые вывески отражаются в лужах",
    "aspect_ratio": "9:16"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.1m",
    "prompt": "Дождливая улица ночного города, неоновые вывески отражаются в лужах",
    "aspect_ratio": "9:16"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="v2.1m"></a>Kling 2.1 Master

> Кинематографичное движение, только 1080p, без последнего кадра, 5 или 10 секунд.

Значение поля model_version: `v2.1m`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: действие, движение камеры, настроение сцены.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `start_frame` (Необязательно)

Одна ссылка на картинку, с которой начнётся видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `quality` (Необязательно)

Эта версия делает видео только в 1080p.

- Тип: Строка
- Допустимые значения: `1080p`
- По умолчанию: `"1080p"`

#### `length` (Необязательно)

Длительность видео: 5 или 10 секунд. 10 секунд стоят вдвое дороже.

- Тип: Целое число
- Минимум: 5
- Максимум: 10
- По умолчанию: `5`

#### `aspect_ratio` (Необязательно)

Пропорции видео без кадров. С первым или последним кадром видео берёт пропорции кадра.

- Тип: Строка
- Допустимые значения: `16:9`, `1:1`, `9:16`
- По умолчанию: `"16:9"`

#### `sound_effects` (Необязательно)

Звуковые эффекты синхронно с видео. Не работают с последним кадром.

- Тип: Да/нет
- По умолчанию: `false`

#### `sfx_sound` (Необязательно)

Какие нужны звуки, например шум волн. Только со звуковыми эффектами.

- Тип: Строка
- Максимум символов: 200

#### `sfx_music` (Необязательно)

Какая нужна фоновая музыка, например мелодичная флейта. Только со звуковыми эффектами.

- Тип: Строка
- Максимум символов: 200

#### `sfx_asmr` (Необязательно)

Режим ASMR: звуки подробнее и объёмнее. Только со звуковыми эффектами.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `api_request` = `true`, `native_audio` = `false`

### Входные данные

- Кадры передаются ссылками на JPG или PNG до 10 МБ: сторона не меньше 300 пикселей, пропорции от 1:2,5 до 2,5:1.
- Кадры мы скачиваем сами: ссылка должна открываться без входа и вести прямо на файл, без переадресации.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `start_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.1m",
    "prompt": "Дождливая улица ночного города, неоновые вывески отражаются в лужах",
    "aspect_ratio": "9:16"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4, со звуком, если он включён.
- Генерация обычно занимает 3-5 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Kling 2.1 Master: возможности и цены](https://api.cyhub.ai/models/kling-2-1-master)
- Другие версии: [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling 2.6 API](https://api.cyhub.ai/models/kling-2-6/api.md), [Kling 2.5 Turbo API](https://api.cyhub.ai/models/kling-2-5-turbo/api.md), [Kling 2.1 API](https://api.cyhub.ai/models/kling-2-1/api.md), [Kling 1.6 API](https://api.cyhub.ai/models/kling-1-6/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Kling 2.1 API

> Видео Kling 2.1 из вашей картинки: первый кадр обязателен, последний можно добавить. 5 или 10 секунд, 720p или 1080p, звуковые эффекты.

Разработчик: Kuaishou
Ключ модели в API: `kling_pro`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.1",
    "prompt": "Девушка поворачивается к камере и смеётся",
    "start_frame": [
      "https://example.com/portrait.jpg"
    ]
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "kling_pro",
    "settings": {
        "model_version": "v2.1",
        "prompt": "Девушка поворачивается к камере и смеётся",
        "start_frame": [
            "https://example.com/portrait.jpg",
        ],
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.1",
    "prompt": "Девушка поворачивается к камере и смеётся",
    "start_frame": [
      "https://example.com/portrait.jpg"
    ]
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.1",
    "prompt": "Девушка поворачивается к камере и смеётся",
    "start_frame": [
      "https://example.com/portrait.jpg"
    ]
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="v2.1"></a>Kling 2.1

> Оживляет картинку: видео только из первого кадра, 5 или 10 секунд, звуковые эффекты.

Значение поля model_version: `v2.1`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: действие, движение камеры, настроение сцены.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `start_frame` (Обязательно)

Одна ссылка на картинку, с которой начнётся видео. Обязательно.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `end_frame` (Необязательно)

Одна ссылка на картинку, которой закончится видео. Только вместе с первым кадром.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `quality` (Необязательно)

Качество: 720p или 1080p, цена зависит от него. С последним кадром только 1080p.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `length` (Необязательно)

Длительность видео: 5 или 10 секунд. 10 секунд стоят вдвое дороже.

- Тип: Целое число
- Минимум: 5
- Максимум: 10
- По умолчанию: `5`

#### `sound_effects` (Необязательно)

Звуковые эффекты синхронно с видео. Не работают с последним кадром.

- Тип: Да/нет
- По умолчанию: `false`

#### `sfx_sound` (Необязательно)

Какие нужны звуки, например шум волн. Только со звуковыми эффектами.

- Тип: Строка
- Максимум символов: 200

#### `sfx_music` (Необязательно)

Какая нужна фоновая музыка, например мелодичная флейта. Только со звуковыми эффектами.

- Тип: Строка
- Максимум символов: 200

#### `sfx_asmr` (Необязательно)

Режим ASMR: звуки подробнее и объёмнее. Только со звуковыми эффектами.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `api_request` = `true`, `native_audio` = `false`

### Входные данные

- Кадры передаются ссылками на JPG или PNG до 10 МБ: сторона не меньше 300 пикселей, пропорции от 1:2,5 до 2,5:1.
- Кадры мы скачиваем сами: ссылка должна открываться без входа и вести прямо на файл, без переадресации.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `start_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |
| `end_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить фото

```json
{
  "model": "kling_pro",
  "settings": {
    "model_version": "v2.1",
    "prompt": "Девушка поворачивается к камере и смеётся",
    "start_frame": [
      "https://example.com/portrait.jpg"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4, со звуком, если он включён.
- Генерация обычно занимает 3-5 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Kling 2.1: возможности и цены](https://api.cyhub.ai/models/kling-2-1)
- Другие версии: [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling 2.6 API](https://api.cyhub.ai/models/kling-2-6/api.md), [Kling 2.5 Turbo API](https://api.cyhub.ai/models/kling-2-5-turbo/api.md), [Kling 2.1 Master API](https://api.cyhub.ai/models/kling-2-1-master/api.md), [Kling 1.6 API](https://api.cyhub.ai/models/kling-1-6/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Kling 1.6 API

> Видео Kling 1.6: стабильная версия с выразительной мимикой и звуковыми эффектами. По описанию или по первому и последнему кадру, 5 или 10 секунд, 720p или 1080p.

Разработчик: Kuaishou
Ключ модели в API: `kling_pro`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v1.6",
    "prompt": "Волны накатывают на берег, над морем летают чайки",
    "sound_effects": true,
    "sfx_sound": "шум прибоя и крики чаек"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "kling_pro",
    "settings": {
        "model_version": "v1.6",
        "prompt": "Волны накатывают на берег, над морем летают чайки",
        "sound_effects": True,
        "sfx_sound": "шум прибоя и крики чаек",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "kling_pro",
  "settings": {
    "model_version": "v1.6",
    "prompt": "Волны накатывают на берег, над морем летают чайки",
    "sound_effects": true,
    "sfx_sound": "шум прибоя и крики чаек"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_pro",
  "settings": {
    "model_version": "v1.6",
    "prompt": "Волны накатывают на берег, над морем летают чайки",
    "sound_effects": true,
    "sfx_sound": "шум прибоя и крики чаек"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="v1.6"></a>Kling 1.6

> Стабильная версия с выразительной мимикой, 5 или 10 секунд, звуковые эффекты.

Значение поля model_version: `v1.6`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: действие, движение камеры, настроение сцены.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `start_frame` (Необязательно)

Одна ссылка на картинку, с которой начнётся видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `end_frame` (Необязательно)

Одна ссылка на картинку, которой закончится видео. Только вместе с первым кадром.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `quality` (Необязательно)

Качество: 720p или 1080p, цена зависит от него. С последним кадром только 1080p.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `length` (Необязательно)

Длительность видео: 5 или 10 секунд. 10 секунд стоят вдвое дороже.

- Тип: Целое число
- Минимум: 5
- Максимум: 10
- По умолчанию: `5`

#### `aspect_ratio` (Необязательно)

Пропорции видео без кадров. С первым или последним кадром видео берёт пропорции кадра.

- Тип: Строка
- Допустимые значения: `16:9`, `1:1`, `9:16`
- По умолчанию: `"16:9"`

#### `sound_effects` (Необязательно)

Звуковые эффекты синхронно с видео. Не работают с последним кадром.

- Тип: Да/нет
- По умолчанию: `false`

#### `sfx_sound` (Необязательно)

Какие нужны звуки, например шум волн. Только со звуковыми эффектами.

- Тип: Строка
- Максимум символов: 200

#### `sfx_music` (Необязательно)

Какая нужна фоновая музыка, например мелодичная флейта. Только со звуковыми эффектами.

- Тип: Строка
- Максимум символов: 200

#### `sfx_asmr` (Необязательно)

Режим ASMR: звуки подробнее и объёмнее. Только со звуковыми эффектами.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `api_request` = `true`, `native_audio` = `false`

### Входные данные

- Кадры передаются ссылками на JPG или PNG до 10 МБ: сторона не меньше 300 пикселей, пропорции от 1:2,5 до 2,5:1.
- Кадры мы скачиваем сами: ссылка должна открываться без входа и вести прямо на файл, без переадресации.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `start_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |
| `end_frame` | Картинки | jpeg, jpg, png | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео со звуковыми эффектами

```json
{
  "model": "kling_pro",
  "settings": {
    "model_version": "v1.6",
    "prompt": "Волны накатывают на берег, над морем летают чайки",
    "sound_effects": true,
    "sfx_sound": "шум прибоя и крики чаек"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4, со звуком, если он включён.
- Генерация обычно занимает 3-5 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Kling 1.6: возможности и цены](https://api.cyhub.ai/models/kling-1-6)
- Другие версии: [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling 2.6 API](https://api.cyhub.ai/models/kling-2-6/api.md), [Kling 2.5 Turbo API](https://api.cyhub.ai/models/kling-2-5-turbo/api.md), [Kling 2.1 Master API](https://api.cyhub.ai/models/kling-2-1-master/api.md), [Kling 2.1 API](https://api.cyhub.ai/models/kling-2-1/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Kling Motion 3.0 API

> Видео Kling Motion 3.0: человек с вашего фото повторяет движения из вашего видео. Версия 3.0 точнее передаёт сложные движения и лицо, 720p или 1080p. Звук из видео с движениями можно оставить.

Разработчик: Kuaishou
Ключ модели в API: `kling_motion`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_motion",
  "settings": {
    "image_url": [
      "https://example.com/person.png"
    ],
    "video_url": [
      "https://example.com/moves.mov"
    ],
    "model_version": "3.0",
    "quality": "pro",
    "with_audio": false,
    "prompt": "Ночная улица с неоновыми вывесками, лёгкий дождь"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "kling_motion",
    "settings": {
        "image_url": [
            "https://example.com/person.png",
        ],
        "video_url": [
            "https://example.com/moves.mov",
        ],
        "model_version": "3.0",
        "quality": "pro",
        "with_audio": False,
        "prompt": "Ночная улица с неоновыми вывесками, лёгкий дождь",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "kling_motion",
  "settings": {
    "image_url": [
      "https://example.com/person.png"
    ],
    "video_url": [
      "https://example.com/moves.mov"
    ],
    "model_version": "3.0",
    "quality": "pro",
    "with_audio": false,
    "prompt": "Ночная улица с неоновыми вывесками, лёгкий дождь"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_motion",
  "settings": {
    "image_url": [
      "https://example.com/person.png"
    ],
    "video_url": [
      "https://example.com/moves.mov"
    ],
    "model_version": "3.0",
    "quality": "pro",
    "with_audio": false,
    "prompt": "Ночная улица с неоновыми вывесками, лёгкий дождь"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

На этой странице версия Kling Motion 3.0: передайте model_version = 3.0. Без поля model_version запустится 2.6.

## <a id="parameters"></a>Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

### `image_url` (Обязательно)

Одна ссылка на фото персонажа. Голова и тело хорошо видны и ничем не закрыты. Персонаж в кадре так же, как человек в видео: по пояс или целиком.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

### `video_url` (Обязательно)

Одна ссылка на видео с движениями: лучше один человек, снятый одним планом, без склеек и движения камеры. Видео уходит в Kling целиком.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

### `prompt` (Необязательно)

Необязательно. Сцена и внешний вид. Движение описывать не нужно, оно берётся из видео.

- Тип: Строка
- Максимум символов: 2500

### `model_version` (Необязательно)

Версия модели. VIDEO 3.0 точнее передаёт сложные движения и лицо, VIDEO 2.6 проверенная и дешевле.

- Тип: Строка
- Допустимые значения: `3.0`
- По умолчанию: `"2.6"`

### `quality` (Необязательно)

Разрешение: Стандарт 720p или Pro 1080p. Pro дороже.

- Тип: Строка
- Допустимые значения: `std` (Стандарт), `pro`
- По умолчанию: `"std"`

### `orientation` (Необязательно)

Как развёрнут персонаж: как человек в видео (лучше для сложных движений, видео до 30 секунд) или как на фото (кадр как на фото, видео до 10 секунд).

- Тип: Строка
- Допустимые значения: `video` (По видео), `image` (По изображению)
- По умолчанию: `"video"`

### `with_audio` (Необязательно)

Оставить в готовом видео звук из видео с движениями.

- Тип: Да/нет
- По умолчанию: `true`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

## <a id="input"></a>Входные данные

- Фото передаётся ссылкой на JPEG или PNG до 10 МБ: не меньше 300 пикселей по каждой стороне, пропорции от 1:2,5 до 2,5:1.
- Видео передаётся ссылкой на MP4 или MOV до 100 МБ, стороны от 340 до 3850 пикселей. Длина от 3 до 30 секунд, с ориентацией по фото до 10.
- Цена за каждую секунду видео с движениями, считается по всей его длине.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_url` | Картинки | jpeg, jpg, png | 1 | 10 МБ |
| `video_url` | Видео | mp4, mov | 1 | 100 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

## <a id="example"></a>Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

VIDEO 3.0 в 1080p, без звука, со сценой

```json
{
  "model": "kling_motion",
  "settings": {
    "image_url": [
      "https://example.com/person.png"
    ],
    "video_url": [
      "https://example.com/moves.mov"
    ],
    "model_version": "3.0",
    "quality": "pro",
    "with_audio": false,
    "prompt": "Ночная улица с неоновыми вывесками, лёгкий дождь"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

## <a id="output"></a>Результат

- Одно видео MP4 длиной с видео движений. Бывает короче: Kling берёт только те движения, которые распознал.
- Генерация занимает 5-10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Kling Motion 3.0: возможности и цены](https://api.cyhub.ai/models/kling-motion)
- Другие версии: [Kling Motion 2.6 API](https://api.cyhub.ai/models/kling-motion-2-6/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Kling Motion 2.6 API

> Видео Kling Motion 2.6: человек с вашего фото повторяет движения из вашего видео. Проверенная и более дешёвая версия, 720p или 1080p.

Разработчик: Kuaishou
Ключ модели в API: `kling_motion`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_motion",
  "settings": {
    "image_url": [
      "https://example.com/person.jpg"
    ],
    "video_url": [
      "https://example.com/dance.mp4"
    ],
    "model_version": "2.6"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "kling_motion",
    "settings": {
        "image_url": [
            "https://example.com/person.jpg",
        ],
        "video_url": [
            "https://example.com/dance.mp4",
        ],
        "model_version": "2.6",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "kling_motion",
  "settings": {
    "image_url": [
      "https://example.com/person.jpg"
    ],
    "video_url": [
      "https://example.com/dance.mp4"
    ],
    "model_version": "2.6"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "kling_motion",
  "settings": {
    "image_url": [
      "https://example.com/person.jpg"
    ],
    "video_url": [
      "https://example.com/dance.mp4"
    ],
    "model_version": "2.6"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="parameters"></a>Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

### `image_url` (Обязательно)

Одна ссылка на фото персонажа. Голова и тело хорошо видны и ничем не закрыты. Персонаж в кадре так же, как человек в видео: по пояс или целиком.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

### `video_url` (Обязательно)

Одна ссылка на видео с движениями: лучше один человек, снятый одним планом, без склеек и движения камеры. Видео уходит в Kling целиком.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

### `prompt` (Необязательно)

Необязательно. Сцена и внешний вид. Движение описывать не нужно, оно берётся из видео.

- Тип: Строка
- Максимум символов: 2500

### `model_version` (Необязательно)

Версия модели. VIDEO 3.0 точнее передаёт сложные движения и лицо, VIDEO 2.6 проверенная и дешевле.

- Тип: Строка
- Допустимые значения: `2.6`
- По умолчанию: `"2.6"`

### `quality` (Необязательно)

Разрешение: Стандарт 720p или Pro 1080p. Pro дороже.

- Тип: Строка
- Допустимые значения: `std` (Стандарт), `pro`
- По умолчанию: `"std"`

### `orientation` (Необязательно)

Как развёрнут персонаж: как человек в видео (лучше для сложных движений, видео до 30 секунд) или как на фото (кадр как на фото, видео до 10 секунд).

- Тип: Строка
- Допустимые значения: `video` (По видео), `image` (По изображению)
- По умолчанию: `"video"`

### `with_audio` (Необязательно)

Оставить в готовом видео звук из видео с движениями.

- Тип: Да/нет
- По умолчанию: `true`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

## <a id="input"></a>Входные данные

- Фото передаётся ссылкой на JPEG или PNG до 10 МБ: не меньше 300 пикселей по каждой стороне, пропорции от 1:2,5 до 2,5:1.
- Видео передаётся ссылкой на MP4 или MOV до 100 МБ, стороны от 340 до 3850 пикселей. Длина от 3 до 30 секунд, с ориентацией по фото до 10.
- Цена за каждую секунду видео с движениями, считается по всей его длине.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_url` | Картинки | jpeg, jpg, png | 1 | 10 МБ |
| `video_url` | Видео | mp4, mov | 1 | 100 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

## <a id="example"></a>Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Повторить танец из видео

```json
{
  "model": "kling_motion",
  "settings": {
    "image_url": [
      "https://example.com/person.jpg"
    ],
    "video_url": [
      "https://example.com/dance.mp4"
    ]
  }
}
```

Кадр как на фото, видео до 10 секунд

```json
{
  "model": "kling_motion",
  "settings": {
    "image_url": [
      "https://example.com/portrait.jpg"
    ],
    "video_url": [
      "https://example.com/short-moves.mp4"
    ],
    "orientation": "image"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

## <a id="output"></a>Результат

- Одно видео MP4 длиной с видео движений. Бывает короче: Kling берёт только те движения, которые распознал.
- Генерация занимает 5-10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Kling Motion 2.6: возможности и цены](https://api.cyhub.ai/models/kling-motion-2-6)
- Другие версии: [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Midjourney 8.2 API

> Картинки Midjourney 8.2 по описанию и по вашим фото: перенос человека или предмета в новую сцену, правка фото словами. Сетка из четырёх вариантов, картинки-подсказки и образцы стиля. Можно выбрать и предыдущую версию 8.1.

Разработчик: Midjourney
Ключ модели в API: `midjourney`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "midjourney",
  "settings": {
    "version": "8.2",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, film photo",
    "aspect_ratio": "3:2",
    "speed": "fast",
    "stylization": 250
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "midjourney",
    "settings": {
        "version": "8.2",
        "prompt": "A cozy reading nook by a rainy window, warm lamp light, film photo",
        "aspect_ratio": "3:2",
        "speed": "fast",
        "stylization": 250,
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "midjourney",
  "settings": {
    "version": "8.2",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, film photo",
    "aspect_ratio": "3:2",
    "speed": "fast",
    "stylization": 250
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "midjourney",
  "settings": {
    "version": "8.2",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, film photo",
    "aspect_ratio": "3:2",
    "speed": "fast",
    "stylization": 250
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="8.2"></a>Midjourney 8.2

> Основные версии: 8.2 по умолчанию, 8.1 предыдущая. В них же перенос человека или предмета с фото в новую сцену и правка фото словами (edit_images), по цене обычной картинки.

Значение поля version: `8.2` `8.1`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что нарисовать. Только обычный текст: параметры Midjourney (--ar, --v и другие), ссылки и варианты в фигурных скобках не принимаются, для настроек и картинок есть поля. Версии 8.2 и 8.1 сами сокращают описание длиннее примерно 1000 знаков, версия 7 берёт текст целиком.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 6000

#### `aspect_ratio` (Необязательно)

Пропорции картинки: ширина и высота целыми числами через двоеточие, только цифры и без пробелов, например 1:1, 16:9, 9:16, 4:5, 2:3, 21:9.

- Тип: Строка
- Максимум символов: 11
- По умолчанию: `"1:1"`

#### `speed` (Необязательно)

Скорость. Relaxed дешевле, но ждёт в очереди, Fast быстрее и дороже. От неё зависит цена.

- Тип: Строка
- Допустимые значения: `relaxed`, `fast`
- По умолчанию: `"relaxed"`

#### `stylization` (Необязательно)

Насколько художественно: 0 строго по описанию, 1000 больше всего красоты, но дальше от описания. Не задано: 100.

- Тип: Целое число
- Минимум: 0
- Максимум: 1000

#### `chaos` (Необязательно)

Насколько разными будут четыре картинки: 0 похожие, 100 самые разные.

- Тип: Целое число
- Минимум: 0
- Максимум: 100

#### `weirdness` (Необязательно)

Необычность: 0 обычная картинка, 3000 сюрреализм и абстракция.

- Тип: Целое число
- Минимум: 0
- Максимум: 3000

#### `raw_mode` (Необязательно)

Без художественной обработки Midjourney: результат ближе к обычному фото.

- Тип: Да/нет
- По умолчанию: `false`

#### `tile` (Необязательно)

Бесшовный узор, который можно повторять во все стороны: обои, ткани, фоны.

- Тип: Да/нет
- По умолчанию: `false`

#### `seed` (Необязательно)

Начальное число. Одинаковые число и описание дают похожий результат. Не задано: случайное.

- Тип: Целое число
- Минимум: 0
- Максимум: 4294967295

#### `exclusions` (Необязательно)

Чего не должно быть на картинке, словами через запятую, например: text, people, blur.

- Тип: Строка
- Максимум символов: 500

#### `image_prompts` (Необязательно)

Картинки-подсказки: Midjourney возьмёт с них сюжет, композицию и цвета. До 4 ссылок.

- Тип: Список (Строка, uri)
- Максимум элементов: 4

#### `iw` (Необязательно)

Сила картинок-подсказок: 0 почти не влияют, 3 сильнее всего. Не задано: 1. Действует только вместе с картинками-подсказками.

- Тип: Число
- Минимум: 0
- Максимум: 3

#### `style_ref_images` (Необязательно)

Образцы стиля: переносятся манера, цвета и настроение, но не сами предметы. До 3 ссылок.

- Тип: Список (Строка, uri)
- Максимум элементов: 3

#### `sref_code` (Необязательно)

Код стиля Midjourney, только цифры, например 123456789. Можно вместе с образцами стиля.

- Тип: Строка

#### `sw` (Необязательно)

Сила стиля: 0 почти не влияет, 1000 сильнее всего. Не задано: 100. Действует только вместе с образцами стиля или кодом стиля.

- Тип: Целое число
- Минимум: 0
- Максимум: 1000

#### `enable_translation` (Необязательно)

Перевести описание на английский перед генерацией. Если перевод не удастся или в нём окажутся параметры, ссылки или варианты в скобках, уйдёт исходное описание.

- Тип: Да/нет
- По умолчанию: `false`

#### `edit_images` (Необязательно)

Фото, по которым Midjourney нарисует новую картинку: перенесёт человека, персонажа или предмет в новую сцену, поменяет одежду или фон, покажет с другой стороны, соберёт несколько фото в одну сцену. Что сделать, пишите в prompt. До 4 ссылок. Пропорции результата задаёт aspect_ratio, а не фото. Не сочетается с tile.

- Тип: Список (Строка, uri)
- Максимум элементов: 4

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `plain_text` = `true`, `rework_button` = `false`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая, картинка для правки по маске только PNG. Ссылка должна открываться без входа и без переадресации.
- Описание и исключения только обычным текстом: без параметров Midjourney, ссылок и вариантов в фигурных скобках. Настройки и картинки задаются полями.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_prompts` | Картинки | jpeg, jpg, png, webp | 4 | 10 МБ |
| `style_ref_images` | Картинки | jpeg, jpg, png, webp | 3 | 10 МБ |
| `edit_images` | Картинки | jpeg, jpg, png, webp | 4 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Картинка по описанию

```json
{
  "model": "midjourney",
  "settings": {
    "version": "8.2",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, film photo",
    "aspect_ratio": "3:2",
    "speed": "fast",
    "stylization": 250
  }
}
```

Описание на русском с переводом

```json
{
  "model": "midjourney",
  "settings": {
    "version": "8.2",
    "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город",
    "aspect_ratio": "4:5",
    "enable_translation": true,
    "exclusions": "text, watermark"
  }
}
```

Картинка в стиле образца

```json
{
  "model": "midjourney",
  "settings": {
    "version": "8.2",
    "prompt": "A lighthouse on a cliff at dusk, waves crashing below",
    "aspect_ratio": "16:9",
    "style_ref_images": [
      "https://example.com/style-sample.jpg"
    ],
    "sw": 300
  }
}
```

Человек с фото в новой сцене

```json
{
  "model": "midjourney",
  "settings": {
    "version": "8.2",
    "prompt": "Make this woman wear a red silk gown on a seaside terrace at sunset, full body",
    "aspect_ratio": "2:3",
    "raw_mode": true,
    "edit_images": [
      "https://example.com/person.jpg"
    ]
  }
}
```

Правка фото словами

```json
{
  "model": "midjourney",
  "settings": {
    "version": "8.2",
    "prompt": "Make the jacket yellow and turn the background into a snowy forest",
    "aspect_ratio": "4:5",
    "edit_images": [
      "https://example.com/photo.jpg"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Четыре картинки JPEG за один запуск, каждая отдельным файлом.
- С Fast результат обычно через минуту, Relaxed ждёт в очереди дольше.
- Увеличение и вариации готовых картинок есть только в боте.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | jpg | 4 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      },
      {
        "index": 2,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/2"
      },
      {
        "index": 3,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/3"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Midjourney 8.2: возможности и цены](https://api.cyhub.ai/models/midjourney)
- Другие версии: [Midjourney Editor API](https://api.cyhub.ai/models/midjourney-editor/api.md), [Midjourney 7 API](https://api.cyhub.ai/models/midjourney-7/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Midjourney Editor API

> Midjourney Editor правит вашу картинку: прозрачные места PNG Midjourney перерисует по описанию. Убрать лишнее, заменить фон или предмет, расширить кадр, остальное останется как было.

Разработчик: Midjourney
Ключ модели в API: `midjourney`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "midjourney",
  "settings": {
    "version": "edit",
    "prompt": "A sunny beach with palm trees and a turquoise sea",
    "image_url": [
      "https://example.com/portrait-transparent-background.png"
    ],
    "speed": "fast"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "midjourney",
    "settings": {
        "version": "edit",
        "prompt": "A sunny beach with palm trees and a turquoise sea",
        "image_url": [
            "https://example.com/portrait-transparent-background.png",
        ],
        "speed": "fast",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "midjourney",
  "settings": {
    "version": "edit",
    "prompt": "A sunny beach with palm trees and a turquoise sea",
    "image_url": [
      "https://example.com/portrait-transparent-background.png"
    ],
    "speed": "fast"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "midjourney",
  "settings": {
    "version": "edit",
    "prompt": "A sunny beach with palm trees and a turquoise sea",
    "image_url": [
      "https://example.com/portrait-transparent-background.png"
    ],
    "speed": "fast"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="edit"></a>Midjourney Editor

> Midjourney перерисует прозрачные места вашей картинки по описанию, остальное останется как было: убрать лишнее, заменить фон или предмет, расширить кадр. Правку делает версия 8.2.

Значение поля version: `edit`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что должно появиться на прозрачных местах картинки. Только обычный текст: параметры Midjourney (--ar, --v и другие), ссылки и варианты в фигурных скобках не принимаются.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 900

#### `image_url` (Обязательно)

Одна ссылка на картинку PNG, которую нужно поправить: прозрачные места Midjourney перерисует по описанию, остальное оставит как было. Длинная сторона до 2048 пикселей, обе стороны делятся на 16.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `speed` (Необязательно)

Скорость. Relaxed дешевле, но ждёт в очереди, Fast быстрее и дороже. От неё зависит цена.

- Тип: Строка
- Допустимые значения: `relaxed`, `fast`
- По умолчанию: `"relaxed"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `plain_text` = `true`, `rework_button` = `false`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая, картинка для правки по маске только PNG. Ссылка должна открываться без входа и без переадресации.
- Описание и исключения только обычным текстом: без параметров Midjourney, ссылок и вариантов в фигурных скобках. Настройки и картинки задаются полями.
- Прозрачные места картинки Midjourney нарисует заново по описанию. Чтобы расширить кадр, добавьте по краям прозрачные поля: пропорции результата будут как у картинки.
- Картинка уходит в Midjourney как есть, без подгонки: PNG до 2048 пикселей по длинной стороне, обе стороны делятся на 16 без остатка, например 1024×1024, 1456×816 или 816×1456. Другая картинка получит отказ, деньги за неё не спишутся.
- Цена как у картинки по описанию с той же скоростью.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_url` | Картинки | png | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Заменить фон

```json
{
  "model": "midjourney",
  "settings": {
    "version": "edit",
    "prompt": "A sunny beach with palm trees and a turquoise sea",
    "image_url": [
      "https://example.com/portrait-transparent-background.png"
    ],
    "speed": "fast"
  }
}
```

Расширить кадр

```json
{
  "model": "midjourney",
  "settings": {
    "version": "edit",
    "prompt": "A wide mountain valley at sunrise, mist over the river",
    "image_url": [
      "https://example.com/photo-with-transparent-margins.png"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Четыре картинки JPEG за один запуск, каждая отдельным файлом.
- С Fast результат обычно через минуту, Relaxed ждёт в очереди дольше.
- Увеличение и вариации готовых картинок есть только в боте.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | jpg | 4 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      },
      {
        "index": 2,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/2"
      },
      {
        "index": 3,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/3"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Midjourney Editor: возможности и цены](https://api.cyhub.ai/models/midjourney-editor)
- Другие версии: [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Midjourney 7 API](https://api.cyhub.ai/models/midjourney-7/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Midjourney 7 API

> Картинки Midjourney 7 по описанию и перенос человека, персонажа или предмета с фото в новую картинку. Сетка из четырёх вариантов, картинки-подсказки и образцы стиля. Запуск с переносом дороже обычного.

Разработчик: Midjourney
Ключ модели в API: `midjourney`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "midjourney",
  "settings": {
    "version": "7",
    "prompt": "This man as an astronaut walking on the Moon, cinematic light",
    "aspect_ratio": "2:3",
    "omni_ref_image": [
      "https://example.com/person.jpg"
    ],
    "ow": 200
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "midjourney",
    "settings": {
        "version": "7",
        "prompt": "This man as an astronaut walking on the Moon, cinematic light",
        "aspect_ratio": "2:3",
        "omni_ref_image": [
            "https://example.com/person.jpg",
        ],
        "ow": 200,
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "midjourney",
  "settings": {
    "version": "7",
    "prompt": "This man as an astronaut walking on the Moon, cinematic light",
    "aspect_ratio": "2:3",
    "omni_ref_image": [
      "https://example.com/person.jpg"
    ],
    "ow": 200
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "midjourney",
  "settings": {
    "version": "7",
    "prompt": "This man as an astronaut walking on the Moon, cinematic light",
    "aspect_ratio": "2:3",
    "omni_ref_image": [
      "https://example.com/person.jpg"
    ],
    "ow": 200
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="7"></a>Midjourney 7

> Перенос человека, персонажа или предмета с фото через Omni Reference, с силой сходства ow. Такой запуск дороже обычного. В версиях 8.2 и 8.1 перенос делает поле edit_images по цене обычной картинки.

Значение поля version: `7`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что нарисовать. Только обычный текст: параметры Midjourney (--ar, --v и другие), ссылки и варианты в фигурных скобках не принимаются, для настроек и картинок есть поля. Версии 8.2 и 8.1 сами сокращают описание длиннее примерно 1000 знаков, версия 7 берёт текст целиком.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 6000

#### `aspect_ratio` (Необязательно)

Пропорции картинки: ширина и высота целыми числами через двоеточие, только цифры и без пробелов, например 1:1, 16:9, 9:16, 4:5, 2:3, 21:9.

- Тип: Строка
- Максимум символов: 11
- По умолчанию: `"1:1"`

#### `speed` (Необязательно)

Скорость. Relaxed дешевле, но ждёт в очереди, Fast быстрее и дороже. От неё зависит цена.

- Тип: Строка
- Допустимые значения: `relaxed`, `fast`
- По умолчанию: `"relaxed"`

#### `stylization` (Необязательно)

Насколько художественно: 0 строго по описанию, 1000 больше всего красоты, но дальше от описания. Не задано: 100.

- Тип: Целое число
- Минимум: 0
- Максимум: 1000

#### `chaos` (Необязательно)

Насколько разными будут четыре картинки: 0 похожие, 100 самые разные.

- Тип: Целое число
- Минимум: 0
- Максимум: 100

#### `weirdness` (Необязательно)

Необычность: 0 обычная картинка, 3000 сюрреализм и абстракция.

- Тип: Целое число
- Минимум: 0
- Максимум: 3000

#### `raw_mode` (Необязательно)

Без художественной обработки Midjourney: результат ближе к обычному фото.

- Тип: Да/нет
- По умолчанию: `false`

#### `tile` (Необязательно)

Бесшовный узор, который можно повторять во все стороны: обои, ткани, фоны.

- Тип: Да/нет
- По умолчанию: `false`

#### `seed` (Необязательно)

Начальное число. Одинаковые число и описание дают похожий результат. Не задано: случайное.

- Тип: Целое число
- Минимум: 0
- Максимум: 4294967295

#### `exclusions` (Необязательно)

Чего не должно быть на картинке, словами через запятую, например: text, people, blur.

- Тип: Строка
- Максимум символов: 500

#### `image_prompts` (Необязательно)

Картинки-подсказки: Midjourney возьмёт с них сюжет, композицию и цвета. До 4 ссылок.

- Тип: Список (Строка, uri)
- Максимум элементов: 4

#### `iw` (Необязательно)

Сила картинок-подсказок: 0 почти не влияют, 3 сильнее всего. Не задано: 1. Действует только вместе с картинками-подсказками.

- Тип: Число
- Минимум: 0
- Максимум: 3

#### `style_ref_images` (Необязательно)

Образцы стиля: переносятся манера, цвета и настроение, но не сами предметы. До 3 ссылок.

- Тип: Список (Строка, uri)
- Максимум элементов: 3

#### `sref_code` (Необязательно)

Код стиля Midjourney, только цифры, например 123456789. Можно вместе с образцами стиля.

- Тип: Строка

#### `sw` (Необязательно)

Сила стиля: 0 почти не влияет, 1000 сильнее всего. Не задано: 100. Действует только вместе с образцами стиля или кодом стиля.

- Тип: Целое число
- Минимум: 0
- Максимум: 1000

#### `enable_translation` (Необязательно)

Перевести описание на английский перед генерацией. Если перевод не удастся или в нём окажутся параметры, ссылки или варианты в скобках, уйдёт исходное описание.

- Тип: Да/нет
- По умолчанию: `false`

#### `omni_ref_image` (Необязательно)

Одна ссылка на фото человека, персонажа или предмета, который появится в новой картинке. С ней запуск дороже.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `ow` (Необязательно)

Насколько держаться за это фото: 1 лёгкий намёк, 1000 как можно ближе. Не задано: 100. Выше 400 результат может стать непредсказуемым. Действует только вместе с фото.

- Тип: Целое число
- Минимум: 1
- Максимум: 1000

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `plain_text` = `true`, `rework_button` = `false`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая, картинка для правки по маске только PNG. Ссылка должна открываться без входа и без переадресации.
- Описание и исключения только обычным текстом: без параметров Midjourney, ссылок и вариантов в фигурных скобках. Настройки и картинки задаются полями.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_prompts` | Картинки | jpeg, jpg, png, webp | 4 | 10 МБ |
| `style_ref_images` | Картинки | jpeg, jpg, png, webp | 3 | 10 МБ |
| `omni_ref_image` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Человек с фото в новой сцене

```json
{
  "model": "midjourney",
  "settings": {
    "version": "7",
    "prompt": "This man as an astronaut walking on the Moon, cinematic light",
    "aspect_ratio": "2:3",
    "omni_ref_image": [
      "https://example.com/person.jpg"
    ],
    "ow": 200
  }
}
```

Картинка в стиле образца

```json
{
  "model": "midjourney",
  "settings": {
    "version": "7",
    "prompt": "A lighthouse on a cliff at dusk, waves crashing below",
    "aspect_ratio": "16:9",
    "style_ref_images": [
      "https://example.com/style-sample.jpg"
    ],
    "sw": 300
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Четыре картинки JPEG за один запуск, каждая отдельным файлом.
- С Fast результат обычно через минуту, Relaxed ждёт в очереди дольше.
- Увеличение и вариации готовых картинок есть только в боте.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | jpg | 4 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      },
      {
        "index": 2,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/2"
      },
      {
        "index": 3,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/3"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Midjourney 7: возможности и цены](https://api.cyhub.ai/models/midjourney-7)
- Другие версии: [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Midjourney Editor API](https://api.cyhub.ai/models/midjourney-editor/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Veo 3.1 API

> Видео Veo 3.1 со звуком: по описанию, по кадрам или по референсам, три уровня качества.

Разработчик: Google
Ключ модели в API: `veo`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "veo",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "veo",
    "settings": {
        "mode": "text_to_video",
        "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
        "tier": "lite",
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "veo",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "veo",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_video"></a>По описанию

> Видео только по тексту, картинки не передаются.

Значение поля mode: `text_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео. Реплики и звуки можно описать словами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `tier` (Необязательно)

Уровень качества, от него зависит цена.

- Тип: Строка
- Допустимые значения: `lite`, `fast`, `quality`
- По умолчанию: `"lite"`

#### `aspect_ratio` (Необязательно)

Горизонтальное 16:9 или вертикальное 9:16.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`
- По умолчанию: `"9:16"`

#### `resolution` (Необязательно)

Разрешение готового видео. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`, `4k`
- По умолчанию: `"720p"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Ролик всегда 8 секунд.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "veo",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4 со звуком.
- Генерация занимает несколько минут, 4K дольше.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="frames_to_video"></a>По кадрам

> Первый кадр или первый и последний: модель оживляет их по описанию.

Значение поля mode: `frames_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео. Реплики и звуки можно описать словами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `tier` (Необязательно)

Уровень качества, от него зависит цена.

- Тип: Строка
- Допустимые значения: `lite`, `fast`, `quality`
- По умолчанию: `"lite"`

#### `aspect_ratio` (Необязательно)

Горизонтальное 16:9 или вертикальное 9:16.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`
- По умолчанию: `"9:16"`

#### `resolution` (Необязательно)

Разрешение готового видео. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`, `4k`
- По умолчанию: `"720p"`

#### `image_urls` (Обязательно)

Одна ссылка: первый кадр. Две ссылки: первый и последний кадры.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Ролик всегда 8 секунд.
- Картинки передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 2 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить кадр

```json
{
  "model": "veo",
  "settings": {
    "mode": "frames_to_video",
    "prompt": "Камера медленно наезжает, листья шевелятся на ветру",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4 со звуком.
- Генерация занимает несколько минут, 4K дольше.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="references_to_video"></a>По референсам

> Персонажи и предметы с ваших картинок в новом видео. Уровень Quality здесь недоступен.

Значение поля mode: `references_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео. Реплики и звуки можно описать словами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `tier` (Необязательно)

Уровень качества, от него зависит цена. Quality с референсами не работает.

- Тип: Строка
- Допустимые значения: `lite`, `fast`
- По умолчанию: `"lite"`

#### `aspect_ratio` (Необязательно)

Горизонтальное 16:9 или вертикальное 9:16.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`
- По умолчанию: `"9:16"`

#### `resolution` (Необязательно)

Разрешение готового видео. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`, `4k`
- По умолчанию: `"720p"`

#### `image_urls` (Обязательно)

От одной до трёх ссылок на картинки с персонажами или предметами.

- Тип: Список (Строка, uri)
- Максимум элементов: 3

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Ролик всегда 8 секунд.
- Картинки передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 3 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Персонаж с картинки

```json
{
  "model": "veo",
  "settings": {
    "mode": "references_to_video",
    "prompt": "Этот персонаж идёт по ночному городу под дождём",
    "tier": "fast",
    "aspect_ratio": "9:16",
    "resolution": "1080p",
    "image_urls": [
      "https://example.com/character.png"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4 со звуком.
- Генерация занимает несколько минут, 4K дольше.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Veo 3.1: возможности и цены](https://api.cyhub.ai/models/veo-3-1)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Wan 3.0 API

> Видео Wan 3.0 по первому и последнему кадру, по референсам и в режиме Omni, где картинки, видео и звук идут вместе. От 2 до 30 секунд, до 1080p.

Разработчик: Alibaba
Ключ модели в API: `wan`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "wan",
  "settings": {
    "mode": "frames",
    "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "quality": "720p",
    "duration": "5s",
    "model": "3_0"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "wan",
    "settings": {
        "mode": "frames",
        "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
        "image_urls": [
            "https://example.com/first-frame.jpg",
        ],
        "quality": "720p",
        "duration": "5s",
        "model": "3_0",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "wan",
  "settings": {
    "mode": "frames",
    "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "quality": "720p",
    "duration": "5s",
    "model": "3_0"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "wan",
  "settings": {
    "mode": "frames",
    "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "quality": "720p",
    "duration": "5s",
    "model": "3_0"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="frames"></a>По кадрам

> Первый кадр или первый и последний: модель оживляет их по описанию. У 3.0 кадр обязателен, у остальных версий можно и без него.

Значение поля mode: `frames`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в ролике: сцена, движение, камера, стиль. До 5000 знаков, у 3.0 до 20 000.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `image_urls` (Необязательно)

Одна ссылка: первый кадр. Две ссылки: первый и последний кадры.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

#### `model` (Необязательно)

Версия Wan. У 3.0, самой новой, нет своего звука и деления на сцены.

- Тип: Строка
- Допустимые значения: `3_0` (Wan 3.0)
- По умолчанию: `"3_0"`

#### `quality` (Необязательно)

Разрешение ролика, набор зависит от версии. От него зависит цена секунды.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра. У 2.5 в 480p только 16:9, 9:16 и 1:1.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- Набор зависит от `quality`.
- По умолчанию: `"16:9"`

#### `duration` (Необязательно)

Длина ролика: у 2.5 только 5 или 10 секунд, у 2.6 и 2.7 от 2 до 15, у 3.0 от 2 до 30. Цена за каждую секунду.

- Тип: Строка
- Допустимые значения: `2s` (2 сек), `3s` (3 сек), `4s` (4 сек), `5s` (5 сек), `6s` (6 сек), `7s` (7 сек), `8s` (8 сек), `9s` (9 сек), `10s` (10 сек), `11s` (11 сек), `12s` (12 сек), `13s` (13 сек), `14s` (14 сек), `15s` (15 сек), `16s` (16 сек), `17s` (17 сек), `18s` (18 сек), `19s` (19 сек), `20s` (20 сек), `21s` (21 сек), `22s` (22 сек), `23s` (23 сек), `24s` (24 сек), `25s` (25 сек), `26s` (26 сек), `27s` (27 сек), `28s` (28 сек), `29s` (29 сек), `30s` (30 сек)
- По умолчанию: `"5s"`

#### `multi_shots` (Необязательно)

Разбить ролик на несколько сцен. Только у 2.6 и 2.7.

- Тип: Да/нет
- По умолчанию: `false`

#### `audio` (Необязательно)

Свой звук для ролика, например голос или музыка: одна ссылка. Есть у 2.6 и 2.7. Звук длиннее ролика обрезается по его длине.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Кадры передаются ссылками на JPEG, PNG или WebP до 10 МБ каждый.
- Звук передаётся ссылкой на MP3 или WAV до 10 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 2 | 10 МБ |
| `audio` | Аудио | mp3, wav | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить кадр

```json
{
  "model": "wan",
  "settings": {
    "mode": "frames",
    "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "quality": "720p",
    "duration": "5s"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 5 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="reference"></a>По референсам

> Персонажи, предметы и места с ваших картинок и видео в новом ролике. Версии 2.7 и 3.0.

Значение поля mode: `reference`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в ролике. На вложения ссылайтесь подписями @Image1, @Video1, каждое нужно упомянуть. До 5000 знаков, у 3.0 до 20 000.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `ref_image_urls` (Необязательно)

Картинки с персонажами, предметами или местом, в описании @Image1, @Image2 по порядку ссылок. Картинок и видео вместе до 5, хотя бы одно из них обязательно.

- Тип: Список (Строка, uri)
- Максимум элементов: 5

#### `ref_video_urls` (Необязательно)

Видео с персонажем, в описании @Video1, @Video2. Каждое от 1 до 5 секунд, их секунды входят в цену. У 2.7 с видео готовый ролик не длиннее 10 секунд.

- Тип: Список (Строка, uri)
- Максимум элементов: 5

#### `first_frame_url` (Необязательно)

Первый кадр ролика, необязательно. С ним пропорции берутся у кадра, и поле aspect_ratio не действует.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `model` (Необязательно)

Версия Wan: 2.7 или 3.0.

- Тип: Строка
- Допустимые значения: `3_0` (Wan 3.0)
- По умолчанию: `"3_0"`

#### `quality` (Необязательно)

Разрешение ролика, набор зависит от версии. От него зависит цена секунды.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- Набор зависит от `quality`.
- По умолчанию: `"16:9"`

#### `duration` (Необязательно)

Длина ролика: у 2.7 от 2 до 15 секунд, а с видео среди вложений до 10; у 3.0 от 2 до 30. Цена за каждую секунду.

- Тип: Строка
- Допустимые значения: `2s` (2 сек), `3s` (3 сек), `4s` (4 сек), `5s` (5 сек), `6s` (6 сек), `7s` (7 сек), `8s` (8 сек), `9s` (9 сек), `10s` (10 сек), `11s` (11 сек), `12s` (12 сек), `13s` (13 сек), `14s` (14 сек), `15s` (15 сек), `16s` (16 сек), `17s` (17 сек), `18s` (18 сек), `19s` (19 сек), `20s` (20 сек), `21s` (21 сек), `22s` (22 сек), `23s` (23 сек), `24s` (24 сек), `25s` (25 сек), `26s` (26 сек), `27s` (27 сек), `28s` (28 сек), `29s` (29 сек), `30s` (30 сек)
- По умолчанию: `"5s"`

#### `multi_shots` (Необязательно)

Разбить ролик на несколько сцен. Только у 2.7.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Каждое вложение нужно упомянуть в описании подписью: @Image1, @Image2, @Video1 и так далее. Номер это место ссылки в поле своего типа. Писать ровно так: с большой буквы, без пробела.
- Картинки передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая, видео ссылками на MP4 или MOV до 100 МБ.
- Видео уходит в модель целиком, без обрезки, и его секунды входят в цену.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `ref_image_urls` | Картинки | jpeg, jpg, png, webp | 5 | 10 МБ |
| `ref_video_urls` | Видео | mp4, mov | 5 | 100 МБ |
| `first_frame_url` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Персонаж с картинки

```json
{
  "model": "wan",
  "settings": {
    "mode": "reference",
    "prompt": "@Image1 идёт по ночному городу под дождём, камера следует за ним",
    "ref_image_urls": [
      "https://example.com/hero.png"
    ],
    "aspect_ratio": "9:16",
    "duration": "5s"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 5 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="omni"></a>Omni

> Картинки, видео и звук вместе, каждое вложение со своей подписью в описании. Только Wan 3.0.

Значение поля mode: `omni`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в ролике. На вложения ссылайтесь подписями @Image1, @Video1, @Audio1, каждое нужно упомянуть. До 20 000 знаков.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `ref_image_urls` (Необязательно)

Картинки, в описании @Image1, @Image2 по порядку ссылок, до 10.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

#### `ref_video_urls` (Необязательно)

Видео, в описании @Video1, @Video2. Каждое от 1 до 15 секунд, все вместе не больше 15. Их секунды входят в цену.

- Тип: Список (Строка, uri)
- Максимум элементов: 5

#### `ref_audio_urls` (Необязательно)

Звук, например голос для реплики, в описании @Audio1, @Audio2. Каждый от 1 до 15 секунд, все вместе не больше 15.

- Тип: Список (Строка, uri)
- Максимум элементов: 5

#### `model` (Необязательно)

Версия Wan: режим есть только у 3.0.

- Тип: Строка
- Допустимые значения: `3_0` (Wan 3.0)
- По умолчанию: `"3_0"`

#### `quality` (Необязательно)

Разрешение ролика, набор зависит от версии. От него зависит цена секунды.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- Набор зависит от `quality`.
- По умолчанию: `"16:9"`

#### `duration` (Необязательно)

Длина ролика от 2 до 30 секунд. Цена за каждую секунду.

- Тип: Строка
- Допустимые значения: `2s` (2 сек), `3s` (3 сек), `4s` (4 сек), `5s` (5 сек), `6s` (6 сек), `7s` (7 сек), `8s` (8 сек), `9s` (9 сек), `10s` (10 сек), `11s` (11 сек), `12s` (12 сек), `13s` (13 сек), `14s` (14 сек), `15s` (15 сек), `16s` (16 сек), `17s` (17 сек), `18s` (18 сек), `19s` (19 сек), `20s` (20 сек), `21s` (21 сек), `22s` (22 сек), `23s` (23 сек), `24s` (24 сек), `25s` (25 сек), `26s` (26 сек), `27s` (27 сек), `28s` (28 сек), `29s` (29 сек), `30s` (30 сек)
- По умолчанию: `"5s"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Каждое вложение нужно упомянуть в описании подписью: @Image1, @Image2, @Video1 и так далее. Номер это место ссылки в поле своего типа. Писать ровно так: с большой буквы, без пробела.
- Нужно хотя бы одно вложение.
- Картинки передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая, видео ссылками на MP4 или MOV до 100 МБ, звук ссылками на MP3 или WAV до 10 МБ.
- Видео уходит в модель целиком, без обрезки, и его секунды входят в цену.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `ref_image_urls` | Картинки | jpeg, jpg, png, webp | 10 | 10 МБ |
| `ref_video_urls` | Видео | mp4, mov | 5 | 100 МБ |
| `ref_audio_urls` | Аудио | mp3, wav | 5 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Разговор двух персонажей

```json
{
  "model": "wan",
  "settings": {
    "mode": "omni",
    "prompt": "@Image1 приходит к @Image2 и говорит ему @Audio1. Фон как в @Video1, звук из видео не брать",
    "ref_image_urls": [
      "https://example.com/fox.png",
      "https://example.com/bear.png"
    ],
    "ref_video_urls": [
      "https://example.com/forest.mp4"
    ],
    "ref_audio_urls": [
      "https://example.com/line.mp3"
    ],
    "quality": "480p",
    "duration": "5s"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 5 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Wan 3.0: возможности и цены](https://api.cyhub.ai/models/wan-3)
- Другие версии: [Wan 2.7 API](https://api.cyhub.ai/models/wan-2-7/api.md), [Wan 2.6 API](https://api.cyhub.ai/models/wan-2-6/api.md), [Wan 2.5 API](https://api.cyhub.ai/models/wan-2-5/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Wan 2.7 API

> Видео Wan 2.7 по описанию, по первому и последнему кадру или по референсам с персонажами, предметами и местами. От 2 до 15 секунд, 720p или 1080p, можно добавить свой звук и разбить ролик на сцены.

Разработчик: Alibaba
Ключ модели в API: `wan`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_7",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "wan",
    "settings": {
        "mode": "text",
        "model": "2_7",
        "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
        "quality": "720p",
        "aspect_ratio": "16:9",
        "duration": "5s",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_7",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_7",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text"></a>По описанию

> Видео только по тексту. Версии 2.5, 2.6 и 2.7, у 3.0 этого режима нет.

Значение поля mode: `text`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в ролике: сцена, движение, камера, стиль. До 5000 знаков.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `model` (Необязательно)

Версия Wan: 2.5, 2.6 или 2.7.

- Тип: Строка
- Допустимые значения: `2_7` (Wan 2.7)
- По умолчанию: `"2_7"`

#### `quality` (Необязательно)

Разрешение ролика, набор зависит от версии. От него зависит цена секунды.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра. У 2.5 в 480p только 16:9, 9:16 и 1:1.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- Набор зависит от `quality`.
- По умолчанию: `"16:9"`

#### `duration` (Необязательно)

Длина ролика: у 2.5 только 5 или 10 секунд, у 2.6 и 2.7 от 2 до 15. Цена за каждую секунду.

- Тип: Строка
- Допустимые значения: `2s` (2 сек), `3s` (3 сек), `4s` (4 сек), `5s` (5 сек), `6s` (6 сек), `7s` (7 сек), `8s` (8 сек), `9s` (9 сек), `10s` (10 сек), `11s` (11 сек), `12s` (12 сек), `13s` (13 сек), `14s` (14 сек), `15s` (15 сек)
- По умолчанию: `"5s"`

#### `multi_shots` (Необязательно)

Разбить ролик на несколько сцен. Только у 2.6 и 2.7.

- Тип: Да/нет
- По умолчанию: `false`

#### `audio` (Необязательно)

Свой звук для ролика, например голос или музыка: одна ссылка. Есть у 2.6 и 2.7. Звук длиннее ролика обрезается по его длине.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Звук передаётся ссылкой на MP3 или WAV до 10 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio` | Аудио | mp3, wav | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_7",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 5 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="frames"></a>По кадрам

> Первый кадр или первый и последний: модель оживляет их по описанию. У 3.0 кадр обязателен, у остальных версий можно и без него.

Значение поля mode: `frames`

На этой странице версия Wan 2.7: передайте model = 2_7. Без поля model запустится 3_0.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в ролике: сцена, движение, камера, стиль. До 5000 знаков, у 3.0 до 20 000.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `image_urls` (Необязательно)

Одна ссылка: первый кадр. Две ссылки: первый и последний кадры.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

#### `model` (Необязательно)

Версия Wan. У 3.0, самой новой, нет своего звука и деления на сцены.

- Тип: Строка
- Допустимые значения: `2_7` (Wan 2.7)
- По умолчанию: `"3_0"`

#### `quality` (Необязательно)

Разрешение ролика, набор зависит от версии. От него зависит цена секунды.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра. У 2.5 в 480p только 16:9, 9:16 и 1:1.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- Набор зависит от `quality`.
- По умолчанию: `"16:9"`

#### `duration` (Необязательно)

Длина ролика: у 2.5 только 5 или 10 секунд, у 2.6 и 2.7 от 2 до 15, у 3.0 от 2 до 30. Цена за каждую секунду.

- Тип: Строка
- Допустимые значения: `2s` (2 сек), `3s` (3 сек), `4s` (4 сек), `5s` (5 сек), `6s` (6 сек), `7s` (7 сек), `8s` (8 сек), `9s` (9 сек), `10s` (10 сек), `11s` (11 сек), `12s` (12 сек), `13s` (13 сек), `14s` (14 сек), `15s` (15 сек)
- По умолчанию: `"5s"`

#### `multi_shots` (Необязательно)

Разбить ролик на несколько сцен. Только у 2.6 и 2.7.

- Тип: Да/нет
- По умолчанию: `false`

#### `audio` (Необязательно)

Свой звук для ролика, например голос или музыка: одна ссылка. Есть у 2.6 и 2.7. Звук длиннее ролика обрезается по его длине.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Кадры передаются ссылками на JPEG, PNG или WebP до 10 МБ каждый.
- Звук передаётся ссылкой на MP3 или WAV до 10 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 2 | 10 МБ |
| `audio` | Аудио | mp3, wav | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Кадр, который говорит вашим голосом

```json
{
  "model": "wan",
  "settings": {
    "mode": "frames",
    "model": "2_7",
    "prompt": "Лев смотрит в камеру и говорит этим голосом",
    "image_urls": [
      "https://example.com/lion.jpg"
    ],
    "audio": [
      "https://example.com/voice.mp3"
    ],
    "duration": "5s"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 5 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="reference"></a>По референсам

> Персонажи, предметы и места с ваших картинок и видео в новом ролике. Версии 2.7 и 3.0.

Значение поля mode: `reference`

На этой странице версия Wan 2.7: передайте model = 2_7. Без поля model запустится 3_0.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в ролике. На вложения ссылайтесь подписями @Image1, @Video1, каждое нужно упомянуть. До 5000 знаков, у 3.0 до 20 000.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `ref_image_urls` (Необязательно)

Картинки с персонажами, предметами или местом, в описании @Image1, @Image2 по порядку ссылок. Картинок и видео вместе до 5, хотя бы одно из них обязательно.

- Тип: Список (Строка, uri)
- Максимум элементов: 5

#### `ref_video_urls` (Необязательно)

Видео с персонажем, в описании @Video1, @Video2. Каждое от 1 до 5 секунд, их секунды входят в цену. У 2.7 с видео готовый ролик не длиннее 10 секунд.

- Тип: Список (Строка, uri)
- Максимум элементов: 5

#### `first_frame_url` (Необязательно)

Первый кадр ролика, необязательно. С ним пропорции берутся у кадра, и поле aspect_ratio не действует.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `model` (Необязательно)

Версия Wan: 2.7 или 3.0.

- Тип: Строка
- Допустимые значения: `2_7` (Wan 2.7)
- По умолчанию: `"3_0"`

#### `quality` (Необязательно)

Разрешение ролика, набор зависит от версии. От него зависит цена секунды.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- Набор зависит от `quality`.
- По умолчанию: `"16:9"`

#### `duration` (Необязательно)

Длина ролика: у 2.7 от 2 до 15 секунд, а с видео среди вложений до 10; у 3.0 от 2 до 30. Цена за каждую секунду.

- Тип: Строка
- Допустимые значения: `2s` (2 сек), `3s` (3 сек), `4s` (4 сек), `5s` (5 сек), `6s` (6 сек), `7s` (7 сек), `8s` (8 сек), `9s` (9 сек), `10s` (10 сек), `11s` (11 сек), `12s` (12 сек), `13s` (13 сек), `14s` (14 сек), `15s` (15 сек)
- По умолчанию: `"5s"`

#### `multi_shots` (Необязательно)

Разбить ролик на несколько сцен. Только у 2.7.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Каждое вложение нужно упомянуть в описании подписью: @Image1, @Image2, @Video1 и так далее. Номер это место ссылки в поле своего типа. Писать ровно так: с большой буквы, без пробела.
- Картинки передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая, видео ссылками на MP4 или MOV до 100 МБ.
- Видео уходит в модель целиком, без обрезки, и его секунды входят в цену.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `ref_image_urls` | Картинки | jpeg, jpg, png, webp | 5 | 10 МБ |
| `ref_video_urls` | Видео | mp4, mov | 5 | 100 МБ |
| `first_frame_url` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Два персонажа и первый кадр

```json
{
  "model": "wan",
  "settings": {
    "mode": "reference",
    "model": "2_7",
    "prompt": "@Image1 встречает @Video1 у входа в кафе и машет рукой",
    "ref_image_urls": [
      "https://example.com/hero.png"
    ],
    "ref_video_urls": [
      "https://example.com/friend.mp4"
    ],
    "first_frame_url": [
      "https://example.com/cafe.jpg"
    ],
    "duration": "5s"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 5 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Wan 2.7: возможности и цены](https://api.cyhub.ai/models/wan-2-7)
- Другие версии: [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [Wan 2.6 API](https://api.cyhub.ai/models/wan-2-6/api.md), [Wan 2.5 API](https://api.cyhub.ai/models/wan-2-5/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Wan 2.6 API

> Видео Wan 2.6 по описанию или по первому и последнему кадру. От 2 до 15 секунд, 720p или 1080p, можно добавить свой звук и разбить ролик на сцены.

Разработчик: Alibaba
Ключ модели в API: `wan`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_6",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "wan",
    "settings": {
        "mode": "text",
        "model": "2_6",
        "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
        "quality": "720p",
        "aspect_ratio": "16:9",
        "duration": "5s",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_6",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_6",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text"></a>По описанию

> Видео только по тексту. Версии 2.5, 2.6 и 2.7, у 3.0 этого режима нет.

Значение поля mode: `text`

На этой странице версия Wan 2.6: передайте model = 2_6. Без поля model запустится 2_7.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в ролике: сцена, движение, камера, стиль. До 5000 знаков.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `model` (Необязательно)

Версия Wan: 2.5, 2.6 или 2.7.

- Тип: Строка
- Допустимые значения: `2_6` (Wan 2.6)
- По умолчанию: `"2_7"`

#### `quality` (Необязательно)

Разрешение ролика, набор зависит от версии. От него зависит цена секунды.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра. У 2.5 в 480p только 16:9, 9:16 и 1:1.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- Набор зависит от `quality`.
- По умолчанию: `"16:9"`

#### `duration` (Необязательно)

Длина ролика: у 2.5 только 5 или 10 секунд, у 2.6 и 2.7 от 2 до 15. Цена за каждую секунду.

- Тип: Строка
- Допустимые значения: `2s` (2 сек), `3s` (3 сек), `4s` (4 сек), `5s` (5 сек), `6s` (6 сек), `7s` (7 сек), `8s` (8 сек), `9s` (9 сек), `10s` (10 сек), `11s` (11 сек), `12s` (12 сек), `13s` (13 сек), `14s` (14 сек), `15s` (15 сек)
- По умолчанию: `"5s"`

#### `multi_shots` (Необязательно)

Разбить ролик на несколько сцен. Только у 2.6 и 2.7.

- Тип: Да/нет
- По умолчанию: `false`

#### `audio` (Необязательно)

Свой звук для ролика, например голос или музыка: одна ссылка. Есть у 2.6 и 2.7. Звук длиннее ролика обрезается по его длине.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Звук передаётся ссылкой на MP3 или WAV до 10 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio` | Аудио | mp3, wav | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_6",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 5 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="frames"></a>По кадрам

> Первый кадр или первый и последний: модель оживляет их по описанию. У 3.0 кадр обязателен, у остальных версий можно и без него.

Значение поля mode: `frames`

На этой странице версия Wan 2.6: передайте model = 2_6. Без поля model запустится 3_0.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в ролике: сцена, движение, камера, стиль. До 5000 знаков, у 3.0 до 20 000.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `image_urls` (Необязательно)

Одна ссылка: первый кадр. Две ссылки: первый и последний кадры.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

#### `model` (Необязательно)

Версия Wan. У 3.0, самой новой, нет своего звука и деления на сцены.

- Тип: Строка
- Допустимые значения: `2_6` (Wan 2.6)
- По умолчанию: `"3_0"`

#### `quality` (Необязательно)

Разрешение ролика, набор зависит от версии. От него зависит цена секунды.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра. У 2.5 в 480p только 16:9, 9:16 и 1:1.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- Набор зависит от `quality`.
- По умолчанию: `"16:9"`

#### `duration` (Необязательно)

Длина ролика: у 2.5 только 5 или 10 секунд, у 2.6 и 2.7 от 2 до 15, у 3.0 от 2 до 30. Цена за каждую секунду.

- Тип: Строка
- Допустимые значения: `2s` (2 сек), `3s` (3 сек), `4s` (4 сек), `5s` (5 сек), `6s` (6 сек), `7s` (7 сек), `8s` (8 сек), `9s` (9 сек), `10s` (10 сек), `11s` (11 сек), `12s` (12 сек), `13s` (13 сек), `14s` (14 сек), `15s` (15 сек)
- По умолчанию: `"5s"`

#### `multi_shots` (Необязательно)

Разбить ролик на несколько сцен. Только у 2.6 и 2.7.

- Тип: Да/нет
- По умолчанию: `false`

#### `audio` (Необязательно)

Свой звук для ролика, например голос или музыка: одна ссылка. Есть у 2.6 и 2.7. Звук длиннее ролика обрезается по его длине.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Кадры передаются ссылками на JPEG, PNG или WebP до 10 МБ каждый.
- Звук передаётся ссылкой на MP3 или WAV до 10 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 2 | 10 МБ |
| `audio` | Аудио | mp3, wav | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить кадр

```json
{
  "model": "wan",
  "settings": {
    "mode": "frames",
    "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "quality": "720p",
    "duration": "5s",
    "model": "2_6"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 5 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Wan 2.6: возможности и цены](https://api.cyhub.ai/models/wan-2-6)
- Другие версии: [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [Wan 2.7 API](https://api.cyhub.ai/models/wan-2-7/api.md), [Wan 2.5 API](https://api.cyhub.ai/models/wan-2-5/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Wan 2.5 API

> Видео Wan 2.5 по описанию или по первому и последнему кадру: 5 или 10 секунд, от 480p до 1080p.

Разработчик: Alibaba
Ключ модели в API: `wan`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_5",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "wan",
    "settings": {
        "mode": "text",
        "model": "2_5",
        "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
        "quality": "720p",
        "aspect_ratio": "16:9",
        "duration": "5s",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_5",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_5",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text"></a>По описанию

> Видео только по тексту. Версии 2.5, 2.6 и 2.7, у 3.0 этого режима нет.

Значение поля mode: `text`

На этой странице версия Wan 2.5: передайте model = 2_5. Без поля model запустится 2_7.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в ролике: сцена, движение, камера, стиль. До 5000 знаков.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `model` (Необязательно)

Версия Wan: 2.5, 2.6 или 2.7.

- Тип: Строка
- Допустимые значения: `2_5` (Wan 2.5)
- По умолчанию: `"2_7"`

#### `quality` (Необязательно)

Разрешение ролика, набор зависит от версии. От него зависит цена секунды.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра. У 2.5 в 480p только 16:9, 9:16 и 1:1.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- Набор зависит от `quality`.
- Исключения:

  | `quality` | `aspect_ratio` |
  |---|---|
  | `480p` | кроме `4:3`, `3:4` |
- По умолчанию: `"16:9"`

#### `duration` (Необязательно)

Длина ролика: у 2.5 только 5 или 10 секунд, у 2.6 и 2.7 от 2 до 15. Цена за каждую секунду.

- Тип: Строка
- Допустимые значения: `5s` (5 сек), `10s` (10 сек)
- По умолчанию: `"5s"`

#### `multi_shots` (Необязательно)

Разбить ролик на несколько сцен. Только у 2.6 и 2.7.

- Тип: Да/нет
- По умолчанию: `false`

#### `audio` (Необязательно)

Свой звук для ролика, например голос или музыка: одна ссылка. Есть у 2.6 и 2.7. Звук длиннее ролика обрезается по его длине.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Звук передаётся ссылкой на MP3 или WAV до 10 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio` | Аудио | mp3, wav | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "wan",
  "settings": {
    "mode": "text",
    "model": "2_5",
    "prompt": "Кот играет с клубком на солнечном подоконнике, камера медленно приближается",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": "5s"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 5 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="frames"></a>По кадрам

> Первый кадр или первый и последний: модель оживляет их по описанию. У 3.0 кадр обязателен, у остальных версий можно и без него.

Значение поля mode: `frames`

На этой странице версия Wan 2.5: передайте model = 2_5. Без поля model запустится 3_0.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в ролике: сцена, движение, камера, стиль. До 5000 знаков, у 3.0 до 20 000.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 20000

#### `image_urls` (Необязательно)

Одна ссылка: первый кадр. Две ссылки: первый и последний кадры.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

#### `model` (Необязательно)

Версия Wan. У 3.0, самой новой, нет своего звука и деления на сцены.

- Тип: Строка
- Допустимые значения: `2_5` (Wan 2.5)
- По умолчанию: `"3_0"`

#### `quality` (Необязательно)

Разрешение ролика, набор зависит от версии. От него зависит цена секунды.

- Тип: Строка
- Допустимые значения: `480p`, `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра. У 2.5 в 480p только 16:9, 9:16 и 1:1.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- Набор зависит от `quality`.
- Исключения:

  | `quality` | `aspect_ratio` |
  |---|---|
  | `480p` | кроме `4:3`, `3:4` |
- По умолчанию: `"16:9"`

#### `duration` (Необязательно)

Длина ролика: у 2.5 только 5 или 10 секунд, у 2.6 и 2.7 от 2 до 15, у 3.0 от 2 до 30. Цена за каждую секунду.

- Тип: Строка
- Допустимые значения: `5s` (5 сек), `10s` (10 сек)
- По умолчанию: `"5s"`

#### `multi_shots` (Необязательно)

Разбить ролик на несколько сцен. Только у 2.6 и 2.7.

- Тип: Да/нет
- По умолчанию: `false`

#### `audio` (Необязательно)

Свой звук для ролика, например голос или музыка: одна ссылка. Есть у 2.6 и 2.7. Звук длиннее ролика обрезается по его длине.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Кадры передаются ссылками на JPEG, PNG или WebP до 10 МБ каждый.
- Звук передаётся ссылкой на MP3 или WAV до 10 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 2 | 10 МБ |
| `audio` | Аудио | mp3, wav | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить кадр

```json
{
  "model": "wan",
  "settings": {
    "mode": "frames",
    "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "quality": "720p",
    "duration": "5s",
    "model": "2_5"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 5 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Wan 2.5: возможности и цены](https://api.cyhub.ai/models/wan-2-5)
- Другие версии: [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [Wan 2.7 API](https://api.cyhub.ai/models/wan-2-7/api.md), [Wan 2.6 API](https://api.cyhub.ai/models/wan-2-6/api.md)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# MiniMax H3 (Hailuo 03) API

> Видео MiniMax H3 (Hailuo 03) со звуком, до 15 секунд: по описанию, по первому и последнему кадру или по референсам. Референсы: картинки, видео и аудио. Качество 768P или 2K, звук модель пишет сама.

Разработчик: MiniMax
Ключ модели в API: `minimax_h3`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "minimax_h3",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот медленно идёт по пляжу на закате, волны тихо набегают на берег",
    "resolution": "768P",
    "aspect_ratio": "16:9",
    "duration": 6
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "minimax_h3",
    "settings": {
        "mode": "text_to_video",
        "prompt": "Кот медленно идёт по пляжу на закате, волны тихо набегают на берег",
        "resolution": "768P",
        "aspect_ratio": "16:9",
        "duration": 6,
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "minimax_h3",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот медленно идёт по пляжу на закате, волны тихо набегают на берег",
    "resolution": "768P",
    "aspect_ratio": "16:9",
    "duration": 6
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "minimax_h3",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот медленно идёт по пляжу на закате, волны тихо набегают на берег",
    "resolution": "768P",
    "aspect_ratio": "16:9",
    "duration": 6
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_video"></a>По описанию

> Видео только по тексту, файлы не передаются.

Значение поля mode: `text_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео, как движется камера, какой звук. Можно расписать по секундам: что происходит с 0 по 3 секунду, с 3 по 7 и так далее.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 7000

#### `resolution` (Необязательно)

Качество видео. 2K детальнее, секунда дороже.

- Тип: Строка
- Допустимые значения: `768P`, `2K`
- По умолчанию: `"768P"`

#### `duration` (Необязательно)

Длина видео в секундах, от 4 до 15. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 15
- По умолчанию: `6`

#### `aspect_ratio` (Необязательно)

Пропорции кадра: от кинематографичного 21:9 до вертикального 9:16.

- Тип: Строка
- Допустимые значения: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`
- По умолчанию: `"16:9"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "minimax_h3",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Кот медленно идёт по пляжу на закате, волны тихо набегают на берег",
    "resolution": "768P",
    "aspect_ratio": "16:9",
    "duration": 6
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4 со звуком: звук модель пишет сама.
- Генерация обычно занимает от 1 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_video"></a>По кадрам

> Видео начинается с первого кадра. Если передан и последний кадр, видео им заканчивается. Пропорции видео берутся у кадров.

Значение поля mode: `image_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео, как движется камера, какой звук. Можно расписать по секундам: что происходит с 0 по 3 секунду, с 3 по 7 и так далее.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 7000

#### `resolution` (Необязательно)

Качество видео. 2K детальнее, секунда дороже.

- Тип: Строка
- Допустимые значения: `768P`, `2K`
- По умолчанию: `"768P"`

#### `duration` (Необязательно)

Длина видео в секундах, от 4 до 15. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 15
- По умолчанию: `6`

#### `image_urls` (Обязательно)

Одна ссылка: первый кадр. Две ссылки: первый и последний кадры.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG или WebP до 30 МБ каждая, стороны от 256 до 5760 пикселей, пропорции от 2:5 до 5:2.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 2 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить кадр

```json
{
  "model": "minimax_h3",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Героиня поворачивается и улыбается, камера медленно наезжает",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "duration": 6
  }
}
```

От первого кадра к последнему

```json
{
  "model": "minimax_h3",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Бутон медленно раскрывается в цветок",
    "image_urls": [
      "https://example.com/bud.jpg",
      "https://example.com/flower.jpg"
    ],
    "resolution": "2K",
    "duration": 5
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4 со звуком: звук модель пишет сама.
- Генерация обычно занимает от 1 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="reference_to_video"></a>По референсам

> Модель переносит в новое видео персонажей и предметы с картинок, движение и монтаж из видео, голос и ритм из аудио. Нужна хотя бы одна картинка или одно видео.

Значение поля mode: `reference_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео, как движется камера, какой звук. Можно расписать по секундам: что происходит с 0 по 3 секунду, с 3 по 7 и так далее.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 7000

#### `resolution` (Необязательно)

Качество видео. 2K детальнее, секунда дороже.

- Тип: Строка
- Допустимые значения: `768P`, `2K`
- По умолчанию: `"768P"`

#### `duration` (Необязательно)

Длина видео в секундах, от 4 до 15. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 4
- Максимум: 15
- По умолчанию: `6`

#### `aspect_ratio` (Необязательно)

Пропорции кадра. adaptive: модель подбирает их по приложенным файлам.

- Тип: Строка
- Допустимые значения: `adaptive` (Адаптивный), `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`
- По умолчанию: `"16:9"`

#### `image_urls` (Необязательно)

До 9 ссылок на картинки с персонажами, предметами или стилем. Первые 5 бесплатно, каждая следующая добавляет к цене.

- Тип: Список (Строка, uri)
- Максимум элементов: 9

#### `video_urls` (Необязательно)

До 3 ссылок на видео, из которых модель берёт движение и монтаж. Секунды видео оплачиваются как секунды результата.

- Тип: Список (Строка, uri)
- Максимум элементов: 3

#### `audio_urls` (Необязательно)

До 3 ссылок на аудио: голос или музыка, под которые модель подгоняет речь и ритм. Бесплатно, только вместе с картинкой или видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 3

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG или WebP до 30 МБ каждая, стороны от 256 до 5760 пикселей, пропорции от 2:5 до 5:2.
- Видео передаются ссылками на MP4 или MOV (H.264 или H.265) до 50 МБ каждое: каждое от 2 до 15 секунд, все вместе не длиннее 15 секунд, стороны от 256 до 5760 пикселей, пропорции от 2:5 до 5:2, от 23,976 до 60 кадров в секунду.
- Аудио передаются ссылками на MP3 или WAV до 15 МБ каждое: каждое от 2 до 15 секунд, все вместе не длиннее 15 секунд.
- Видео и аудио уходят в модель целиком. Цена видео считается по длине самих файлов: их секунды прибавляются к секундам результата.
- Длины видео и аудио сверяются до отправки в модель: если они не подходят, задача завершается отказом с причиной и ничего не стоит.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 9 | 30 МБ |
| `video_urls` | Видео | mp4, mov | 3 | 50 МБ |
| `audio_urls` | Аудио | mp3, wav | 3 | 15 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Персонаж с картинки

```json
{
  "model": "minimax_h3",
  "settings": {
    "mode": "reference_to_video",
    "prompt": "Девушка с картинки идёт по ночному городу под дождём",
    "image_urls": [
      "https://example.com/girl.png"
    ],
    "aspect_ratio": "9:16",
    "duration": 6
  }
}
```

Движение из видео, музыка из аудио

```json
{
  "model": "minimax_h3",
  "settings": {
    "mode": "reference_to_video",
    "prompt": "Девушка с картинки танцует как в видео под музыку из аудио",
    "image_urls": [
      "https://example.com/girl.png"
    ],
    "video_urls": [
      "https://example.com/dance.mp4"
    ],
    "audio_urls": [
      "https://example.com/music.mp3"
    ],
    "aspect_ratio": "adaptive",
    "duration": 8
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4 со звуком: звук модель пишет сама.
- Генерация обычно занимает от 1 до 10 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть MiniMax H3 (Hailuo 03): возможности и цены](https://api.cyhub.ai/models/minimax-h3)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [Gemini Omni API](https://api.cyhub.ai/models/gemini-omni/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Gemini Omni API

> Видео Gemini Omni по описанию: с картинками, исходным видео и голосом или от первого кадра к последнему.

Разработчик: Google
Ключ модели в API: `gemeni_omni`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "gemeni_omni",
  "settings": {
    "mode": "materials",
    "prompt": "Рыжий кот в шляпе идёт по осенней улице, камера медленно едет следом",
    "duration": "6",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "voice": "achernar"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "gemeni_omni",
    "settings": {
        "mode": "materials",
        "prompt": "Рыжий кот в шляпе идёт по осенней улице, камера медленно едет следом",
        "duration": "6",
        "aspect_ratio": "9:16",
        "resolution": "720p",
        "voice": "achernar",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "gemeni_omni",
  "settings": {
    "mode": "materials",
    "prompt": "Рыжий кот в шляпе идёт по осенней улице, камера медленно едет следом",
    "duration": "6",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "voice": "achernar"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "gemeni_omni",
  "settings": {
    "mode": "materials",
    "prompt": "Рыжий кот в шляпе идёт по осенней улице, камера медленно едет следом",
    "duration": "6",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "voice": "achernar"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="materials"></a>По описанию и материалам

> Видео по описанию. Можно приложить картинки, исходное видео и выбрать голос, всё это необязательно. Материалов не больше семи мест: картинка занимает одно, видео два.

Значение поля mode: `materials`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: кто действует, где, как движется камера.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `duration` (Необязательно)

Длина ролика в секундах, от неё зависит цена.

- Тип: Строка
- Допустимые значения: `4`, `6`, `8`, `10`
- По умолчанию: `"4"`

#### `aspect_ratio` (Необязательно)

Вертикальное 9:16 или горизонтальное 16:9.

- Тип: Строка
- Допустимые значения: `9:16`, `16:9`
- По умолчанию: `"9:16"`

#### `resolution` (Необязательно)

Разрешение готового видео. 360p, 720p и 1080p стоят одинаково, 4K дороже.

- Тип: Строка
- Допустимые значения: `360p`, `720p`, `1080p`, `4k`
- По умолчанию: `"720p"`

#### `image_urls` (Необязательно)

До семи ссылок на картинки: люди, предметы, места, стиль. С исходным видео не больше пяти. Модель видит их сама, в описании достаточно сказать словами, например «женщина с фото идёт по улице».

- Тип: Список (Строка, uri)
- Максимум элементов: 7

#### `video_url` (Необязательно)

Одна ссылка на исходное видео не длиннее 30 секунд. Модель берёт из него первые 10 секунд. С видео поле duration не действует: длину нового ролика выбирает модель, а цена одна при любой длине.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `voice` (Необязательно)

Необязательно: голос из готового набора, которым говорят в видео. Голоса англоязычные, на русском могут говорить с акцентом.

- Тип: Строка
- Допустимые значения: `achernar`, `achird`, `algenib`, `algieba`, `alnilam`, `aoede`, `autonoe`, `callirrhoe`, `charon`, `despina`, `enceladus`, `erinome`, `fenrir`, `gacrux`, `iapetus`, `kore`, `laomedeia`, `leda`, `orus`, `puck`, `pulcherrima`, `rasalgethi`, `sadachbia`, `sadaltager`, `schedar`, `sulafat`, `umbriel`, `vindemiatrix`, `zephyr`, `zubenelgenubi`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинки передаются ссылками на JPEG, PNG или WebP до 20 МБ каждая.
- Видео передаётся ссылкой на MP4 или MOV до 100 МБ и не длиннее 30 секунд.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 7 | 20 МБ |
| `video_url` | Видео | mp4, mov | 1 | 100 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "gemeni_omni",
  "settings": {
    "mode": "materials",
    "prompt": "Рыжий кот в шляпе идёт по осенней улице, камера медленно едет следом",
    "duration": "6",
    "aspect_ratio": "9:16",
    "resolution": "720p"
  }
}
```

Видео по картинкам

```json
{
  "model": "gemeni_omni",
  "settings": {
    "mode": "materials",
    "prompt": "Женщина с фото идёт по набережной на закате",
    "image_urls": [
      "https://example.com/woman.jpg",
      "https://example.com/embankment.jpg"
    ],
    "duration": "8",
    "aspect_ratio": "16:9"
  }
}
```

По исходному видео с голосом

```json
{
  "model": "gemeni_omni",
  "settings": {
    "mode": "materials",
    "prompt": "Тот же танец на крыше под дождём, в конце танцор говорит «Поехали!»",
    "video_url": [
      "https://example.com/dance.mp4"
    ],
    "voice": "puck"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 3 до 15 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="frames"></a>Первый и последний кадр

> Видео идёт от первого кадра к последнему. Первый кадр обязателен, последний можно не давать. Других материалов модель в этом режиме не принимает.

Значение поля mode: `frames`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: кто действует, где, как движется камера.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `duration` (Необязательно)

Длина ролика в секундах, от неё зависит цена.

- Тип: Строка
- Допустимые значения: `4`, `6`, `8`, `10`
- По умолчанию: `"4"`

#### `aspect_ratio` (Необязательно)

Вертикальное 9:16 или горизонтальное 16:9.

- Тип: Строка
- Допустимые значения: `9:16`, `16:9`
- По умолчанию: `"9:16"`

#### `resolution` (Необязательно)

Разрешение готового видео. 360p, 720p и 1080p стоят одинаково, 4K дороже.

- Тип: Строка
- Допустимые значения: `360p`, `720p`, `1080p`, `4k`
- По умолчанию: `"720p"`

#### `first_frame_url` (Обязательно)

Одна ссылка на картинку: первый кадр видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `last_frame_url` (Необязательно)

Одна ссылка на картинку: последний кадр видео. Только вместе с первым.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинки передаются ссылками на JPEG, PNG или WebP до 20 МБ каждая.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `first_frame_url` | Картинки | jpeg, jpg, png, webp | 1 | 20 МБ |
| `last_frame_url` | Картинки | jpeg, jpg, png, webp | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

От первого кадра к последнему

```json
{
  "model": "gemeni_omni",
  "settings": {
    "mode": "frames",
    "prompt": "Бутон медленно раскрывается в цветок, мягкий утренний свет",
    "first_frame_url": [
      "https://example.com/bud.png"
    ],
    "last_frame_url": [
      "https://example.com/flower.png"
    ],
    "duration": "4"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация обычно занимает от 3 до 15 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Gemini Omni: возможности и цены](https://api.cyhub.ai/models/gemini-omni)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Grok Imagine Video API

> Видео Grok: по описанию, из картинки или по референсам, правка и продолжение вашего ролика. Две модели: Grok с роликами до 30 секунд и Grok Pro.

Разработчик: xAI
Ключ модели в API: `grok_video`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "grok_video",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом",
    "model": "grok",
    "aspect_ratio": "16:9",
    "duration": 10
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "grok_video",
    "settings": {
        "mode": "text_to_video",
        "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом",
        "model": "grok",
        "aspect_ratio": "16:9",
        "duration": 10,
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "grok_video",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом",
    "model": "grok",
    "aspect_ratio": "16:9",
    "duration": 10
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "grok_video",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом",
    "model": "grok",
    "aspect_ratio": "16:9",
    "duration": 10
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_video"></a>По описанию

> Видео только по тексту, файлы не передаются.

Значение поля mode: `text_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео. У Grok до 5000 символов, у Grok Pro до 4096 знаков латиницей, русская буква у него считается за две.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `model` (Необязательно)

Модель. Grok дешевле, ролик до 30 секунд, есть режимы генерации. Grok Pro качественнее, ролик до 15 секунд.

- Тип: Строка
- Допустимые значения: `grok`, `grok_pro` (Grok Pro)
- По умолчанию: `"grok"`

#### `generation_mode` (Необязательно)

Настроение ролика у Grok, варианты в списке. У Grok Pro настроений нет, оставьте «Обычный».

- Тип: Строка
- Допустимые значения: `normal` (Обычный), `fun` (Весёлый), `spicy` (Острый (18+))
- По умолчанию: `"normal"`

#### `aspect_ratio` (Необязательно)

Пропорции видео. У Grok Pro их больше: ещё 4:3 и 3:4.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `3:2`, `2:3`
- Набор зависит от `model`.
- Исключения:

  | `model` | `aspect_ratio` |
  |---|---|
  | `grok_pro` | и ещё `4:3`, `3:4` |
- По умолчанию: `"9:16"`

#### `quality` (Необязательно)

Разрешение видео. 720p дороже.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"480p"`

#### `duration` (Необязательно)

Длина видео в секундах: у Grok от 6 до 30, у Grok Pro от 1 до 15. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 1
- Максимум: 30
- По умолчанию: `6`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "grok_video",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лиса бежит по заснеженному лесу, камера движется рядом",
    "model": "grok",
    "aspect_ratio": "16:9",
    "duration": 10
  }
}
```

Grok Pro в 720p

```json
{
  "model": "grok_video",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Бармен подбрасывает шейкер и ловит его за спиной, тёплый свет бара",
    "model": "grok_pro",
    "aspect_ratio": "4:3",
    "quality": "720p",
    "duration": 8
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 2 до 5 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_video"></a>Из картинки

> Видео начинается с вашей картинки, или модель берёт персонажей и предметы с картинок-референсов. Нужна картинка или хотя бы один референс.

Значение поля mode: `image_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео. До 4096 символов, у Grok с референсами до 5000. Grok Pro считает русскую букву за две.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `model` (Необязательно)

Модель. Grok дешевле, ролик до 30 секунд, есть режимы генерации. Grok Pro качественнее, ролик до 15 секунд.

- Тип: Строка
- Допустимые значения: `grok`, `grok_pro` (Grok Pro)
- По умолчанию: `"grok"`

#### `image_urls` (Необязательно)

Одна ссылка на картинку, с которой начнётся видео. Можно не давать, если есть референсы.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `reference_image_urls` (Необязательно)

До 7 ссылок на картинки с персонажами, предметами или стилем. У Grok вместе с главной картинкой не больше 7, Grok Pro главную картинку вместе с референсами не берёт.

- Тип: Список (Строка, uri)
- Максимум элементов: 7

#### `generation_mode` (Необязательно)

Настроение ролика: «Обычный» или «Весёлый». Работает только у Grok с референсами, в остальных случаях оставьте «Обычный».

- Тип: Строка
- Допустимые значения: `normal` (Обычный), `fun` (Весёлый)
- По умолчанию: `"normal"`

#### `aspect_ratio` (Необязательно)

Пропорции видео. Auto только у Grok с одной главной картинкой без референсов, 4:3 и 3:4 у Grok с референсами недоступны.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `auto`
- Набор зависит от `model`.
- Исключения:

  | `model` | `aspect_ratio` |
  |---|---|
  | `grok_pro` | кроме `auto` |
- По умолчанию: `"9:16"`

#### `quality` (Необязательно)

Разрешение видео. 720p дороже.

- Тип: Строка
- Допустимые значения: `480p`, `720p`
- По умолчанию: `"480p"`

#### `duration` (Необязательно)

Длина видео в секундах: от 1 до 15, у Grok с референсами от 6 до 30, у Grok Pro с референсами до 10. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 1
- Максимум: 30
- По умолчанию: `6`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Картинки передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая.
- У Grok с одной картинкой (главной или единственным референсом) пропорции видео берутся у картинки. У Grok Pro главная картинка растягивается под выбранные пропорции.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |
| `reference_image_urls` | Картинки | jpeg, jpg, png, webp | 7 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить картинку

```json
{
  "model": "grok_video",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Камера медленно наезжает, волосы героини развеваются на ветру",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "duration": 8
  }
}
```

Персонаж с референсов

```json
{
  "model": "grok_video",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Этот персонаж в этом пальто идёт по ночному городу под дождём",
    "model": "grok_pro",
    "duration": 8,
    "reference_image_urls": [
      "https://example.com/character.png",
      "https://example.com/coat.png"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 2 до 5 минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_to_video"></a>Правка видео

> Grok Pro меняет ваш ролик по описанию: одежду, предметы, цвета. Остальное в кадре модель старается сохранить.

Значение поля mode: `video_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что изменить в ролике, до 4096 знаков латиницей: русская буква считается за две.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 4096

#### `video_urls` (Обязательно)

Одна ссылка на ролик MP4 не длиннее 8.7 секунды.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`, `model` = `"grok_pro"`

### Входные данные

- Ролик передаётся ссылкой на MP4, адрес должен заканчиваться на .mp4. Длина не больше 8.7 секунды, ролик уходит целиком, обрезки нет.
- Предела веса xAI не называет, 50 МБ это наш совет, а не его предел.
- Цена за каждую секунду исходного ролика, неполная секунда считается целой. Считается как за 720p.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4 | 1 | 50 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Надеть шляпу

```json
{
  "model": "grok_video",
  "settings": {
    "mode": "video_to_video",
    "prompt": "Надень на героиню широкополую чёрную шляпу",
    "video_urls": [
      "https://example.com/clip.mp4"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 2 до 5 минут.
- Длина и пропорции как у исходного ролика, разрешение как у него, но не выше 720p.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_extend"></a>Продолжение видео

> Grok Pro продолжает ваш ролик с его последнего кадра по описанию того, что будет дальше.

Значение поля mode: `video_extend`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит дальше, до 4096 знаков латиницей: русская буква считается за две.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 4096

#### `video_urls` (Обязательно)

Одна ссылка на ролик MP4 длиной от 2 до 15 секунд.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `duration` (Необязательно)

Длина продолжения в секундах, от 2 до 10. Каждая секунда продолжения добавляет к цене.

- Тип: Целое число
- Минимум: 2
- Максимум: 10
- По умолчанию: `6`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`, `model` = `"grok_pro"`

### Входные данные

- Ролик передаётся ссылкой на MP4, адрес должен заканчиваться на .mp4. Длина от 2 до 15 секунд, ролик уходит целиком, обрезки нет.
- Предела веса xAI не называет, 50 МБ это наш совет, а не его предел.
- В цену входят секунды исходного ролика и секунды готового видео, то есть исходника вместе с продолжением. Неполная секунда считается целой, цена как за 720p.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4 | 1 | 50 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Продолжить ролик

```json
{
  "model": "grok_video",
  "settings": {
    "mode": "video_extend",
    "prompt": "Камера отъезжает и показывает весь город с высоты",
    "video_urls": [
      "https://example.com/clip.mp4"
    ],
    "duration": 6
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 2 до 5 минут.
- Готовое видео это исходный ролик вместе с продолжением. Пропорции и разрешение как у исходного, но не выше 720p.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Grok Imagine Video: возможности и цены](https://api.cyhub.ai/models/grok-video)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Grok Imagine 2.0 API

> Картинки Grok Imagine 2.0 от xAI по текстовому описанию, пять вариантов пропорций.

Разработчик: xAI
Ключ модели в API: `grok_image2`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "grok_image2",
  "settings": {
    "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город, тёплый свет лампы",
    "aspect_ratio": "3:2"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "grok_image2",
    "settings": {
        "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город, тёплый свет лампы",
        "aspect_ratio": "3:2",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "grok_image2",
  "settings": {
    "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город, тёплый свет лампы",
    "aspect_ratio": "3:2"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "grok_image2",
  "settings": {
    "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город, тёплый свет лампы",
    "aspect_ratio": "3:2"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="parameters"></a>Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

### `prompt` (Обязательно)

Что нарисовать: кто в кадре, что вокруг, как снято, какой свет и настроение.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

### `aspect_ratio` (Необязательно)

Пропорции картинки: 1:1 квадрат, 2:3 и 3:2 как у фотографии, 16:9 широкий кадр, 9:16 вертикальный.

- Тип: Строка
- Допустимые значения: `1:1`, `2:3`, `3:2`, `16:9`, `9:16`
- По умолчанию: `"1:1"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `edit_button` = `false`

## <a id="input"></a>Входные данные

- Только текст: картинки на вход модель не принимает.

## <a id="example"></a>Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Картинка по описанию

```json
{
  "model": "grok_image2",
  "settings": {
    "prompt": "Рыжий кот спит на подоконнике, за окном вечерний город, тёплый свет лампы",
    "aspect_ratio": "3:2"
  }
}
```

Вертикальная картинка для Stories

```json
{
  "model": "grok_image2",
  "settings": {
    "prompt": "Девушка в жёлтом дождевике на мокрой улице ночного Токио, неоновые вывески",
    "aspect_ratio": "9:16"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

## <a id="output"></a>Результат

- Одна картинка за запуск, обычно за 1-4 минуты.
- Доработка готовой картинки по частям есть только в боте.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | jpg, png | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Grok Imagine 2.0: возможности и цены](https://api.cyhub.ai/models/grok-imagine-2)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# FLUX 3 API

> Видео FLUX 3 со звуком до 20 секунд: по описанию, по кадрам или продолжение готового ролика. Черновик стоит примерно треть полного видео.

Разработчик: Black Forest Labs
Ключ модели в API: `flux3`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "flux3",
  "settings": {
    "mode": "t2v",
    "prompt": "Лиса бежит сквозь утренний туман, под лапами хрустят ветки",
    "aspect_ratio": "16:9",
    "duration": 8
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "flux3",
    "settings": {
        "mode": "t2v",
        "prompt": "Лиса бежит сквозь утренний туман, под лапами хрустят ветки",
        "aspect_ratio": "16:9",
        "duration": 8,
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "flux3",
  "settings": {
    "mode": "t2v",
    "prompt": "Лиса бежит сквозь утренний туман, под лапами хрустят ветки",
    "aspect_ratio": "16:9",
    "duration": 8
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "flux3",
  "settings": {
    "mode": "t2v",
    "prompt": "Лиса бежит сквозь утренний туман, под лапами хрустят ветки",
    "aspect_ratio": "16:9",
    "duration": 8
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="t2v"></a>По описанию

> Видео только по тексту, файлы не передаются.

Значение поля mode: `t2v`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: сцена, движение камеры, звуки. Реплики и надписи в кадре тоже можно описать словами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `render` (Необязательно)

Полное видео или черновик. Черновик быстрее, всегда в HD и стоит примерно треть полного. Пересобрать черновик в полном качестве через API нельзя: полное видео это новая генерация, и сцена может выйти иначе.

- Тип: Строка
- Допустимые значения: `full` (Полное видео), `draft` (Черновик)
- По умолчанию: `"full"`

#### `resolution` (Необязательно)

Качество полного видео: HD или Full HD, Full HD дороже. Черновик всегда в HD, для него это поле не действует.

- Тип: Строка
- Допустимые значения: `hd`, `fhd` (Full HD)
- По умолчанию: `"hd"`

#### `aspect_ratio` (Необязательно)

Пропорции видео. Авто: модель подберёт сама, по кадрам или по исходному ролику.

- Тип: Строка
- Допустимые значения: `auto` (Авто), `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`
- По умолчанию: `"9:16"`

#### `audio` (Необязательно)

Со звуком или без. Речь, эффекты и фон модель пишет в том же запуске, отдельно звук не оплачивается.

- Тип: Строка
- Допустимые значения: `on` (Со звуком), `off` (Без звука)
- По умолчанию: `"on"`

#### `duration` (Необязательно)

Длительность видео в секундах, от 5 до 20. Цена за секунду, поэтому растёт вместе с длительностью.

- Тип: Целое число
- Минимум: 5
- Максимум: 20
- По умолчанию: `5`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "flux3",
  "settings": {
    "mode": "t2v",
    "prompt": "Лиса бежит сквозь утренний туман, под лапами хрустят ветки",
    "aspect_ratio": "16:9",
    "duration": 8
  }
}
```

Черновик, чтобы проверить идею

```json
{
  "model": "flux3",
  "settings": {
    "mode": "t2v",
    "prompt": "Бармен подбрасывает шейкер, ловит его за спиной и говорит: «Ваш коктейль»",
    "render": "draft",
    "duration": 6
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4, 24 кадра в секунду, со звуком, если он не выключен.
- Генерация занимает от 1 до 10 минут в зависимости от длины и качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="i2v"></a>По кадрам

> Ваши картинки становятся кадрами видео: одна открывает ролик, две задают начало и конец, больше двух модель расставит равномерно от начала к концу.

Значение поля mode: `i2v`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: сцена, движение камеры, звуки. Реплики и надписи в кадре тоже можно описать словами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `render` (Необязательно)

Полное видео или черновик. Черновик быстрее, всегда в HD и стоит примерно треть полного. Пересобрать черновик в полном качестве через API нельзя: полное видео это новая генерация, и сцена может выйти иначе.

- Тип: Строка
- Допустимые значения: `full` (Полное видео), `draft` (Черновик)
- По умолчанию: `"full"`

#### `resolution` (Необязательно)

Качество полного видео: HD или Full HD, Full HD дороже. Черновик всегда в HD, для него это поле не действует.

- Тип: Строка
- Допустимые значения: `hd`, `fhd` (Full HD)
- По умолчанию: `"hd"`

#### `aspect_ratio` (Необязательно)

Пропорции видео. По умолчанию Авто: модель подберёт их по вашим кадрам.

- Тип: Строка
- Допустимые значения: `auto` (Авто), `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`
- По умолчанию: `"auto"`

#### `audio` (Необязательно)

Со звуком или без. Речь, эффекты и фон модель пишет в том же запуске, отдельно звук не оплачивается.

- Тип: Строка
- Допустимые значения: `on` (Со звуком), `off` (Без звука)
- По умолчанию: `"on"`

#### `duration` (Необязательно)

Длительность видео в секундах, от 5 до 20. Цена за секунду, поэтому растёт вместе с длительностью.

- Тип: Целое число
- Минимум: 5
- Максимум: 20
- По умолчанию: `5`

#### `image_urls` (Обязательно)

От одной до десяти ссылок на кадры, по порядку.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Кадры передаются ссылками на картинки JPEG, PNG или WebP, каждая не меньше 256 на 256 точек.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 10 |  |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить кадр

```json
{
  "model": "flux3",
  "settings": {
    "mode": "i2v",
    "prompt": "Камера медленно наезжает, листья шевелятся на ветру",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ]
  }
}
```

Начало и конец

```json
{
  "model": "flux3",
  "settings": {
    "mode": "i2v",
    "prompt": "Бутон распускается в цветок, капли росы блестят на солнце",
    "aspect_ratio": "1:1",
    "duration": 6,
    "image_urls": [
      "https://example.com/bud.png",
      "https://example.com/flower.png"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4, 24 кадра в секунду, со звуком, если он не выключен.
- Генерация занимает от 1 до 10 минут в зависимости от длины и качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="v2v"></a>Продолжение видео

> Модель продолжает ваш ролик с его последних кадров. Исходник в результат не входит. Стоит заметно дороже остальных режимов.

Значение поля mode: `v2v`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео: сцена, движение камеры, звуки. Реплики и надписи в кадре тоже можно описать словами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `render` (Необязательно)

Полное видео или черновик. Черновик быстрее, всегда в HD и стоит примерно треть полного. Пересобрать черновик в полном качестве через API нельзя: полное видео это новая генерация, и сцена может выйти иначе.

- Тип: Строка
- Допустимые значения: `full` (Полное видео), `draft` (Черновик)
- По умолчанию: `"full"`

#### `resolution` (Необязательно)

Качество полного видео: HD или Full HD, Full HD дороже. Черновик всегда в HD, для него это поле не действует.

- Тип: Строка
- Допустимые значения: `hd`, `fhd` (Full HD)
- По умолчанию: `"hd"`

#### `aspect_ratio` (Необязательно)

Пропорции видео. По умолчанию Авто: продолжение берёт пропорции исходного ролика, и стык выходит ровным.

- Тип: Строка
- Допустимые значения: `auto` (Авто), `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`
- По умолчанию: `"auto"`

#### `audio` (Необязательно)

Со звуком или без. Речь, эффекты и фон модель пишет в том же запуске, отдельно звук не оплачивается.

- Тип: Строка
- Допустимые значения: `on` (Со звуком), `off` (Без звука)
- По умолчанию: `"on"`

#### `duration` (Необязательно)

Длительность видео в секундах, от 5 до 15. Цена за секунду, поэтому растёт вместе с длительностью.

- Тип: Целое число
- Минимум: 5
- Максимум: 15
- По умолчанию: `5`

#### `video_urls` (Обязательно)

Одна ссылка на ролик MP4, который нужно продолжить.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Ролик передаётся ссылкой на MP4 до 50 МБ и не длиннее 60 секунд. Он уходит целиком, обрезки нет: лишнее отрежьте заранее.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4 | 1 | 50 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Продолжить ролик

```json
{
  "model": "flux3",
  "settings": {
    "mode": "v2v",
    "prompt": "Машина уходит в поворот, из-под колёс летит гравий, камера догоняет её",
    "duration": 5,
    "video_urls": [
      "https://example.com/clip.mp4"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4, 24 кадра в секунду, со звуком, если он не выключен.
- Генерация занимает от 1 до 10 минут в зависимости от длины и качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть FLUX 3: возможности и цены](https://api.cyhub.ai/models/flux-3)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Vidu Q3 API

> Видео Vidu Q3 со звуком до 16 секунд и до 1080p: по описанию, из одного кадра, по первому и последнему кадру или по референсам.

Разработчик: ShengShu
Ключ модели в API: `vidu`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "vidu",
  "settings": {
    "mode": "t2v",
    "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»",
    "tier": "turbo",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "vidu",
    "settings": {
        "mode": "t2v",
        "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»",
        "tier": "turbo",
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "duration": 5,
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "vidu",
  "settings": {
    "mode": "t2v",
    "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»",
    "tier": "turbo",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "vidu",
  "settings": {
    "mode": "t2v",
    "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»",
    "tier": "turbo",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="t2v"></a>По описанию

> Видео только по тексту, картинки не передаются.

Значение поля mode: `t2v`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в кадре, кто в нём, как движется камера, что слышно. Реплики персонажей можно написать прямо в описании, модель попадёт в губы.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `audio` (Необязательно)

Со звуком (речь, эффекты и фон) или без. За звук доплаты нет.

- Тип: Строка
- Допустимые значения: `on` (Со звуком), `off` (Без звука)
- По умолчанию: `"on"`

#### `tier` (Необязательно)

Скорость: Turbo быстрее и дешевле, Pro аккуратнее с деталями, движением и лицами. Цена зависит от неё.

- Тип: Строка
- Допустимые значения: `turbo`, `pro`
- По умолчанию: `"turbo"`

#### `resolution` (Необязательно)

Качество видео. Цена считается за секунду и от качества зависит.

- Тип: Строка
- Допустимые значения: `540p`, `720p`, `1080p`
- Набор зависит от `tier`.
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длительность в секундах, от 1 до 16. Цена считается за секунду.

- Тип: Целое число
- Минимум: 1
- Максимум: 16
- По умолчанию: `5`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`
- По умолчанию: `"9:16"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Описание нужно в каждом режиме.
- Цена считается за секунду ролика и зависит от режима, скорости и качества.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "vidu",
  "settings": {
    "mode": "t2v",
    "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»",
    "tier": "turbo",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 1 до 10 минут в зависимости от длины и качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="i2v"></a>Оживить кадр

> Модель приводит картинку в движение по описанию, сохраняя, что на ней. Пропорции видео берутся от картинки.

Значение поля mode: `i2v`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в кадре, кто в нём, как движется камера, что слышно. Реплики персонажей можно написать прямо в описании, модель попадёт в губы.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `audio` (Необязательно)

Со звуком (речь, эффекты и фон) или без. За звук доплаты нет.

- Тип: Строка
- Допустимые значения: `on` (Со звуком), `off` (Без звука)
- По умолчанию: `"on"`

#### `tier` (Необязательно)

Скорость: Turbo быстрее и дешевле, Pro аккуратнее с деталями, движением и лицами. Цена зависит от неё.

- Тип: Строка
- Допустимые значения: `turbo`, `pro`
- По умолчанию: `"turbo"`

#### `resolution` (Необязательно)

Качество видео. Цена считается за секунду и от качества зависит.

- Тип: Строка
- Допустимые значения: `540p`, `720p`, `1080p`
- Набор зависит от `tier`.
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длительность в секундах, от 1 до 16. Цена считается за секунду.

- Тип: Целое число
- Минимум: 1
- Максимум: 16
- По умолчанию: `5`

#### `image_urls` (Обязательно)

Одна ссылка на картинку, которую нужно оживить.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Описание нужно в каждом режиме.
- Цена считается за секунду ролика и зависит от режима, скорости и качества.
- Картинки передаются ссылками на JPEG, PNG или WebP до 50 МБ каждая.
- Одна сторона картинки не может быть длиннее другой больше чем в 4 раза.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 50 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить фото

```json
{
  "model": "vidu",
  "settings": {
    "mode": "i2v",
    "prompt": "Кот поворачивает голову к камере и громко мяукает",
    "image_urls": [
      "https://example.com/cat.jpg"
    ],
    "duration": 5
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 1 до 10 минут в зависимости от длины и качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="se2v"></a>Первый и последний кадр

> Две картинки: с чего видео начинается и чем заканчивается, переход между ними модель придумает сама. Пропорции видео берутся от кадров.

Значение поля mode: `se2v`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в кадре, кто в нём, как движется камера, что слышно. Реплики персонажей можно написать прямо в описании, модель попадёт в губы.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `audio` (Необязательно)

Со звуком (речь, эффекты и фон) или без. За звук доплаты нет.

- Тип: Строка
- Допустимые значения: `on` (Со звуком), `off` (Без звука)
- По умолчанию: `"on"`

#### `tier` (Необязательно)

Скорость: Turbo быстрее и дешевле, Pro аккуратнее с деталями, движением и лицами. Цена зависит от неё.

- Тип: Строка
- Допустимые значения: `turbo`, `pro`
- По умолчанию: `"turbo"`

#### `resolution` (Необязательно)

Качество видео. Цена считается за секунду и от качества зависит.

- Тип: Строка
- Допустимые значения: `540p`, `720p`, `1080p`
- Набор зависит от `tier`.
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длительность в секундах, от 1 до 16. Цена считается за секунду.

- Тип: Целое число
- Минимум: 1
- Максимум: 16
- По умолчанию: `5`

#### `image_urls` (Обязательно)

Ровно две ссылки по порядку: первая это начальный кадр, вторая конечный.

- Тип: Список (Строка, uri)
- Максимум элементов: 2

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Описание нужно в каждом режиме.
- Цена считается за секунду ролика и зависит от режима, скорости и качества.
- Картинки передаются ссылками на JPEG, PNG или WebP до 50 МБ каждая.
- Пропорции двух кадров должны быть близкими: одни отличаются от других не больше чем в 1,25 раза.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 2 | 50 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Переход между кадрами

```json
{
  "model": "vidu",
  "settings": {
    "mode": "se2v",
    "prompt": "Утро плавно сменяется ночью, камера стоит на месте",
    "image_urls": [
      "https://example.com/first.jpg",
      "https://example.com/last.jpg"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 1 до 10 минут в зависимости от длины и качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="r2v"></a>По референсам

> До семи картинок: персонажи, предметы, одежда, обстановка, стиль. Модель собирает из них сцену и держит их похожими весь ролик. Длительность от 3 секунд.

Значение поля mode: `r2v`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в кадре, кто в нём, как движется камера, что слышно. Реплики персонажей можно написать прямо в описании, модель попадёт в губы.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `audio` (Необязательно)

Со звуком (речь, эффекты и фон) или без. За звук доплаты нет.

- Тип: Строка
- Допустимые значения: `on` (Со звуком), `off` (Без звука)
- По умолчанию: `"on"`

#### `tier` (Необязательно)

Скорость: Turbo быстрее и дешевле, Pro аккуратнее с деталями, движением и лицами. Цена зависит от неё. Mix даёт лучшую картинку, дороже Pro и без 540p.

- Тип: Строка
- Допустимые значения: `turbo`, `pro`, `mix`
- По умолчанию: `"turbo"`

#### `resolution` (Необязательно)

Качество видео. Цена считается за секунду и от качества зависит.

- Тип: Строка
- Допустимые значения: `540p`, `720p`, `1080p`
- Набор зависит от `tier`.
- Исключения:

  | `tier` | `resolution` |
  |---|---|
  | `mix` | кроме `540p` |
- По умолчанию: `"720p"`

#### `duration` (Необязательно)

Длительность в секундах, от 3 до 16. Цена считается за секунду.

- Тип: Целое число
- Минимум: 3
- Максимум: 16
- По умолчанию: `5`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`
- По умолчанию: `"9:16"`

#### `image_urls` (Обязательно)

От одной до семи ссылок на картинки с тем, что должно быть в видео.

- Тип: Список (Строка, uri)
- Максимум элементов: 7

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Описание нужно в каждом режиме.
- Цена считается за секунду ролика и зависит от режима, скорости и качества.
- Картинки передаются ссылками на JPEG, PNG или WebP до 50 МБ каждая.
- Одна сторона картинки не может быть длиннее другой больше чем в 4 раза.
- Каждая картинка не меньше 128 на 128 точек.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 7 | 50 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Персонаж и предмет с картинок

```json
{
  "model": "vidu",
  "settings": {
    "mode": "r2v",
    "prompt": "Девушка с первой картинки в куртке со второй идёт по ночной набережной",
    "tier": "pro",
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "duration": 6,
    "image_urls": [
      "https://example.com/girl.png",
      "https://example.com/jacket.png"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 1 до 10 минут в зависимости от длины и качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Vidu Q3: возможности и цены](https://api.cyhub.ai/models/vidu-q3)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# HappyHorse 1.1 API

> Видео HappyHorse: по описанию, из картинки, по картинкам-референсам или правка готового ролика.

Разработчик: Alibaba
Ключ модели в API: `happyhorse`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "happyhorse",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лошадь скачет по полю на закате, камера движется рядом",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "happyhorse",
    "settings": {
        "mode": "text_to_video",
        "prompt": "Лошадь скачет по полю на закате, камера движется рядом",
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "duration": 5,
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "happyhorse",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лошадь скачет по полю на закате, камера движется рядом",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "happyhorse",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лошадь скачет по полю на закате, камера движется рядом",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_video"></a>По описанию

> Видео только по тексту, картинки не передаются.

Значение поля mode: `text_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео. Можно на любом языке, для китайского текста до 2500 знаков.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `resolution` (Необязательно)

Разрешение готового видео, от него зависит цена.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра: горизонтальное, вертикальное, квадрат или классические 4:3 и 3:4.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- По умолчанию: `"9:16"`

#### `duration` (Необязательно)

Длина видео в секундах, от 3 до 15. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 3
- Максимум: 15
- По умолчанию: `5`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Видео по описанию

```json
{
  "model": "happyhorse",
  "settings": {
    "mode": "text_to_video",
    "prompt": "Лошадь скачет по полю на закате, камера движется рядом",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 3 до 15 минут, дольше у длинных роликов.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_video"></a>Из картинки

> Картинка становится первым кадром, модель оживляет её по описанию. Пропорции видео берутся у картинки.

Значение поля mode: `image_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео. Можно на любом языке, для китайского текста до 2500 знаков.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `resolution` (Необязательно)

Разрешение готового видео, от него зависит цена.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `image_urls` (Обязательно)

Одна ссылка на картинку для первого кадра.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `duration` (Необязательно)

Длина видео в секундах, от 3 до 15. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 3
- Максимум: 15
- По умолчанию: `5`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 20 МБ, каждая сторона не меньше 300 пикселей, пропорции от 1:2,5 до 2,5:1.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Оживить картинку

```json
{
  "model": "happyhorse",
  "settings": {
    "mode": "image_to_video",
    "prompt": "Камера медленно наезжает, волосы героини развеваются на ветру",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "duration": 5
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 3 до 15 минут, дольше у длинных роликов.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="reference_to_video"></a>По референсам

> Персонажи, предметы и окружение с ваших картинок в новом видео.

Значение поля mode: `reference_to_video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что происходит в видео. Можно на любом языке, для китайского текста до 2500 знаков.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `resolution` (Необязательно)

Разрешение готового видео, от него зависит цена.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `reference_image_urls` (Обязательно)

От 1 до 9 ссылок на картинки с персонажами, предметами или окружением.

- Тип: Список (Строка, uri)
- Максимум элементов: 9

#### `aspect_ratio` (Необязательно)

Пропорции кадра: горизонтальное, вертикальное, квадрат или классические 4:3 и 3:4.

- Тип: Строка
- Допустимые значения: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- По умолчанию: `"9:16"`

#### `duration` (Необязательно)

Длина видео в секундах, от 3 до 15. Цена за каждую секунду.

- Тип: Целое число
- Минимум: 3
- Максимум: 15
- По умолчанию: `5`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинки передаются ссылками на JPEG, PNG или WebP до 20 МБ каждая, короткая сторона не меньше 400 пикселей.
- В описании на картинки можно ссылаться по порядку ссылок: [Image 1], [Image 2] и так далее.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `reference_image_urls` | Картинки | jpeg, jpg, png, webp | 9 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Персонаж с картинки

```json
{
  "model": "happyhorse",
  "settings": {
    "mode": "reference_to_video",
    "prompt": "Женщина с [Image 1] идёт по ночному городу под дождём",
    "reference_image_urls": [
      "https://example.com/woman.png"
    ],
    "aspect_ratio": "9:16",
    "duration": 5
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 3 до 15 минут, дольше у длинных роликов.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video_edit"></a>Правка видео

> Готовый ролик меняется по описанию: другая одежда, стиль, предметы. Работает на версии 1.0, поэтому секунда здесь дороже.

Значение поля mode: `video_edit`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что изменить в ролике, например «надень на героя свитер с картинки». Можно на любом языке, для китайского текста до 2500 знаков.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `resolution` (Необязательно)

Разрешение готового видео, от него зависит цена.

- Тип: Строка
- Допустимые значения: `720p`, `1080p`
- По умолчанию: `"720p"`

#### `video_url` (Обязательно)

Одна ссылка на ролик, который нужно изменить.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `reference_image_urls` (Необязательно)

До 5 ссылок на картинки с тем, что нужно добавить в ролик. Необязательно.

- Тип: Список (Строка, uri)
- Максимум элементов: 5

#### `audio_setting` (Необязательно)

Звук результата: новый, подобранный под изменённое видео, или звук исходного ролика.

- Тип: Строка
- Допустимые значения: `auto` (Авто (новое аудио по контексту)), `origin` (Оставить оригинальное)
- По умолчанию: `"auto"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Видео передаётся ссылкой на MP4 или MOV до 100 МБ, длиной от 3 до 60 секунд, стороны от 320 до 2160 пикселей, пропорции от 1:2,5 до 2,5:1, частота кадров больше 8 в секунду.
- Ролик уходит в модель целиком. Цена считается по его длине: за секунды исходника и столько же за результат, неполная секунда считается целой.
- Картинки передаются ссылками на JPEG, PNG или WebP до 10 МБ каждая, каждая сторона не меньше 300 пикселей, пропорции от 1:2,5 до 2,5:1.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_url` | Видео | mp4, mov | 1 | 100 МБ |
| `reference_image_urls` | Картинки | jpeg, jpg, png, webp | 5 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Переодеть героя

```json
{
  "model": "happyhorse",
  "settings": {
    "mode": "video_edit",
    "prompt": "Надень на героя полосатый свитер с картинки",
    "video_url": [
      "https://example.com/clip.mp4"
    ],
    "reference_image_urls": [
      "https://example.com/sweater.png"
    ],
    "audio_setting": "origin"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одно видео MP4.
- Генерация занимает от 3 до 15 минут, дольше у длинных роликов.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть HappyHorse 1.1: возможности и цены](https://api.cyhub.ai/models/happyhorse)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# HeyGen Lip Sync API

> HeyGen LipSync: новая звуковая дорожка для готового видео, губы человека в кадре двигаются под неё.

Разработчик: HeyGen
Ключ модели в API: `heygen`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "heygen",
  "settings": {
    "video_url": [
      "https://example.com/speaker.mp4"
    ],
    "audio_url": [
      "https://example.com/new_voice.mp3"
    ]
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "heygen",
    "settings": {
        "video_url": [
            "https://example.com/speaker.mp4",
        ],
        "audio_url": [
            "https://example.com/new_voice.mp3",
        ],
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "heygen",
  "settings": {
    "video_url": [
      "https://example.com/speaker.mp4"
    ],
    "audio_url": [
      "https://example.com/new_voice.mp3"
    ]
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "heygen",
  "settings": {
    "video_url": [
      "https://example.com/speaker.mp4"
    ],
    "audio_url": [
      "https://example.com/new_voice.mp3"
    ]
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="parameters"></a>Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

### `mode` (Необязательно)

Качество. Быстрый подходит, когда лицо почти не двигается. Точный лучше справляется с поворотами головы, движением и частично закрытым лицом, работает дольше и стоит дороже.

- Тип: Строка
- Допустимые значения: `speed`, `precision`
- По умолчанию: `"speed"`

### `video_url` (Обязательно)

Одна ссылка на исходное видео. Лицо говорящего должно быть хорошо видно, а в видео должна быть своя звуковая дорожка с речью.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

### `audio_url` (Обязательно)

Одна ссылка на новую звуковую дорожку: под неё двигаются губы.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

### `enable_dynamic_duration` (Необязательно)

Подогнать длину готового видео под длину аудио. Включено: длины аудио и видео должны отличаться не больше чем на 15%, иначе HeyGen откажет. Выключено: видео сохраняет свою длину.

- Тип: Да/нет
- По умолчанию: `true`

### `disable_music_track` (Необязательно)

Убрать фоновую музыку из исходного видео.

- Тип: Да/нет
- По умолчанию: `false`

### `enable_speech_enhancement` (Необязательно)

Улучшить звучание речи в готовом видео.

- Тип: Да/нет
- По умолчанию: `false`

### `keep_the_same_format` (Необязательно)

Сохранить разрешение и битрейт исходного видео.

- Тип: Да/нет
- По умолчанию: `true`

### `enable_watermark` (Необязательно)

Поставить на готовое видео водяной знак HeyGen.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

## <a id="input"></a>Входные данные

- Видео передаётся ссылкой на MP4, MOV или WebM до 200 МБ, аудио ссылкой на MP3, WAV, M4A, OGG или FLAC до 50 МБ. Видео не длиннее 10 минут, аудио не длиннее 10 минут.
- Ссылки должны быть открыты всем и начинаться с https://: HeyGen скачивает файлы сам.
- В исходном видео нужна своя звуковая дорожка с речью: по ней HeyGen находит, кто и когда говорит. Видео без звука или с тишиной он не берёт.
- Видео уходит в HeyGen целиком, и цена считается по его полной длине в секундах.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_url` | Видео | mp4, mov, webm | 1 | 200 МБ |
| `audio_url` | Аудио | mp3, wav, m4a, ogg, flac | 1 | 50 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

## <a id="example"></a>Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Новая озвучка видео

```json
{
  "model": "heygen",
  "settings": {
    "video_url": [
      "https://example.com/speaker.mp4"
    ],
    "audio_url": [
      "https://example.com/new_voice.mp3"
    ]
  }
}
```

Точный режим, видео своей длины

```json
{
  "model": "heygen",
  "settings": {
    "mode": "precision",
    "video_url": [
      "https://example.com/interview.mov"
    ],
    "audio_url": [
      "https://example.com/dub.wav"
    ],
    "enable_dynamic_duration": false,
    "disable_music_track": true
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

## <a id="output"></a>Результат

- Одно видео с новой звуковой дорожкой.
- Обработка обычно идёт несколько минут, изредка до получаса.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть HeyGen Lip Sync: возможности и цены](https://api.cyhub.ai/models/heygen-lip-sync)
- Похожие модели: [Seedance 2.5 API](https://api.cyhub.ai/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/models/minimax-h3/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Seedream 5.0 API

> Картинки Seedream 5.0 по описанию и по референсам (до 14), качество 2K или 3K. Результат PNG или JPEG.

Разработчик: ByteDance
Ключ модели в API: `seedream`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream",
  "settings": {
    "mode": "5.0",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "3:4",
    "quality": "3K",
    "output_format": "png"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "seedream",
    "settings": {
        "mode": "5.0",
        "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
        "aspect_ratio": "3:4",
        "quality": "3K",
        "output_format": "png",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "seedream",
  "settings": {
    "mode": "5.0",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "3:4",
    "quality": "3K",
    "output_format": "png"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream",
  "settings": {
    "mode": "5.0",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "3:4",
    "quality": "3K",
    "output_format": "png"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="5.0"></a>Seedream 5.0

> Качество 2K или 3K, до 14 референсов, результат PNG или JPEG.

Значение поля mode: `5.0`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Описание картинки или что сделать с референсами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `image_urls` (Необязательно)

Ссылки на референсы, до 14. Без них картинка рисуется только по описанию.

- Тип: Список (Строка, uri)
- Максимум элементов: 14

#### `aspect_ratio` (Необязательно)

Пропорции картинки.

- Тип: Строка
- Допустимые значения: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9`
- По умолчанию: `"9:16"`

#### `quality` (Необязательно)

Качество картинки: 2K или 3K.

- Тип: Строка
- Допустимые значения: `2K`, `3K`
- По умолчанию: `"2K"`

#### `output_format` (Необязательно)

Формат файла результата.

- Тип: Строка
- Допустимые значения: `png`, `jpeg`
- По умолчанию: `"png"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `model_version` = `"5.0"`

### Входные данные

- Референсы передаются ссылками на картинки JPEG, PNG, WebP, BMP, TIFF или GIF до 30 МБ каждая.
- У каждой картинки обе стороны больше 14 пикселей, площадь не больше 6000×6000 пикселей, одна сторона длиннее другой не больше чем в 16 раз.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, tif, gif | 14 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Картинка по описанию

```json
{
  "model": "seedream",
  "settings": {
    "mode": "5.0",
    "prompt": "Уютная кофейня дождливым вечером, тёплый свет в окнах",
    "aspect_ratio": "3:4",
    "quality": "3K",
    "output_format": "png"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка за запуск в выбранном формате.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg | 1 | Формат задаёт output_format. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Seedream 5.0: возможности и цены](https://api.cyhub.ai/models/seedream-5)
- Другие версии: [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md), [Seedream 4.5 API](https://api.cyhub.ai/models/seedream-4-5/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Seedream 5.0 PRO API

> Картинки Seedream 5.0 PRO по описанию и по референсам (до 10), качество 1K или 2K. Ещё она разбирает картинку на слои с прозрачностью и правит картинку PNG с прозрачным фоном, сохраняя прозрачность.

Разработчик: ByteDance
Ключ модели в API: `seedream`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream",
  "settings": {
    "mode": "5.0_pro",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "aspect_ratio": "21:9",
    "quality": "2K"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "seedream",
    "settings": {
        "mode": "5.0_pro",
        "prompt": "Горный хребет на рассвете, туман в долинах",
        "aspect_ratio": "21:9",
        "quality": "2K",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "seedream",
  "settings": {
    "mode": "5.0_pro",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "aspect_ratio": "21:9",
    "quality": "2K"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream",
  "settings": {
    "mode": "5.0_pro",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "aspect_ratio": "21:9",
    "quality": "2K"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="5.0_pro"></a>Seedream 5.0 PRO

> Новейшая версия: качество 1K или 2K, до 10 референсов. Каждый референс со второго немного добавляет к цене.

Значение поля mode: `5.0_pro`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Описание картинки или что сделать с референсами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `image_urls` (Необязательно)

Ссылки на референсы, до 10. Без них картинка рисуется только по описанию.

- Тип: Список (Строка, uri)
- Максимум элементов: 10

#### `aspect_ratio` (Необязательно)

Пропорции картинки.

- Тип: Строка
- Допустимые значения: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9`
- По умолчанию: `"9:16"`

#### `quality` (Необязательно)

Качество картинки: 1K или 2K. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `1K`, `2K`
- По умолчанию: `"1K"`

#### `output_format` (Необязательно)

Формат файла результата.

- Тип: Строка
- Допустимые значения: `png`, `jpeg`
- По умолчанию: `"png"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `model_version` = `"5.0_pro"`

### Входные данные

- Референсы передаются ссылками на картинки JPEG, PNG, WebP, BMP, TIFF или GIF до 30 МБ каждая.
- У каждой картинки обе стороны больше 14 пикселей, площадь не больше 6000×6000 пикселей, одна сторона длиннее другой не больше чем в 16 раз.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, tif, gif | 10 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Широкая картинка в 2K

```json
{
  "model": "seedream",
  "settings": {
    "mode": "5.0_pro",
    "prompt": "Горный хребет на рассвете, туман в долинах",
    "aspect_ratio": "21:9",
    "quality": "2K"
  }
}
```

Персонаж с референса

```json
{
  "model": "seedream",
  "settings": {
    "mode": "5.0_pro",
    "prompt": "Этот персонаж на обложке журнала о путешествиях",
    "image_urls": [
      "https://example.com/character.png"
    ],
    "aspect_ratio": "3:4"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка за запуск в выбранном формате.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg | 1 | Формат задаёт output_format. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="layers"></a>Разбор на слои

> Версия 5.0 PRO разбирает одну картинку на части: подложку без вытащенных элементов и каждый заметный элемент отдельным PNG с прозрачностью. Сколько выйдет частей, решает модель. Цена показана за максимум, списывается только за вернувшиеся файлы.

Значение поля mode: `layers`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на картинку, которую разобрать.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `prompt` (Необязательно)

Что разобрать, словами, например «кот и надпись сверху». Нужную часть можно показать и рамкой <bbox>x1 y1 x2 y2</bbox>: углы в долях картинки от 0 до 1000, левый верхний и правый нижний. Без описания модель сама находит все заметные элементы.

- Тип: Строка
- Максимум символов: 5000

#### `quality` (Необязательно)

Размер подложки и слоёв. 1K и 1.5K стоят одинаково, у 1.5K файлы крупнее. 2K дороже.

- Тип: Строка
- Допустимые значения: `1K`, `1.5K`, `2K`
- По умолчанию: `"1.5K"`

#### `output_format` (Необязательно)

Формат подложки. Слои всегда PNG.

- Тип: Строка
- Допустимые значения: `png`, `jpeg`
- По умолчанию: `"png"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `model_version` = `"5.0_pro"`, `layer_decomposition` = `true`

### Входные данные

- Одна картинка JPEG или PNG до 30 МБ, по площади от 512×512 до 6000×6000 пикселей, одна сторона длиннее другой не больше чем в 16 раз.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png | 1 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Разобрать всю картинку

```json
{
  "model": "seedream",
  "settings": {
    "mode": "layers",
    "image_urls": [
      "https://example.com/poster.png"
    ]
  }
}
```

Достать названные элементы

```json
{
  "model": "seedream",
  "settings": {
    "mode": "layers",
    "image_urls": [
      "https://example.com/poster.png"
    ],
    "prompt": "Кот и надпись сверху",
    "quality": "2K"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Подложка картинкой и архив ZIP: подложка, каждый слой отдельным PNG с прозрачностью, собранный из слоёв кадр и опись слоёв с названиями от модели.
- Слоёв бывает от одного до шестнадцати.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg | 1 | Подложка, формат задаёт output_format. |
| `document` | zip | 1 | Архив: подложка, каждый слой отдельным PNG, собранный из слоёв кадр и список слоёв. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.zip",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="keep_transparency"></a>Правка с прозрачностью

> Версия 5.0 PRO правит картинку PNG с прозрачным фоном так, что прозрачность остаётся. Обычный снимок так прозрачным не сделать: для этого есть разбор на слои.

Значение поля mode: `keep_transparency`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что поправить в картинке.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `image_urls` (Обязательно)

Одна ссылка на PNG, в котором уже есть прозрачные места.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `aspect_ratio` (Необязательно)

Пропорции картинки.

- Тип: Строка
- Допустимые значения: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9`
- По умолчанию: `"9:16"`

#### `quality` (Необязательно)

Качество картинки: 1K или 2K. Цена зависит от него.

- Тип: Строка
- Допустимые значения: `1K`, `2K`
- По умолчанию: `"1K"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `model_version` = `"5.0_pro"`, `keep_transparency` = `true`, `output_format` = `"png"`

### Входные данные

- Одна картинка PNG до 30 МБ, в которой уже есть прозрачные места.
- У каждой картинки обе стороны больше 14 пикселей, площадь не больше 6000×6000 пикселей, одна сторона длиннее другой не больше чем в 16 раз.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | png | 1 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Перекрасить логотип без фона

```json
{
  "model": "seedream",
  "settings": {
    "mode": "keep_transparency",
    "prompt": "Сделай логотип синим, форму не меняй",
    "image_urls": [
      "https://example.com/logo.png"
    ],
    "aspect_ratio": "1:1"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка PNG с прозрачным фоном.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Seedream 5.0 PRO: возможности и цены](https://api.cyhub.ai/models/seedream-5-pro)
- Другие версии: [Seedream 5.0 API](https://api.cyhub.ai/models/seedream-5/api.md), [Seedream 4.5 API](https://api.cyhub.ai/models/seedream-4-5/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Seedream 4.5 API

> Картинки Seedream 4.5 по описанию и по референсам (до 14), качество 2K или 4K. Предыдущая версия, результат всегда JPEG.

Разработчик: ByteDance
Ключ модели в API: `seedream`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream",
  "settings": {
    "mode": "4.5",
    "prompt": "Маяк на скале в шторм, кинематографичный свет",
    "aspect_ratio": "16:9",
    "quality": "4K"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "seedream",
    "settings": {
        "mode": "4.5",
        "prompt": "Маяк на скале в шторм, кинематографичный свет",
        "aspect_ratio": "16:9",
        "quality": "4K",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "seedream",
  "settings": {
    "mode": "4.5",
    "prompt": "Маяк на скале в шторм, кинематографичный свет",
    "aspect_ratio": "16:9",
    "quality": "4K"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream",
  "settings": {
    "mode": "4.5",
    "prompt": "Маяк на скале в шторм, кинематографичный свет",
    "aspect_ratio": "16:9",
    "quality": "4K"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="4.5"></a>Seedream 4.5

> Предыдущая версия: качество 2K или 4K, до 14 референсов. Результат всегда JPEG.

Значение поля mode: `4.5`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Описание картинки или что сделать с референсами.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 5000

#### `image_urls` (Необязательно)

Ссылки на референсы, до 14. Без них картинка рисуется только по описанию.

- Тип: Список (Строка, uri)
- Максимум элементов: 14

#### `aspect_ratio` (Необязательно)

Пропорции картинки.

- Тип: Строка
- Допустимые значения: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9`
- По умолчанию: `"9:16"`

#### `quality` (Необязательно)

Качество картинки: 2K или 4K.

- Тип: Строка
- Допустимые значения: `2K`, `4K`
- По умолчанию: `"2K"`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `model_version` = `"4.5"`, `output_format` = `"jpeg"`

### Входные данные

- Референсы передаются ссылками на картинки JPEG, PNG, WebP, BMP, TIFF или GIF до 30 МБ каждая.
- У каждой картинки обе стороны больше 14 пикселей, площадь не больше 6000×6000 пикселей, одна сторона длиннее другой не больше чем в 16 раз.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp, bmp, tiff, tif, gif | 14 | 30 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Картинка в 4K

```json
{
  "model": "seedream",
  "settings": {
    "mode": "4.5",
    "prompt": "Маяк на скале в шторм, кинематографичный свет",
    "aspect_ratio": "16:9",
    "quality": "4K"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Одна картинка JPEG за запуск.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | jpg | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.jpg",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Seedream 4.5: возможности и цены](https://api.cyhub.ai/models/seedream-4-5)
- Другие версии: [Seedream 5.0 API](https://api.cyhub.ai/models/seedream-5/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Recraft API](https://api.cyhub.ai/models/recraft/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Recraft API

> Картинки Recraft и настоящий вектор SVG по описанию, версии V4.1 и V4.1 Pro. Правка вашей картинки: замена и стирание области по маске, расширение кадра, замена фона. Ещё похожие варианты, перевод в вектор, удаление фона и апскейл.

Разработчик: Recraft
Ключ модели в API: `recraft`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
    "engine": "v4_1",
    "aspect_ratio": "3:2"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "recraft",
    "settings": {
        "mode": "text_to_image",
        "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
        "engine": "v4_1",
        "aspect_ratio": "3:2",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
    "engine": "v4_1",
    "aspect_ratio": "3:2"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
    "engine": "v4_1",
    "aspect_ratio": "3:2"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_image"></a>Картинка по описанию

> Рисует картинку с нуля по описанию. Recraft хорошо держит текст в кадре.

Значение поля mode: `text_to_image`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что нарисовать. Слова, которые должны быть на картинке, пишите в кавычках. С движками V3 и V2 не длиннее 1000 символов.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 2000

#### `engine` (Необязательно)

Движок, от него зависит цена. V4.1: лучший баланс. V4.1 Pro: максимум качества, крупнее (квадрат 2048 на 2048 против 1024 на 1024) и заметно дороже. V3: умеет готовые стили. V2: самый дешёвый.

- Тип: Строка
- Допустимые значения: `v4_1` (V4.1 (лучший баланс)), `v4_1_pro` (V4.1 Pro (максимум качества))
- По умолчанию: `"v4_1"`

#### `style` (Необязательно)

Готовый стиль: фотореализм или иллюстрация. Есть только у V3 и V2, у V4.1 манеру задают словами в описании.

- Тип: Строка
- Допустимые значения: `none`
- Набор зависит от `engine`.
- По умолчанию: `"none"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2`
- По умолчанию: `"1:1"`

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Вывеска с надписью

```json
{
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
    "engine": "v4_1",
    "aspect_ratio": "3:2"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинки приходят файлами WebP без потери качества, столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="text_to_vector"></a>Вектор по описанию

> Рисует с нуля настоящий вектор SVG: логотипы, иконки, плоские иллюстрации.

Значение поля mode: `text_to_vector`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что нарисовать. Слова, которые должны быть на картинке, пишите в кавычках. С движками V3 и V2 не длиннее 1000 символов.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 2000

#### `engine` (Необязательно)

Движок, от него зависит цена. V4.1: лучший баланс. V4.1 Pro: максимум качества, заметно дороже. V3: прошлое поколение. V2: самый дешёвый.

- Тип: Строка
- Допустимые значения: `v4_1` (V4.1 (лучший баланс)), `v4_1_pro` (V4.1 Pro (максимум качества))
- По умолчанию: `"v4_1"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2`
- По умолчанию: `"1:1"`

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Иконка

```json
{
  "model": "recraft",
  "settings": {
    "mode": "text_to_vector",
    "prompt": "Плоская иконка ракеты в два цвета, толстый контур",
    "engine": "v4_1",
    "aspect_ratio": "1:1"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Результат в SVG: настоящий вектор, его можно увеличивать без потерь и править в редакторе. Файлов столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `document` | svg | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "document",
        "filename": "result.svg",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_image"></a>Переделать картинку

> Ваша картинка плюс описание: модель рисует новую, сохраняя композицию и цвета исходника. Насколько далеко уйти, задаёт strength.

Значение поля mode: `image_to_image`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `prompt` (Обязательно)

Какой должна получиться картинка, до 1000 символов. Предметы называйте словами: модель рисует по описанию и не понимает отсылок вроде «тот же предмет».

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1000

#### `strength` (Необязательно)

Насколько далеко уйти от исходника: 0.2 слегка подправить, 0.5 заметно переделать, 0.8 почти нарисовать заново.

- Тип: Строка
- Допустимые значения: `0.2` (Слегка подправить), `0.5` (Заметно переделать), `0.8` (Почти нарисовать заново)
- По умолчанию: `"0.5"`

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 256 до 4096 пикселей.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Другой интерьер

```json
{
  "model": "recraft",
  "settings": {
    "mode": "image_to_image",
    "image_urls": [
      "https://example.com/living-room.jpg"
    ],
    "prompt": "Гостиная в скандинавском стиле: светлый диван, дубовый стол, растения в горшках",
    "strength": "0.5"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинки приходят файлами WebP без потери качества, столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="inpaint"></a>Заменить область

> Перерисовывает по описанию часть картинки, отмеченную маской. Остальное не меняется.

Значение поля mode: `inpaint`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `mask_urls` (Обязательно)

Одна ссылка на маску: картинку в оттенках серого ровно того же размера, что исходник. Белым отмечено то, что перерисовать, чёрным то, что оставить.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `prompt` (Обязательно)

Описание всей картинки, какой она должна стать, а не только отмеченного куска, до 1000 символов. Короткая команда вроде «напиши тут GG» область только затрёт.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1000

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 256 до 4096 пикселей.
- Маска: картинка PNG или JPEG в оттенках серого (один канал, без цвета и прозрачности) ровно того же размера, что исходник. Белым отмечено то, что меняется, чёрным то, что остаётся. Цветная маска не подойдёт, даже если на вид она чёрно-белая.
- Лучше PNG: нужны только чистый чёрный и чистый белый, а JPEG при сжатии даёт серые пиксели на границах.
- Картинку и маску мы скачиваем сами: ссылка должна отдавать файл сразу, без переадресации.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |
| `mask_urls` | Картинки | jpeg, jpg, png | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Кактус на подоконнике

```json
{
  "model": "recraft",
  "settings": {
    "mode": "inpaint",
    "image_urls": [
      "https://example.com/room.jpg"
    ],
    "mask_urls": [
      "https://example.com/room-mask.png"
    ],
    "prompt": "Светлая комната, на подоконнике стоит глиняный горшок с кактусом"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинки приходят файлами WebP без потери качества, столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="erase"></a>Стереть лишнее

> Убирает с картинки то, что отмечено маской, и достраивает фон под ним. Описание не нужно.

Значение поля mode: `erase`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `mask_urls` (Обязательно)

Одна ссылка на маску: картинку в оттенках серого ровно того же размера, что исходник. Белым отмечено то, что стереть, чёрным то, что оставить.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 256 до 4096 пикселей.
- Маска: картинка PNG или JPEG в оттенках серого (один канал, без цвета и прозрачности) ровно того же размера, что исходник. Белым отмечено то, что меняется, чёрным то, что остаётся. Цветная маска не подойдёт, даже если на вид она чёрно-белая.
- Лучше PNG: нужны только чистый чёрный и чистый белый, а JPEG при сжатии даёт серые пиксели на границах.
- Картинку и маску мы скачиваем сами: ссылка должна отдавать файл сразу, без переадресации.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |
| `mask_urls` | Картинки | jpeg, jpg, png | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Убрать прохожего

```json
{
  "model": "recraft",
  "settings": {
    "mode": "erase",
    "image_urls": [
      "https://example.com/beach.jpg"
    ],
    "mask_urls": [
      "https://example.com/beach-mask.png"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинка приходит файлом WebP без потери качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="outpaint"></a>Расширить кадр

> Дорисовывает картинку в стороны на заданное число пикселей.

Значение поля mode: `outpaint`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `prompt` (Обязательно)

Что должно появиться в дорисованной части, до 1000 символов.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1000

#### `expand_left` (Необязательно)

На сколько пикселей дорисовать слева, от 0 до 1024.

- Тип: Целое число
- Минимум: 0
- Максимум: 1024
- По умолчанию: `0`

#### `expand_right` (Необязательно)

На сколько пикселей дорисовать справа, от 0 до 1024.

- Тип: Целое число
- Минимум: 0
- Максимум: 1024
- По умолчанию: `0`

#### `expand_top` (Необязательно)

На сколько пикселей дорисовать сверху, от 0 до 1024.

- Тип: Целое число
- Минимум: 0
- Максимум: 1024
- По умолчанию: `0`

#### `expand_bottom` (Необязательно)

На сколько пикселей дорисовать снизу, от 0 до 1024.

- Тип: Целое число
- Минимум: 0
- Максимум: 1024
- По умолчанию: `0`

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 256 до 4096 пикселей.
- Хотя бы одна сторона больше нуля. Итоговый кадр не больше 4096 пикселей по каждой стороне.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Шире по бокам

```json
{
  "model": "recraft",
  "settings": {
    "mode": "outpaint",
    "image_urls": [
      "https://example.com/portrait.jpg"
    ],
    "prompt": "Песчаный пляж и спокойное море до горизонта",
    "expand_left": 512,
    "expand_right": 512
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинки приходят файлами WebP без потери качества, столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="replace_background"></a>Заменить фон

> Объект остаётся, а фон Recraft находит сам и переписывает по описанию.

Значение поля mode: `replace_background`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `prompt` (Обязательно)

Каким должен стать фон, до 1000 символов.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1000

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 256 до 4096 пикселей.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Товар на мраморе

```json
{
  "model": "recraft",
  "settings": {
    "mode": "replace_background",
    "image_urls": [
      "https://example.com/bottle.png"
    ],
    "prompt": "Мраморная столешница, мягкий утренний свет"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинки приходят файлами WebP без потери качества, столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="generate_background"></a>Фон по маске

> Как замена фона, но где фон, задаёт маска.

Значение поля mode: `generate_background`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `mask_urls` (Обязательно)

Одна ссылка на маску: картинку в оттенках серого ровно того же размера, что исходник. Белым отмечено, где рисовать новый фон, чёрным объект, который остаётся.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `prompt` (Обязательно)

Каким должен стать фон, до 1000 символов.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1000

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 256 до 4096 пикселей.
- Маска: картинка PNG или JPEG в оттенках серого (один канал, без цвета и прозрачности) ровно того же размера, что исходник. Белым отмечено то, что меняется, чёрным то, что остаётся. Цветная маска не подойдёт, даже если на вид она чёрно-белая.
- Лучше PNG: нужны только чистый чёрный и чистый белый, а JPEG при сжатии даёт серые пиксели на границах.
- Картинку и маску мы скачиваем сами: ссылка должна отдавать файл сразу, без переадресации.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |
| `mask_urls` | Картинки | jpeg, jpg, png | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Кроссовок у стены

```json
{
  "model": "recraft",
  "settings": {
    "mode": "generate_background",
    "image_urls": [
      "https://example.com/sneaker.png"
    ],
    "mask_urls": [
      "https://example.com/sneaker-mask.png"
    ],
    "prompt": "Бетонная стена с граффити, дневной свет"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинки приходят файлами WebP без потери качества, столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="variate"></a>Похожие варианты

> Несколько вариаций вашей картинки: меняются детали, положение предметов и композиция, общая идея остаётся. Описание не нужно.

Значение поля mode: `variate`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `aspect_ratio` (Необязательно)

Пропорции вариантов.

- Тип: Строка
- Допустимые значения: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2`
- По умолчанию: `"1:1"`

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 256 до 4096 пикселей.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Три варианта персонажа

```json
{
  "model": "recraft",
  "settings": {
    "mode": "variate",
    "image_urls": [
      "https://example.com/mascot.png"
    ],
    "aspect_ratio": "1:1",
    "count": 3
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинки приходят файлами WebP без потери качества, столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="vectorize"></a>Перевести в вектор

> Переводит картинку в настоящий вектор SVG. Описание не нужно.

Значение поля mode: `vectorize`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 256 до 4096 пикселей.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Логотип в вектор

```json
{
  "model": "recraft",
  "settings": {
    "mode": "vectorize",
    "image_urls": [
      "https://example.com/logo.png"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Результат: один файл SVG.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `document` | svg | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "document",
        "filename": "result.svg",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="remove_background"></a>Убрать фон

> Вырезает объект и убирает фон. Описание не нужно.

Значение поля mode: `remove_background`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 256 до 4096 пикселей.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Товар без фона

```json
{
  "model": "recraft",
  "settings": {
    "mode": "remove_background",
    "image_urls": [
      "https://example.com/product.jpg"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинка с прозрачным фоном, файл WebP без потери качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="upscale_crisp"></a>Апскейл

> Увеличивает картинку: линии остаются резкими, нового не появляется. Описание не нужно.

Значение поля mode: `upscale_crisp`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 32 до 4096 пикселей.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Увеличить маленькую картинку

```json
{
  "model": "recraft",
  "settings": {
    "mode": "upscale_crisp",
    "image_urls": [
      "https://example.com/small.png"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинка приходит файлом WebP без потери качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="upscale_creative"></a>Апскейл с дорисовкой

> Увеличивает картинку и досочиняет мелкие детали: поры кожи, волоски, фактуру ткани. Спасает маленькие и мыльные исходники, но детали может переписать по-своему. Описание не нужно.

Значение поля mode: `upscale_creative`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `image_urls` (Обязательно)

Одна ссылка на исходную картинку.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Картинка передаётся ссылкой на JPEG, PNG или WebP до 10 МБ, не больше 16 мегапикселей, каждая сторона от 256 до 4096 пикселей.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_urls` | Картинки | jpeg, jpg, png, webp | 1 | 10 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Старое фото крупнее

```json
{
  "model": "recraft",
  "settings": {
    "mode": "upscale_creative",
    "image_urls": [
      "https://example.com/old-photo.jpg"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинка приходит файлом WebP без потери качества.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | 1 |  |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Recraft: возможности и цены](https://api.cyhub.ai/models/recraft)
- Другие версии: [Recraft V3 API](https://api.cyhub.ai/models/recraft-v3/api.md), [Recraft V2 API](https://api.cyhub.ai/models/recraft-v2/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Recraft V3 API

> Картинки Recraft V3 с готовыми стилями и настоящий вектор SVG по описанию: логотипы, иконки, плоские иллюстрации. Стили: фотореализм или иллюстрация. До 6 штук за один запуск.

Разработчик: Recraft
Ключ модели в API: `recraft`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Чашка капучино на мраморном столе, утренний свет из окна",
    "engine": "v3",
    "style": "realistic_image",
    "count": 2
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "recraft",
    "settings": {
        "mode": "text_to_image",
        "prompt": "Чашка капучино на мраморном столе, утренний свет из окна",
        "engine": "v3",
        "style": "realistic_image",
        "count": 2,
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Чашка капучино на мраморном столе, утренний свет из окна",
    "engine": "v3",
    "style": "realistic_image",
    "count": 2
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Чашка капучино на мраморном столе, утренний свет из окна",
    "engine": "v3",
    "style": "realistic_image",
    "count": 2
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_image"></a>Картинка по описанию

> Рисует картинку с нуля по описанию. Recraft хорошо держит текст в кадре.

Значение поля mode: `text_to_image`

На этой странице версия Recraft V3: передайте engine = v3. Без поля engine запустится v4_1.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что нарисовать. Слова, которые должны быть на картинке, пишите в кавычках. С движками V3 и V2 не длиннее 1000 символов.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 2000

#### `engine` (Необязательно)

Движок, от него зависит цена. V4.1: лучший баланс. V4.1 Pro: максимум качества, крупнее (квадрат 2048 на 2048 против 1024 на 1024) и заметно дороже. V3: умеет готовые стили. V2: самый дешёвый.

- Тип: Строка
- Допустимые значения: `v3`
- По умолчанию: `"v4_1"`

#### `style` (Необязательно)

Готовый стиль: фотореализм или иллюстрация. Есть только у V3 и V2, у V4.1 манеру задают словами в описании.

- Тип: Строка
- Допустимые значения: `none` (Без стиля), `realistic_image` (Фотореализм), `digital_illustration` (Иллюстрация)
- По умолчанию: `"none"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2`
- По умолчанию: `"1:1"`

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Фотореализм на V3, два варианта

```json
{
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Чашка капучино на мраморном столе, утренний свет из окна",
    "engine": "v3",
    "style": "realistic_image",
    "count": 2
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинки приходят файлами WebP без потери качества, столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="text_to_vector"></a>Вектор по описанию

> Рисует с нуля настоящий вектор SVG: логотипы, иконки, плоские иллюстрации.

Значение поля mode: `text_to_vector`

На этой странице версия Recraft V3: передайте engine = v3. Без поля engine запустится v4_1.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что нарисовать. Слова, которые должны быть на картинке, пишите в кавычках. С движками V3 и V2 не длиннее 1000 символов.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 2000

#### `engine` (Необязательно)

Движок, от него зависит цена. V4.1: лучший баланс. V4.1 Pro: максимум качества, заметно дороже. V3: прошлое поколение. V2: самый дешёвый.

- Тип: Строка
- Допустимые значения: `v3`
- По умолчанию: `"v4_1"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2`
- По умолчанию: `"1:1"`

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Иконка

```json
{
  "model": "recraft",
  "settings": {
    "mode": "text_to_vector",
    "prompt": "Плоская иконка ракеты в два цвета, толстый контур",
    "engine": "v3",
    "aspect_ratio": "1:1"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Результат в SVG: настоящий вектор, его можно увеличивать без потерь и править в редакторе. Файлов столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `document` | svg | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "document",
        "filename": "result.svg",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Recraft V3: возможности и цены](https://api.cyhub.ai/models/recraft-v3)
- Другие версии: [Recraft API](https://api.cyhub.ai/models/recraft/api.md), [Recraft V2 API](https://api.cyhub.ai/models/recraft-v2/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Recraft V2 API

> Картинки Recraft V2 и настоящий вектор SVG по описанию: логотипы, иконки, плоские иллюстрации. Самый дешёвый движок Recraft, с готовыми стилями: фотореализм или иллюстрация. До 6 штук за один запуск.

Разработчик: Recraft
Ключ модели в API: `recraft`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
    "engine": "v2",
    "aspect_ratio": "3:2"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "recraft",
    "settings": {
        "mode": "text_to_image",
        "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
        "engine": "v2",
        "aspect_ratio": "3:2",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
    "engine": "v2",
    "aspect_ratio": "3:2"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
    "engine": "v2",
    "aspect_ratio": "3:2"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_image"></a>Картинка по описанию

> Рисует картинку с нуля по описанию. Recraft хорошо держит текст в кадре.

Значение поля mode: `text_to_image`

На этой странице версия Recraft V2: передайте engine = v2. Без поля engine запустится v4_1.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что нарисовать. Слова, которые должны быть на картинке, пишите в кавычках. С движками V3 и V2 не длиннее 1000 символов.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 2000

#### `engine` (Необязательно)

Движок, от него зависит цена. V4.1: лучший баланс. V4.1 Pro: максимум качества, крупнее (квадрат 2048 на 2048 против 1024 на 1024) и заметно дороже. V3: умеет готовые стили. V2: самый дешёвый.

- Тип: Строка
- Допустимые значения: `v2`
- По умолчанию: `"v4_1"`

#### `style` (Необязательно)

Готовый стиль: фотореализм или иллюстрация. Есть только у V3 и V2, у V4.1 манеру задают словами в описании.

- Тип: Строка
- Допустимые значения: `none` (Без стиля), `realistic_image` (Фотореализм), `digital_illustration` (Иллюстрация)
- По умолчанию: `"none"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2`
- По умолчанию: `"1:1"`

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Вывеска с надписью

```json
{
  "model": "recraft",
  "settings": {
    "mode": "text_to_image",
    "prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
    "engine": "v2",
    "aspect_ratio": "3:2"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Картинки приходят файлами WebP без потери качества, столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | webp | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.webp",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="text_to_vector"></a>Вектор по описанию

> Рисует с нуля настоящий вектор SVG: логотипы, иконки, плоские иллюстрации.

Значение поля mode: `text_to_vector`

На этой странице версия Recraft V2: передайте engine = v2. Без поля engine запустится v4_1.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Что нарисовать. Слова, которые должны быть на картинке, пишите в кавычках. С движками V3 и V2 не длиннее 1000 символов.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 2000

#### `engine` (Необязательно)

Движок, от него зависит цена. V4.1: лучший баланс. V4.1 Pro: максимум качества, заметно дороже. V3: прошлое поколение. V2: самый дешёвый.

- Тип: Строка
- Допустимые значения: `v2`
- По умолчанию: `"v4_1"`

#### `aspect_ratio` (Необязательно)

Пропорции кадра.

- Тип: Строка
- Допустимые значения: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2`
- По умолчанию: `"1:1"`

#### `count` (Необязательно)

Сколько вариантов сделать за раз, от 1 до 6. Каждый оплачивается отдельно.

- Тип: Целое число
- Минимум: 1
- Максимум: 6
- По умолчанию: `1`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Иконка

```json
{
  "model": "recraft",
  "settings": {
    "mode": "text_to_vector",
    "prompt": "Плоская иконка ракеты в два цвета, толстый контур",
    "engine": "v2",
    "aspect_ratio": "1:1"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Обычно готово за время от нескольких секунд до минуты.
- Результат в SVG: настоящий вектор, его можно увеличивать без потерь и править в редакторе. Файлов столько, сколько задано в count.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `document` | svg | от 1 до 6 | Сколько задано в count. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "document",
        "filename": "result.svg",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Recraft V2: возможности и цены](https://api.cyhub.ai/models/recraft-v2)
- Другие версии: [Recraft API](https://api.cyhub.ai/models/recraft/api.md), [Recraft V3 API](https://api.cyhub.ai/models/recraft-v3/api.md)
- Похожие модели: [GPT Image 2.5 API](https://api.cyhub.ai/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/models/seedream-5-pro/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Eleven Music API

> Музыка Eleven Music от ElevenLabs: трек по описанию с вокалом или без, музыка под ваш ролик и разбор готовой записи на дорожки.

Разработчик: ElevenLabs
Ключ модели в API: `elevenlabs_music`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "song",
    "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря",
    "duration": 90,
    "title": "Летний вечер",
    "model": "music_v2_5"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "elevenlabs_music",
    "settings": {
        "mode": "song",
        "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря",
        "duration": 90,
        "title": "Летний вечер",
        "model": "music_v2_5",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "elevenlabs_music",
  "settings": {
    "mode": "song",
    "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря",
    "duration": 90,
    "title": "Летний вечер",
    "model": "music_v2_5"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "song",
    "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря",
    "duration": 90,
    "title": "Летний вечер",
    "model": "music_v2_5"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="song"></a>Трек по описанию

> Трек по текстовому описанию, с вокалом или без. Можно приложить образец звучания.

Значение поля mode: `song`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Какая нужна музыка: жанр, настроение, инструменты, темп. Здесь же описывается голос, и здесь же можно дать свои слова песни с указанием языка.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 4100

#### `model` (Необязательно)

Версия модели: 2.5 новейшая, 2 прежняя. Цена одинаковая.

- Тип: Строка
- Допустимые значения: `music_v2_5` (Версия 2.5)
- По умолчанию: `"music_v2_5"`

#### `vocal` (Необязательно)

С вокалом или без голоса. Без голоса модель не принимает negative_prompt, seed, образец звучания и adherence, кроме high.

- Тип: Строка
- Допустимые значения: `with_vocals` (С вокалом), `instrumental` (Без голоса)
- По умолчанию: `"with_vocals"`

#### `duration` (Необязательно)

Длительность трека в секундах, от 10 до 600. Цена растёт вместе с ней.

- Тип: Целое число
- Минимум: 10
- Максимум: 600
- По умолчанию: `60`

#### `style` (Необязательно)

Готовый стиль из библиотеки ElevenLabs: модель держится его звучания, описание задаёт остальное. none: без стиля.

- Тип: Строка
- Допустимые значения: `none` (Без стиля), `hrgo9qt4ebv9ondvrfby` (Percussive Rhythm), `myxkfft8fgqlknydgc9j` (Cinematic Ambient Atmosphere), `c8gueokxdvc0websp3mh` (Relaxing Ambient), `jhkwafhohc9agcda0cfr` (Whispery Angelic (Female)), `cmogtn8kgmqiog8dhexe` (Deep Hip-Hop Voice (Male)), `p1ywem2msdf5te27nvsq` (18th Century Symphony), `da3djkopsam0aiywt9pr` (Emotional Piano), `xiuhw6zlkhnmecbjoa1m` (Country), `vwseitetkxqcdgsmkp8q` (EDM Dance Pop (Female)), `pqqhd6miiqq1sck8hxpo` ('80s Nu-Disco Revival), `slmgjlsj7you9jtua7rs` (Bass Techno), `ycnbaxci6zvbfumryyjn` (Dark Cinematic), `iurf2sy9ee0sdcpenlxj` (Emo Trap Autotune (Male)), `ibgjl6wsy1m9zi7osp27` (Hard Rock (Male)), `p7uzmv4semqmck6dqlnh` (Hype Hip-Hop), `vs645jaw0kcr5ei0rsjv` (Deep House Groove), `pjrzgdgqqvyyukiukl7m` (High Energy House), `v1hamfp8dn8witowl0ku` (Golden Hour Indie Guitar), `aslj0pdvdods2agammwb` (Indie Dance), `rhesfql7yrkaaboxnxgp` (Angsty Alt Rock (Male)), `ojz144r6sblq1foezx1g` (Melancholic Indie (Male)), `rqjgx0tz2gjqz9bkewmb` (Jazz Hop), `sqwy9yr9rgik4fjq83lq` (Lofi Pulse), `etmjawmxfo7j0rhjoh9b` (Melodic House And Techno), `cba2y9ttpddnmakxzwps` (Metal), `voz6njhbsmhfoxlq4iiz` (Superhero Swell inspired by Stan Lee), `hs1ude6s5b5xecfqkeus` (Brazilian Funk), `kzyrnjd6p1wkctkwcndw` (Commercial Pop), `deg4quj3g28cbyuetrwl` (Power Pop (Male)), `gduoyhnzn5nvb246gg7i` (Upbeat Pop), `hzluexd1oy54d4g2rili` (Y2K RnB Pop (Female)), `suq4dir7rrlyldbl2hzq` (Reggaeton), `zhmmiqfkkv39avzbamxn` ('70s Cambodian Rock), `idlsxb9wbecwwrfdsctg` (Electronic Rock), `fc7ohoxr46pbtqmwpbub` (Gothic Power Rock (Female)), `el6hpw7kwoqvxf6xixct` (Peak Energy), `lh6n3z81aznqz0ohl9pn` (Rock Français), `mgvvvssqtnvoghqnciso` (Emo Trap), `tr9up85ilbll68sx8s7y` (Wooden Slit Drum), `vqipbdqc1msstidmcusy` (Afro House Beats), `isbeh7g7hu3yntwv25af` (Arabic Groove), `dnzdxqdeszfpxwry2pbe` (Baile Beats), `ymhinvkahlf4oath9qfu` (Golden Age Mambo inspired by Celia Cruz), `g6jrtolcvctpxfjtzt0b` (New York Salsa inspired by Celia Cruz), `psgsvdptlafmrwao54vr` (Retro Fanfare inspired by Stan Lee)
- По умолчанию: `"none"`

#### `title` (Необязательно)

Название трека: встанет в подпись и в имя файла. Не задано: название придумает модель.

- Тип: Строка
- Максимум символов: 80

#### `negative_prompt` (Необязательно)

Чего в музыке быть не должно, через запятую: без барабанов, без крика.

- Тип: Строка
- Максимум символов: 500

#### `adherence` (Необязательно)

Насколько строго держаться описания: high почти дословно, low как настроение.

- Тип: Строка
- Допустимые значения: `high` (Строго), `medium` (Средне), `low` (Свободно)
- По умолчанию: `"high"`

#### `seed` (Необязательно)

Зерно повтора: с тем же числом и теми же настройками результат похож, но не обязательно тот же. Не задано: каждый раз новый вариант.

- Тип: Целое число
- Минимум: 0
- Максимум: 2147483647

#### `audio_urls` (Необязательно)

Образец звучания: одна ссылка на запись до 30 секунд. Модель возьмёт от неё инструменты, звучание, темп и настроение, жанр образец не меняет. Оплачивается как генерация такой же длины.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `reference_strength` (Необязательно)

Насколько сильно образец задаёт звучание. Без образца не действует.

- Тип: Строка
- Допустимые значения: `low` (Слабо), `medium` (Средне), `high` (Сильно), `xhigh` (Максимально)
- По умолчанию: `"medium"`

#### `output` (Необязательно)

Формат готового файла: MP3 обычный, MP3 лучшего качества или WAV без потерь. На цену не влияет.

- Тип: Строка
- Допустимые значения: `mp3_44100_192` (MP3, обычный), `mp3_48000_320` (MP3, лучший), `pcm_44100` (WAV без потерь)
- По умолчанию: `"mp3_44100_192"`

#### `lyrics_file` (Необязательно)

Приложить слова песни с таймингом отдельным файлом LRC: для субтитров и караоке.

- Тип: Да/нет
- По умолчанию: `false`

#### `ai_mark` (Необязательно)

Невидимая пометка внутри файла о том, что музыка сделана нейросетью. Звук не меняет, работает только с MP3.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Образец звучания передаётся ссылкой на MP3 или WAV до 50 МБ и до 30 секунд и уходит целиком.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio_urls` | Аудио | mp3, wav | 1 | 50 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Песня по описанию

```json
{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "song",
    "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря",
    "duration": 90,
    "title": "Летний вечер"
  }
}
```

Музыка без голоса

```json
{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "song",
    "prompt": "Энергичная электроника для спортивного ролика, быстрый темп",
    "vocal": "instrumental",
    "duration": 30,
    "output": "pcm_44100"
  }
}
```

Трек по образцу звучания

```json
{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "song",
    "prompt": "Тёплый лоу-фай хип-хоп для учёбы, тихий мужской вокал",
    "audio_urls": [
      "https://example.com/reference.mp3"
    ],
    "reference_strength": "high",
    "duration": 60
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Трек MP3 или WAV. У песни со словами ещё и текст песни, по запросу слова с таймингом файлом LRC.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` или `document` | mp3, wav | 1 | WAV (output = pcm_44100) приходит как document. |
| `document` | lrc | 0 или 1 | Слова с таймингом: при lyrics_file = true, если в песне есть слова. |

`result.texts`: Слова песни, если в ней есть слова.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.lrc",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video"></a>Музыка под видео

> Фоновая музыка под ваш ролик: длина и настроение подбираются по картинке. Музыка здесь всегда без пения.

Значение поля mode: `video`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Какая музыка нужна под ролик: настроение, жанр, инструменты.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1000

#### `model` (Необязательно)

Версия модели: 2.5 новейшая, 2 прежняя. Цена одинаковая.

- Тип: Строка
- Допустимые значения: `music_v2_5` (Версия 2.5)
- По умолчанию: `"music_v2_5"`

#### `video_urls` (Обязательно)

Одна ссылка на ролик. Длина музыки и цена берутся от ролика.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `tags` (Необязательно)

Слова о звучании через запятую, до 10: метал, оркестр, быстрый темп. Про сюжет модель и так видит по ролику.

- Тип: Строка
- Максимум символов: 200

#### `title` (Необязательно)

Название музыки: встанет в подпись и в имена файлов ролика и музыки. Не задано: файлы будут называться music.

- Тип: Строка
- Максимум символов: 80

#### `output` (Необязательно)

Формат готового файла: MP3 или WAV без потерь. MP3 лучшего качества в этом режиме ElevenLabs не отдаёт. На цену не влияет.

- Тип: Строка
- Допустимые значения: `mp3_44100_192` (MP3, обычный), `pcm_44100` (WAV без потерь)
- По умолчанию: `"mp3_44100_192"`

#### `ai_mark` (Необязательно)

Невидимая пометка внутри файла о том, что музыка сделана нейросетью. Звук не меняет, работает только с MP3.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Ролик передаётся ссылкой на MP4 до 200 МБ и до 10 минут и уходит целиком.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4 | 1 | 200 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Музыка под ролик

```json
{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "video",
    "prompt": "Лёгкая вдохновляющая музыка для ролика о путешествии",
    "tags": "акустика, струнные, светлое настроение",
    "video_urls": [
      "https://example.com/trip.mp4"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Ваш ролик с новой музыкой и та же музыка отдельным файлом MP3 или WAV.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 | Ваш ролик с новой музыкой. |
| `audio` или `document` | mp3, wav | 1 | Та же музыка отдельно, WAV приходит как document. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="stems"></a>Разложить на дорожки

> Готовая запись раскладывается на отдельные дорожки: голос, барабаны, бас и остальное.

Значение поля mode: `stems`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `audio_urls` (Обязательно)

Одна ссылка на запись, которую нужно разложить. Цена по её длительности.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `stems` (Необязательно)

Две дорожки: голос и вся остальная музыка. Шесть: голос, барабаны, бас, гитара, клавиши и прочее. Шесть вдвое дороже двух.

- Тип: Строка
- Допустимые значения: `two_stems_v1` (Две дорожки), `six_stems_v1` (Шесть дорожек)
- По умолчанию: `"two_stems_v1"`

#### `output` (Необязательно)

Формат готового файла: MP3 или WAV без потерь. MP3 лучшего качества в этом режиме ElevenLabs не отдаёт. На цену не влияет.

- Тип: Строка
- Допустимые значения: `mp3_44100_192` (MP3, обычный), `pcm_44100` (WAV без потерь)
- По умолчанию: `"mp3_44100_192"`

#### `ai_mark` (Необязательно)

Невидимая пометка внутри файла о том, что музыка сделана нейросетью. Звук не меняет, работает только с MP3.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Запись передаётся ссылкой на MP3 до 50 МБ и до 10 минут и уходит целиком.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio_urls` | Аудио | mp3 | 1 | 50 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Голос отдельно от музыки

```json
{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "stems",
    "audio_urls": [
      "https://example.com/song.mp3"
    ],
    "stems": "two_stems_v1"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- ZIP-архив, в нём каждая дорожка отдельным файлом в выбранном формате.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `document` | zip | 1 | Внутри каждая дорожка отдельным файлом MP3 или WAV. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "document",
        "filename": "result.zip",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Eleven Music: возможности и цены](https://api.cyhub.ai/models/eleven-music)
- Другие версии: [Eleven Music v2 API](https://api.cyhub.ai/models/eleven-music-v2/api.md)
- Похожие модели: [Suno V6 API](https://api.cyhub.ai/models/suno/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Eleven Music v2 API

> Музыка Eleven Music v2 от ElevenLabs: трек по описанию с вокалом или без и фоновая музыка под ваш ролик. Трек до 10 минут, можно приложить образец звучания.

Разработчик: ElevenLabs
Ключ модели в API: `elevenlabs_music`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "song",
    "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря",
    "duration": 90,
    "title": "Летний вечер",
    "model": "music_v2"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "elevenlabs_music",
    "settings": {
        "mode": "song",
        "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря",
        "duration": 90,
        "title": "Летний вечер",
        "model": "music_v2",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "elevenlabs_music",
  "settings": {
    "mode": "song",
    "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря",
    "duration": 90,
    "title": "Летний вечер",
    "model": "music_v2"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "song",
    "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря",
    "duration": 90,
    "title": "Летний вечер",
    "model": "music_v2"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="song"></a>Трек по описанию

> Трек по текстовому описанию, с вокалом или без. Можно приложить образец звучания.

Значение поля mode: `song`

На этой странице версия Eleven Music v2: передайте model = music_v2. Без поля model запустится music_v2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Какая нужна музыка: жанр, настроение, инструменты, темп. Здесь же описывается голос, и здесь же можно дать свои слова песни с указанием языка.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 4100

#### `model` (Необязательно)

Версия модели: 2.5 новейшая, 2 прежняя. Цена одинаковая.

- Тип: Строка
- Допустимые значения: `music_v2` (Версия 2)
- По умолчанию: `"music_v2_5"`

#### `vocal` (Необязательно)

С вокалом или без голоса. Без голоса модель не принимает negative_prompt, seed, образец звучания и adherence, кроме high.

- Тип: Строка
- Допустимые значения: `with_vocals` (С вокалом), `instrumental` (Без голоса)
- По умолчанию: `"with_vocals"`

#### `duration` (Необязательно)

Длительность трека в секундах, от 10 до 600. Цена растёт вместе с ней.

- Тип: Целое число
- Минимум: 10
- Максимум: 600
- По умолчанию: `60`

#### `style` (Необязательно)

Готовый стиль из библиотеки ElevenLabs: модель держится его звучания, описание задаёт остальное. none: без стиля.

- Тип: Строка
- Допустимые значения: `none` (Без стиля), `hrgo9qt4ebv9ondvrfby` (Percussive Rhythm), `myxkfft8fgqlknydgc9j` (Cinematic Ambient Atmosphere), `c8gueokxdvc0websp3mh` (Relaxing Ambient), `jhkwafhohc9agcda0cfr` (Whispery Angelic (Female)), `cmogtn8kgmqiog8dhexe` (Deep Hip-Hop Voice (Male)), `p1ywem2msdf5te27nvsq` (18th Century Symphony), `da3djkopsam0aiywt9pr` (Emotional Piano), `xiuhw6zlkhnmecbjoa1m` (Country), `vwseitetkxqcdgsmkp8q` (EDM Dance Pop (Female)), `pqqhd6miiqq1sck8hxpo` ('80s Nu-Disco Revival), `slmgjlsj7you9jtua7rs` (Bass Techno), `ycnbaxci6zvbfumryyjn` (Dark Cinematic), `iurf2sy9ee0sdcpenlxj` (Emo Trap Autotune (Male)), `ibgjl6wsy1m9zi7osp27` (Hard Rock (Male)), `p7uzmv4semqmck6dqlnh` (Hype Hip-Hop), `vs645jaw0kcr5ei0rsjv` (Deep House Groove), `pjrzgdgqqvyyukiukl7m` (High Energy House), `v1hamfp8dn8witowl0ku` (Golden Hour Indie Guitar), `aslj0pdvdods2agammwb` (Indie Dance), `rhesfql7yrkaaboxnxgp` (Angsty Alt Rock (Male)), `ojz144r6sblq1foezx1g` (Melancholic Indie (Male)), `rqjgx0tz2gjqz9bkewmb` (Jazz Hop), `sqwy9yr9rgik4fjq83lq` (Lofi Pulse), `etmjawmxfo7j0rhjoh9b` (Melodic House And Techno), `cba2y9ttpddnmakxzwps` (Metal), `voz6njhbsmhfoxlq4iiz` (Superhero Swell inspired by Stan Lee), `hs1ude6s5b5xecfqkeus` (Brazilian Funk), `kzyrnjd6p1wkctkwcndw` (Commercial Pop), `deg4quj3g28cbyuetrwl` (Power Pop (Male)), `gduoyhnzn5nvb246gg7i` (Upbeat Pop), `hzluexd1oy54d4g2rili` (Y2K RnB Pop (Female)), `suq4dir7rrlyldbl2hzq` (Reggaeton), `zhmmiqfkkv39avzbamxn` ('70s Cambodian Rock), `idlsxb9wbecwwrfdsctg` (Electronic Rock), `fc7ohoxr46pbtqmwpbub` (Gothic Power Rock (Female)), `el6hpw7kwoqvxf6xixct` (Peak Energy), `lh6n3z81aznqz0ohl9pn` (Rock Français), `mgvvvssqtnvoghqnciso` (Emo Trap), `tr9up85ilbll68sx8s7y` (Wooden Slit Drum), `vqipbdqc1msstidmcusy` (Afro House Beats), `isbeh7g7hu3yntwv25af` (Arabic Groove), `dnzdxqdeszfpxwry2pbe` (Baile Beats), `ymhinvkahlf4oath9qfu` (Golden Age Mambo inspired by Celia Cruz), `g6jrtolcvctpxfjtzt0b` (New York Salsa inspired by Celia Cruz), `psgsvdptlafmrwao54vr` (Retro Fanfare inspired by Stan Lee)
- По умолчанию: `"none"`

#### `title` (Необязательно)

Название трека: встанет в подпись и в имя файла. Не задано: название придумает модель.

- Тип: Строка
- Максимум символов: 80

#### `negative_prompt` (Необязательно)

Чего в музыке быть не должно, через запятую: без барабанов, без крика.

- Тип: Строка
- Максимум символов: 500

#### `adherence` (Необязательно)

Насколько строго держаться описания: high почти дословно, low как настроение.

- Тип: Строка
- Допустимые значения: `high` (Строго), `medium` (Средне), `low` (Свободно)
- По умолчанию: `"high"`

#### `seed` (Необязательно)

Зерно повтора: с тем же числом и теми же настройками результат похож, но не обязательно тот же. Не задано: каждый раз новый вариант.

- Тип: Целое число
- Минимум: 0
- Максимум: 2147483647

#### `audio_urls` (Необязательно)

Образец звучания: одна ссылка на запись до 30 секунд. Модель возьмёт от неё инструменты, звучание, темп и настроение, жанр образец не меняет. Оплачивается как генерация такой же длины.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `reference_strength` (Необязательно)

Насколько сильно образец задаёт звучание. Без образца не действует.

- Тип: Строка
- Допустимые значения: `low` (Слабо), `medium` (Средне), `high` (Сильно), `xhigh` (Максимально)
- По умолчанию: `"medium"`

#### `output` (Необязательно)

Формат готового файла: MP3 обычный, MP3 лучшего качества или WAV без потерь. На цену не влияет.

- Тип: Строка
- Допустимые значения: `mp3_44100_192` (MP3, обычный), `mp3_48000_320` (MP3, лучший), `pcm_44100` (WAV без потерь)
- По умолчанию: `"mp3_44100_192"`

#### `lyrics_file` (Необязательно)

Приложить слова песни с таймингом отдельным файлом LRC: для субтитров и караоке.

- Тип: Да/нет
- По умолчанию: `false`

#### `ai_mark` (Необязательно)

Невидимая пометка внутри файла о том, что музыка сделана нейросетью. Звук не меняет, работает только с MP3.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Образец звучания передаётся ссылкой на MP3 или WAV до 50 МБ и до 30 секунд и уходит целиком.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `audio_urls` | Аудио | mp3, wav | 1 | 50 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Песня по описанию

```json
{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "song",
    "prompt": "Спокойная акустическая гитара и мягкие барабаны, женский вокал на русском о летнем вечере у моря",
    "duration": 90,
    "title": "Летний вечер",
    "model": "music_v2"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Трек MP3 или WAV. У песни со словами ещё и текст песни, по запросу слова с таймингом файлом LRC.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `audio` или `document` | mp3, wav | 1 | WAV (output = pcm_44100) приходит как document. |
| `document` | lrc | 0 или 1 | Слова с таймингом: при lyrics_file = true, если в песне есть слова. |

`result.texts`: Слова песни, если в ней есть слова.

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [
      "Текст результата, например слова песни"
    ],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.lrc",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="video"></a>Музыка под видео

> Фоновая музыка под ваш ролик: длина и настроение подбираются по картинке. Музыка здесь всегда без пения.

Значение поля mode: `video`

На этой странице версия Eleven Music v2: передайте model = music_v2. Без поля model запустится music_v2_5.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `prompt` (Обязательно)

Какая музыка нужна под ролик: настроение, жанр, инструменты.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1000

#### `model` (Необязательно)

Версия модели: 2.5 новейшая, 2 прежняя. Цена одинаковая.

- Тип: Строка
- Допустимые значения: `music_v2` (Версия 2)
- По умолчанию: `"music_v2_5"`

#### `video_urls` (Обязательно)

Одна ссылка на ролик. Длина музыки и цена берутся от ролика.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `tags` (Необязательно)

Слова о звучании через запятую, до 10: метал, оркестр, быстрый темп. Про сюжет модель и так видит по ролику.

- Тип: Строка
- Максимум символов: 200

#### `title` (Необязательно)

Название музыки: встанет в подпись и в имена файлов ролика и музыки. Не задано: файлы будут называться music.

- Тип: Строка
- Максимум символов: 80

#### `output` (Необязательно)

Формат готового файла: MP3 или WAV без потерь. MP3 лучшего качества в этом режиме ElevenLabs не отдаёт. На цену не влияет.

- Тип: Строка
- Допустимые значения: `mp3_44100_192` (MP3, обычный), `pcm_44100` (WAV без потерь)
- По умолчанию: `"mp3_44100_192"`

#### `ai_mark` (Необязательно)

Невидимая пометка внутри файла о том, что музыка сделана нейросетью. Звук не меняет, работает только с MP3.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

> Эти настройки API задаёт сам, передавать их не нужно: `files_as_is` = `true`

### Входные данные

- Ролик передаётся ссылкой на MP4 до 200 МБ и до 10 минут и уходит целиком.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `video_urls` | Видео | mp4 | 1 | 200 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Музыка под ролик

```json
{
  "model": "elevenlabs_music",
  "settings": {
    "mode": "video",
    "prompt": "Лёгкая вдохновляющая музыка для ролика о путешествии",
    "tags": "акустика, струнные, светлое настроение",
    "video_urls": [
      "https://example.com/trip.mp4"
    ],
    "model": "music_v2"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Ваш ролик с новой музыкой и та же музыка отдельным файлом MP3 или WAV.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `video` | mp4 | 1 | Ваш ролик с новой музыкой. |
| `audio` или `document` | mp3, wav | 1 | Та же музыка отдельно, WAV приходит как document. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "audio",
        "filename": "audio.mp3",
        "size": 4194304,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Eleven Music v2: возможности и цены](https://api.cyhub.ai/models/eleven-music-v2)
- Другие версии: [Eleven Music API](https://api.cyhub.ai/models/eleven-music/api.md)
- Похожие модели: [Suno V6 API](https://api.cyhub.ai/models/suno/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Tripo 3D API

> 3D-модели Tripo по описанию, по одному фото или по нескольким ракурсам объекта.

Ключ модели в API: `tripo3d`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "tripo3d",
    "settings": {
        "task_type": "text_to_model",
        "prompt": "Деревянный сундук с железными уголками",
        "texture_quality": "standard",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_model"></a>По описанию

> Модель по текстовому описанию, без картинок.

Значение поля task_type: `text_to_model`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model_version` (Необязательно)

Версия модели. v3.1 и v3.0 самые детальные и со всеми настройками. У v2.5 и P1 часть настроек недоступна, P1 для низкополигональных моделей.

- Тип: Строка
- Допустимые значения: `v3.1-20260211` (v3.1), `P1-20260311` (P1 (низкополигональная))
- По умолчанию: `"v3.1-20260211"`

#### `texture` (Необязательно)

Модель с текстурой. Без неё только форма.

- Тип: Да/нет
- По умолчанию: `true`

#### `pbr` (Необязательно)

Реалистичные материалы с отражениями и бликами. Включает и текстуру.

- Тип: Да/нет
- По умолчанию: `true`

#### `texture_quality` (Необязательно)

Качество текстуры. HD детальнее, цена выше. HD есть только у версий v3.1, v3.0 и P1.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (HD (детализированное))
- По умолчанию: `"standard"`

#### `geometry_quality` (Необязательно)

Качество формы. Ultra детальнее, дольше и дороже, только у v3.1 и v3.0.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (Ultra (максимальная детализация))
- По умолчанию: `"standard"`

#### `face_limit` (Необязательно)

Сколько полигонов в модели. Не задано: подбирается само. Допустимый предел зависит от версии и настроек: у P1 от 50 до 20 000, у smart low-poly от 500 до 20 000.

- Тип: Целое число
- Минимум: 48
- Максимум: 2000000

#### `auto_size` (Необязательно)

Привести модель к реальным размерам в метрах. Есть только у версий v3.1, v3.0 и P1.

- Тип: Да/нет
- По умолчанию: `false`

#### `orientation` (Необязательно)

Поворот готовой модели: обычный или как на исходном фото. Действует только у модели по фото или по ракурсам и только с текстурой.

- Тип: Строка
- Допустимые значения: `default` (По умолчанию), `align_image` (Выровнять по изображению)
- По умолчанию: `"default"`

#### `quad` (Необязательно)

Модель из четырёхугольников, удобнее для правки и анимации. Файл будет в FBX. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `smart_low_poly` (Необязательно)

Низкополигональная модель с аккуратной сеткой. Лучше для простых объектов. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `generate_parts` (Необязательно)

Модель из отдельных частей. Не сочетается с текстурой, PBR, четырёхугольниками и smart low-poly. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `prompt` (Обязательно)

Какой объект нужен. Можно на любом языке.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1024

#### `negative_prompt` (Необязательно)

Чего в модели быть не должно.

- Тип: Строка
- Максимум символов: 255

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Фото передаются ссылками на JPEG или PNG до 20 МБ.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Модель по описанию

```json
{
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Файл 3D-модели GLB (с четырёхугольниками FBX) и картинка-превью.
- Генерация занимает несколько минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg, webp | 0 или 1 | Картинка-превью модели, если Tripo её прислал. |
| `document` | glb, fbx | 1 | Файл 3D-модели: FBX при quad = true, иначе GLB. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.glb",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_model"></a>По фото

> Модель по одному фото объекта. Лучше всего фото с чистым фоном, объект целиком.

Значение поля task_type: `image_to_model`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model_version` (Необязательно)

Версия модели. v3.1 и v3.0 самые детальные и со всеми настройками. У v2.5 и P1 часть настроек недоступна, P1 для низкополигональных моделей.

- Тип: Строка
- Допустимые значения: `v3.1-20260211` (v3.1), `P1-20260311` (P1 (низкополигональная))
- По умолчанию: `"v3.1-20260211"`

#### `texture` (Необязательно)

Модель с текстурой. Без неё только форма.

- Тип: Да/нет
- По умолчанию: `true`

#### `pbr` (Необязательно)

Реалистичные материалы с отражениями и бликами. Включает и текстуру.

- Тип: Да/нет
- По умолчанию: `true`

#### `texture_quality` (Необязательно)

Качество текстуры. HD детальнее, цена выше. HD есть только у версий v3.1, v3.0 и P1.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (HD (детализированное))
- По умолчанию: `"standard"`

#### `geometry_quality` (Необязательно)

Качество формы. Ultra детальнее, дольше и дороже, только у v3.1 и v3.0.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (Ultra (максимальная детализация))
- По умолчанию: `"standard"`

#### `face_limit` (Необязательно)

Сколько полигонов в модели. Не задано: подбирается само. Допустимый предел зависит от версии и настроек: у P1 от 50 до 20 000, у smart low-poly от 500 до 20 000.

- Тип: Целое число
- Минимум: 48
- Максимум: 2000000

#### `auto_size` (Необязательно)

Привести модель к реальным размерам в метрах. Есть только у версий v3.1, v3.0 и P1.

- Тип: Да/нет
- По умолчанию: `false`

#### `orientation` (Необязательно)

Поворот готовой модели: обычный или как на исходном фото. Действует только у модели по фото или по ракурсам и только с текстурой.

- Тип: Строка
- Допустимые значения: `default` (По умолчанию), `align_image` (Выровнять по изображению)
- По умолчанию: `"default"`

#### `quad` (Необязательно)

Модель из четырёхугольников, удобнее для правки и анимации. Файл будет в FBX. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `smart_low_poly` (Необязательно)

Низкополигональная модель с аккуратной сеткой. Лучше для простых объектов. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `generate_parts` (Необязательно)

Модель из отдельных частей. Не сочетается с текстурой, PBR, четырёхугольниками и smart low-poly. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `image_url` (Обязательно)

Одна ссылка на фото объекта.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `texture_alignment` (Необязательно)

Как накладывать текстуру: точнее по фото или точнее по форме модели.

- Тип: Строка
- Допустимые значения: `original_image` (По изображению), `geometry` (По геометрии)
- По умолчанию: `"original_image"`

#### `enable_image_autofix` (Необязательно)

Сначала подправить фото для лучшего результата.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Фото передаются ссылками на JPEG или PNG до 20 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Модель по фото

```json
{
  "model": "tripo3d",
  "settings": {
    "task_type": "image_to_model",
    "image_url": [
      "https://example.com/chair.png"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Файл 3D-модели GLB (с четырёхугольниками FBX) и картинка-превью.
- Генерация занимает несколько минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg, webp | 0 или 1 | Картинка-превью модели, если Tripo её прислал. |
| `document` | glb, fbx | 1 | Файл 3D-модели: FBX при quad = true, иначе GLB. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.glb",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="multiview_to_model"></a>По ракурсам

> Модель по нескольким фото одного объекта с разных сторон: самая точная форма. Нужно фото спереди и хотя бы ещё одно, каждое в поле своей стороны. Бока считаются от самого объекта: в left_url фото, где он смотрит влево. Если перепутать бока, у модели может получиться второй перед вместо спины.

Значение поля task_type: `multiview_to_model`

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model_version` (Необязательно)

Версия модели. v3.1 и v3.0 самые детальные и со всеми настройками. У v2.5 и P1 часть настроек недоступна, P1 для низкополигональных моделей.

- Тип: Строка
- Допустимые значения: `v3.1-20260211` (v3.1), `P1-20260311` (P1 (низкополигональная))
- По умолчанию: `"v3.1-20260211"`

#### `texture` (Необязательно)

Модель с текстурой. Без неё только форма.

- Тип: Да/нет
- По умолчанию: `true`

#### `pbr` (Необязательно)

Реалистичные материалы с отражениями и бликами. Включает и текстуру.

- Тип: Да/нет
- По умолчанию: `true`

#### `texture_quality` (Необязательно)

Качество текстуры. HD детальнее, цена выше. HD есть только у версий v3.1, v3.0 и P1.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (HD (детализированное))
- По умолчанию: `"standard"`

#### `geometry_quality` (Необязательно)

Качество формы. Ultra детальнее, дольше и дороже, только у v3.1 и v3.0.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (Ultra (максимальная детализация))
- По умолчанию: `"standard"`

#### `face_limit` (Необязательно)

Сколько полигонов в модели. Не задано: подбирается само. Допустимый предел зависит от версии и настроек: у P1 от 50 до 20 000, у smart low-poly от 500 до 20 000.

- Тип: Целое число
- Минимум: 48
- Максимум: 2000000

#### `auto_size` (Необязательно)

Привести модель к реальным размерам в метрах. Есть только у версий v3.1, v3.0 и P1.

- Тип: Да/нет
- По умолчанию: `false`

#### `orientation` (Необязательно)

Поворот готовой модели: обычный или как на исходном фото. Действует только у модели по фото или по ракурсам и только с текстурой.

- Тип: Строка
- Допустимые значения: `default` (По умолчанию), `align_image` (Выровнять по изображению)
- По умолчанию: `"default"`

#### `quad` (Необязательно)

Модель из четырёхугольников, удобнее для правки и анимации. Файл будет в FBX. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `smart_low_poly` (Необязательно)

Низкополигональная модель с аккуратной сеткой. Лучше для простых объектов. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `generate_parts` (Необязательно)

Модель из отдельных частей. Не сочетается с текстурой, PBR, четырёхугольниками и smart low-poly. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `front_url` (Обязательно)

Фото объекта спереди. Обязательно.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `left_url` (Необязательно)

Фото левого бока объекта: на фото объект смотрит влево, у персонажа к камере его левая рука.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `back_url` (Необязательно)

Фото объекта сзади.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `right_url` (Необязательно)

Фото правого бока объекта: на фото объект смотрит вправо, у персонажа к камере его правая рука.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `texture_alignment` (Необязательно)

Как накладывать текстуру: точнее по фото или точнее по форме модели.

- Тип: Строка
- Допустимые значения: `original_image` (По изображению), `geometry` (По геометрии)
- По умолчанию: `"original_image"`

#### `enable_image_autofix` (Необязательно)

Сначала подправить фото для лучшего результата.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Фото передаются ссылками на JPEG или PNG до 20 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `front_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |
| `left_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |
| `back_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |
| `right_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Модель по фото спереди и сзади

```json
{
  "model": "tripo3d",
  "settings": {
    "task_type": "multiview_to_model",
    "front_url": [
      "https://example.com/front.png"
    ],
    "back_url": [
      "https://example.com/back.png"
    ]
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Файл 3D-модели GLB (с четырёхугольниками FBX) и картинка-превью.
- Генерация занимает несколько минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg, webp | 0 или 1 | Картинка-превью модели, если Tripo её прислал. |
| `document` | glb, fbx | 1 | Файл 3D-модели: FBX при quad = true, иначе GLB. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.glb",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Tripo 3D: возможности и цены](https://api.cyhub.ai/models/tripo-3d)
- Другие версии: [Tripo 3.0 API](https://api.cyhub.ai/models/tripo-3-0/api.md), [Tripo 2.5 API](https://api.cyhub.ai/models/tripo-2-5/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Tripo 3.0 API

> 3D-модели Tripo 3.0 по описанию, по одному фото или по нескольким ракурсам объекта. Максимальная детализация и все настройки модели.

Ключ модели в API: `tripo3d`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard",
    "model_version": "v3.0-20250812"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "tripo3d",
    "settings": {
        "task_type": "text_to_model",
        "prompt": "Деревянный сундук с железными уголками",
        "texture_quality": "standard",
        "model_version": "v3.0-20250812",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard",
    "model_version": "v3.0-20250812"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard",
    "model_version": "v3.0-20250812"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_model"></a>По описанию

> Модель по текстовому описанию, без картинок.

Значение поля task_type: `text_to_model`

На этой странице версия Tripo 3.0: передайте model_version = v3.0-20250812. Без поля model_version запустится v3.1-20260211.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model_version` (Необязательно)

Версия модели. v3.1 и v3.0 самые детальные и со всеми настройками. У v2.5 и P1 часть настроек недоступна, P1 для низкополигональных моделей.

- Тип: Строка
- Допустимые значения: `v3.0-20250812` (v3.0)
- По умолчанию: `"v3.1-20260211"`

#### `texture` (Необязательно)

Модель с текстурой. Без неё только форма.

- Тип: Да/нет
- По умолчанию: `true`

#### `pbr` (Необязательно)

Реалистичные материалы с отражениями и бликами. Включает и текстуру.

- Тип: Да/нет
- По умолчанию: `true`

#### `texture_quality` (Необязательно)

Качество текстуры. HD детальнее, цена выше. HD есть только у версий v3.1, v3.0 и P1.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (HD (детализированное))
- По умолчанию: `"standard"`

#### `geometry_quality` (Необязательно)

Качество формы. Ultra детальнее, дольше и дороже, только у v3.1 и v3.0.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (Ultra (максимальная детализация))
- По умолчанию: `"standard"`

#### `face_limit` (Необязательно)

Сколько полигонов в модели. Не задано: подбирается само. Допустимый предел зависит от версии и настроек: у P1 от 50 до 20 000, у smart low-poly от 500 до 20 000.

- Тип: Целое число
- Минимум: 48
- Максимум: 2000000

#### `auto_size` (Необязательно)

Привести модель к реальным размерам в метрах. Есть только у версий v3.1, v3.0 и P1.

- Тип: Да/нет
- По умолчанию: `false`

#### `orientation` (Необязательно)

Поворот готовой модели: обычный или как на исходном фото. Действует только у модели по фото или по ракурсам и только с текстурой.

- Тип: Строка
- Допустимые значения: `default` (По умолчанию), `align_image` (Выровнять по изображению)
- По умолчанию: `"default"`

#### `quad` (Необязательно)

Модель из четырёхугольников, удобнее для правки и анимации. Файл будет в FBX. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `smart_low_poly` (Необязательно)

Низкополигональная модель с аккуратной сеткой. Лучше для простых объектов. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `generate_parts` (Необязательно)

Модель из отдельных частей. Не сочетается с текстурой, PBR, четырёхугольниками и smart low-poly. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `prompt` (Обязательно)

Какой объект нужен. Можно на любом языке.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1024

#### `negative_prompt` (Необязательно)

Чего в модели быть не должно.

- Тип: Строка
- Максимум символов: 255

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Фото передаются ссылками на JPEG или PNG до 20 МБ.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Модель по описанию

```json
{
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard",
    "model_version": "v3.0-20250812"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Файл 3D-модели GLB (с четырёхугольниками FBX) и картинка-превью.
- Генерация занимает несколько минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg, webp | 0 или 1 | Картинка-превью модели, если Tripo её прислал. |
| `document` | glb, fbx | 1 | Файл 3D-модели: FBX при quad = true, иначе GLB. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.glb",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_model"></a>По фото

> Модель по одному фото объекта. Лучше всего фото с чистым фоном, объект целиком.

Значение поля task_type: `image_to_model`

На этой странице версия Tripo 3.0: передайте model_version = v3.0-20250812. Без поля model_version запустится v3.1-20260211.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model_version` (Необязательно)

Версия модели. v3.1 и v3.0 самые детальные и со всеми настройками. У v2.5 и P1 часть настроек недоступна, P1 для низкополигональных моделей.

- Тип: Строка
- Допустимые значения: `v3.0-20250812` (v3.0)
- По умолчанию: `"v3.1-20260211"`

#### `texture` (Необязательно)

Модель с текстурой. Без неё только форма.

- Тип: Да/нет
- По умолчанию: `true`

#### `pbr` (Необязательно)

Реалистичные материалы с отражениями и бликами. Включает и текстуру.

- Тип: Да/нет
- По умолчанию: `true`

#### `texture_quality` (Необязательно)

Качество текстуры. HD детальнее, цена выше. HD есть только у версий v3.1, v3.0 и P1.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (HD (детализированное))
- По умолчанию: `"standard"`

#### `geometry_quality` (Необязательно)

Качество формы. Ultra детальнее, дольше и дороже, только у v3.1 и v3.0.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (Ultra (максимальная детализация))
- По умолчанию: `"standard"`

#### `face_limit` (Необязательно)

Сколько полигонов в модели. Не задано: подбирается само. Допустимый предел зависит от версии и настроек: у P1 от 50 до 20 000, у smart low-poly от 500 до 20 000.

- Тип: Целое число
- Минимум: 48
- Максимум: 2000000

#### `auto_size` (Необязательно)

Привести модель к реальным размерам в метрах. Есть только у версий v3.1, v3.0 и P1.

- Тип: Да/нет
- По умолчанию: `false`

#### `orientation` (Необязательно)

Поворот готовой модели: обычный или как на исходном фото. Действует только у модели по фото или по ракурсам и только с текстурой.

- Тип: Строка
- Допустимые значения: `default` (По умолчанию), `align_image` (Выровнять по изображению)
- По умолчанию: `"default"`

#### `quad` (Необязательно)

Модель из четырёхугольников, удобнее для правки и анимации. Файл будет в FBX. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `smart_low_poly` (Необязательно)

Низкополигональная модель с аккуратной сеткой. Лучше для простых объектов. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `generate_parts` (Необязательно)

Модель из отдельных частей. Не сочетается с текстурой, PBR, четырёхугольниками и smart low-poly. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `image_url` (Обязательно)

Одна ссылка на фото объекта.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `texture_alignment` (Необязательно)

Как накладывать текстуру: точнее по фото или точнее по форме модели.

- Тип: Строка
- Допустимые значения: `original_image` (По изображению), `geometry` (По геометрии)
- По умолчанию: `"original_image"`

#### `enable_image_autofix` (Необязательно)

Сначала подправить фото для лучшего результата.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Фото передаются ссылками на JPEG или PNG до 20 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Модель по фото

```json
{
  "model": "tripo3d",
  "settings": {
    "task_type": "image_to_model",
    "image_url": [
      "https://example.com/chair.png"
    ],
    "model_version": "v3.0-20250812"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Файл 3D-модели GLB (с четырёхугольниками FBX) и картинка-превью.
- Генерация занимает несколько минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg, webp | 0 или 1 | Картинка-превью модели, если Tripo её прислал. |
| `document` | glb, fbx | 1 | Файл 3D-модели: FBX при quad = true, иначе GLB. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.glb",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="multiview_to_model"></a>По ракурсам

> Модель по нескольким фото одного объекта с разных сторон: самая точная форма. Нужно фото спереди и хотя бы ещё одно, каждое в поле своей стороны. Бока считаются от самого объекта: в left_url фото, где он смотрит влево. Если перепутать бока, у модели может получиться второй перед вместо спины.

Значение поля task_type: `multiview_to_model`

На этой странице версия Tripo 3.0: передайте model_version = v3.0-20250812. Без поля model_version запустится v3.1-20260211.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model_version` (Необязательно)

Версия модели. v3.1 и v3.0 самые детальные и со всеми настройками. У v2.5 и P1 часть настроек недоступна, P1 для низкополигональных моделей.

- Тип: Строка
- Допустимые значения: `v3.0-20250812` (v3.0)
- По умолчанию: `"v3.1-20260211"`

#### `texture` (Необязательно)

Модель с текстурой. Без неё только форма.

- Тип: Да/нет
- По умолчанию: `true`

#### `pbr` (Необязательно)

Реалистичные материалы с отражениями и бликами. Включает и текстуру.

- Тип: Да/нет
- По умолчанию: `true`

#### `texture_quality` (Необязательно)

Качество текстуры. HD детальнее, цена выше. HD есть только у версий v3.1, v3.0 и P1.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (HD (детализированное))
- По умолчанию: `"standard"`

#### `geometry_quality` (Необязательно)

Качество формы. Ultra детальнее, дольше и дороже, только у v3.1 и v3.0.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (Ultra (максимальная детализация))
- По умолчанию: `"standard"`

#### `face_limit` (Необязательно)

Сколько полигонов в модели. Не задано: подбирается само. Допустимый предел зависит от версии и настроек: у P1 от 50 до 20 000, у smart low-poly от 500 до 20 000.

- Тип: Целое число
- Минимум: 48
- Максимум: 2000000

#### `auto_size` (Необязательно)

Привести модель к реальным размерам в метрах. Есть только у версий v3.1, v3.0 и P1.

- Тип: Да/нет
- По умолчанию: `false`

#### `orientation` (Необязательно)

Поворот готовой модели: обычный или как на исходном фото. Действует только у модели по фото или по ракурсам и только с текстурой.

- Тип: Строка
- Допустимые значения: `default` (По умолчанию), `align_image` (Выровнять по изображению)
- По умолчанию: `"default"`

#### `quad` (Необязательно)

Модель из четырёхугольников, удобнее для правки и анимации. Файл будет в FBX. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `smart_low_poly` (Необязательно)

Низкополигональная модель с аккуратной сеткой. Лучше для простых объектов. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `generate_parts` (Необязательно)

Модель из отдельных частей. Не сочетается с текстурой, PBR, четырёхугольниками и smart low-poly. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `front_url` (Обязательно)

Фото объекта спереди. Обязательно.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `left_url` (Необязательно)

Фото левого бока объекта: на фото объект смотрит влево, у персонажа к камере его левая рука.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `back_url` (Необязательно)

Фото объекта сзади.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `right_url` (Необязательно)

Фото правого бока объекта: на фото объект смотрит вправо, у персонажа к камере его правая рука.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `texture_alignment` (Необязательно)

Как накладывать текстуру: точнее по фото или точнее по форме модели.

- Тип: Строка
- Допустимые значения: `original_image` (По изображению), `geometry` (По геометрии)
- По умолчанию: `"original_image"`

#### `enable_image_autofix` (Необязательно)

Сначала подправить фото для лучшего результата.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Фото передаются ссылками на JPEG или PNG до 20 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `front_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |
| `left_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |
| `back_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |
| `right_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Модель по фото спереди и сзади

```json
{
  "model": "tripo3d",
  "settings": {
    "task_type": "multiview_to_model",
    "front_url": [
      "https://example.com/front.png"
    ],
    "back_url": [
      "https://example.com/back.png"
    ],
    "model_version": "v3.0-20250812"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Файл 3D-модели GLB (с четырёхугольниками FBX) и картинка-превью.
- Генерация занимает несколько минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg, webp | 0 или 1 | Картинка-превью модели, если Tripo её прислал. |
| `document` | glb, fbx | 1 | Файл 3D-модели: FBX при quad = true, иначе GLB. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.glb",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Tripo 3.0: возможности и цены](https://api.cyhub.ai/models/tripo-3-0)
- Другие версии: [Tripo 3D API](https://api.cyhub.ai/models/tripo-3d/api.md), [Tripo 2.5 API](https://api.cyhub.ai/models/tripo-2-5/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)

---

# Tripo 2.5 API

> 3D-модели Tripo 2.5 по описанию, по одному фото или по нескольким ракурсам объекта. Прежняя стабильная версия, часть настроек у неё недоступна.

Ключ модели в API: `tripo3d`

## Подключение в три шага

1. [Получите ключ](https://api.cyhub.ai/docs/connection.md?lang=ru): Ключ создаётся в кабинете после подтверждения почты. Один ключ открывает все модели.
2. [Узнайте цену](https://api.cyhub.ai/docs/generations.md?lang=ru): POST /v1/price считает стоимость запуска заранее, деньги при этом не списываются.
3. [Запустите задачу и заберите результат](https://api.cyhub.ai/docs/tasks.md?lang=ru): POST /v1/tasks ставит задачу, GET /v1/tasks/{id} показывает её статус и файлы.

## Готовый код

Замените YOUR_API_KEY своим ключом. Код ставит задачу и ждёт результата. В cURL второй запрос повторяйте, подставив вместо TASK_ID поле id из ответа первого, пока status не станет succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard",
    "model_version": "v2.5-20250123"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

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

body = {
    "model": "tripo3d",
    "settings": {
        "task_type": "text_to_model",
        "prompt": "Деревянный сундук с железными уголками",
        "texture_quality": "standard",
        "model_version": "v2.5-20250123",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard",
    "model_version": "v2.5-20250123"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Получить ключ](https://cyhub.ai/cabinet/keys)

## Цена до запуска

Отправьте те же настройки в POST /v1/price: ответ покажет цену запуска, деньги при этом не списываются.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard",
    "model_version": "v2.5-20250123"
  }
}'
```

- amount_minor: цена запуска в копейках (для рублей)
- currency: валюта кошелька
- available_minor: сколько сейчас доступно на балансе для новых задач

## <a id="text_to_model"></a>По описанию

> Модель по текстовому описанию, без картинок.

Значение поля task_type: `text_to_model`

На этой странице версия Tripo 2.5: передайте model_version = v2.5-20250123. Без поля model_version запустится v3.1-20260211.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model_version` (Необязательно)

Версия модели. v3.1 и v3.0 самые детальные и со всеми настройками. У v2.5 и P1 часть настроек недоступна, P1 для низкополигональных моделей.

- Тип: Строка
- Допустимые значения: `v2.5-20250123` (v2.5)
- По умолчанию: `"v3.1-20260211"`

#### `texture` (Необязательно)

Модель с текстурой. Без неё только форма.

- Тип: Да/нет
- По умолчанию: `true`

#### `pbr` (Необязательно)

Реалистичные материалы с отражениями и бликами. Включает и текстуру.

- Тип: Да/нет
- По умолчанию: `true`

#### `texture_quality` (Необязательно)

Качество текстуры. HD детальнее, цена выше. HD есть только у версий v3.1, v3.0 и P1.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (HD (детализированное))
- По умолчанию: `"standard"`

#### `geometry_quality` (Необязательно)

Качество формы. Ultra детальнее, дольше и дороже, только у v3.1 и v3.0.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (Ultra (максимальная детализация))
- По умолчанию: `"standard"`

#### `face_limit` (Необязательно)

Сколько полигонов в модели. Не задано: подбирается само. Допустимый предел зависит от версии и настроек: у P1 от 50 до 20 000, у smart low-poly от 500 до 20 000.

- Тип: Целое число
- Минимум: 48
- Максимум: 2000000

#### `auto_size` (Необязательно)

Привести модель к реальным размерам в метрах. Есть только у версий v3.1, v3.0 и P1.

- Тип: Да/нет
- По умолчанию: `false`

#### `orientation` (Необязательно)

Поворот готовой модели: обычный или как на исходном фото. Действует только у модели по фото или по ракурсам и только с текстурой.

- Тип: Строка
- Допустимые значения: `default` (По умолчанию), `align_image` (Выровнять по изображению)
- По умолчанию: `"default"`

#### `quad` (Необязательно)

Модель из четырёхугольников, удобнее для правки и анимации. Файл будет в FBX. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `smart_low_poly` (Необязательно)

Низкополигональная модель с аккуратной сеткой. Лучше для простых объектов. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `generate_parts` (Необязательно)

Модель из отдельных частей. Не сочетается с текстурой, PBR, четырёхугольниками и smart low-poly. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `prompt` (Обязательно)

Какой объект нужен. Можно на любом языке.

- Тип: Строка
- Минимум символов: 1
- Максимум символов: 1024

#### `negative_prompt` (Необязательно)

Чего в модели быть не должно.

- Тип: Строка
- Максимум символов: 255

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Фото передаются ссылками на JPEG или PNG до 20 МБ.

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Модель по описанию

```json
{
  "model": "tripo3d",
  "settings": {
    "task_type": "text_to_model",
    "prompt": "Деревянный сундук с железными уголками",
    "texture_quality": "standard",
    "model_version": "v2.5-20250123"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Файл 3D-модели GLB (с четырёхугольниками FBX) и картинка-превью.
- Генерация занимает несколько минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg, webp | 0 или 1 | Картинка-превью модели, если Tripo её прислал. |
| `document` | glb, fbx | 1 | Файл 3D-модели: FBX при quad = true, иначе GLB. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.glb",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="image_to_model"></a>По фото

> Модель по одному фото объекта. Лучше всего фото с чистым фоном, объект целиком.

Значение поля task_type: `image_to_model`

На этой странице версия Tripo 2.5: передайте model_version = v2.5-20250123. Без поля model_version запустится v3.1-20260211.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model_version` (Необязательно)

Версия модели. v3.1 и v3.0 самые детальные и со всеми настройками. У v2.5 и P1 часть настроек недоступна, P1 для низкополигональных моделей.

- Тип: Строка
- Допустимые значения: `v2.5-20250123` (v2.5)
- По умолчанию: `"v3.1-20260211"`

#### `texture` (Необязательно)

Модель с текстурой. Без неё только форма.

- Тип: Да/нет
- По умолчанию: `true`

#### `pbr` (Необязательно)

Реалистичные материалы с отражениями и бликами. Включает и текстуру.

- Тип: Да/нет
- По умолчанию: `true`

#### `texture_quality` (Необязательно)

Качество текстуры. HD детальнее, цена выше. HD есть только у версий v3.1, v3.0 и P1.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (HD (детализированное))
- По умолчанию: `"standard"`

#### `geometry_quality` (Необязательно)

Качество формы. Ultra детальнее, дольше и дороже, только у v3.1 и v3.0.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (Ultra (максимальная детализация))
- По умолчанию: `"standard"`

#### `face_limit` (Необязательно)

Сколько полигонов в модели. Не задано: подбирается само. Допустимый предел зависит от версии и настроек: у P1 от 50 до 20 000, у smart low-poly от 500 до 20 000.

- Тип: Целое число
- Минимум: 48
- Максимум: 2000000

#### `auto_size` (Необязательно)

Привести модель к реальным размерам в метрах. Есть только у версий v3.1, v3.0 и P1.

- Тип: Да/нет
- По умолчанию: `false`

#### `orientation` (Необязательно)

Поворот готовой модели: обычный или как на исходном фото. Действует только у модели по фото или по ракурсам и только с текстурой.

- Тип: Строка
- Допустимые значения: `default` (По умолчанию), `align_image` (Выровнять по изображению)
- По умолчанию: `"default"`

#### `quad` (Необязательно)

Модель из четырёхугольников, удобнее для правки и анимации. Файл будет в FBX. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `smart_low_poly` (Необязательно)

Низкополигональная модель с аккуратной сеткой. Лучше для простых объектов. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `generate_parts` (Необязательно)

Модель из отдельных частей. Не сочетается с текстурой, PBR, четырёхугольниками и smart low-poly. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `image_url` (Обязательно)

Одна ссылка на фото объекта.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `texture_alignment` (Необязательно)

Как накладывать текстуру: точнее по фото или точнее по форме модели.

- Тип: Строка
- Допустимые значения: `original_image` (По изображению), `geometry` (По геометрии)
- По умолчанию: `"original_image"`

#### `enable_image_autofix` (Необязательно)

Сначала подправить фото для лучшего результата.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Фото передаются ссылками на JPEG или PNG до 20 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `image_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Модель по фото

```json
{
  "model": "tripo3d",
  "settings": {
    "task_type": "image_to_model",
    "image_url": [
      "https://example.com/chair.png"
    ],
    "model_version": "v2.5-20250123"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Файл 3D-модели GLB (с четырёхугольниками FBX) и картинка-превью.
- Генерация занимает несколько минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg, webp | 0 или 1 | Картинка-превью модели, если Tripo её прислал. |
| `document` | glb, fbx | 1 | Файл 3D-модели: FBX при quad = true, иначе GLB. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.glb",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## <a id="multiview_to_model"></a>По ракурсам

> Модель по нескольким фото одного объекта с разных сторон: самая точная форма. Нужно фото спереди и хотя бы ещё одно, каждое в поле своей стороны. Бока считаются от самого объекта: в left_url фото, где он смотрит влево. Если перепутать бока, у модели может получиться второй перед вместо спины.

Значение поля task_type: `multiview_to_model`

На этой странице версия Tripo 2.5: передайте model_version = v2.5-20250123. Без поля model_version запустится v3.1-20260211.

### Параметры

Параметры модели передаются внутри settings. Пропущенные необязательные поля берут значение по умолчанию.

#### `model_version` (Необязательно)

Версия модели. v3.1 и v3.0 самые детальные и со всеми настройками. У v2.5 и P1 часть настроек недоступна, P1 для низкополигональных моделей.

- Тип: Строка
- Допустимые значения: `v2.5-20250123` (v2.5)
- По умолчанию: `"v3.1-20260211"`

#### `texture` (Необязательно)

Модель с текстурой. Без неё только форма.

- Тип: Да/нет
- По умолчанию: `true`

#### `pbr` (Необязательно)

Реалистичные материалы с отражениями и бликами. Включает и текстуру.

- Тип: Да/нет
- По умолчанию: `true`

#### `texture_quality` (Необязательно)

Качество текстуры. HD детальнее, цена выше. HD есть только у версий v3.1, v3.0 и P1.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (HD (детализированное))
- По умолчанию: `"standard"`

#### `geometry_quality` (Необязательно)

Качество формы. Ultra детальнее, дольше и дороже, только у v3.1 и v3.0.

- Тип: Строка
- Допустимые значения: `standard` (Стандартное), `detailed` (Ultra (максимальная детализация))
- По умолчанию: `"standard"`

#### `face_limit` (Необязательно)

Сколько полигонов в модели. Не задано: подбирается само. Допустимый предел зависит от версии и настроек: у P1 от 50 до 20 000, у smart low-poly от 500 до 20 000.

- Тип: Целое число
- Минимум: 48
- Максимум: 2000000

#### `auto_size` (Необязательно)

Привести модель к реальным размерам в метрах. Есть только у версий v3.1, v3.0 и P1.

- Тип: Да/нет
- По умолчанию: `false`

#### `orientation` (Необязательно)

Поворот готовой модели: обычный или как на исходном фото. Действует только у модели по фото или по ракурсам и только с текстурой.

- Тип: Строка
- Допустимые значения: `default` (По умолчанию), `align_image` (Выровнять по изображению)
- По умолчанию: `"default"`

#### `quad` (Необязательно)

Модель из четырёхугольников, удобнее для правки и анимации. Файл будет в FBX. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `smart_low_poly` (Необязательно)

Низкополигональная модель с аккуратной сеткой. Лучше для простых объектов. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `generate_parts` (Необязательно)

Модель из отдельных частей. Не сочетается с текстурой, PBR, четырёхугольниками и smart low-poly. Есть только у версий v3.1 и v3.0.

- Тип: Да/нет
- По умолчанию: `false`

#### `front_url` (Обязательно)

Фото объекта спереди. Обязательно.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `left_url` (Необязательно)

Фото левого бока объекта: на фото объект смотрит влево, у персонажа к камере его левая рука.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `back_url` (Необязательно)

Фото объекта сзади.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `right_url` (Необязательно)

Фото правого бока объекта: на фото объект смотрит вправо, у персонажа к камере его правая рука.

- Тип: Список (Строка, uri)
- Максимум элементов: 1

#### `texture_alignment` (Необязательно)

Как накладывать текстуру: точнее по фото или точнее по форме модели.

- Тип: Строка
- Допустимые значения: `original_image` (По изображению), `geometry` (По геометрии)
- По умолчанию: `"original_image"`

#### `enable_image_autofix` (Необязательно)

Сначала подправить фото для лучшего результата.

- Тип: Да/нет
- По умолчанию: `false`

Параметры, которых нет в списке, не принимаются: ответ 422 unknown_setting.

### Входные данные

- Фото передаются ссылками на JPEG или PNG до 20 МБ.

| Поле | Что принимает | Форматы | Файлов | Размер файла до |
|---|---|---|---|---|
| `front_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |
| `left_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |
| `back_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |
| `right_url` | Картинки | jpeg, jpg, png | 1 | 20 МБ |

[Как передать файлы](https://api.cyhub.ai/docs/files.md?lang=ru)

### Пример запроса

Отправьте этот JSON в POST /v1/tasks с ключом API. Чтобы узнать цену заранее, тот же JSON можно отправить в POST /v1/price.

Модель по фото спереди и сзади

```json
{
  "model": "tripo3d",
  "settings": {
    "task_type": "multiview_to_model",
    "front_url": [
      "https://example.com/front.png"
    ],
    "back_url": [
      "https://example.com/back.png"
    ],
    "model_version": "v2.5-20250123"
  }
}
```

Цена считается при приёме задачи, валюта `RUB`.

[Полный пример запуска](https://api.cyhub.ai/docs/generations.md?lang=ru)

### Результат

- Файл 3D-модели GLB (с четырёхугольниками FBX) и картинка-превью.
- Генерация занимает несколько минут.

| Вид (kind) | Форматы | Сколько | Пояснение |
|---|---|---|---|
| `image` | png, jpg, webp | 0 или 1 | Картинка-превью модели, если Tripo её прислал. |
| `document` | glb, fbx | 1 | Файл 3D-модели: FBX при quad = true, иначе GLB. |

Так выглядит готовая задача в ответе GET /v1/tasks/{id} (часть полей опущена). Подпись caption бывает у задачи или у отдельного файла и может быть пустой, имя файла задаёт модель.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Подпись к результату: модель и настройки",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "image",
        "filename": "image.png",
        "size": 1843200,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      },
      {
        "index": 1,
        "kind": "document",
        "filename": "result.glb",
        "size": 2097152,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/1"
      }
    ]
  }
}
```

[Как читать результат и скачивать файлы](https://api.cyhub.ai/docs/tasks.md?lang=ru#result)

## Смотрите также

- [Нейросеть Tripo 2.5: возможности и цены](https://api.cyhub.ai/models/tripo-2-5)
- Другие версии: [Tripo 3D API](https://api.cyhub.ai/models/tripo-3d/api.md), [Tripo 3.0 API](https://api.cyhub.ai/models/tripo-3-0/api.md)
- [Документация API](https://api.cyhub.ai/docs.md?lang=ru)
- [Ошибки API и что с ними делать](https://api.cyhub.ai/docs/errors.md?lang=ru)