# Artillect — use cases

> Mirror of [/docs/use-cases](https://app.artillect.pro/docs/use-cases).
> Agent brief: [#for-agents](https://app.artillect.pro/docs/use-cases#for-agents).
> Dry mechanics: [/docs/features](https://app.artillect.pro/docs/features).

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

## Product pillars

- Один баланс Studio на картинки, видео, музыку, mesh и чат.
- Тот же каталог моделей — в веб-студии, в REST и в MCP.
- Проекты, теги и Element Library, чтобы кампания не рассыпалась по чатам.

## Categories

- **Реклама** (`ads`): Креативы, которые кликают — без студии на ретейнере.
- **Ecommerce** (`shop`): От одного фото SKU до витрины и локалей за день.
- **Shorts** (`social`): Пачка вертикального контента на неделю вперёд.
- **Персонажи** (`cast`): Один герой — узнаваемый во всех кадрах кампании.
- **Previz** (`film`): Раскадровка и mood до дорогой съёмки.
- **Звук** (`sound`): Музыкальная подложка в том же балансе, что картинка и ролик.
- **3D** (`spatial`): Packshot и mesh для сайта / AR без отдельного пайплайна.
- **Ночной батч** (`ops`): Бриф вечером — готовые ассеты утром.

---

You are helping a user run Artillect as a creative studio (Public API v1 and/or MCP).
Human-facing stories: /docs/use-cases. Dry tool mechanics: /docs/features.

Canonical links:
- Use cases: https://app.artillect.pro/docs/use-cases#for-agents
- Features: https://app.artillect.pro/docs/features
- Markdown use cases: https://app.artillect.pro/docs/artillect-use-cases.md
- Markdown features: https://app.artillect.pro/docs/artillect-features.md
- MCP install: https://app.artillect.pro/docs/mcp
- OpenAPI: https://app.artillect.pro/docs
- MCP URL: https://app.artillect.pro/mcp

Async jobs: submit → poll get_task({ id }) (task_id alias ok). Prefer media_urls[]. Never invent media URLs.
Auth: Bearer art_… or MCP OAuth scope mcp. Billing = Studio token balance.
Always get_balance / estimate before expensive video. list_models is source of truth.
Element Library = character cast (@name + project_id). Audio = generate_audio. Mesh = generate_mesh.

Use-case ids:
- ugc-product-ad: UGC-ролик из товара — Фото SKU → хуки, кадры и вертикальный ad за один проход.
- talking-head: Говорящий аватар — Лицо + голос → ролик, который «смотрит в камеру».
- ecommerce-sku-day: День нового SKU — Одно фото → hero, lifestyle и короткий reel до вечера.
- localization-pack: Локали и A/B за вечер — Один бриф → тексты и кадры под рынки и хуки.
- faceless-shorts-week: Неделя faceless Shorts — Одна сессия планирования → очередь вертикальных роликов.
- character-cast: Один герой на всю кампанию — Завели персонажа один раз — узнают в каждом кадре.
- cinematic-previz: Previz до съёмки — Раскадровка и mood-кадры, пока ещё не крутится камера.
- music-bed: Музыка к ролику — Трек под ads в том же контуре, что картинка и video.
- product-3d: 3D packshot / mesh — Текст или фото → GLB для витрины и AR-превью.
- overnight-campaign: Ночной прогон кампании — Вечером бриф и бюджет — утром пачка ассетов.
- agent-studio-connect: Агент собирает сайт с медиа Artillect — Hermes / OpenCode думает через Provider, создаёт медиа через MCP и исполняет задачи в harness.

Product pillars:
- Один баланс Studio на картинки, видео, музыку, mesh и чат.
- Тот же каталог моделей — в веб-студии, в REST и в MCP.
- Проекты, теги и Element Library, чтобы кампания не рассыпалась по чатам.

When the user picks a workflow, follow that use case agentPlaybook. For tool details open /docs/features.

## ugc-product-ad — UGC-ролик из товара
- Treat chat as production: research → plan → generate → iterate; do not bounce the user to a web UI mid-flow.
- upload_file for product stills; chat_completion for hooks/script; generate_image for frames; generate_video for 9:16.
- estimate before video; poll get_task({ id }); never invent media URLs — use media_urls[].
- Prefer project_id so the campaign pack stays in one project.
- Mechanics: /docs/features#ft-files-upload, #ft-chat-llm, #ft-image-from-prompt, #ft-video-catalog.

## talking-head — Говорящий аватар
- Confirm model supports avatar/lipsync via list_models.
- Pass audio_url / reference_audios; distinct from generate_audio music.
- Mechanics: /docs/features#ft-video-catalog, #ft-files-upload.

## ecommerce-sku-day — День нового SKU
- Batch: estimate each expensive job; generate_image variants in parallel only if rate limits allow.
- On 429 RATE_LIMITED: read retry_after_sec, back off; do not parallel-spam.
- Optional REST webhooks for completion; MCP: poll get_task({ id }).
- Mechanics: /docs/features#ft-image-to-image, #ft-webhooks, #ft-project-billing.

## localization-pack — Локали и A/B за вечер
- Use chat_completion for copy localization; keep visual identity via Element Library when needed.
- Label variants with tag_ids / project when available.
- Mechanics: /docs/features#ft-chat-llm, #ft-project-billing, #ft-project-tags.

## faceless-shorts-week — Неделя faceless Shorts
- Plan 5–14 shorts in chat_completion, then enqueue generate_* jobs; poll get_task (or REST webhooks).
- Use recommend_model + list_models; do not hard-code obscure slugs.
- Submit the planned batch and poll get_task (or use REST webhooks); already submitted provider jobs continue independently of the page.
- Mechanics: /docs/features#ft-history-list, #ft-model-pick.

## character-cast — Один герой на всю кампанию
- Continuity playbook: create_project_element once, reuse @Name across shots.
- Prefer kling-3 / kling-o3 when the user asks for native element continuity.
- Mechanics: /docs/features#ft-element-library.

## cinematic-previz — Previz до съёмки
- Storyboard = ordered image jobs + optional short video; keep @character and project_id.
- Mechanics: /docs/features#ft-element-library, #ft-image-from-prompt, #ft-video-catalog.

## music-bed — Музыка к ролику
- generate_audio + get_task; wait for real URLs in media_urls / audio[].
- Soft-launch: empty complete is a bug — keep polling briefly or report.
- Mechanics: /docs/features#ft-audio-suno.

## product-3d — 3D packshot / mesh
- generate_mesh + get_task; return GLB URL. Prefer t2m unless image provided.
- Mechanics: /docs/features#ft-mesh-meshy.

## overnight-campaign — Ночной прогон кампании
- Before overnight batch: get_balance + estimate sum; warn if spend cap may trip.
- Prefer webhooks for long batches on REST; MCP must poll get_task({ id }).
- Idempotency-Key on REST submits if the host may retry POSTs.
- Mechanics: /docs/features#ft-estimate-balance, #ft-webhooks, #ft-idempotency.

## agent-studio-connect — Агент собирает сайт с медиа Artillect
- 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 доступ и разрешение нужны отдельно.
- 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.
- Use the website_media MCP prompt for local assets and resume; preserve existing approved budget.


---

## Human summaries

<a id="uc-ugc-product-ad"></a>
### UGC-ролик из товара (`ugc-product-ad`)

**Реклама** · Performance и growth-команды

_Фото SKU → хуки, кадры и вертикальный ad за один проход._

**Outcome:** 3–5 hook-вариантов + hero-кадры + 9:16 ролик под Meta/TikTok.

Вы даёте фото продукта и одну фразу про оффер. Дальше — как мини-продакшн: тексты, визуалы, ролик — в одном месте, на одном балансе.
Не «пресет из коробки», а живой цикл: отбрифовали → сгенерировали → открутили слабое → оставили то, что бьёт.

**Steps:**
1. Загрузите фото товара и коротко опишите аудиторию / оффер.
2. Соберите хуки и VO, затем кадры и вертикальное видео.
3. Заберите ссылки, итерируйте промпт или кадр — без смены инструмента.

**Features:** [`files-upload`](https://app.artillect.pro/docs/features#ft-files-upload), [`chat-llm`](https://app.artillect.pro/docs/features#ft-chat-llm), [`image-from-prompt`](https://app.artillect.pro/docs/features#ft-image-from-prompt), [`video-catalog`](https://app.artillect.pro/docs/features#ft-video-catalog), [`estimate-balance`](https://app.artillect.pro/docs/features#ft-estimate-balance)

<a id="uc-talking-head"></a>
### Говорящий аватар (`talking-head`)

**Реклама** · UGC и personal-brand команды

_Лицо + голос → ролик, который «смотрит в камеру»._

**Outcome:** Lipsync / avatar-видео под объявление или онбординг.

Нужен говорящий кадр без съёмочного дня: портрет, аудиодорожка — и модель, которая умеет lipsync/avatar.
Это не генерация музыки: звук сюда как вход. Музыку для подложки берите отдельным сценарием «Музыка к ролику».

**Steps:**
1. Загрузите лицо и аудио (или ссылку на дорожку).
2. Выберите video-продукт с avatar/lipsync и запустите генерацию.
3. Проверьте результат; при необходимости смените take или аудио.

**Features:** [`video-catalog`](https://app.artillect.pro/docs/features#ft-video-catalog), [`files-upload`](https://app.artillect.pro/docs/features#ft-files-upload)

<a id="uc-ecommerce-sku-day"></a>
### День нового SKU (`ecommerce-sku-day`)

**Ecommerce** · Ecommerce и marketplace-менеджеры

_Одно фото → hero, lifestyle и короткий reel до вечера._

**Outcome:** Пакет витрины: несколько ракурсов + опциональный short-video.

Товар уже на складе, а контента нет. Вместо ожидания фотосессии собираете пакет витрины из одного кадра и карточки.
Можно гнать пачкой: сначала оценка стоимости, потом серия картинок и один короткий ролик — всё в одном проекте.

**Steps:**
1. Загрузите фото и текст карточки товара.
2. Сгенерируйте набор ракурсов / фонов; при необходимости — короткий reel.
3. Сложите ассеты в проект или теги, чтобы потом найти пачкой.

**Features:** [`image-to-image`](https://app.artillect.pro/docs/features#ft-image-to-image), [`video-catalog`](https://app.artillect.pro/docs/features#ft-video-catalog), [`webhooks`](https://app.artillect.pro/docs/features#ft-webhooks), [`project-billing`](https://app.artillect.pro/docs/features#ft-project-billing)

<a id="uc-localization-pack"></a>
### Локали и A/B за вечер (`localization-pack`)

**Ecommerce** · Growth и international ecommerce

_Один бриф → тексты и кадры под рынки и хуки._

**Outcome:** Набор вариантов copy + визуалов под 2–4 локали / оффера.

Один сильный креатив редко переживает перевод «в лоб». Здесь сначала переписываются хуки и VO под тон рынка, потом штампуются визуальные варианты.
Идентичность героя можно держать через библиотеку элементов — чтобы локали не разъехались по лицам.

**Steps:**
1. Опишите исходный оффер и список локалей / тонов.
2. Соберите тексты, затем визуальные варианты с разными промптами.
3. Сверьте пачку в истории проекта и отметьте победителей тегами.

**Features:** [`project-tags`](https://app.artillect.pro/docs/features#ft-project-tags), [`image-from-prompt`](https://app.artillect.pro/docs/features#ft-image-from-prompt), [`video-catalog`](https://app.artillect.pro/docs/features#ft-video-catalog), [`project-billing`](https://app.artillect.pro/docs/features#ft-project-billing)

<a id="uc-faceless-shorts-week"></a>
### Неделя faceless Shorts (`faceless-shorts-week`)

**Shorts** · Faceless и short-form авторы

_Одна сессия планирования → очередь вертикальных роликов._

**Outcome:** План на 5–14 шортсов и готовые медиа-URL к утру / к дедлайну.

Не сидеть каждый день «с нуля»: один раз набросали рубрики, поставили очередь генераций, забрали готовое, когда удобно.
Сила не в волшебной кнопке, а в каталоге моделей + оркестрации: агент или сценарий крутит джобы, вы выбираете лучшие take.

**Steps:**
1. Соберите бриф на неделю: темы, тон, формат 9:16.
2. Спланируйте серию, затем поставьте image/video-джобы в один проект.
3. Заберите completed-ссылки и отсейте слабые.

**Features:** [`chat-llm`](https://app.artillect.pro/docs/features#ft-chat-llm), [`video-catalog`](https://app.artillect.pro/docs/features#ft-video-catalog), [`image-from-prompt`](https://app.artillect.pro/docs/features#ft-image-from-prompt), [`history-list`](https://app.artillect.pro/docs/features#ft-history-list), [`webhooks`](https://app.artillect.pro/docs/features#ft-webhooks)

<a id="uc-character-cast"></a>
### Один герой на всю кампанию (`character-cast`)

**Персонажи** · Бренды и сериальные кампании

_Завели персонажа один раз — узнают в каждом кадре._

**Outcome:** Элемент в библиотеке проекта + серия шотов с одним @именем.

Самое дорогое в серийном контенте — когда «лицо» плывёт от ролика к ролику. Element Library фиксирует героя в проекте: frontal, имя, дальше @Name в промптах.
Для моделей с native elements берите линейки вроде Kling, где это реально поддержано — без фейковых полей «для галочки».

**Steps:**
1. Создайте элемент персонажа в проекте и запомните project_id.
2. Все шоты кампании — с тем же @Name и проектом.
3. Итерируйте по истории генераций, не пересоздавая героя с нуля.

**Features:** [`element-library`](https://app.artillect.pro/docs/features#ft-element-library), [`video-catalog`](https://app.artillect.pro/docs/features#ft-video-catalog), [`image-from-prompt`](https://app.artillect.pro/docs/features#ft-image-from-prompt)

<a id="uc-cinematic-previz"></a>
### Previz до съёмки (`cinematic-previz`)

**Previz** · Режиссёры, продюсеры, pitch-команды

_Раскадровка и mood-кадры, пока ещё не крутится камера._

**Outcome:** Упорядоченный storyboard (image) + выборочные short video previz.

Дорогой продакшн начинается с согласия «как это выглядит». Здесь агент или вы сами держите персонажа, гоняете шоты и короткие previz — пока бюджет съёмки ещё не сожжён.
Комментарии заказчика остаются в том же проекте: следующий take — не новый хаос папок.

**Steps:**
1. Зафиксируйте героя / мир (элемент или сильный референс).
2. Соберите серию кадров по сценам; выборочно оживите ключевые шоты видео.
3. Соберите питч-пакет из лучших URL.

**Features:** [`element-library`](https://app.artillect.pro/docs/features#ft-element-library), [`image-from-prompt`](https://app.artillect.pro/docs/features#ft-image-from-prompt), [`video-catalog`](https://app.artillect.pro/docs/features#ft-video-catalog)

<a id="uc-music-bed"></a>
### Музыка к ролику (`music-bed`)

**Звук** · Монтажёры и performance-продакшн

_Трек под ads в том же контуре, что картинка и video._

**Outcome:** Playable audio URL (Suno) под монтаж или параллельный video-job.

Не прыгать в отдельный сервис «только за музыкой»: подложка генерируется на том же балансе Studio.
Склейка с видео — у вас в монтаже; мы отдаём нормальный URL, когда трек реально готов.

**Steps:**
1. Оцените стоимость audio-джоба и опишите mood / BPM / роль трека.
2. Дождитесь playable URL в статусе генерации.
3. Параллельно или после — видео; сведите у себя.

**Features:** [`audio-suno`](https://app.artillect.pro/docs/features#ft-audio-suno), [`estimate-balance`](https://app.artillect.pro/docs/features#ft-estimate-balance)

<a id="uc-product-3d"></a>
### 3D packshot / mesh (`product-3d`)

**3D** · Product и web-команды

_Текст или фото → GLB для витрины и AR-превью._

**Outcome:** Mesh (GLB) из Meshy — без отдельного 3D-пайплайна.

Нужен объёмный packshot или превью для сайта — без недели в Blender. Текст или фото уходит в mesh-генерацию, на выходе GLB.
Сейчас это mesh-генерация (не полный texture-PBR пайплайн) — честно и достаточно для многих витрин.

**Steps:**
1. Опишите объект или приложите фото.
2. Запустите mesh-генерацию и дождитесь GLB.
3. Вставьте в сайт / AR-превью.

**Features:** [`mesh-meshy`](https://app.artillect.pro/docs/features#ft-mesh-meshy)

<a id="uc-overnight-campaign"></a>
### Ночной прогон кампании (`overnight-campaign`)

**Ночной батч** · Операторы контента и агентства

_Вечером бриф и бюджет — утром пачка ассетов._

**Outcome:** Очередь completed-джобов / webhook-доставки к утру.

Пока вы спите, очередь генераций крутится сама: картинки, ролики, ретраи. Утром забираете готовое, а не открываете пустой чат.
Для своих воркеров — webhooks. Для агента в Cursor/Claude — poll. Бюджет заранее через estimate и баланс.

**Steps:**
1. Зафиксируйте бриф, лимит токенов и project_id.
2. Поставьте пачку генераций на ночь.
3. Утром заберите completed из истории или доставок.

**Features:** [`estimate-balance`](https://app.artillect.pro/docs/features#ft-estimate-balance), [`webhooks`](https://app.artillect.pro/docs/features#ft-webhooks), [`idempotency`](https://app.artillect.pro/docs/features#ft-idempotency), [`history-list`](https://app.artillect.pro/docs/features#ft-history-list)

<a id="uc-agent-studio-connect"></a>
### Агент собирает сайт с медиа Artillect (`agent-studio-connect`)

**Ночной батч** · Команды, которые уже живут в агентах

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

**Outcome:** Сайт с проверенными локальными ассетами, manifest и медиа в выбранном проекте; публикация отдельно.

Нужны только модели для кода/чата — подключите 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. Ключи не публикуйте и не коммитьте.
Бесплатно напрямую: GET /api/v1/provider/models/, GET /api/v1/me/; MCP initialize/tools list, get_started/get_balance. Это auth/discovery, не проверка платного inference. Сообщение LLM-агенту оплачивается, даже если инструмент бесплатный.

**Steps:**
1. Выбрать проект, найти модель и входы в каталоге. Зачем: project_id сохраняет медиа для продолжения в Studio; capabilities.input в живом Provider /models определяет vision.
2. Оценить точные параметры каждого ассета; сверить баланс и авторизованный бюджет. Зачем: Оценка до submit помогает контролировать расходы; уже разрешённый бюджет не требует повторных подтверждений.
3. Сериализовать generate_*; заранее сохранить стабильный idempotency_key, затем task_id. Зачем: Media submit — платный. Тот же payload/key защищает повтор в пределах 24 часов; после окна сначала сверить историю.
4. get_task с task_id/poll_args до terminal; ошибка останавливает polling, успех требует media_urls. Зачем: Асинхронная задача продолжается после обрыва; повторный submit может купить дубликат.
5. Показать результат; в 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. Проверить реальные файлы и сайт сборкой/тестами; скриншоты — только при поддержке vision в host. Зачем: Постер — один кадр, не просмотр видео. Сборка сайта и публикация различаются; hosting доступ и разрешение нужны отдельно.

**Features:** [`provider-media-agent`](https://app.artillect.pro/docs/features#ft-provider-media-agent), [`auth-keys`](https://app.artillect.pro/docs/features#ft-auth-keys), [`estimate-balance`](https://app.artillect.pro/docs/features#ft-estimate-balance)