# 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`, then run `node --import tsx scripts/generate-features-md.mts`.

---

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

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

### Ключи и 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.

### 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.

### 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. MCP сейчас читает проекты; полный CRUD — REST.

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

list / create / get / patch / delete. MCP: list_projects, get_project.

Surfaces: api, mcp

Public API: полный CRUD. MCP: только list + get (create/update/delete — REST).
Личный hub удалять нельзя.

**Steps:**

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

**Agent playbook:**

- Prefer list_projects then get_project. To create/rename — REST until MCP grows.

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

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

Surfaces: api

GET roles · members CRUD · PATCH me (folder_id, is_favorite). Нет MCP-tools — только REST.

**Steps:**

1. GET /projects/roles/ → POST …/members/ → PATCH/DELETE …/members/{userId}/.

**Agent playbook:**

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

### Папки проектов (`project-folders`)

GET/POST /folders — группировка проектов в сайдбаре.

Surfaces: api

PATCH/DELETE папки в Public API пока нет — только list + create.

**Steps:**

1. GET /api/v1/folders/ → POST { name, parent_id? }.

**Agent playbook:**

- Use folders when user organizes many projects.

### 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.

### Лента и история (`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/ — плоская история ключа, без q/tag_ids.
MCP list_project_generations сегодня: limit|cursor|kind|source (без q/tag_ids) — для поиска используйте REST.
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.
- For search/filter by tag use REST project feed; MCP list is a thin subset.
- Do not invent group_by — not in Public API.

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

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

Surfaces: api, mcp

Как цветные метки в 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=.

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

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

Surfaces: api, mcp

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.

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

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

Surfaces: api, mcp

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.

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

list/create/update/delete (+ reorder REST).

Surfaces: api, mcp

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

**Steps:**

1. list_projects → create_project_element → generate_* с @Name и project_id.
2. delete_project_element · REST POST …/elements/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-аккаунта.

### upload_file (`files-upload`)

POST /files/ → { url, key }. Лимиты: image 10MB, video 200MB, audio 50MB.

Surfaces: api, mcp

Предпочтительнее чужих хостов: меньше 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.

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

prompt → job → URL. Дефолт MCP: gpt-image-2.

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.

### 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.

### Видео (каталог моделей) (`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.

### 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.

### Музыка Suno (`audio-suno`)

generate_audio / suno-v55. Poll only (webhooks для audio пока нет).

Surfaces: api, mcp

Soft-launch: дождитесь audio[]/tracks[] с URL. Не путать с avatar audio_url.

**Steps:**

1. estimate type=audio → generate_audio → get_task.

**Agent playbook:**

- generate_audio + get_task; poll until playable URLs; do not invent CDN links.

### 3D mesh Meshy (`mesh-meshy`)

meshy-v6-t2m / i2m → mesh[{url,format}], GLB первым.

Surfaces: api, mcp

texture-pbr вне Public API. Poll only.

**Steps:**

1. estimate type=mesh → generate_mesh → get_task.

**Agent playbook:**

- Prefer meshy-v6-t2m unless user supplies image_url (i2m).

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

Sync JSON default; stream:true SSE только gpt-5-5; 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.

**Steps:**

1. create_chat_conversation → chat_completion({ conversation_id, messages }).
2. get_chat_messages / list_chat_conversations.
3. stream:true только gpt-5-5; без 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.

### cancel_* (`cancel-refund`)

Отмена до терминального статуса (+ refund path).

Surfaces: api, mcp

Нет фейкового tasks.cancel — только cancel_*_generation.

**Steps:**

1. cancel_* → подтвердить get_task.

**Agent playbook:**

- Use cancel_* tools (destructive). Confirm via get_task.

### 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.

### 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.