# Artillect — API & MCP features (Studio layers)

> Mirror of [/docs/features](https://app.artillect.pro/docs/features).
> Marketing stories: [/docs/use-cases](https://app.artillect.pro/docs/use-cases).

Edit source: `src/lib/docs/featuresCatalog.ts`; build: `pnpm knowledge:control build --write`.

---

## Внешние агенты и Provider + MCP

Как подключить Hermes/OpenCode: роли, независимые подключения, этапы и зачем они нужны.

<a id="ft-provider-media-agent"></a>

### Provider + MCP: модели и медиа для агента (`provider-media-agent`)

Hermes / OpenCode думает через Provider, создаёт медиа через MCP и исполняет задачи в harness.

Surfaces: api, mcp, cli

Нужны только модели для кода/чата — подключите Provider. Нужны только медиа у уже настроенного агента — подключите MCP, менять его LLM не обязательно.
Оба подключения полезны для лендинга с оригинальными фото, рекламного комплекта с видео/озвучкой или игровых ассетов: агент связывает код и медиа, а проект сохраняет результат для Studio.
Provider — LLM inference: Chat Completions, Responses, Anthropic Messages; возвращает ответы и предложения tool calls, сам инструменты не исполняет.
MCP — инструменты Artillect: каталог, estimate, генерация изображений/видео/аудио/3D, get_task, проекты и доставка ассетов.
Harness (Hermes, OpenCode и другие клиенты) — агентский цикл: вызывает инструменты, а при наличии разрешённых shell/files пишет код и скачивает файлы.
Поиск публичной справки: https://app.artillect.pro/knowledge/#knowledge-search ; рецепты MCP: https://app.artillect.pro/docs/mcp/recipes.md . Поиск не читает личные проекты и файлы.
Подключения независимы: MCP работает с другим LLM-провайдером; Provider работает без MCP и без генерации медиа. Вместе дают агенту модели и медиаматериалы одного сервиса.
Setup: /provider/, /provider/hermes/, /provider/opencode/; MCP: /docs/mcp; API-ключ: /api/. Provider URL https://app.artillect.pro/api/v1/provider; MCP URL https://app.artillect.pro/mcp.
Для совместного API-key setup: provider:write, models:read, images:write (также audio/mesh), videos:write, projects:write. files:write — для загрузки медиа и текстовых документов в хранилище. MCP отдельно поддерживает OAuth. Ключи не публикуйте и не коммитьте.
Хранилище доступно через Public API, MCP и CLI. Можно хранить инструкции агентов (AGENTS.md), описания skills (SKILL.md) и сопроводительные Markdown/TXT-файлы: UTF-8, до 10 МиБ на документ. REST: POST /api/v1/files/ или /files/from-url/, GET /api/v1/assets/?kind=file, GET/POST/DELETE /api/v1/assets/{asset_id}/. MCP: upload_file, list_media_assets, get_media_asset, copy_media_asset, delete_media_asset. CLI: upload, assets list/get/download/copy/delete. Сохраняйте ast_…; URL для скачивания получайте заново. Хранение файлов не запускает агента и не устанавливает skill; применение инструкций выполняет клиент.
Контекст Provider: приложение хранит историю и отправляет нужные сообщения в каждом запросе. Prompt caching выполняет провайдер модели через OpenRouter; Artillect не подменяет его собственной памятью диалога. В Chat Completions для anthropic/* без явных настроек добавляется cache_control: ephemeral; явные настройки клиента сохраняются. В native Messages/Responses клиент передаёт настройки своего протокола. Cache hit зависит от модели, совпадения префикса, срока жизни и маршрута; session_id/X-Session-Id помогает закрепить маршрут, но не восстанавливает историю. Фактические cached_tokens/cache_write_tokens и usage.cost отражают чтение/запись кэша. Файл в хранилище не становится кэшем контекста автоматически.
Бесплатно напрямую: GET /api/v1/provider/models/, GET /api/v1/me/; MCP initialize/tools list, get_started/get_balance. Это auth/discovery, не проверка платного inference. Сообщение LLM-агенту оплачивается, даже если инструмент бесплатный.
Provider использует личный накопительный ledger: округляется общая стоимость, новый запрос списывает её прирост. Старые запросы остаются по прежней политике. Studio/media тарифы не меняются; project media может использовать другой баланс. Общего автоматического жёсткого бюджета LLM+media нет.
GET /api/v1/provider/requests/?id=<X-Artillect-Request-Id> с тем же user/API key и provider:write показывает исход и расчёт. Status lookup не воспроизводит ответ; inference idempotent replay отсутствует. При неоднозначном обрыве сначала status, не слепой retry.
MCP image/poster blocks предназначены user+assistant, но передачу байтов модели и показ превью решает host. Нужны vision-модель и поддержка клиента; сервер не гарантирует одинаковый UI или автоматическое зрение.
Studio Assistant направляет запросы на создание сайта или целого приложения к Artillect Provider в Hermes/OpenCode; не пишет целое приложение в чате. Он объясняет подключение и помогает подготовить задачу; для медиа предлагает MCP. Его catalog tools не устанавливают конфиги и не исполняют shell/deployment; generation offers подтверждаются через UI. Внешний агент пишет код и собирает проект в пределах своих прав и бюджета.
Каждый запрос Provider получает короткий контекст Artillect и условных возможностей MCP. Он сохраняет инструкции клиента; наличие контекста не подключает MCP и не добавляет инструментов. Дополнительный вход учитывается в резерве и фактической стоимости LLM.

**Steps:**

1. discover: Выбрать проект, найти модель и входы в каталоге. Зачем: project_id сохраняет медиа для продолжения в Studio; capabilities.input в живом Provider /models определяет vision.
2. estimate: Оценить точные параметры каждого ассета; сверить баланс и авторизованный бюджет. Зачем: Оценка до submit помогает контролировать расходы; уже разрешённый бюджет не требует повторных подтверждений.
3. submit: Сериализовать generate_*; заранее сохранить стабильный idempotency_key, затем task_id. Зачем: Media submit — платный. Тот же payload/key защищает повтор в пределах 24 часов; после окна сначала сверить историю.
4. poll: get_task с task_id/poll_args до terminal; ошибка останавливает polling, успех требует media_urls. Зачем: Асинхронная задача продолжается после обрыва; повторный submit может купить дубликат.
5. deliver: Показать результат; в coding host скачать существующий TASK_ID через artillect generate wait TASK_ID --out public/assets --json; вести artillect-assets.json. Зачем: Manifest хранит project/task IDs и проверенные local paths без ключей/capability URLs. Сбой скачивания чинится повторной доставкой, готовый файл переиспользуется.
6. verify: Проверить реальные файлы и сайт сборкой/тестами; скриншоты — только при поддержке vision в host. Зачем: Постер — один кадр, не просмотр видео. Сборка сайта и публикация различаются; hosting доступ и разрешение нужны отдельно.

**Agent playbook:**

- discover: Выбрать проект, найти модель и входы в каталоге. Зачем: project_id сохраняет медиа для продолжения в Studio; capabilities.input в живом Provider /models определяет vision.
- estimate: Оценить точные параметры каждого ассета; сверить баланс и авторизованный бюджет. Зачем: Оценка до submit помогает контролировать расходы; уже разрешённый бюджет не требует повторных подтверждений.
- submit: Сериализовать generate_*; заранее сохранить стабильный idempotency_key, затем task_id. Зачем: Media submit — платный. Тот же payload/key защищает повтор в пределах 24 часов; после окна сначала сверить историю.
- poll: get_task с task_id/poll_args до terminal; ошибка останавливает polling, успех требует media_urls. Зачем: Асинхронная задача продолжается после обрыва; повторный submit может купить дубликат.
- deliver: Показать результат; в coding host скачать существующий TASK_ID через artillect generate wait TASK_ID --out public/assets --json; вести artillect-assets.json. Зачем: Manifest хранит project/task IDs и проверенные local paths без ключей/capability URLs. Сбой скачивания чинится повторной доставкой, готовый файл переиспользуется.
- verify: Проверить реальные файлы и сайт сборкой/тестами; скриншоты — только при поддержке vision в host. Зачем: Постер — один кадр, не просмотр видео. Сборка сайта и публикация различаются; hosting доступ и разрешение нужны отдельно.
- Use the shared Provider + MCP guide. Explain or act only with the host's actual tools, existing authorization and budget. Studio explanation does not grant shell/deployment privileges.

## Аккаунт и деньги

Тот же Studio-баланс и каталог моделей. Сначала me/balance/estimate — потом любой generate. Ключи и MCP OAuth живут здесь же.

<a id="ft-cloud-storage"></a>

### Облачное хранилище (`cloud-storage`)

Медиа, документы, инструкции агентов и skills в одном хранилище.

Surfaces: studio, api, mcp, cli

/storage — загрузка, поиск и скачивание своих файлов и результатов. Проектные файлы доступны по правам проекта.
Храните инструкции агентов AGENTS.md, определения skills SKILL.md и другие Markdown/TXT-документы в UTF-8, до 10 МиБ. Сохранение не запускает агента и не подключает инструкции к модели автоматически.
Public API: POST /api/v1/files/, GET /api/v1/assets/?kind=file, GET/POST/DELETE /api/v1/assets/{asset_id}/. MCP: upload_file, list_media_assets, get_media_asset, copy_media_asset, delete_media_asset. CLI: upload, assets list/get/download/copy/delete.
Публичные ссылки для передачи файлов вне проекта пока не реализованы.

**Steps:**

1. Откройте /storage для работы с файлами.

**Agent playbook:**

- Storage is available via Public API, MCP and CLI. Agent instructions and skill definitions are stored Markdown/text documents, loaded by the host explicitly. Preserve ast_… and resolve a fresh URL with get_media_asset; do not treat storage as automatic agent execution or prompt caching.

<a id="ft-project-archive-trash"></a>

### Архив и корзина проектов (`project-archive-trash`)

Архив сохраняет проект, корзина даёт время восстановить его.

Surfaces: studio

Архив и корзина открываются шторкой из проводника, нижнего меню и хранилища; полные страницы /projects/archive и /projects/trash.
Архивный проект можно вернуть в проводник. Удалённый проект можно восстановить в течение 7 дней; окончательное удаление необратимо.
Автоматическая очистка и физическое освобождение media требуют работающих purge workers; наличие корзины не доказывает, что worker включён. Не обещайте освобождение байтов сразу после скрытия строки.

**Steps:**

1. Откройте архив или корзину → выберите восстановление проекта. Для полного экрана используйте ссылку в шторке.

**Agent playbook:**

- Link to the correct page, distinguish archive from deletion, never execute irreversible purge on behalf of a knowledge answer.

<a id="ft-public-profile"></a>

### Профиль, никнейм и публичная страница (`public-profile`)

Имя, аватар, о себе, сайт и соцсети; публикация по согласию.

Surfaces: studio

Поля профиля сохраняются на сервере. Уникальный никнейм задаёт адрес /u/{nickname}; публичная страница доступна только при включённой публикации профиля.
На публичной странице показываются имя, никнейм, аватар и выбранные сведения профиля; email, баланс и личные файлы не публикуются. Существующие аккаунты по умолчанию приватны.

**Steps:**

1. Откройте /profile → редактируйте сведения и никнейм → при желании включите публичность → сохраните.

**Agent playbook:**

- Do not imply that choosing a handle publishes the account. Never infer a private profile URL from unrelated identity data.

<a id="ft-auth-keys"></a>

### Ключи и OAuth (`auth-keys`)

Bearer art_… или MCP OAuth scope mcp. UI: /api · /docs/mcp.

Surfaces: api, mcp

Кредиты = Studio. Device flow для CI. HTTP /mcp без Bearer/OAuth → 401 (нет env-fallback).
get_me — кто владелец ключа; тот же identity, что Studio.

**Steps:**

1. Создать ключ на /api или подключить /mcp → Authorization.
2. MCP/API: get_me, get_balance.

**Agent playbook:**

- Never print full API keys. On 401 → send user to /api or /docs/mcp.

<a id="ft-estimate-balance"></a>

### estimate + get_balance (`estimate-balance`)

Цена до списания; daily spend cap на ключ.

Surfaces: api, mcp

429 SPEND_CAP_EXCEEDED / RATE_LIMITED — остановите параллельные submit.
estimate type=audio|mesh без prompt отдаёт flat cost (DX).

**Steps:**

1. get_balance → estimate → generate_*.

**Agent playbook:**

- Always estimate video/upscale unless user already approved spend.

<a id="ft-model-pick"></a>

### recommend_model + list_models (`model-pick`)

Каталог живой — не хардкодьте slug.

Surfaces: api, mcp

recommend_model = эвристика; источник правды = GET /models / list_models.

**Steps:**

1. recommend_model → list_models → estimate → generate_*.

**Agent playbook:**

- Do not skip catalog check for obscure slugs.

## Проекты и коллаб

Как в Studio: проекты, папки, роли, лимиты. Сюда кладёте генерации (project_id) и Element Library. API, MCP и CLI используют один lifecycle/collaboration contract.

<a id="ft-projects-crud"></a>

### Проекты CRUD (`projects-crud`)

list / create / get / patch / delete. MCP и CLI покрывают тот же lifecycle.

Surfaces: api, mcp

Public API, MCP и CLI поддерживают один CRUD lifecycle; transport names могут отличаться.
Личный hub удалять нельзя.

**Steps:**

1. GET/POST /api/v1/projects/ · MCP list_projects.
2. GET/PATCH/DELETE /api/v1/projects/{id}/ · MCP get/update/delete_project.

**Agent playbook:**

- Prefer list_projects then get_project. Use create/update/delete only with explicit user intent.

<a id="ft-project-members"></a>

### Участники и роли (`project-members`)

Invite / role / token_limit / leave — как в UI проекта.

Surfaces: api, mcp, cli, studio

GET roles · members CRUD · PATCH me (is_favorite). MCP и CLI используют те же member operations.

**Steps:**

1. GET /projects/roles/ → POST …/members/ → PATCH/DELETE …/members/{userId}/; MCP/CLI дают те же действия.

**Agent playbook:**

- Owner/admin only for invites. On 403 explain Studio role limits.

<a id="ft-project-billing"></a>

### project_id / billing_source / analytics (`project-billing`)

Кладём джобы в проект; кто платит — owner|self; analytics/billing read.

Surfaces: api, mcp

На generate_*: project_id + billing_source. GET …/analytics/ и …/billing/ — REST.

**Steps:**

1. list_projects → generate_* с project_id (+ tag_ids).
2. Опционально GET …/analytics/ · …/billing/.

**Agent playbook:**

- Include project_id when user works inside a project.

## Библиотека генераций

Лента проекта, поиск, теги, лайки, избранное, copy/move/delete — то, чем живёт галерея Studio. Grouping (по автору/дате/тегу) в Public API нет — только в Studio feed/meta.

<a id="ft-history-list"></a>

### Лента и история (`history-list`)

Project feed: q / tag_ids / dates. Modality list: limit/cursor/source.

Surfaces: api, mcp

GET /projects/{id}/generations/ — главный Studio-паритет: q (≥2), tag_ids (AND), date/date_from/date_to, mine_only, source, kind.
GET /{images|videos|…}/generations/ — плоская история ключа с общими status/job_id/source/date filters.
MCP и CLI передают те же list filters (включая q/date/status/job_id); API остаётся каноническим transport contract.
Grouping / feed meta (author|date|service|tag) — только Studio UI, не Public API.

**Steps:**

1. Лента: GET …/projects/{id}/generations/?q=hero&tag_ids=1,2&source=all.
2. MCP: list_project_generations или list_*_generations.

**Agent playbook:**

- Never fabricate prior results — only list/get responses.
- Use the same filters across API, MCP and CLI; when a new filter is added, update the shared contract and parity test.
- Do not invent group_by — not in Public API.

<a id="ft-project-tags"></a>

### Теги проекта (`project-tags`)

CRUD тегов + tag_ids на submit + assign на существующую gen.

Surfaces: api, mcp, cli

Как цветные метки в Studio. До 10 custom на проект, имя ≤10 символов. Лайки/архив — не в tag_ids.
Пайплайн: create_project_tag / POST …/tags/ → generate_* с project_id + tag_ids → тег сразу на новой gen.
Неверный tag id молча пропускается (submit не падает).

**Steps:**

1. create_project_tag { name } или POST /projects/{id}/tags/ → сохранить tag.id.
2. Submit с project_id + tag_ids: [id] (image/video/upscale/switchx/audio/mesh).
3. Или assign_generation_tags / POST …/generations/{genId}/tags/ { tag_ids, mode }.

**Agent playbook:**

- create_project_tag then pass tag_ids on the next generate with same project_id.
- Or assign_generation_tags on an existing gen_id. Verify with list_project_generations / feed ?tag_ids=.

<a id="ft-likes-favorites"></a>

### Лайки и избранное (`likes-favorites`)

Персональный like · favorited mask · GET favorites.

Surfaces: api, mcp, cli

Like ≠ custom tag. Favorites list проекта + system slug **favorite** через assign_generation_tags.

**Steps:**

1. like_generation (mode add|remove|toggle) или POST …/likes/.
2. list_project_favorites или GET …/favorites/?with_items=1.
3. Системный favorite: assign_generation_tags system_slugs=[**favorite**].

**Agent playbook:**

- like_generation for personal signal; create_project_tag / assign for shared labels.

<a id="ft-generation-repeat"></a>

### Повторить генерацию (`generation-repeat`)

Вернуть исходные параметры в форму генератора, проверить и запустить заново.

Surfaces: studio

В меню карточки генерации выберите «Повторить». Откроется соответствующий генератор; он восстановит модель, промпт и доступные исходные параметры и медиа из сохранённого запроса.
Повторить не запускает платную генерацию автоматически. Перед новым запуском проверьте восстановленные настройки и актуальную цену: каталог моделей или доступность исходных файлов могли измениться.
Перенос и копирование между проектами — отдельные действия. Повторить создаёт новую задачу, а не переносит старый результат; идентичный результат не гарантируется.

**Steps:**

1. Откройте меню ⋮ карточки в галерее или проекте и выберите «Повторить».
2. Проверьте модель, промпт, референсы, параметры и выбранный проект в открывшемся генераторе.
3. Нажмите кнопку генерации после проверки цены.

**Agent playbook:**

- Explain form restoration and distinguish it from automatic submission or copying a result.

<a id="ft-gen-library-ops"></a>

### Copy / move / delete (`gen-library-ops`)

Как в галерее: копия в другой проект, перенос, удаление.

Surfaces: api, mcp, cli

copy_generation → новый объект в destination; move_generation меняет project_id.
Move снимает теги (strip on move). delete_generation — hard-delete (осторожно).

**Steps:**

1. copy_generation { project_id, gen_id, destination_project_id }.
2. move_generation { project_id, gen_id, destination_project_id }.
3. delete_generation { project_id, gen_id }.

**Agent playbook:**

- Prefer copy when the source must stay. Confirm before delete_generation.

## Element Library

Каст персонажа между шотами (Soul-класс). Создали элемент → @Name в промптах с тем же project_id. Native elements — kling-3 / kling-o3.

<a id="ft-element-library"></a>

### Element Library (@name) (`element-library`)

list/create/get/update/delete/reorder через API, MCP и CLI.

Surfaces: api, mcp, cli

kind image|video + media_json. Soft-delete: delete_project_element. Gemini/audio create — не в Public API.

**Steps:**

1. list_projects → create_project_element → generate_* с @Name и project_id.
2. delete_project_element · reorder_project_elements / element-reorder.

**Agent playbook:**

- list_projects, list_project_elements (project_id may be string — coerced).
- create_project_element kind image|video; name without @.
- On generate_*: project_id + @Name. Prefer kling-3 / kling-o3 for native continuity.

## Файлы

Один upload → много generate / elements. Без отдельного CDN-аккаунта.

<a id="ft-files-upload"></a>

### upload_file (`files-upload`)

POST /files/ → { url, key }. Лимиты: image 150MB, video 200MB, audio 50MB. HEIC/HEIF, AVIF, WebP, TIFF, GIF и SVG приводятся к JPEG перед провайдером.

Surfaces: api, mcp, cli

Предпочтительнее чужих хостов: меньше SSRF-отказов.

**Steps:**

1. upload_file → url → generate_* / create_project_element.

**Agent playbook:**

- Prefer upload_file over random third-party hosts when possible.

## Генерация

Image / video / upscale / SwitchX / audio / mesh / chat — async (кроме chat). Тот же каталог, что Studio. Маркетинг-сюжеты → /docs/use-cases.

<a id="ft-model-settings"></a>

### Настройки моделей и повторение (`model-settings`)

Как выбрать параметры, проверить цену и восстановить нули и выключенные переключатели.

Surfaces: studio, api, mcp, cli

OmniHuman 2.0: выберите «Говорящий аватар», добавьте одно фото и аудио 4–300 секунд. Результат 720p; в настройках можно выключить водяной знак. OmniHuman 1.5 остаётся отдельным вариантом с 1080p.
PixVerse V6 Max: генерация по тексту или начальному кадру, 1–15 секунд, 360p/540p/720p/1080p, звук по желанию и Seed, включая 0. При начальном кадре пропорции определяются изображением.
HeyGen Video создаёт видео с нативным звуком: текст, один начальный кадр или до 9 изображений, 3 видео и 3 аудиореференсов. Длительность 5–15 секунд, 480p/768p/1080p/2K; кадровый и референсный режимы разделены. Доступны улучшение промпта, Seed и проверка безопасности. Это отдельная модель от HeyGen для липсинка.
VEED Dubbing находится в задаче «Перевести видео»: загрузите видео до 10 минут, выберите язык и обычный режим или Pro. Pro добавляет диалекты и настройку сходства голоса 0–10. В дополнительных настройках можно указать имена и термины. Цена считается по длительности исходного видео.
Недавно добавленные модели получают бейдж NEW в течение 14 дней. Порядок рекомендаций учитывает назначение модели; фильтр задачи сохраняет совместимость входов. Повторить сохраняет новые настройки, включая выключенные переключатели и нулевые значения.
Kling 4: создаёт видео 3–30 секунд в 720p/1080p. В «Раскадровке» задайте до 10 последовательных кадров, но не больше длительности в секундах плюс один. В режиме референсов можно сочетать до 10 изображений, 5 видео, 7 персонажей и 3 голосов — всего до 15 материалов; видео вместе до 30 секунд. Голоса загружаются как аудиореференсы @Audio1–3 и могут привязываться к персонажам. Ключевые кадры и референсы используются отдельно. Без входного видео звук создаётся автоматически; при наличии видео можно сохранить его звук. Стоимость с видео зависит от входной и выходной длительности. Повторить сохраняет кадры, голоса и настройки.
Midjourney: выберите модель в Изображениях и откройте «Инструменты Midjourney» в дополнительных настройках или меню результата. Там доступны смешивание 2–4 фото, редактирование, четыре промпта по фото, увеличение, вариации, повтор сетки, расширение, изменение композиции и редактирование области. Эти операции не занимают отдельные карточки в общем списке идей.
Редактирование области Midjourney: сначала увеличьте результат, затем запустите подготовку. После готовности в течение 30 минут отправьте PNG-маску и описание; прозрачные области меняются, белые сохраняются. Продолжение использует ту же задачу без повторного списания; без маски расширяется кадр.
Midjourney Video оживляет одно загруженное изображение или кадр из своей генерации Midjourney. Ролик около 5 секунд без звука, 480p/720p, спокойное или выраженное движение, 1/2/4 ролика, необязательный последний кадр. Изображение и исходная задача взаимоисключаются; авторежим доступен только для исходной задачи.
Настройки зависят от конкретной модели, операции и поверхности: проверяйте её актуальную карточку и совместимость входных слотов.
Семейный контекст LLM не равен лимиту текущего маршрута; кроме каталога действуют ограничения выбранного продукта.
Откройте дополнительные параметры в генераторе. Названия полей Studio и Public API могут отличаться; для интеграции используйте её reference.
Минимальная цена в каталоге не заменяет оценку выбранного запроса: размер, длительность, качество и референсы могут менять стоимость.
Повторить восстанавливает сохранённые модель, сценарий, порядок входов и настройки, включая seed=0 и false. Ноль не означает отсутствие выбора; Meshy Idle=0 — выбранная анимация.
Повторить не запускает платную задачу автоматически. Проверьте восстановленные файлы, проект и актуальную цену перед новым запуском.

**Steps:**

1. Выберите модель и проверьте текущую карточку с входами, выходами и ограничениями.
2. Проверьте явные нули и выключенные переключатели: seed=0 и false — сохранённые значения.
3. Проверьте стоимость выбранных параметров; после изменения входов получите новую оценку.
4. После Повторить проверьте форму и самостоятельно запустите новую задачу.

**Agent playbook:**

- Midjourney images use action imagine/blend/edits/describe/upscale/variation/high_variation/low_variation/reroll/zoom/pan/remix_strong/remix_subtle/inpaint. Follow-ups require source_generation_id in the same project and index 1–4; pan requires parent version 6/6.1/7, reshape requires 8.1/8.2, inpaint requires upscale. Poll awaiting_input, then action modal + job_id continues the existing reservation. Midjourney Video uses model midjourney-video with one start_image_url OR source_generation_id and index 0–3, animate_mode manual/auto, motion low/high, resolution 480p/720p, batch_size 1/2/4. Quote before submitting; the batch multiplies the video price.
- Use model_details and the exact surface catalog; do not infer fields, route context or price from a family name.
- Keep explicit zero/false values and input order. Form restoration is not a paid submit or copying the original result.

- [Особенности конкретных моделей](/docs/knowledge/guides/model-specific-settings.md)
- [Руководство настроек и Повторить](/docs/knowledge/guides/repeat-and-settings.md)
- [Текущие карточки Studio](/models/index.md)
- [Карточки и параметры API/MCP](/docs/models/index.md)

<a id="ft-image-from-prompt"></a>

### Картинка из текста (`image-from-prompt`)

prompt → job → URL. Defaults are explicit per adapter; query list_models before relying on one.

Surfaces: api, mcp

Асинхронный цикл: submit → poll. Не ждите SSE на images.

**Steps:**

1. estimate → generate_image / POST /images/generations/.
2. Полл get_task / GET …/images/generations/{id}/.

**Agent playbook:**

- Call get_balance or estimate before paid generate.
- Poll get_task until completed or failed. Never invent result URLs.

<a id="ft-image-tasks-and-ideas"></a>

### Задачи, шаблоны и идеи для изображений (`image-tasks-and-ideas`)

Задача выбирает операцию; идея дополняет промпт без смены модели.

Surfaces: studio

В /images доступны создание и правка, векторная графика, векторизация, удаление фона, смена ракурса, разложение на слои и примерка одежды. Задача определяет совместимые модели и обязательные входы.
В режиме облачка выбор задачи находится в верхней панели перед проектом. Для задач с отдельными входами используется полная форма; вернуться можно через «Создать или изменить».
Новые идеи добавляют текст к промпту, не выбирают другую модель. Старые ссылки и сохранённые шаблоны сохраняют отдельную миграционную логику.

**Steps:**

1. Откройте /images → выберите задачу → добавьте обязательные входы → проверьте модель и цену.
2. Для свободной смены модели после «Слоёв» выберите «Создать или изменить».

**Agent playbook:**

- Не обещай выбор произвольной модели для специализированной задачи и не путай идеи промптов со сменой операции.

<a id="ft-lora-library"></a>

### Свои LoRA: библиотека, обучение и версии (`lora-library`)

LoRa в /my-models: импорт весов или обучение на фото; применение только к совместимой базе.

Surfaces: studio, api, mcp

Ресурс содержит версии весов. В генераторе выбираются конкретная версия и сила применения. Допускаются готовые версии с проверенной структурой или подтверждением провайдера.
Поддерживаемые базы: Z-Image Turbo, Qwen Image 2512, FLUX.2 dev и LTX 2.3. Совпадение названия семейства не означает совместимость: веса Qwen Image 2512 не подходят Qwen Image 3; веса FLUX.2 dev не подходят Pro, Max или Flex.
При переходе на несовместимую модель выбранная LoRA сохраняется, но не применяется. Обучение LTX на фото задаёт внешность и стиль, а не движение или звук.
Public API предоставляет GET /api/v1/loras/ и /api/v1/loras/{id}/ для своих ресурсов. Image/video submit принимает lora_selection {id, version_id, scale} и проверяет владельца, готовность и совместимость. В MCP generate_image/generate_video этот объект передаётся через extra.lora_selection; отдельного инструмента списка LoRA пока нет.

**Steps:**

1. Откройте /my-models → создайте или импортируйте LoRA → дождитесь готовой версии → нажмите использовать.
2. Проверьте совместимую модель, версию, trigger phrase, силу и цену перед генерацией.

**Agent playbook:**

- Для импорта/обучения направь в /my-models: публичных write/train операций и Studio chat offer для этого нет. Для применения через API/MCP нужны реальные owned lor_/lov_ IDs и совместимая модель; не выдумывай IDs и list_loras tool.
- Не называй проверку структуры весов доказательством качества; обучение платное, цена зависит от базы и шагов и показана до отправки.

<a id="ft-image-to-image"></a>

### i2i / edit по референсу (`image-to-image`)

upload_file или HTTPS → input_urls.

Surfaces: api, mcp

Приватные хосты отклоняются SSRF-гардом.

**Steps:**

1. upload_file → generate_image с input_urls → get_task.

**Agent playbook:**

- upload_file → use returned url in generate_image.input_urls.

<a id="ft-generation-cancel-grace"></a>

### Отмена за 4 секунды (`generation-cancel-grace`)

Независимое pre-submit окно с возвратом токенов в Studio, REST, MCP и CLI.

Surfaces: studio, api, mcp, cli

Каждый submit получает собственный 4-секундный дедлайн и не блокирует следующие генерации.
Отмена допустима только пока задача не ушла провайдеру; после submit provider-side cancel отсутствует.

**Steps:**

1. Submit → получить id → вызвать modality-specific cancel endpoint/tool в первые 4 секунды.
2. После дедлайна использовать get_task / poll: отмена вернёт 409 GENERATION_NOT_CANCELLABLE.

**Agent playbook:**

- Если пользователь передумал сразу после submit — отправь cancel; ожидай refunded=true.
- Не обещай отмену после 4 секунд: оплаченная provider task продолжит выполняться.

<a id="ft-video-catalog"></a>

### Видео (каталог моделей) (`video-catalog`)

t2v / i2v / flf2v / motion / avatar… — list_models.

Surfaces: api, mcp

Дефолт MCP video — kling-3-turbo. Character continuity — Element Library + kling-3 / kling-o3.

**Steps:**

1. list_models → estimate type=video → generate_video → get_task.

**Agent playbook:**

- Prefer list_models / recommend_model. Set task when not t2v.

<a id="ft-upscale-switchx"></a>

### Upscale и SwitchX (`upscale-switchx`)

Отдельные поверхности, не «ещё один image model».

Surfaces: api, mcp

Тот же async-паттерн и биллинг.

**Steps:**

1. list_models → generate_upscale / generate_switchx → get_task.

**Agent playbook:**

- Tools: generate_upscale, generate_switchx. Public HTTPS or Artillect media only.

<a id="музыка-suno-audio-suno"></a>
<a id="ft-audio-suno"></a>

### Аудио: музыка, речь и обработка (`audio-suno`)

list_models → estimate → generate_audio → get_task. Audio использует polling.

Surfaces: api, mcp

Audio API включает музыку, речь, клонирование и обработку по объявленным model-operation. Входы и формат результата проверяйте в текущем audio catalog.
Дождитесь результата выбранной операции: аудио/видео-артефактов с URL либо текстовых artifacts. Входной audio_url для avatar/lipsync — отдельная сущность.

**Steps:**

1. estimate type=audio → generate_audio → get_task.

**Agent playbook:**

- generate_audio + get_task for asynchronous jobs; verify output_kind and expected artifacts (audio/video URLs or text). Do not invent CDN links or audio URLs for text output.

<a id="3d-mesh-meshy-mesh-meshy"></a>
<a id="ft-mesh-meshy"></a>

### 3D: генерация и обработка (`mesh-meshy`)

Текст, изображения или processing inputs → generate_mesh → get_task.

Surfaces: api, mcp

Модели и операции 3D различаются по входам и форматам. Используйте текущий mesh catalog; не переносите настройки Meshy на другое семейство. Audio/mesh используют polling.

**Steps:**

1. estimate type=mesh → generate_mesh → get_task.

**Agent playbook:**

- Use current list_models/model cards for exact input fields, format and processing operation; estimate before a paid submit.

<a id="ft-chat-llm"></a>

### Chat / LLM (`chat-llm`)

Sync JSON default; stream:true SSE для поддерживаемых chat-моделей; optional conversation store.

Surfaces: api, mcp

MCP chat_completion sync. create_chat_conversation → conversation_id на completions сохраняет ход в chat_messages (тот же store, что Studio LLM).
Клиент по-прежнему шлёт полный messages[]; store — persistence, не server-side memory injection.
Лимиты изображений индивидуальны: GET /api/v1/models возвращает max_images_per_message/max_images_total и источник для каждой chat-модели. Общий лимит 4/8 снят; null означает, что числовой потолок не подтверждён. Контекст и payload маршрута OpenRouter могут ограничить запрос раньше. API-тред не обрезает новые вложения до Studio-бюджета 4; запросы с изображениями рассчитываются по фактическому usage.

**Steps:**

1. create_chat_conversation → chat_completion({ conversation_id, messages }).
2. get_chat_messages / list_chat_conversations.
3. stream:true доступен для поддерживаемых chat-моделей; без Idempotency-Key.

**Agent playbook:**

- For multi-turn agents: create_chat_conversation once, pass conversation_id + full messages each turn.
- Prefer sync unless client needs SSE. On 429: backoff once.

## Операции и интеграции

Идемпотентность REST и webhooks для image/video/upscale/switchx. Audio/mesh — только poll; отмена доступна с возвратом только в первые 4 секунды до provider submit.

<a id="ft-idempotency"></a>

### Idempotency-Key (`idempotency`)

Безопасный retry POST (не для stream:true).

Surfaces: api

24h Redis. MCP hosts обычно не шлют ключ.

**Steps:**

1. UUID на клиенте → тот же заголовок при сетевом retry.

**Agent playbook:**

- Do not reuse the same key for a different body. Never with chat stream:true.

<a id="ft-webhooks"></a>

### Webhooks (`webhooks`)

Per-key HTTPS callback (image/video/upscale/switchx).

Surfaces: api, mcp

SSRF-guard на URL. Audio/mesh — poll only. MCP: get/upsert/delete/rotate/deliveries.

**Steps:**

1. POST /api/v1/webhooks/ → submit → deliveries.

**Agent playbook:**

- REST or MCP webhook tools. Reject private hosts. Poll as fallback.