<!-- /docs/creative-api (ru) -->

# Изображения, текст, музыка и речь

REST-контракты шести модулей Make сверены с исходниками 8 сентября 2026 года; доступ и стоимость зависят от аккаунта и выбранной операции.

## Подключение и выполнение запроса

Все пути ниже полные, начиная с `/franklab/api`. Используйте ключ своего аккаунта в `X-API-Key`; храните его только в переменной окружения сервера. Пример одного запроса:

```bash
export FRANKLAB_BASE_URL='https://apergrex.ru/franklab/api'
# FRANKLAB_KEY уже задан через защищённое окружение
cat > request.json <<'JSON'
{"model_key":"moon_gpt","prompt":"Return the word OK.","max_output_tokens":16,"async_mode":true}
JSON
curl --fail-with-body --max-time 300 -X POST \
  -H "X-API-Key: ${FRANKLAB_KEY:?Set your account key}" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json \
  "$FRANKLAB_BASE_URL/make/dola/generate"
```

Пример вызывает генерацию и может резервировать средства. Для другого действия замените суффикс пути, метод и JSON по таблице. `REPLACE_WITH_…` и `example.com` — шаблоны, которые надо заменить собственными ID/медиа; примеры не следует запускать подряд. GET принимает указанные query-параметры, path ID подставляется в URL, тело не отправляется.

Обязательность и варианты относятся к выбранной операции; условия указаны отдельно. «Make default» — значение формы, которое REST-клиент должен передать явно, если хочет повторить поведение Make. Это не обещание серверного default.

## Биллинг, ошибки и повторные запросы

Сначала проверьте [баланс и тариф](/docs/billing). Alibaba предоставляет `/make/alibaba/estimate`; общий `/v1/billing/pricing/estimate` принимает `modelId` из актуального `/v1/billing/pricing/catalog` и только поддерживаемые параметры. Идентификатор ценового каталога не равен автоматически `model_key`/`model_name`. У остальных действий может не быть отдельного публичного estimate; неизвестная цена не равна нулю. Сверяйте резерв, итоговую стоимость и возврат по задаче и транзакциям. Франк (₣) — внутренняя расчётная единица.

Ошибки: 400 — неверные поля/модель/ссылки, 401 — ключ, 403 — доступ, 404 — отсутствующий или недоступный вашему аккаунту ресурс, 429 — ограничение частоты. Недоступность модели, недостаточный баланс и ошибки выполнения также могут быть внутри `code`, `message`/`msg`, `data.error`/`error_message` при HTTP 200. Проверяйте HTTP и тело. При неизвестном исходе POST сохраните идентификаторы и обратитесь к истории/поддержке; не повторяйте платную отправку автоматически. Состояния, ошибки и поля результатов зависят от модуля.

## FrankLab Alibaba Image

**Доступность на 8 сентября 2026:** проверка Z-Image Turbo вернула `code:503` на этапе оценки, до создания задачи. Если оценка недоступна для вашего аккаунта, не переходите к генерации; уточните доступ в поддержке. Эта проверка не устанавливает доступность других моделей Alibaba.

Создание изображения Z-Image, генерация и редактирование Qwen Image 3.0 и Qwen Image 3.0 Pro. REST-операции синхронные: сначала разбирайте ответ. Наличие кода не подтверждает доступ аккаунта или работу в production; оценка и генерация проверяют доступность операции.

Для редактирования Qwen передавайте `editImageIds`: 1–3 UUID **StoredFile вашего аккаунта**. URL, объекты Make `{value}` и file ID из MOON GPT не подходят. Обычная публичная загрузка возвращает URL, а не требуемое поле StoredFile ID; до редактирования получите собственный ID через поддерживаемый процесс работы с ассетами. Не придумывайте UUID. Qwen требует `width`/`height`: каждая сторона до 2048, площадь от 512² до 2048² пикселей; `n` от 1 до 6 (по умолчанию 1). `prompt_extend_mode=agent` работает только для text-to-image. Результат Qwen — PNG. Размер Z-Image записывается через `*`, например `1024*1024`.

В успешном ответе проверяйте `data.imageUrl` (первое изображение), `data.taskId`, размеры и `estimated_cost_franks`/`final_cost_franks`/`cost_status`. Кроме HTTP проверяйте `code` и `error_message`. Оценка не создаёт изображение. Для оценки Qwen поле называется `qwenOperation`, для генерации — `operation`. `/make/alibaba/status/:taskId` опрашивает видео и не подходит для результата изображения.

| Действие | Метод | Путь |
|---|---|---|
| `z-image-turbo:text_to_image` | POST | `/franklab/api/make/alibaba/images` |
| `qwen-image-3.0-pro:text_to_image` | POST | `/franklab/api/make/alibaba/images` |
| `qwen-image-3.0-pro:image_edit` | POST | `/franklab/api/make/alibaba/images` |
| `qwen-image-3.0:text_to_image` | POST | `/franklab/api/make/alibaba/images` |
| `qwen-image-3.0:image_edit` | POST | `/franklab/api/make/alibaba/images` |
| `estimate` | POST | `/franklab/api/make/alibaba/estimate` |

### z-image-turbo:text_to_image

`POST /franklab/api/make/alibaba/images`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model` | string | да | `"z-image-turbo"` |
| `prompt` | string | да | — |
| `size` | string | да | `["1024*1024","832*1248","1248*832","864*1152","1152*864","896*1152","1152*896","720*1280","576*1344","1280*720","1344*576","1280*1280","1024*1536","1536*1024","1104*1472","1472*1104","1120*1440","1440*1120","864*1536","720*1680","1536*864","1680*720","1536*1536","1248*1872","1872*1248","1296*1728","1728*1296","1344*1728","1728*1344","1152*2048","864*2016","2048*1152","2016*864"]`; Make default: "1024*1024" |
| `seed` | integer | нет | — |

JSON-шаблон:

```json
{
  "model": "z-image-turbo",
  "prompt": "A short calm synthetic test.",
  "size": "1024*1024"
}
```

### qwen-image-3.0-pro:text_to_image

`POST /franklab/api/make/alibaba/images`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model` | string | да | `"qwen-image-3.0-pro"` |
| `operation` | string | да | `"text_to_image"` |
| `prompt` | string | да | — |
| `width` | integer | да | Make default: 1024 |
| `height` | integer | да | Make default: 1024 |
| `n` | integer | нет | Сервер default: 1 |
| `seed` | integer | нет | — |
| `negative_prompt` | string | нет | — |
| `prompt_extend` | boolean | нет | Make default: false |
| `prompt_extend_mode` | string | нет | `["direct","agent"]`; Make default: "direct" |
| `enable_thinking` | boolean | нет | Make default: false |
| `watermark` | boolean | нет | Make default: false |

JSON-шаблон:

```json
{
  "model": "qwen-image-3.0-pro",
  "operation": "text_to_image",
  "prompt": "A short calm synthetic test.",
  "width": 1024,
  "height": 1024
}
```

### qwen-image-3.0-pro:image_edit

`POST /franklab/api/make/alibaba/images`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model` | string | да | `"qwen-image-3.0-pro"` |
| `operation` | string | да | `"image_edit"` |
| `prompt` | string | да | — |
| `width` | integer | да | Make default: 1024 |
| `height` | integer | да | Make default: 1024 |
| `n` | integer | нет | Сервер default: 1 |
| `editImageIds` | array | да | items: string |
| `seed` | integer | нет | — |
| `negative_prompt` | string | нет | — |
| `prompt_extend` | boolean | нет | Make default: false |
| `enable_thinking` | boolean | нет | Make default: false |
| `watermark` | boolean | нет | Make default: false |

JSON-шаблон:

```json
{
  "model": "qwen-image-3.0-pro",
  "operation": "image_edit",
  "prompt": "A short calm synthetic test.",
  "width": 1024,
  "height": 1024,
  "editImageIds": [
    "REPLACE_WITH_OWNED_STORED_FILE_UUID_V4"
  ]
}
```

### qwen-image-3.0:text_to_image

`POST /franklab/api/make/alibaba/images`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model` | string | да | `"qwen-image-3.0"` |
| `operation` | string | да | `"text_to_image"` |
| `prompt` | string | да | — |
| `width` | integer | да | Make default: 1024 |
| `height` | integer | да | Make default: 1024 |
| `n` | integer | нет | Сервер default: 1 |
| `seed` | integer | нет | — |
| `negative_prompt` | string | нет | — |
| `prompt_extend` | boolean | нет | Make default: false |
| `prompt_extend_mode` | string | нет | `["direct","agent"]`; Make default: "direct" |
| `enable_thinking` | boolean | нет | Make default: false |
| `watermark` | boolean | нет | Make default: false |

JSON-шаблон:

```json
{
  "model": "qwen-image-3.0",
  "operation": "text_to_image",
  "prompt": "A short calm synthetic test.",
  "width": 1024,
  "height": 1024
}
```

### qwen-image-3.0:image_edit

