Features: студия через API и MCP

Те же сущности, что в UI: проекты, теги, лента, лайки, Element Library, генерации. Сгруппировано по главам Studio — не dump эндпоинтов.

Введение

Public API и MCP — программный вход в ту же студию. Ниже механика по слоям: аккаунт → проекты → библиотека (поиск/теги/лайки/copy) → elements → generate → ops. Маркетинг (UGC, overnight) — на /docs/use-cases.

Где написано REST only — в MCP пока нет tool (теги, лайки, copy/move). Grouping ленты (по автору/дате/тегу) есть только в Studio UI, не в Public API.

ОглавлениеUse casesMCPOpenAPI

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

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

REST APIMCP

Ключи и OAuth

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

Кредиты = Studio. Device flow для CI. HTTP /mcp без Bearer/OAuth → 401 (нет env-fallback).

get_me — кто владелец ключа; тот же identity, что Studio.

Шаги

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

Playbook для агента

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

estimate + get_balance

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

429 SPEND_CAP_EXCEEDED / RATE_LIMITED — остановите параллельные submit.

estimate type=audio|mesh без prompt отдаёт flat cost (DX).

Шаги

  1. get_balance → estimate → generate_*.

Playbook для агента

  1. Always estimate video/upscale unless user already approved spend.
REST APIMCP

recommend_model + list_models

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

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

Шаги

  1. recommend_model → list_models → estimate → generate_*.

Playbook для агента

  1. Do not skip catalog check for obscure slugs.

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

Как в Studio: проекты, папки, роли, лимиты. Сюда кладёте генерации (project_id) и Element Library. MCP сейчас читает проекты; полный CRUD — REST.

REST APIMCP

Проекты CRUD

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

Public API: полный CRUD. MCP: только list + get (create/update/delete — REST).

Личный hub удалять нельзя.

Шаги

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

Playbook для агента

  1. Prefer list_projects then get_project. To create/rename — REST until MCP grows.
REST APIREST only

Участники и роли

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

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

Шаги

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

Playbook для агента

  1. Owner/admin only for invites. On 403 explain Studio role limits.
REST APIREST only

Папки проектов

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

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

Шаги

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

Playbook для агента

  1. Use folders when user organizes many projects.
REST APIMCP

project_id / billing_source / analytics

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

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

Шаги

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

Playbook для агента

  1. Include project_id when user works inside a project.

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

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

REST APIMCP

Лента и история

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

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.

Шаги

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

Playbook для агента

  1. Never fabricate prior results — only list/get responses.
  2. For search/filter by tag use REST project feed; MCP list is a thin subset.
  3. Do not invent group_by — not in Public API.
REST APIMCP

Теги проекта

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

Как цветные метки в Studio. До 10 custom на проект, имя ≤10 символов. Лайки/архив — не в tag_ids.

Пайплайн: create_project_tag / POST …/tags/ → generate_* с project_id + tag_ids → тег сразу на новой gen.

Неверный tag id молча пропускается (submit не падает).

Шаги

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

Playbook для агента

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

Лайки и избранное

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

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

Шаги

  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__].

Playbook для агента

  1. like_generation for personal signal; create_project_tag / assign for shared labels.
REST APIMCP

Copy / move / delete

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

copy_generation → новый объект в destination; move_generation меняет project_id.

Move снимает теги (strip on move). delete_generation — hard-delete (осторожно).

Шаги

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

Playbook для агента

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

Element Library

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

REST APIMCP

Element Library (@name)

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

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

Шаги

  1. list_projects → create_project_element → generate_* с @Name и project_id.
  2. delete_project_element · REST POST …/elements/reorder/.

Playbook для агента

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

Файлы

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

REST APIMCP

upload_file

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

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

Шаги

  1. upload_file → url → generate_* / create_project_element.

Playbook для агента

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

Генерация

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

REST APIMCP

Картинка из текста

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

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

Шаги

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

Playbook для агента

  1. Call get_balance or estimate before paid generate.
  2. Poll get_task until completed or failed. Never invent result URLs.
REST APIMCP

i2i / edit по референсу

upload_file или HTTPS → input_urls.

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

Шаги

  1. upload_file → generate_image с input_urls → get_task.

Playbook для агента

  1. upload_file → use returned url in generate_image.input_urls.
REST APIMCP

Видео (каталог моделей)

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

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

Шаги

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

Playbook для агента

  1. Prefer list_models / recommend_model. Set task when not t2v.
REST APIMCP

Upscale и SwitchX

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

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

Шаги

  1. list_models → generate_upscale / generate_switchx → get_task.

Playbook для агента

  1. Tools: generate_upscale, generate_switchx. Public HTTPS or Artillect media only.
REST APIMCP

Музыка Suno

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

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

Шаги

  1. estimate type=audio → generate_audio → get_task.

Playbook для агента

  1. generate_audio + get_task; poll until playable URLs; do not invent CDN links.
REST APIMCP

3D mesh Meshy

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

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

Шаги

  1. estimate type=mesh → generate_mesh → get_task.

Playbook для агента

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

Chat / LLM

Sync JSON default; stream:true SSE только gpt-5-5; optional conversation store.

MCP chat_completion sync. create_chat_conversation → conversation_id на completions сохраняет ход в chat_messages (тот же store, что Studio LLM).

Клиент по-прежнему шлёт полный messages[]; store — persistence, не server-side memory injection.

Шаги

  1. create_chat_conversation → chat_completion({ conversation_id, messages }).
  2. get_chat_messages / list_chat_conversations.
  3. stream:true только gpt-5-5; без Idempotency-Key.

Playbook для агента

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

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

Отмена до терминала, идемпотентность REST, webhooks для image/video/upscale/switchx. Audio/mesh — только poll.

REST APIMCP

cancel_*

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

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

Шаги

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

Playbook для агента

  1. Use cancel_* tools (destructive). Confirm via get_task.
REST APIREST only

Idempotency-Key

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

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

Шаги

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

Playbook для агента

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

Webhooks

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

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

Шаги

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

Playbook для агента

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