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 casesMCPCLIOpenAPI

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

Тот же 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. API, MCP и CLI используют один lifecycle/collaboration contract.

REST APIMCP

Проекты CRUD

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

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

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

Шаги

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

Playbook для агента

  1. Prefer list_projects then get_project. Use create/update/delete only with explicit user intent.
REST APIMCP

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

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

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

Шаги

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

Playbook для агента

  1. Owner/admin only for invites. On 403 explain Studio role limits.
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/ — плоская история ключа с общими 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.

Шаги

  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. Use the same filters across API, MCP and CLI; when a new filter is added, update the shared contract and parity test.
  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/get/update/delete/reorder через API, MCP и CLI.

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

Шаги

  1. list_projects → create_project_element → generate_* с @Name и project_id.
  2. delete_project_element · reorder_project_elements / element-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 150MB, video 200MB, audio 50MB. HEIC/HEIF, AVIF, WebP, TIFF, GIF и SVG приводятся к JPEG перед провайдером.

Предпочтительнее чужих хостов: меньше 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. Defaults are explicit per adapter; query list_models before relying on one.

Асинхронный цикл: 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

Отмена за 4 секунды

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

Каждый submit получает собственный 4-секундный дедлайн и не блокирует следующие генерации.

Отмена допустима только пока задача не ушла провайдеру; после submit provider-side cancel отсутствует.

Шаги

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

Playbook для агента

  1. Если пользователь передумал сразу после submit — отправь cancel; ожидай refunded=true.
  2. Не обещай отмену после 4 секунд: оплаченная provider task продолжит выполняться.
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/v7 t2m / i2m / multi-i2m → mesh[{url,format}], GLB первым.

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

Шаги

  1. estimate type=mesh → generate_mesh → get_task.

Playbook для агента

  1. Use list_models for current Meshy slugs; default stays meshy-v6-t2m, image_url selects i2m, and multi-image uses meshy-v7-multi-i2m.
REST APIMCP

Chat / LLM

Sync JSON default; stream:true SSE для поддерживаемых chat-моделей; 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 доступен для поддерживаемых chat-моделей; без 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; отмена доступна с возвратом только в первые 4 секунды до provider submit.

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.