`POST /franklab/api/make/alibaba/images`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model` | string | да | `"qwen-image-3.0"` |
| `operation` | string | да | `"image_edit"` |
| `prompt` | string | да | — |
| `width` | integer | да | Make default: 1024 |
| `height` | integer | да | Make default: 1024 |
| `n` | integer | нет | Сервер default: 1 |
| `editImageIds` | array | да | items: string |
| `seed` | integer | нет | — |
| `negative_prompt` | string | нет | — |
| `prompt_extend` | boolean | нет | Make default: false |
| `enable_thinking` | boolean | нет | Make default: false |
| `watermark` | boolean | нет | Make default: false |

JSON-шаблон:

```json
{
  "model": "qwen-image-3.0",
  "operation": "image_edit",
  "prompt": "A short calm synthetic test.",
  "width": 1024,
  "height": 1024,
  "editImageIds": [
    "REPLACE_WITH_OWNED_STORED_FILE_UUID_V4"
  ]
}
```

### estimate

Для оценки изображения передайте `model=z-image-turbo|qwen-image-3.0-pro|qwen-image-3.0`. Для HappyHorse-видео не передавайте model; для WAN используйте `wan3.0-video`. `happyhorse-1.1` — значение переключателя Make, а не допустимое значение REST DTO.

`POST /franklab/api/make/alibaba/estimate`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `media` | string | да | — |
| `model` | string | нет | — |
| `operation` | string | нет | — |
| `width` | integer | нет | — |
| `height` | integer | нет | — |
| `n` | integer | нет | — |
| `imageCount` | integer | нет | — |
| `resolution` | string | нет | — |
| `durationSeconds` | integer | нет | — |
| `qwenOperation` | string | нет | `text_to_image` / `image_edit`; только оценка Qwen |

JSON-шаблон:

```json
{
  "media": "image",
  "model": "z-image-turbo"
}
```

## JUPITER

Сначала выберите маршрут и модель. Поле Make `mode` выбирает маршрут и **не передаётся в REST JSON**. MIST использует `model_name=mist`, Kling — `jupiter-v1-5`; Gemini/Seedream — `model_id`; подписочные маршруты — `execution_mode`. Доступность каждого маршрута проверяется отдельно. Каталог моделей не гарантирует возможность генерации.

Формы референсов различаются: MIST/Kling/Gemini — `image_list:[{"image_url":"https://…"}]`; Seedream — `image:["https://…"]`; подписочные маршруты — `reference_images:["https://…"]`; прежний Nano Banana Pro — `image_input:["https://…"]`; редактирование Grok — `image:{"url":"https://…"}`. URL собственных файлов получите по [инструкции загрузки](/docs/integration).

Сохраняйте маршрут отправки вместе с `data.task_id`/`data.taskId`. Обычно статус получается добавлением `/:taskId`; прежний Nano Banana Pro использует `/v1/google/:taskId/record-info`. Не отправляйте Gemini/Seedream ID в omni-image poller. Опрос — примерно раз в 5 секунд, с ограничением времени. Проверяйте `data.status`, `task_status` или `state`; успешные значения включают `completed`, `succeed`, `success`, `succeeded`, `done`. При failed/refunded/cancelled опрос прекращается. Истечение времени ожидания не разрешает повторную генерацию.

Изображения могут находиться в `data.images`, `data.task_result.images`, `data.result.task_result.images`, `data.output.images`, `data.output.imageUrls`; старые ответы содержат JSON-строку `data.resultJson` с `resultUrls`. Gemini также возвращает `output_text`, `grounding`, `citations`, `search_suggestions`, `interaction_id`. Поле Make `image_url` — производная проекция, а не универсальная форма REST. `final_cost_franks` при `cost_status=reserved` ещё означает резерв.

| Действие | Метод | Путь |
|---|---|---|
| `mist` | POST | `/franklab/api/v1/images/omni-image` |
| `gpt_image_codex` | POST | `/franklab/api/v1/images/gpt-image-codex` |
| `google_sub_image` | POST | `/franklab/api/v1/images/google-sub` |
| `jupiter` | POST | `/franklab/api/v1/images/omni-image` |
| `xai_imagine_image_2` | POST | `/franklab/api/v1/images/xai-imagine` |
| `xai_imagine_image` | POST | `/franklab/api/v1/images/xai-imagine` |
| `google_gemini_image` | POST | `/franklab/api/v1/google/gemini-image` |
| `seedream_image` | POST | `/franklab/api/v1/images/seedream-image` |
| `google_nano_banana_pro` | POST | `/franklab/api/v1/google/nano-banana-pro` |
| `poll:v1/google/:taskId/record-info` | GET | `/franklab/api/v1/google/:taskId/record-info` |
| `poll:v1/google/gemini-image/:taskId` | GET | `/franklab/api/v1/google/gemini-image/:taskId` |
| `poll:v1/images/google-sub/:taskId` | GET | `/franklab/api/v1/images/google-sub/:taskId` |
| `poll:v1/images/gpt-image-codex/:taskId` | GET | `/franklab/api/v1/images/gpt-image-codex/:taskId` |
| `poll:v1/images/omni-image/:taskId` | GET | `/franklab/api/v1/images/omni-image/:taskId` |
| `poll:v1/images/seedream-image/:taskId` | GET | `/franklab/api/v1/images/seedream-image/:taskId` |
| `poll:v1/images/xai-imagine/:taskId` | GET | `/franklab/api/v1/images/xai-imagine/:taskId` |

### mist

`POST /franklab/api/v1/images/omni-image`

Опрос: `GET /franklab/api/v1/images/omni-image/:taskId`.

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model_name` | string | да | `"mist"` |
| `quality` | string | нет | `["auto","low","medium","high"]`; Make default: "auto" |
| `output_format` | string | нет | `["png","jpeg","webp"]`; Make default: "png" |
| `background` | string | нет | `["auto","opaque"]`; Make default: "auto" |
| `moderation` | string | нет | `["auto","low"]`; Make default: "auto" |
| `partial_images` | string | нет | `[0,1,2,3]`; Make default: 0 |
| `input_fidelity` | string | нет | `["high","auto"]`; Make default: "high" |
| `prompt` | string | да | — |
| `image_list` | array | нет | `image_url:string` |
| `aspect_ratio` | string | нет | `["1:1","16:9","9:16","21:9","custom"]`; Make default: "1:1" |
| `custom_aspect_ratio` | string | нет | При aspect_ratio=custom |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "model_name": "mist",
  "prompt": "A short calm synthetic test."
}
```

### gpt_image_codex

`POST /franklab/api/v1/images/gpt-image-codex`

Опрос: `GET /franklab/api/v1/images/gpt-image-codex/:taskId`.

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `execution_mode` | string | да | `"openai_codex"` |
| `quality` | string | нет | `["low","medium","high"]`; Make default: "medium" |
| `prompt` | string | да | — |
| `reference_images` | array | нет | items: string |
| `aspect_ratio` | string | нет | `["1:1","16:9","9:16","custom"]`; Make default: "1:1" |
| `custom_aspect_ratio` | string | нет | При aspect_ratio=custom |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "execution_mode": "openai_codex",
  "prompt": "A short calm synthetic test."
}
```

### google_sub_image

`POST /franklab/api/v1/images/google-sub`

Опрос: `GET /franklab/api/v1/images/google-sub/:taskId`.

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `execution_mode` | string | да | `"google_subscription"` |
| `prompt` | string | да | — |
| `reference_images` | array | нет | items: string |
| `aspect_ratio` | string | нет | `["1:1","16:9","9:16","4:3","3:4"]`; Make default: "1:1" |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "execution_mode": "google_subscription",
  "prompt": "A short calm synthetic test."
}
```

### jupiter

`POST /franklab/api/v1/images/omni-image`

Опрос: `GET /franklab/api/v1/images/omni-image/:taskId`.

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model_name` | string | да | `"jupiter-v1-5"` |
| `resolution` | string | да | `["1k","2k","4k"]`; Make default: "1k" |
| `result_type` | string | нет | `["single","series"]`; Make default: "single" |
| `series_amount` | integer or string | нет | `["auto",2,3,4,5,6,7,8,9]`; Make default: "auto"; При result_type=series |
| `prompt` | string | да | — |
| `n` | number | нет | Make default: 1 |
| `image_list` | array | нет | `image_url:string` |
| `element_list` | array | нет | `element_id:string` |
| `aspect_ratio` | string | нет | `["auto","1:1","16:9","9:16","4:3","3:4","3:2","2:3","21:9","custom"]`; Make default: "auto" |
| `custom_aspect_ratio` | string | нет | При aspect_ratio=custom |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "model_name": "jupiter-v1-5",
  "resolution": "1k",
  "prompt": "A short calm synthetic test."
}
```

### xai_imagine_image_2

`POST /franklab/api/v1/images/xai-imagine`

Опрос: `GET /franklab/api/v1/images/xai-imagine/:taskId`.

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model_name` | string | да | `"xai-imagine-image-2"` |
| `response_format` | string | да | `"url"` |
| `prompt` | string | да | — |
| `quality` | string | да | `["medium","low"]`; Make default: "medium" |
| `aspect_ratio` | string | да | `["auto","1:1","16:9","9:16","4:3","3:4","3:2","2:3","2:1","1:2","19.5:9","9:19.5","20:9","9:20"]`; Make default: "auto" |
| `resolution` | string | да | `["1k","2k"]`; Make default: "1k" |
| `n` | number | да | Make default: 1 |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "model_name": "xai-imagine-image-2",
  "response_format": "url",
  "prompt": "A short calm synthetic test.",
  "quality": "medium",
  "aspect_ratio": "auto",
  "resolution": "1k",
  "n": 1
}
```

### xai_imagine_image

`POST /franklab/api/v1/images/xai-imagine`

Опрос: `GET /franklab/api/v1/images/xai-imagine/:taskId`.

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model_name` | string | да | `"xai-imagine-image-quality"` |
| `response_format` | string | да | `"url"` |
| `execution_mode` | string | нет | `["xai_api","supergrok"]`; Make default: "xai_api" |
| `prompt` | string | да | — |
| `image` | object | нет | При image edit requested; `url:string` |
| `aspect_ratio` | string | нет | `["auto","1:1","16:9","9:16","4:3","3:4"]`; Make default: "auto" |
| `resolution` | string | нет | `["1k","2k"]`; Make default: "1k" |
| `n` | number | нет | Make default: 1 |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "model_name": "xai-imagine-image-quality",
  "response_format": "url",
  "prompt": "A short calm synthetic test."
}
```

### google_gemini_image

`POST /franklab/api/v1/google/gemini-image`

Опрос: `GET /franklab/api/v1/google/gemini-image/:taskId`.

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model_id` | string | да | `["gemini-3.1-flash-image","gemini-3.1-flash-lite-image","gemini-3-pro-image","gemini-2.5-flash-image"]`; Make default: "gemini-3.1-flash-image" |
| `prompt` | string | по условию | При model_id=gemini-3.1-flash-image |
| `image_list` | array | нет | При model_id=gemini-3.1-flash-image; `image_url:string` |
| `video_url` | string | нет | При model_id=gemini-3.1-flash-image |
| `previous_interaction_id` | string | нет | При model_id=gemini-3.1-flash-image |
| `aspect_ratio` | string | нет | `["auto","1:1","16:9","9:16","4:3","3:4","3:2","2:3","4:5","5:4","1:4","1:8","4:1","8:1","21:9"]`; Make default: "auto"; При model_id=gemini-3.1-flash-image |
| `image_size` | string | нет | `["0.5K","1K","2K","4K"]`; Make default: "1K"; При model_id=gemini-3.1-flash-image |
| `output_format` | string | нет | `["png","jpeg","webp"]`; Make default: "png"; При model_id=gemini-3.1-flash-image |
| `use_google_search` | boolean | нет | Make default: false; При model_id=gemini-3.1-flash-image |
| `use_image_search` | boolean | нет | Make default: false; При model_id=gemini-3.1-flash-image |
| `prompt` | string | по условию | При model_id=gemini-3.1-flash-lite-image |
| `image_list` | array | нет | При model_id=gemini-3.1-flash-lite-image; `image_url:string` |
| `aspect_ratio` | string | нет | `["auto","1:1","16:9","9:16","4:3","3:4","3:2","2:3","4:5","5:4","21:9"]`; Make default: "auto"; При model_id=gemini-3.1-flash-lite-image |
| `output_format` | string | нет | `["png","jpeg","webp"]`; Make default: "png"; При model_id=gemini-3.1-flash-lite-image |
| `prompt` | string | по условию | При model_id=gemini-3-pro-image |
| `image_list` | array | нет | При model_id=gemini-3-pro-image; `image_url:string` |
| `previous_interaction_id` | string | нет | При model_id=gemini-3-pro-image |
| `aspect_ratio` | string | нет | `["auto","1:1","16:9","9:16","4:3","3:4","3:2","2:3","4:5","5:4","21:9"]`; Make default: "auto"; При model_id=gemini-3-pro-image |
| `image_size` | string | нет | `["1K","2K","4K"]`; Make default: "1K"; При model_id=gemini-3-pro-image |
| `output_format` | string | нет | `["png","jpeg","webp"]`; Make default: "png"; При model_id=gemini-3-pro-image |
| `use_google_search` | boolean | нет | Make default: false; При model_id=gemini-3-pro-image |
| `prompt` | string | по условию | При model_id=gemini-2.5-flash-image |
| `image_list` | array | нет | При model_id=gemini-2.5-flash-image; `image_url:string` |
| `aspect_ratio` | string | нет | `["auto","1:1","16:9","9:16","4:3","3:4","3:2","2:3","4:5","5:4","21:9"]`; Make default: "auto"; При model_id=gemini-2.5-flash-image |
| `output_format` | string | нет | `["png","jpeg","webp"]`; Make default: "png"; При model_id=gemini-2.5-flash-image |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "model_id": "gemini-3.1-flash-image",
  "prompt": "A flat blue circle on white.",
  "image_size": "0.5K"
}
```

### seedream_image

`POST /franklab/api/v1/images/seedream-image`

Опрос: `GET /franklab/api/v1/images/seedream-image/:taskId`.

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model_id` | string | да | `["seedream-5-0-lite","seedream-5-0-pro"]`; Make default: "seedream-5-0-lite" |
| `prompt` | string | по условию | При model_id=seedream-5-0-lite |
| `image` | array | нет | При model_id=seedream-5-0-lite; items: string |
| `sequential_image_generation` | string | нет | `["disabled","auto"]`; Make default: "disabled"; При model_id=seedream-5-0-lite |
| `max_images` | string | нет | `[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]`; Make default: 4; При model_id=seedream-5-0-lite; sequential_image_generation=auto |
| `resolution` | string | по условию | `["2K","3K","4K"]`; Make default: "2K"; При model_id=seedream-5-0-lite |
| `aspect_ratio` | string | нет | `["","1:1","4:3","3:4","16:9","9:16","3:2","2:3","21:9"]`; Make default: ""; При model_id=seedream-5-0-lite |
| `output_format` | string | нет | `["jpeg","png"]`; Make default: "jpeg"; При model_id=seedream-5-0-lite |
| `watermark` | boolean | нет | Make default: false; При model_id=seedream-5-0-lite |
| `prompt` | string | по условию | При model_id=seedream-5-0-pro |
| `image` | array | нет | При model_id=seedream-5-0-pro; items: string |
| `resolution` | string | по условию | `["1K","2K"]`; Make default: "2K"; При model_id=seedream-5-0-pro |
| `aspect_ratio` | string | нет | `["","1:1","4:3","3:4","16:9","9:16","3:2","2:3","21:9"]`; Make default: ""; При model_id=seedream-5-0-pro |
| `output_format` | string | нет | `["jpeg","png"]`; Make default: "jpeg"; При model_id=seedream-5-0-pro |
| `watermark` | boolean | нет | Make default: false; При model_id=seedream-5-0-pro |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "model_id": "seedream-5-0-lite",
  "prompt": "A flat blue circle on white.",
  "resolution": "2K"
}
```

### google_nano_banana_pro

`POST /franklab/api/v1/google/nano-banana-pro`

Опрос: `GET /franklab/api/v1/google/:taskId/record-info`.

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `image_input` | array | нет | items: string |
| `prompt` | string | нет | — |
| `aspect_ratio` | string | нет | `["1:1","9:16","16:9","3:4","4:3"]` |
| `resolution` | string | да | `["1K","2K","4K"]`; Make default: "1K" |
| `output_format` | string | нет | `["png","jpg"]`; Make default: "png" |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "resolution": "1K",
  "prompt": "A blue circle on white."
}
```

### poll:v1/google/:taskId/record-info

`GET /franklab/api/v1/google/:taskId/record-info`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | path |

### poll:v1/google/gemini-image/:taskId

`GET /franklab/api/v1/google/gemini-image/:taskId`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | path |

### poll:v1/images/google-sub/:taskId

`GET /franklab/api/v1/images/google-sub/:taskId`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | path |

### poll:v1/images/gpt-image-codex/:taskId

`GET /franklab/api/v1/images/gpt-image-codex/:taskId`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | path |

### poll:v1/images/omni-image/:taskId

`GET /franklab/api/v1/images/omni-image/:taskId`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | path |

### poll:v1/images/seedream-image/:taskId

`GET /franklab/api/v1/images/seedream-image/:taskId`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | path |

### poll:v1/images/xai-imagine/:taskId

`GET /franklab/api/v1/images/xai-imagine/:taskId`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | path |

## KUSOK v.2

Все 16 действий используют `POST /make/kusok/operation` с `backend` и `action`. `backend=kusok` управляет элементами и голосами, `backend=moon` — верификацией и Moon assets. Для KUSOK старые сервисные ключи отклоняются. Идентификаторы принадлежат аккаунту; ID задачи, элемента, asset и голоса не взаимозаменяемы.

Создание требует `element_name` (1–20 символов), `element_description` (до 100) и `reference_type`. Для `image_refer` передайте собственное `frontal_image` и при необходимости `refer_images:[{"image_url":"…","type":"side"}]`; для `video_refer` — `refer_videos:[{"video_url":"…"}]`. Создание голоса требует аудио/видео, которое вы вправе использовать. Для проверок интеграции используйте синтетические материалы.

Следуйте `data.should_poll` и `data.taskId`/`task_id`: create/recognize могут вернуть async-задачу, остальные действия имеют собственные ответы. Опрос `/make/kusok/async/tasks/:taskId` — до `completed` или `failed`, затем проверка `data.result`, `error_message` и пригодного `element_id`/результата распознавания. Ответ диспетчера `poll_task` лишь предписывает опрос, а не доказывает состояние очереди.

Moon `verify_start` запускает H5-верификацию человеком. Полученный токен передаётся в REST как **`byted_token`**, а не поле Make `verification_token`. `verify_get_result`: HTTP `200` — результат, `202` — ожидание, `409` — ошибка, `410` — срок истёк. Ссылки H5 и токены храните приватно. Для загрузки asset используйте подтверждённый `group_id`; до использования референса дождитесь `Active`. Удаление изменяет ресурсы и не служит проверкой подключения.

| Действие | Метод | Путь |
|---|---|---|
| `kusok:create` | POST | `/franklab/api/make/kusok/operation` |
| `kusok:get` | POST | `/franklab/api/make/kusok/operation` |
| `kusok:list` | POST | `/franklab/api/make/kusok/operation` |
| `kusok:delete` | POST | `/franklab/api/make/kusok/operation` |
| `kusok:recognize` | POST | `/franklab/api/make/kusok/operation` |
| `kusok:poll_task` | POST | `/franklab/api/make/kusok/operation` |
| `kusok:create_voice` | POST | `/franklab/api/make/kusok/operation` |
| `kusok:get_voice` | POST | `/franklab/api/make/kusok/operation` |
| `kusok:list_voices` | POST | `/franklab/api/make/kusok/operation` |
| `kusok:list_preset_voices` | POST | `/franklab/api/make/kusok/operation` |
| `kusok:delete_voice` | POST | `/franklab/api/make/kusok/operation` |
| `moon:verify_start` | POST | `/franklab/api/make/kusok/operation` |
| `moon:verify_get_result` | POST | `/franklab/api/make/kusok/operation` |
| `moon:create_asset` | POST | `/franklab/api/make/kusok/operation` |
| `moon:get_asset` | POST | `/franklab/api/make/kusok/operation` |
| `moon:list_assets` | POST | `/franklab/api/make/kusok/operation` |
| `poll` | GET | `/franklab/api/make/kusok/async/tasks/:taskId` |
| `getAllKusoks RPC` | GET | `/franklab/api/make/kusok/elements` |

### kusok:create

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"create"` |
| `element_name` | string | да | — |
| `element_description` | string | да | — |
| `reference_type` | string | да | `["image_refer","video_refer"]`; Make default: "image_refer" |
| `frontal_image` | string | нет | — |
| `refer_images` | array | нет | `image_url:string, type:string` |
| `refer_videos` | array | нет | `video_url:string` |
| `element_voice_id` | string | нет | — |
| `tag_list` | array | нет | `tag_id:string` |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "create",
  "element_name": "Synthetic circle",
  "element_description": "A blue synthetic circle.",
  "reference_type": "image_refer",
  "frontal_image": "https://example.com/owned-synthetic-image.png"
}
```

### kusok:get

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"get"` |
| `element_id` | string | да | — |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "get",
  "element_id": "REPLACE_WITH_OWNED_ELEMENT_ID"
}
```

### kusok:list

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"list"` |
| `pageNum` | integer | нет | Make default: 1 |
| `pageSize` | integer | нет | Make default: 200 |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "list"
}
```

### kusok:delete

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"delete"` |
| `element_id` | string | да | — |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "delete",
  "element_id": "REPLACE_WITH_OWNED_ELEMENT_ID"
}
```

### kusok:recognize

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"recognize"` |
| `image` | string | да | — |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "recognize",
  "image": "https://example.com/owned-synthetic-media.png"
}
```

### kusok:poll_task

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"poll_task"` |
| `task_id` | string | да | — |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "poll_task",
  "task_id": "REPLACE_WITH_OWNED_TASK_ID"
}
```

### kusok:create_voice

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"create_voice"` |
| `voice_name` | string | да | — |
| `voice_audio_list` | array | нет | `audio_url:string` |
| `voice_url` | string | нет | — |
| `video_id` | string | нет | — |
| `source_task_id` | string | нет | — |
| `callback_url` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "create_voice",
  "voice_name": "Synthetic Voice",
  "voice_url": "https://example.com/owned-synthetic-audio.mp3"
}
```

### kusok:get_voice

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"get_voice"` |
| `voice_id` | string | да | — |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "get_voice",
  "voice_id": "REPLACE_WITH_OWNED_VOICE_ID"
}
```

### kusok:list_voices

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"list_voices"` |
| `pageNum` | integer | нет | Make default: 1 |
| `pageSize` | integer | нет | Make default: 200 |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "list_voices"
}
```

### kusok:list_preset_voices

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"list_preset_voices"` |
| `pageNum` | integer | нет | Make default: 1 |
| `pageSize` | integer | нет | Make default: 200 |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "list_preset_voices"
}
```

### kusok:delete_voice

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"kusok"` |
| `action` | string | да | `"delete_voice"` |
| `voice_id` | string | да | — |

JSON-шаблон:

```json
{
  "backend": "kusok",
  "action": "delete_voice",
  "voice_id": "REPLACE_WITH_OWNED_VOICE_ID"
}
```

### moon:verify_start

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"moon"` |
| `action` | string | да | `"verify_start"` |
| `callback_url` | string | нет | — |
| `project_name` | string | нет | — |
| `external_task_id` | string | нет | — |

JSON-шаблон:

```json
{
  "backend": "moon",
  "action": "verify_start"
}
```

### moon:verify_get_result

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"moon"` |
| `action` | string | да | `"verify_get_result"` |
| `byted_token` | string | да | — |
| `project_name` | string | нет | — |

JSON-шаблон:

```json
{
  "backend": "moon",
  "action": "verify_get_result",
  "byted_token": "REPLACE_WITH_OWNED_BYTED_TOKEN"
}
```

### moon:create_asset

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"moon"` |
| `action` | string | да | `"create_asset"` |
| `group_id` | string | да | — |
| `url` | string | да | — |
| `asset_type` | string | да | `["Image","Video","Audio"]`; Make default: "Image" |
| `name` | string | нет | — |
| `project_name` | string | нет | — |

JSON-шаблон:

```json
{
  "backend": "moon",
  "action": "create_asset",
  "group_id": "REPLACE_WITH_OWNED_GROUP_ID",
  "url": "https://example.com/owned-synthetic-media.png",
  "asset_type": "Image"
}
```

### moon:get_asset

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"moon"` |
| `action` | string | да | `"get_asset"` |
| `asset_id` | string | да | — |
| `project_name` | string | нет | — |

JSON-шаблон:

```json
{
  "backend": "moon",
  "action": "get_asset",
  "asset_id": "REPLACE_WITH_OWNED_ASSET_ID"
}
```

### moon:list_assets

`POST /franklab/api/make/kusok/operation`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `backend` | string | да | `"moon"` |
| `action` | string | да | `"list_assets"` |
| `group_id` | string | нет | — |
| `statuses` | string | нет | `["Active","Processing","Failed"]` |
| `name` | string | нет | — |
| `pageNumber` | integer | нет | Make default: 1 |
| `pageSize` | integer | нет | Make default: 20 |

JSON-шаблон:

```json
{
  "backend": "moon",
  "action": "list_assets"
}
```

### poll

`GET /franklab/api/make/kusok/async/tasks/:taskId`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | path |

### getAllKusoks RPC

`GET /franklab/api/make/kusok/elements`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `pageNum` | integer | нет | Сервер default: 1; query |
| `pageSize` | integer | нет | Сервер default: 200; query |

## MOON GPT

Генерация текста, структурированного JSON и мультимодальных ответов через `/make/dola`. Нужен ключ партнёра; старые сервисные ключи получают 403. Получайте `model_key` и возможности моделей через `GET /make/dola/models`. По умолчанию выбирается `moon_gpt`; статический список ниже описывает исходный контракт, а не права аккаунта.

Обязателен `prompt`. Без REST `async_mode` запрос синхронный; передайте `true`, чтобы получить `billing_task_id` и опрашивать `/make/dola/tasks/:billing_task_id`. Пока `data.cost_status=pending`, продолжайте ограниченный опрос. Результат: `output_text`/`content`, `parsed_json`, `json_parse_ok`/`json_parse_error`, `usage`, `conversation_id` и поля списания. Завершённый биллинг сам по себе не подтверждает соответствие JSON вашей схеме.

Для `response_format=json_schema` нужны `json_schema_name` и JSON-объект `json_schema`, не строка. Поле Make `max_tokens` преобразуется в REST `max_output_tokens`; API принимает и `max_tokens`, но оба одновременно передавать не следует. Максимум зависит от модели и не превышает 65536. `thinking_level` и `thinking_budget` взаимоисключающие. Новые Gemini отклоняют `temperature` и прежний budget. Продолжение диалога сохраняет модель и собственный `conversation_id` либо поддерживаемый `previous_response_id`.

Загрузка URL: `/files/from-url`; загрузка файла: multipart `file` вместе с `filename` в `/files/upload`, максимум 100 МиБ. Затем запрашивайте `/files/:file_id`. JSON-вариант: base64 `file_data`, `filename`, необязательные `mime_type`/`purpose`; файл и base64 вместе запрещены. MIME: PDF, JPEG, PNG, GIF, WebP, MP4, QuickTime, AVI, octet-stream. Встроенные файловые объекты Make ограничены 48 КиБ. `image_refs`, `document_refs`, `video_refs` принимают HTTPS/data URI; ссылки `file-*` работают только с транспортом MOON GPT. Проверяйте поддержку модальности моделью и готовность файла. RPC JSON-схемы формирует поля редактора Make и не является REST endpoint.

| Действие | Метод | Путь |
|---|---|---|
| `generate` | POST | `/franklab/api/make/dola/generate` |
| `upload_file_from_url` | POST | `/franklab/api/make/dola/files/from-url` |
| `upload_file` | POST | `/franklab/api/make/dola/files/upload` |
| `get_file` | GET | `/franklab/api/make/dola/files/:file_id` |
| `delete_file` | DELETE | `/franklab/api/make/dola/files/:file_id` |
| `task_status` | GET | `/franklab/api/make/dola/tasks/:billing_task_id` |
| `models` | GET | `/franklab/api/make/dola/models` |
| `list_files` | GET | `/franklab/api/make/dola/files` |

### generate

`POST /franklab/api/make/dola/generate`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `prompt` | string | да | — |
| `async_mode` | boolean | нет | Make default: true |
| `system_prompt` | string | нет | — |
| `model_key` | string | нет | `["moon_gpt","gemini_3_7_flash","gemini_3_5_flash","gemini_3_6_flash","gemini_3_5_flash_lite","opus","sonnet","gpt","gpt5_5","gpt56_sol","gpt56_terra","gpt56_luna","deepseek_pro","deepseek_flash","kimi","grok","alibaba_qwen3_7_max_2026_06_08","alibaba_qwen3_7_plus_2026_05_26"]` |
| `previous_response_id` | string | нет | При model_key=moon_gpt |
| `image_refs` | array | нет | При model_key=moon_gpt; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=moon_gpt; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `video_refs` | array | нет | При model_key=moon_gpt; items: text |
| `conversation_mode` | boolean | нет | Make default: false; При model_key=moon_gpt |
| `conversation_id` | string | нет | При model_key=moon_gpt |
| `deepwiki_enabled` | boolean | нет | Make default: false; При model_key=moon_gpt |
| `image_refs` | array | нет | При model_key=gemini_3_7_flash; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=gemini_3_7_flash; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `video_refs` | array | нет | При model_key=gemini_3_7_flash; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `thinking_level` | string | нет | `["minimal","low","medium","high"]`; При model_key=gemini_3_7_flash |
| `image_refs` | array | нет | При model_key=gemini_3_5_flash; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=gemini_3_5_flash; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `video_refs` | array | нет | При model_key=gemini_3_5_flash; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `thinking_level` | string | нет | `["minimal","low","medium","high"]`; При model_key=gemini_3_5_flash |
| `thinking_budget` | integer | нет | При model_key=gemini_3_5_flash |
| `image_refs` | array | нет | При model_key=gemini_3_6_flash; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=gemini_3_6_flash; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `video_refs` | array | нет | При model_key=gemini_3_6_flash; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `thinking_level` | string | нет | `["minimal","low","medium","high"]`; При model_key=gemini_3_6_flash |
| `image_refs` | array | нет | При model_key=gemini_3_5_flash_lite; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=gemini_3_5_flash_lite; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `video_refs` | array | нет | При model_key=gemini_3_5_flash_lite; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `thinking_level` | string | нет | `["minimal","low","medium","high"]`; При model_key=gemini_3_5_flash_lite |
| `image_refs` | array | нет | При model_key=opus; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=opus; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `image_refs` | array | нет | При model_key=sonnet; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=sonnet; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `image_refs` | array | нет | При model_key=gpt; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=gpt; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `image_refs` | array | нет | При model_key=gpt5_5; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=gpt5_5; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `image_refs` | array | нет | При model_key=gpt56_sol; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=gpt56_sol; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `image_refs` | array | нет | При model_key=gpt56_terra; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=gpt56_terra; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `image_refs` | array | нет | При model_key=gpt56_luna; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `document_refs` | array | нет | При model_key=gpt56_luna; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `image_refs` | array | нет | При model_key=kimi; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `video_refs` | array | нет | При model_key=kimi; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `image_refs` | array | нет | При model_key=grok; `source_type:string, value:string, file_name:string, file_data:string (base64), data_url:string`; items: collection |
| `response_format` | string | нет | `["text","json_object","json_schema"]`; Make default: "text" |
| `json_schema_name` | string | по условию | При response_format=json_schema |
| `json_schema` | object | по условию | При response_format=json_schema |
| `max_output_tokens` | integer | нет | Make default: 8192 |
| `temperature` | number | нет | Make default: 0.7 |

JSON-шаблон:

```json
{
  "model_key": "moon_gpt",
  "prompt": "Return the word OK.",
  "max_output_tokens": 16,
  "async_mode": true
}
```

### upload_file_from_url

`POST /franklab/api/make/dola/files/from-url`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `url` | string | да | — |
| `filename` | string | нет | — |
| `purpose` | string | нет | Make default: "user_data" |

JSON-шаблон:

```json
{
  "url": "https://example.com/owned-synthetic-media.png"
}
```

### upload_file

`POST /franklab/api/make/dola/files/upload`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `filename` | string | да | — |
| `file_data` | string | нет | — |
| `file` | binary | нет | — |
| `mime_type` | string | нет | — |
| `purpose` | string | нет | — |

JSON-шаблон:

```json
{
  "filename": "synthetic.png",
  "mime_type": "image/png",
  "file_data": "REPLACE_WITH_BASE64"
}
```

```bash
curl --fail-with-body --max-time 120 -X POST \
  -H "X-API-Key: ${FRANKLAB_KEY:?Set your account key}" \
  -F 'file=@./synthetic.png' -F 'filename=synthetic.png' \
  "$FRANKLAB_BASE_URL/make/dola/files/upload"
```

### get_file

`GET /franklab/api/make/dola/files/:file_id`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `file_id` | string | да | path |

### delete_file

`DELETE /franklab/api/make/dola/files/:file_id`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `file_id` | string | да | path |

### task_status

`GET /franklab/api/make/dola/tasks/:billing_task_id`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `billing_task_id` | string | да | path |

### models

`GET /franklab/api/make/dola/models`

Тело и параметры не требуются.

### list_files

`GET /franklab/api/make/dola/files`

Тело и параметры не требуются.

## ORKESTR

Проверка `lyrics` 8 сентября 2026 завершилась отказом из-за обязательного callback у поставщика; резерв возвращён, но публичный опрос продолжал показывать `processing`. Эта операция требует исправления. Не повторяйте отправку из-за зависшего статуса.

18 операций музыки/текста/обработки и опрос. Выбирайте путь запроса; поле Make `operation` в JSON не передаётся. Требуется ключ партнёра; старые сервисные ключи отклоняются. Большинство Suno-операций принимают `model`: `V5`, `V4_5PLUS`, `V4_5ALL`, `V4_5`, `V4`. Только generate добавляет по умолчанию `V5`, `customMode=false`, `instrumental=false`.

REST **`taskId`** соответствует Make `sourceTaskId`, `name`/`description` — `personaName`/`personaDescription`. Передавайте ID собственных исходных задач и аудио из предыдущих результатов, а не промпт или произвольный UUID. Для upload-cover/extend/mashup нужны доступные URL собственных файлов `uploadUrl`/`uploadUrl1`/`uploadUrl2`. При `customMode=true` заполните поля текста, стиля и названия согласно выбранной модели. `continueAt`, `infillStartS`, `infillEndS`, `vocalStart`, `vocalEnd` измеряются в секундах; интервалы должны быть упорядочены и находиться внутри исходного аудио. Callback-маршрут задаётся сервисом.

Сохраните FrankLab `data.taskId`; опрашивайте `/make/orkestr/v2/tasks/:taskId` примерно раз в 5 секунд, ограничивая время. `queued`/`processing` — ожидание, `completed`/`failed` — остановка. Проверяйте `data.result` и `data.error`. Медиа обычно находятся в `data.result.task_result.audios`, `.videos`, `.images`; lyrics/style возвращают текст/JSON, а не обязательную ссылку на аудио. `timestamped_lyrics`, `boost_style`, `generate_persona` возвращают результат сразу. Поля `track1_*`/`track2_*` — проекции Make, не универсальные REST-поля.

Lyria: `model=clip` или `pro`. Clip имеет фиксированную длину 30 секунд; pro создаёт полный трек и воспринимает `duration_seconds` как пожелание, а не точную длину. Дополнительно поддерживается `output_format=mp3|wav`. Результат: `data.audio_url`, `lyrics_text`, `duration_seconds`, `interaction_id`. Стоимость зависит от аккаунта; отсутствие отдельного estimate-маршрута или final-cost поля не означает бесплатность.

| Действие | Метод | Путь |
|---|---|---|
| `poll` | GET | `/franklab/api/make/orkestr/v2/tasks/:taskId` |
| `generate` | POST | `/franklab/api/make/orkestr/v2/generate` |
| `extend` | POST | `/franklab/api/make/orkestr/v2/extend` |
| `upload_cover` | POST | `/franklab/api/make/orkestr/v2/upload-cover` |
| `upload_extend` | POST | `/franklab/api/make/orkestr/v2/upload-extend` |
| `add_instrumental` | POST | `/franklab/api/make/orkestr/v2/add-instrumental` |
| `add_vocals` | POST | `/franklab/api/make/orkestr/v2/add-vocals` |
| `replace_section` | POST | `/franklab/api/make/orkestr/v2/replace-section` |
| `mashup` | POST | `/franklab/api/make/orkestr/v2/mashup` |
| `lyrics` | POST | `/franklab/api/make/orkestr/v2/lyrics` |
| `timestamped_lyrics` | POST | `/franklab/api/make/orkestr/v2/timestamped-lyrics` |
| `separate_vocals` | POST | `/franklab/api/make/orkestr/v2/separate-vocals` |
| `generate_midi` | POST | `/franklab/api/make/orkestr/v2/generate-midi` |
| `convert_wav` | POST | `/franklab/api/make/orkestr/v2/convert-wav` |
| `music_video` | POST | `/franklab/api/make/orkestr/v2/music-video` |
| `cover_image` | POST | `/franklab/api/make/orkestr/v2/cover-image` |
| `boost_style` | POST | `/franklab/api/make/orkestr/v2/boost-style` |
| `generate_persona` | POST | `/franklab/api/make/orkestr/v2/generate-persona` |
| `lyria_music` | POST | `/franklab/api/make/orkestr/v2/lyria-music` |

### poll

`GET /franklab/api/make/orkestr/v2/tasks/:taskId`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | path |

### generate

`POST /franklab/api/make/orkestr/v2/generate`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model` | string | да | `["V5","V4_5PLUS","V4_5ALL","V4_5","V4"]` |
| `customMode` | boolean | нет | — |
| `instrumental` | boolean | нет | — |
| `prompt` | string | да | — |
| `style` | string | нет | — |
| `title` | string | нет | — |
| `negativeTags` | string | нет | — |
| `vocalGender` | string | нет | `["f","m"]` |
| `styleWeight` | number | нет | — |
| `weirdnessConstraint` | number | нет | — |
| `audioWeight` | number | нет | — |
| `personaId` | string | нет | — |

JSON-шаблон:

```json
{
  "model": "V5",
  "prompt": "A short calm synthetic test."
}
```

### extend

`POST /franklab/api/make/orkestr/v2/extend`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `audioId` | string | да | — |
| `defaultParamFlag` | boolean | нет | — |
| `model` | string | да | `["V5","V4_5PLUS","V4_5ALL","V4_5","V4"]` |
| `continueAt` | number | нет | — |
| `prompt` | string | нет | — |
| `style` | string | нет | — |
| `title` | string | нет | — |
| `negativeTags` | string | нет | — |
| `vocalGender` | string | нет | `["f","m"]` |
| `personaId` | string | нет | — |

JSON-шаблон:

```json
{
  "audioId": "REPLACE_WITH_OWNED_AUDIOID",
  "model": "V5"
}
```

### upload_cover

`POST /franklab/api/make/orkestr/v2/upload-cover`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `uploadUrl` | string | да | — |
| `model` | string | да | `["V5","V4_5PLUS","V4_5ALL","V4_5","V4"]` |
| `customMode` | boolean | нет | — |
| `instrumental` | boolean | нет | — |
| `prompt` | string | нет | — |
| `style` | string | нет | — |
| `title` | string | нет | — |
| `negativeTags` | string | нет | — |
| `vocalGender` | string | нет | `["f","m"]` |
| `personaId` | string | нет | — |

JSON-шаблон:

```json
{
  "uploadUrl": "https://example.com/owned-synthetic-audio.mp3",
  "model": "V5"
}
```

### upload_extend

`POST /franklab/api/make/orkestr/v2/upload-extend`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `uploadUrl` | string | да | — |
| `model` | string | да | `["V5","V4_5PLUS","V4_5ALL","V4_5","V4"]` |
| `defaultParamFlag` | boolean | нет | — |
| `instrumental` | boolean | нет | — |
| `continueAt` | number | да | — |
| `prompt` | string | нет | — |
| `style` | string | нет | — |
| `title` | string | нет | — |
| `negativeTags` | string | нет | — |
| `vocalGender` | string | нет | `["f","m"]` |
| `personaId` | string | нет | — |

JSON-шаблон:

```json
{
  "uploadUrl": "https://example.com/owned-synthetic-audio.mp3",
  "model": "V5",
  "continueAt": 1
}
```

### add_instrumental

`POST /franklab/api/make/orkestr/v2/add-instrumental`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `uploadUrl` | string | да | — |
| `title` | string | да | — |
| `tags` | string | да | — |
| `negativeTags` | string | нет | — |
| `model` | string | нет | `["V5","V4_5PLUS","V4_5ALL","V4_5","V4"]` |
| `vocalGender` | string | нет | `["f","m"]` |

JSON-шаблон:

```json
{
  "uploadUrl": "https://example.com/owned-synthetic-audio.mp3",
  "title": "Synthetic test",
  "tags": "REPLACE_WITH_OWNED_TAGS"
}
```

### add_vocals

`POST /franklab/api/make/orkestr/v2/add-vocals`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `uploadUrl` | string | да | — |
| `prompt` | string | да | — |
| `title` | string | да | — |
| `style` | string | да | — |
| `negativeTags` | string | нет | — |
| `model` | string | нет | `["V5","V4_5PLUS","V4_5ALL","V4_5","V4"]` |
| `vocalGender` | string | нет | `["f","m"]` |

JSON-шаблон:

```json
{
  "uploadUrl": "https://example.com/owned-synthetic-audio.mp3",
  "prompt": "A short calm synthetic test.",
  "title": "Synthetic test",
  "style": "REPLACE_WITH_OWNED_STYLE"
}
```

### replace_section

`POST /franklab/api/make/orkestr/v2/replace-section`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | — |
| `audioId` | string | да | — |
| `prompt` | string | да | — |
| `tags` | string | да | — |
| `title` | string | да | — |
| `infillStartS` | number | да | — |
| `infillEndS` | number | да | — |
| `negativeTags` | string | нет | — |
| `fullLyrics` | string | нет | — |

JSON-шаблон:

```json
{
  "taskId": "REPLACE_WITH_OWNED_TASKID",
  "audioId": "REPLACE_WITH_OWNED_AUDIOID",
  "prompt": "A short calm synthetic test.",
  "tags": "REPLACE_WITH_OWNED_TAGS",
  "title": "Synthetic test",
  "infillStartS": 1,
  "infillEndS": 2
}
```

### mashup

`POST /franklab/api/make/orkestr/v2/mashup`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `uploadUrl1` | string | да | — |
| `uploadUrl2` | string | да | — |
| `model` | string | да | `["V5","V4_5PLUS","V4_5ALL","V4_5","V4"]` |
| `customMode` | boolean | нет | — |
| `instrumental` | boolean | нет | — |
| `prompt` | string | нет | — |
| `style` | string | нет | — |
| `title` | string | нет | — |
| `negativeTags` | string | нет | — |
| `vocalGender` | string | нет | `["f","m"]` |

JSON-шаблон:

```json
{
  "uploadUrl1": "https://example.com/owned-synthetic-audio.mp3",
  "uploadUrl2": "https://example.com/owned-synthetic-audio-2.mp3",
  "model": "V5"
}
```

### lyrics

`POST /franklab/api/make/orkestr/v2/lyrics`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `prompt` | string | да | — |

JSON-шаблон:

```json
{
  "prompt": "A short calm synthetic test."
}
```

### timestamped_lyrics

`POST /franklab/api/make/orkestr/v2/timestamped-lyrics`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | — |
| `audioId` | string | да | — |

JSON-шаблон:

```json
{
  "taskId": "REPLACE_WITH_OWNED_TASKID",
  "audioId": "REPLACE_WITH_OWNED_AUDIOID"
}
```

### separate_vocals

`POST /franklab/api/make/orkestr/v2/separate-vocals`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | — |
| `audioId` | string | да | — |
| `type` | string | да | `["separate_vocal","split_stem"]` |

JSON-шаблон:

```json
{
  "taskId": "REPLACE_WITH_OWNED_TASKID",
  "audioId": "REPLACE_WITH_OWNED_AUDIOID",
  "type": "separate_vocal"
}
```

### generate_midi

`POST /franklab/api/make/orkestr/v2/generate-midi`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | — |
| `audioId` | string | нет | — |

JSON-шаблон:

```json
{
  "taskId": "REPLACE_WITH_OWNED_TASKID"
}
```

### convert_wav

`POST /franklab/api/make/orkestr/v2/convert-wav`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | — |
| `audioId` | string | да | — |

JSON-шаблон:

```json
{
  "taskId": "REPLACE_WITH_OWNED_TASKID",
  "audioId": "REPLACE_WITH_OWNED_AUDIOID"
}
```

### music_video

`POST /franklab/api/make/orkestr/v2/music-video`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | — |
| `audioId` | string | да | — |
| `author` | string | нет | — |
| `domainName` | string | нет | — |

JSON-шаблон:

```json
{
  "taskId": "REPLACE_WITH_OWNED_TASKID",
  "audioId": "REPLACE_WITH_OWNED_AUDIOID"
}
```

### cover_image

`POST /franklab/api/make/orkestr/v2/cover-image`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | — |

JSON-шаблон:

```json
{
  "taskId": "REPLACE_WITH_OWNED_TASKID"
}
```

### boost_style

`POST /franklab/api/make/orkestr/v2/boost-style`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `content` | string | да | — |

JSON-шаблон:

```json
{
  "content": "A short calm synthetic test."
}
```

### generate_persona

`POST /franklab/api/make/orkestr/v2/generate-persona`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | — |
| `audioId` | string | да | — |
| `name` | string | да | — |
| `description` | string | да | — |
| `vocalStart` | number | нет | — |
| `vocalEnd` | number | нет | — |
| `style` | string | нет | — |

JSON-шаблон:

```json
{
  "taskId": "REPLACE_WITH_OWNED_TASKID",
  "audioId": "REPLACE_WITH_OWNED_AUDIOID",
  "name": "Synthetic test",
  "description": "REPLACE_WITH_OWNED_DESCRIPTION"
}
```

### lyria_music

`POST /franklab/api/make/orkestr/v2/lyria-music`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `model` | string | да | `["clip","pro"]` |
| `prompt` | string | да | — |
| `instrumental` | boolean | нет | — |
| `lyrics` | string | нет | — |
| `language` | string | нет | — |
| `genre` | string | нет | — |
| `era` | string | нет | — |
| `instruments` | string | нет | — |
| `song_structure` | string | нет | — |
| `timed_events` | string | нет | — |
| `vocal_profile` | string | нет | — |
| `key_scale` | string | нет | — |
| `mood` | string | нет | — |
| `duration_seconds` | number | нет | — |
| `reference_images` | array | нет | `image_url:string`; items: collection |

JSON-шаблон:

```json
{
  "model": "clip",
  "prompt": "Calm original instrumental piano.",
  "instrumental": true
}
```

## VOLNA

Все 19 действий Make отправляются в `POST /make/volna/tts`. Всегда указывайте `operation`; для действий вне TTS оно обязательно. Выбор: диалог/TTS/Turbo ElevenLabs, TTS Google Gemini, Seed Audio, TTS Grok, распознавание, эффекты, изоляция, голоса, дубляж. Список голосов/моделей проверяет метаданные, а не генерацию аудио. Создание/дизайн/сохранение голоса и usage stats отклоняют старые сервисные ключи.

ElevenLabs `voice_id` берите из `/v1/elevenlabs/voices-rpc`, Grok — из `/v1/xai/voices-rpc`; результат RPC: `data:[{id,name,…}]`. Не придумывайте ID голоса. Google `google_tts_mode=single` использует `google_voice_name`; `multi` — `speaker_1_name`, `speaker_1_voice`, `speaker_2_name`, `speaker_2_voice` с совпадающими метками в `text`. Голос Grok по умолчанию — `eve`. `xai_tts_settings` и переключатели STT существуют только в интерфейсе Make.

STT и изоляция принимают собственный `audio_url`; дубляж — `source_url` и `target_lang`. Передавайте JSON boolean/number, а `keyterm` — массив строк. Для клонирования REST использует `name`/`description` (алиасы Make clone_name/clone_description нормализуются) и разрешённый `file_url`. Созданный дизайн сохраняется отдельным действием с `voice_name`/`generated_voice_id`.

Seed Audio: `text_prompt` до 3000 символов, максимум 3 `references`. Элемент задаёт `reference_type=audio|image` и один источник: `speaker`, `audio_url`, `audio_data` либо `audio_file_data`/`audio_file_name`; для изображений — соответствующие image-поля. Не передавайте все альтернативы одновременно. Формат mp3/wav/pcm/ogg_opus, частота 8000/16000/24000/32000/44100/48000. Темп/громкость -50..100, высота -12..12. Переключатель метаданных REST — **boolean `audio_aigc_metadata_enable`**, не Make `audio_aigc_metadata_mode`.

При наличии `data.taskId` опрашивайте `/make/volna/tasks/:taskId` примерно раз в 5 секунд до `completed`/`failed`; у синхронного результата/метаданных ID может отсутствовать. Проверяйте `data.result`, `audio_url`/`audioUrl`, `resultUrl`, `text`, `words`, `segments`, `duration_seconds`, доступные поля биллинга и транзакции. Make нормализует разные формы ответа. Тайм-аут платного запроса не разрешает повторную отправку.

| Действие | Метод | Путь |
|---|---|---|
| `text-to-dialogue` | POST | `/franklab/api/make/volna/tts` |
| `text-to-speech` | POST | `/franklab/api/make/volna/tts` |
| `text-to-speech-turbo` | POST | `/franklab/api/make/volna/tts` |
| `google-3-1-tts` | POST | `/franklab/api/make/volna/tts` |
| `seed-audio-1-0` | POST | `/franklab/api/make/volna/tts` |
| `xai-text-to-speech` | POST | `/franklab/api/make/volna/tts` |
| `speech-to-text` | POST | `/franklab/api/make/volna/tts` |
| `xai-speech-to-text` | POST | `/franklab/api/make/volna/tts` |
| `google-speech-to-text` | POST | `/franklab/api/make/volna/tts` |
| `sound-effect` | POST | `/franklab/api/make/volna/tts` |
| `audio-isolation` | POST | `/franklab/api/make/volna/tts` |
| `voice-list` | POST | `/franklab/api/make/volna/tts` |
| `xai-voice-list` | POST | `/franklab/api/make/volna/tts` |
| `voice-clone` | POST | `/franklab/api/make/volna/tts` |
| `voice-design` | POST | `/franklab/api/make/volna/tts` |
| `voice-design-save` | POST | `/franklab/api/make/volna/tts` |
| `dubbing` | POST | `/franklab/api/make/volna/tts` |
| `usage-stats` | POST | `/franklab/api/make/volna/tts` |
| `models-list` | POST | `/franklab/api/make/volna/tts` |
| `poll` | GET | `/franklab/api/make/volna/tasks/:taskId` |
| `getVoices RPC` | GET | `/franklab/api/v1/elevenlabs/voices-rpc` |
| `getGrokVoices RPC` | GET | `/franklab/api/v1/xai/voices-rpc` |

### text-to-dialogue

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"text-to-dialogue"` |
| `text` | string | да | — |
| `voice_id` | string | да | — |
| `voice_id_2` | string | нет | — |
| `seed` | number | нет | — |

JSON-шаблон:

```json
{
  "operation": "text-to-dialogue",
  "text": "A short calm synthetic test.",
  "voice_id": "REPLACE_WITH_OWNED_VOICE_ID"
}
```

### text-to-speech

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"text-to-speech"` |
| `text` | string | да | — |
| `voice_id` | string | да | — |
| `model_id` | string | нет | `["eleven_multilingual_v2","eleven_flash_v2_5","eleven_v3"]` |
| `language_code` | string | нет | — |
| `stability` | number | нет | — |
| `similarity_boost` | number | нет | — |
| `style` | number | нет | — |
| `speed` | number | нет | — |
| `output_format` | string | нет | `["mp3_44100_128","mp3_44100_192","pcm_16000","pcm_22050","pcm_44100"]` |

JSON-шаблон:

```json
{
  "operation": "text-to-speech",
  "text": "A short calm synthetic test.",
  "voice_id": "REPLACE_WITH_OWNED_VOICE_ID"
}
```

### text-to-speech-turbo

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"text-to-speech-turbo"` |
| `text` | string | да | — |
| `voice_id` | string | да | — |
| `language_code` | string | нет | — |
| `stability` | number | нет | — |
| `similarity_boost` | number | нет | — |
| `style` | number | нет | — |
| `speed` | number | нет | — |

JSON-шаблон:

```json
{
  "operation": "text-to-speech-turbo",
  "text": "A short calm synthetic test.",
  "voice_id": "REPLACE_WITH_OWNED_VOICE_ID"
}
```

### google-3-1-tts

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"google-3-1-tts"` |
| `google_tts_mode` | string | да | `["single","multi"]` |
| `text` | string | по условию | При google_tts_mode=single |
| `google_voice_name` | string | по условию | `["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"]`; При google_tts_mode=single |
| `style_prompt` | string | нет | При google_tts_mode=single |
| `output_format` | string | нет | `["wav_24000_16","mp3_44100_128","mp3_44100_192","opus_48000_64"]`; При google_tts_mode=single |
| `request_id` | string | нет | При google_tts_mode=single |
| `text` | string | по условию | При google_tts_mode=multi |
| `speaker_1_name` | string | по условию | При google_tts_mode=multi |
| `speaker_1_voice` | string | по условию | `["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"]`; При google_tts_mode=multi |
| `speaker_2_name` | string | по условию | При google_tts_mode=multi |
| `speaker_2_voice` | string | по условию | `["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"]`; При google_tts_mode=multi |
| `style_prompt` | string | нет | При google_tts_mode=multi |
| `output_format` | string | нет | `["wav_24000_16","mp3_44100_128","mp3_44100_192","opus_48000_64"]`; При google_tts_mode=multi |
| `request_id` | string | нет | При google_tts_mode=multi |

JSON-шаблон:

```json
{
  "operation": "google-3-1-tts",
  "text": "Hello.",
  "google_tts_mode": "single",
  "google_voice_name": "Kore"
}
```

### seed-audio-1-0

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"seed-audio-1-0"` |
| `text_prompt` | string | да | — |
| `references` | array | нет | `reference_type, speaker, audio_url/audio_data/audio_file_data, audio_file_name, image_url/image_data/image_file_data, image_file_name`; items: collection |
| `audio_format` | string | нет | `["mp3","wav","pcm","ogg_opus"]`; Make default: "mp3" |
| `audio_sample_rate` | string | нет | `["8000","16000","24000","32000","44100","48000"]`; Make default: "44100" |
| `audio_speech_rate` | number | нет | — |
| `audio_loudness_rate` | number | нет | — |
| `audio_pitch_rate` | number | нет | — |
| `audio_enable_subtitle` | boolean | нет | — |
| `audio_aigc_watermark` | boolean | нет | — |
| `audio_aigc_metadata_enable` | boolean | нет | `[false,true]`; Make default: false |
| `audio_content_producer` | string | нет | При audio_aigc_metadata_enable=true |
| `audio_produce_id` | string | нет | При audio_aigc_metadata_enable=true |
| `audio_content_propagator` | string | нет | При audio_aigc_metadata_enable=true |
| `audio_propagate_id` | string | нет | При audio_aigc_metadata_enable=true |

JSON-шаблон:

```json
{
  "operation": "seed-audio-1-0",
  "text_prompt": "A short calm synthetic test."
}
```

### xai-text-to-speech

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"xai-text-to-speech"` |
| `text` | string | да | — |
| `voice_id` | string | нет | Make default: "eve" |
| `language` | string | нет | `["auto","ru","en","es","de","fr","it","ja","pt-BR"]`; Make default: "auto" |
| `output_format` | string | нет | `["mp3_44100_128","mp3_44100_192","wav_24000","pcm_24000"]`; Make default: "mp3_44100_128" |
| `with_timestamps` | boolean | нет | — |
| `speed` | string | нет | `["0.8","0.9","1","1.1","1.2"]`; Make default: "1" |

JSON-шаблон:

```json
{
  "operation": "xai-text-to-speech",
  "text": "Hello.",
  "voice_id": "eve",
  "output_format": "mp3_44100_128"
}
```

### speech-to-text

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"speech-to-text"` |
| `audio_url` | string | да | — |
| `language_code` | string | нет | — |
| `diarize` | boolean | нет | — |
| `num_speakers` | number | нет | — |

JSON-шаблон:

```json
{
  "operation": "speech-to-text",
  "audio_url": "https://example.com/owned-synthetic-audio.mp3"
}
```

### xai-speech-to-text

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"xai-speech-to-text"` |
| `audio_url` | string | да | — |
| `language` | string | нет | `["auto","ru","en","es","de","fr","it","ja","pt-BR"]`; Make default: "auto" |
| `format` | boolean | нет | — |
| `diarize` | boolean | нет | — |
| `filler_words` | boolean | нет | — |
| `chunked_recovery` | boolean | нет | — |
| `keyterm` | array | нет | items: string |

JSON-шаблон:

```json
{
  "operation": "xai-speech-to-text",
  "audio_url": "https://example.com/owned-synthetic-audio.mp3"
}
```

### google-speech-to-text

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"google-speech-to-text"` |
| `audio_url` | string | да | — |
| `language_code` | string | нет | `["auto","ru-RU","en-US","en-GB","de-DE","fr-FR","es-ES","it-IT","pt-BR","ja-JP","ko-KR","uk-UA"]`; Make default: "auto" |
| `diarize` | boolean | нет | — |
| `format` | boolean | нет | — |
| `keyterm` | array | нет | items: string |

JSON-шаблон:

```json
{
  "operation": "google-speech-to-text",
  "audio_url": "https://example.com/owned-synthetic-audio.mp3"
}
```

### sound-effect

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"sound-effect"` |
| `text` | string | да | — |
| `duration_seconds` | number | нет | — |
| `prompt_influence` | number | нет | — |

JSON-шаблон:

```json
{
  "operation": "sound-effect",
  "text": "A short calm synthetic test."
}
```

### audio-isolation

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"audio-isolation"` |
| `audio_url` | string | да | — |

JSON-шаблон:

```json
{
  "operation": "audio-isolation",
  "audio_url": "https://example.com/owned-synthetic-audio.mp3"
}
```

### voice-list

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"voice-list"` |

JSON-шаблон:

```json
{
  "operation": "voice-list"
}
```

### xai-voice-list

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"xai-voice-list"` |

JSON-шаблон:

```json
{
  "operation": "xai-voice-list"
}
```

### voice-clone

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"voice-clone"` |
| `name` | string | да | — |
| `description` | string | нет | — |
| `file_url` | string | да | — |

JSON-шаблон:

```json
{
  "operation": "voice-clone",
  "name": "Synthetic test",
  "file_url": "https://example.com/owned-synthetic-audio.mp3"
}
```

### voice-design

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"voice-design"` |
| `voice_description` | string | да | — |
| `design_text` | string | нет | — |
| `guidance_scale` | number | нет | — |
| `should_enhance` | boolean | нет | — |

JSON-шаблон:

```json
{
  "operation": "voice-design",
  "voice_description": "REPLACE_WITH_OWNED_VOICE_DESCRIPTION"
}
```

### voice-design-save

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"voice-design-save"` |
| `voice_name` | string | да | — |
| `generated_voice_id` | string | да | — |
| `voice_description` | string | нет | — |

JSON-шаблон:

```json
{
  "operation": "voice-design-save",
  "voice_name": "REPLACE_WITH_OWNED_VOICE_NAME",
  "generated_voice_id": "REPLACE_WITH_OWNED_GENERATED_VOICE_ID"
}
```

### dubbing

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"dubbing"` |
| `source_url` | string | да | — |
| `target_lang` | string | да | — |
| `source_lang` | string | нет | — |
| `dubbing_name` | string | нет | — |
| `num_speakers` | number | нет | — |

JSON-шаблон:

```json
{
  "operation": "dubbing",
  "source_url": "https://example.com/owned-synthetic-audio.mp3",
  "target_lang": "en"
}
```

### usage-stats

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"usage-stats"` |

JSON-шаблон:

```json
{
  "operation": "usage-stats"
}
```

### models-list

`POST /franklab/api/make/volna/tts`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `operation` | string | да | `"models-list"` |

JSON-шаблон:

```json
{
  "operation": "models-list"
}
```

### poll

`GET /franklab/api/make/volna/tasks/:taskId`

| REST-поле | Тип | Обязательно | Значения / условия |
|---|---|---|---|
| `taskId` | string | да | path |

### getVoices RPC

`GET /franklab/api/v1/elevenlabs/voices-rpc`

Тело и параметры не требуются.

### getGrokVoices RPC

`GET /franklab/api/v1/xai/voices-rpc`

Тело и параметры не требуются.

## Дополнительные маршруты подключения и результата

| Модуль | Метод и путь | Параметры |
|---|---|---|
| JUPITER | `GET /franklab/api/v1/images/omni-image` | — |
| KUSOK v.2 | `GET /franklab/api/v1/general/advanced-custom-elements` | — |
| ORKESTR | `GET /franklab/api/v1/suno/generate/record-info` | `taskId` (query) |
| VOLNA | `GET /franklab/api/make/volna/dubbing/:dubbingId` | `dubbingId` (path) |
| VOLNA | `GET /franklab/api/make/volna/dubbing/:dubbingId/audio/:languageCode` | `dubbingId` (path), `languageCode` (path) |

Запрос подключения с несуществующим task ID может вернуть 404: это не проверка генерации. Для новых задач используйте статус-маршрут операции, которая вернула ID.

## Далее

Выберите одну операцию, проверьте ключ/баланс/доступную оценку, выполните минимальный запрос со своими синтетическими данными и сохраните ID. Затем проверьте итоговый результат и списание. [Порядок интеграции](/docs/integration) · [Ошибки](/docs/errors) · [Поддержка](/docs/contacts).