Перейти до документації
v4v.Документація розробникаПОПЕРЕДНЯ ВЕРСІЯВаші ключі API ↗
У ЦЬОМУ ПОСІБНИКУ
Підключіть вашого асистентаАвторизація OAuth 2.1ChatGPT (OAuth)Claude WebVS CodeClaude CodeCursorCodex CLIGemini CLIOpenCodeІнші клієнти MCPПочніть з короткого брифуДоступні інструментиПовторне використання контенту бібліотеки та попередній перегляд вартостіВаріанти, назви проєктів і прикладиОрганізуйте наявні проєктиМедіафайли та генераціяОтримання результатуВебхуки завершенняКредити та доступУсунення несправностейВідеомоделі Kling 4.0GPT-6 Astra чатПоточні моделі зображень і чатівМасові відео продуктів у СтудіїВідеоредакторGemini text-to-voiceСтилізований текст, підписи та транскрипція GoogleТворчі колекції та планування агента
Доступно для тестування
Попередній перегляд з прямим доступом
MCP connection guide

Створюйте за допомогою свого ШІ-асистента.

Увійдіть через OAuth 2.1 або підключіться за допомогою API-ключа. Знаходьте моделі, створюйте з референсними медіафайлами, збирайте багатошаровий монтаж і додавайте готові відео, зображення та аудіо у свою розмову.

Почати →
КІНЦЕВА ТОЧКАhttps://v4v.ai/api/mcp
OAuth
{
  "type": "http",
  "url": "https://v4v.ai/api/mcp"
}
01

Підключіть вашого асистента#

Для покрокового налаштування оберіть вашого асистента на сторінці підключення MCP.

V4V MCP дозволяє ШІ-асистенту знаходити моделі генерації, працювати з референсними медіафайлами, створювати зображення, відео, аудіо та відповіді в чаті, а також отримувати результати. Він використовує той самий обліковий запис, кредити та історію генерації, що й V4V API.

URL сервера: https://v4v.ai/api/mcp

Транспорт: HTTP з потоковою передачею

Аутентифікація: вхід через OAuth 2.1 на увімкнених розгортаннях або API-ключ у клієнтах, що підтримують користувацькі заголовки запитів. Обидва варіанти використовують ваш наявний обліковий запис V4V і кредити.

Використовуйте домен вашого розгортання замість v4v.ai при тестуванні іншого середовища. Сервер уже розміщено; запуск локального процесу не потрібен.

Увійти через OAuth

Choose this option in ChatGPT, Claude, or a supported editor or CLI. You do not need to create an API key. Add the remote server URL, select OAuth / Sign in, and complete the V4V permission screen. See OAuth authorization and the client-specific steps below.

Підключитися за допомогою API-ключа

  1. Відкрийте свій профіль V4V і створіть ключ у розділі API Keys.
  2. Збережіть секрет API у безпечних налаштуваннях клієнта MCP.
  3. Додайте сервер із заголовком x-api-key: YOUR_V4V_API_KEY або Authorization: Bearer YOUR_V4V_API_KEY.
  4. Підключіться та почніть із get_balance або list_models.

Надсилайте один заголовок автентифікації. Якщо надіслано обидва, вони повинні містити однаковий ключ; конфліктні або некоректні облікові дані повертають HTTP 401. Значення x-api-key — це сам ключ без префікса Bearer . Обидва формати заголовків API-ключа використовують однакові дозволи, кредити, ліміти запитів і відкликання ключа.

Клієнти з API-ключем продовжують використовувати ті самі заголовки та дозволи. Клієнти OAuth входять у свій існуючий обліковий запис V4V через браузер. Ніколи не вставляйте ключ або токен у розмову з асистентом або не комітьте їх у репозиторій.

02
V4V / MCP connection guideСтворюйте те, що хочеться дивитися.

Авторизація OAuth 2.1#

  1. Add https://v4v.ai/api/mcp as a remote Streamable HTTP server in your assistant.
  2. Choose OAuth / Sign in. If asked for an OAuth client, select Register automatically (dynamic client registration, or DCR). Leave Client ID and Client Secret empty.
  3. Your assistant opens V4V in your browser. Sign in to the V4V account whose credits and library you want to use.
  4. Review the assistant and all three required permissions: view your account and media; upload, estimate costs, edit and share; generate media and transcribe using credits. All three are selected and locked. Choose Accept all permissions, or Cancel to decline.
  5. Return to your assistant, finish connecting if prompted, and ask it to check your balance. Tool permissions and confirmations inside the assistant are managed separately by that client.

Асистент виявляє кінцеві точки OAuth на сервері та використовує PKCE для завершення входу. Не створюйте API-ключ і не вставляйте токен Bearer для цього потоку. Приклад OAuth на початку цієї сторінки містить лише HTTP-транспорт і URL сервера; кожен клієнт має власний формат конфігурації.

Підключення не витрачає кредити. Генерації використовують ваш існуючий баланс V4V. Токени доступу діють максимум одну годину і автоматично оновлюються, якщо клієнт це підтримує. Підключення закінчується через 30 днів; повторно підключіться тоді або після відкликання доступу. Керуйте та відключайте сесії в Профіль V4V → Підключення асистента. Уже подані завдання продовжують виконання після відключення.

Якщо OAuth недоступний у вашому розгортанні, попросіть оператора увімкнути підключення асистентів або використайте API-ключ у сумісному клієнті.

03

ChatGPT (OAuth)#

OAuth спершу має бути увімкнено на розгортанні V4V. Дозволи облікового запису та робочого простору в ChatGPT визначають, чи доступне користувацьке підключення MCP.

  1. Відкрийте ChatGPT Plugins → Personal, оберіть Add (або +), потім Add custom MCP server (назва може відрізнятися залежно від облікового запису).
  2. Введіть V4V і URL сервера https://v4v.ai/api/mcp.
  3. Оберіть OAuth та динамічну реєстрацію клієнта (DCR). Залиште Client ID і Client Secret порожніми; V4V автоматично реєструє публічного клієнта PKCE. Ця версія підтримує DCR, а не CIMD.
  4. Підключіться та увійдіть у свій наявний обліковий запис V4V.
  5. На екрані дозволів V4V перегляньте обліковий запис і хост зворотного виклику. Усі три дозволи обов’язкові: читання облікового запису, редагування/завантаження та генерація з кредитами. Три прапорці вибрані та заблоковані. Оберіть Accept all permissions для підключення або Cancel для відмови; часткова згода не підтримується.
  6. Поверніться до ChatGPT і встановіть плагін, якщо буде запропоновано. У Personal plugins відкрийте меню з трьома крапками V4V і оберіть Manage.
  7. Відкрийте рядок Permission. Для викликів інструментів без затвердження оберіть Allow all tools. Генерації все одно використовують ваші кредити V4V, тому перед початком запитайте оцінку.
  8. Почніть нову розмову, оберіть + → Plugins → V4V (або згадайте його з @) і запитайте Check my V4V balance.

Інструкція зі скріншотами ChatGPT проходить усі вісім екранів. Крок із деталями підключення має кнопки копіювання для назви плагіна, опису та URL сервера поточного розгортання, а також опційне завантаження іконки V4V.

Приклад:

Створіть три вертикальні концепції продуктового відео 9:16 за цим посиланням на продукт. Спочатку покажіть концепції та оцінку кредитів. Чекайте на моє схвалення перед початком генерації.

Асистент використовує наявні інструменти discovery, estimate_generation і generate_studio_variants. Оцінки не запускають рендеринг і не резервують кредити, але можуть імпортувати медіафайли для перевірки, тому потрібен дозвіл на редагування. Платні інструменти застосовують дозвіл на генерацію на сервері. Дозвіл — це доступ до облікового запису, а не схвалення окремого творчого завдання: однак перед авторизацією рендерингу все одно переглядайте запитані концепції та бюджет. Контроль пакетних max_credits і ідемпотентності залишається в силі.

Токени доступу діють максимум одну годину. Токени оновлення змінюються при кожному використанні, а підключення закінчується через 30 днів. Підключіться знову, коли воно закінчиться або знадобляться додаткові дозволи. У Профіль V4V → Підключення асистента переглядайте використання, відключайте асистента або відкривайте його секрет підпису вебхука для вашого приймача. Не вставляйте секрет підпису в чат.

Відключення блокує нові запити інструментів, оновлення токена та невикористані посилання для завантаження. Уже подані завдання продовжують виконання за існуючими правилами черги та кредитів; відключення не скасовує і не повертає їх. Раніше видані підписані посилання на медіафайли зберігають звичайний термін дії.

Завантаження файлів із середовища виконання ChatGPT залежить від мережевого доступу та доступу до вкладень у цьому середовищі. Обмежене посилання для завантаження в браузері залишається доступним як резервний варіант. Саме лише підключення MCP не гарантує автоматичного передавання вкладень.

Тестування користувацького підключення та публікація плагіна — це окремі кроки. Див. інструкцію OpenAI з підключення MCP, вимоги OAuth та вимоги до публічної перевірки.

04

Claude Web#

Підключення OAuth

Відкрийте Add to Claude. Форма відкриється з попередньо заповненими ім’ям V4V і URL сервера продуктивного середовища. Для розробки або іншого розгортання використовуйте сторінку підключення, яка заповнює URL відповідного розгортання. Якщо вхід у Claude очищує форму, відкрийте посилання знову після входу.

Дотримуйтесь шестикрокової інструкції зі скріншотами паралельно з Claude:

  1. Перегляньте попередньо заповнені назву та URL, потім оберіть Continue.
  2. Claude автоматично перевіряє сервер. Залиште виявлені налаштування Sign in now і Register automatically та оберіть Add; інші налаштування змінювати не потрібно. Залиште Client ID і Client Secret порожніми, без API-ключа або заголовків запиту.
  3. На сторінці конектора оберіть Connect та увійдіть у V4V.
  4. Перегляньте свій обліковий запис і всі три необхідні дозволи, потім оберіть Accept all permissions. Підключення не витрачає кредити.
  5. У розділі Tool permissions → Read-only tools відкрийте Custom поруч із назвою групи та оберіть Always allow.
  6. Прокрутіть до Write/delete tools і також оберіть Custom → Always allow для цієї групи. Увімкніть V4V у розмові та запитайте Check my V4V balance. Генерації використовують ваші кредити V4V; перед початком запитайте оцінку.

Дозволи інструментів Claude відокремлені від авторизації облікового запису V4V. Меню груп дозволяють дозволити інструменти без зміни кожного окремо. Ви можете змінити ці налаштування в параметрах конектора Claude.

Хостовані зворотні виклики Claude на claude.ai та claude.com підтримуються без додаткової конфігурації середовища. Використовуйте Register automatically; опублікована ідентичність клієнта Claude (CIMD) не реалізована в цій версії. Існуючі підключення з API-ключем продовжують працювати, як описано нижче.

Якщо показано налаштування транспорту, використовуйте Streamable HTTP. Додавання конектора та авторизація доступу до облікового запису — це окремі кроки, якщо Claude їх так подає.

Альтернатива з API-ключем: створіть свій API-ключ V4V

Відкрийте свій профіль V4V, перейдіть до API Keys і створіть ключ. Підготуйте його для заголовка конектора нижче.

2. Додайте конектор

  1. Open Add to Claude, or open Customize → Connectors → Add → Custom web connector.
  2. Set Name to V4V.
  3. Set MCP server URL to https://v4v.ai/api/mcp.
  4. Under Authentication, select No sign-in.
  5. Click Add header and enter:
Налаштування заголовкаЗначення
Назваx-api-key
ЗначенняВаш API-ключ V4V, точно як скопійовано
  1. Натисніть Add / Connect і зачекайте на завершення підключення.

Використовуйте ключ лише в x-api-key, без префікса Bearer . No sign-in пропускає OAuth; заголовок усе одно автентифікує кожен запит до V4V. Залиште Client ID і Client Secret порожніми.

3. Дозвольте інструменти

  1. Відкрийте Менеджер конекторів Claude.
  2. Виберіть новий конектор V4V.
  3. Відкрийте Дозволи інструментів і дозвольте всі інструменти V4V.
  4. Переконайтеся, що create_upload_link, get_upload, get_model і generate_lab доступні та увімкнені.

Після додавання або оновлення інструментів V4V оновіть інструменти конектора або перепідключіть його перед початком нової розмови.

4. Дозвольте автоматичне завантаження файлів

  1. Відкрийте Settings → Capabilities.
  2. Увімкніть Code execution and file creation і Allow network egress, якщо вони вимкнені.
  3. У Domain allowlist додайте такі записи:
text
v4v.ai
*.v4v.ai
*.v4vcdn.space

Залишайте і кореневий домен, і запис з підстановкою, щоб покрити домен додатка та його піддомени. Вводьте лише доменні імена без https:// або /api/mcp і збережіть зміни. Якщо ваш робочий простір керує цим налаштуванням централізовано, попросіть адміністратора оновити список дозволених доменів.

Це дозволяє середовищу виконання Claude надсилати оригінальне вкладення безпосередньо до V4V, використовуючи короткостроковий дозвіл на завантаження, виданий MCP. Без цього налаштування конектор може працювати, але завантаження файлів завершуватимуться помилкою host_not_allowed.

Тестування на dev: використовуйте https://h4000.kitpes.com/api/mcp як URL конектора і додайте h4000.kitpes.com окремо до списку дозволених доменів. Записи доменів V4V не покривають dev-хост.

5. Почніть нову розмову

Увімкніть конектор V4V у новому чаті, додайте своє зображення і запитайте:

Збільшіть це зображення в 4 рази за допомогою V4V. Автоматично завантажте оригінальний файл, а потім використайте його ID файлу з моделлю Topaz.

Claude повинен отримати дозвіл на завантаження через MCP, передати файл зі свого середовища виконання без копіювання base64 у чат і подати запит на генерацію. Вам не потрібно повторно завантажувати файл на окремій сторінці браузера, якщо мережевий доступ дозволено.

Для загального конектора Claude та мережевих контролів див. керування конекторами та виконання коду і мережевий доступ.

05

VS Code#

Вхід через OAuth

Використовуйте Встановити у VS Code на сторінці підключення або додайте це до .vscode/mcp.json:

json
{
  "servers": {
    "v4v": {
      "type": "http",
      "url": "https://v4v.ai/api/mcp"
    }
  }
}

Запустіть сервер, перегляньте запит щодо довіри та завершіть вхід у V4V, коли VS Code відкриє ваш браузер. Увімкніть інструменти, які хочете використовувати в чаті агента.

Альтернатива з API-ключем

Для чату редактора додайте наступне до .vscode/mcp.json. VS Code запросить ключ і приховає введення. Залиште заповнювач у файлі.

json
{
  "inputs": [
    {
      "id": "v4v-api-key",
      "type": "promptString",
      "description": "V4V API key",
      "password": true
    }
  ],
  "servers": {
    "v4v": {
      "type": "http",
      "url": "https://v4v.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:v4v-api-key}"
      }
    }
  }
}

Запустіть сервер із конфігурації MCP і увімкніть його інструменти у вашій сесії чату. Перед дозволом витрачати кредити перегляньте виклик інструменту генерації.

Для інших середовищ агента VS Code дотримуйтесь поточних посилань на конфігурацію MCP для підтримуваного розташування конфігурації цього середовища.

06

Claude Code#

Вхід через OAuth

Зареєструйте віддалений сервер без заголовка автентифікації:

bash
claude mcp add --transport http v4v https://v4v.ai/api/mcp

Запустіть Claude Code, виконайте /mcp, оберіть V4V і автентифікуйтеся. Завершіть екран дозволів V4V у браузері, потім поверніться до CLI.

Альтернатива з API-ключем

Безпечно встановіть V4V_API_KEY у вашому середовищі оболонки, потім зареєструйте віддалений сервер:

bash
claude mcp add --transport http \
  --header "x-api-key: $V4V_API_KEY" \
  v4v https://v4v.ai/api/mcp

Використовуйте /mcp всередині Claude Code для перевірки з’єднання. Реєстрація зберігає налаштований заголовок у локальній конфігурації клієнта; захистіть цей файл і не додавайте його до системи контролю версій. Див. керівництво MCP для Claude Code щодо області конфігурації та керування ключами.

07

Cursor#

На сторінці підключення оберіть вхід через V4V або API-ключ і натисніть Встановити в Cursor. Перегляньте встановлення в Cursor перед підтвердженням. OAuth відкриває вхід у браузері; налаштування API-ключа встановлює заповнювач, який ви локально замінюєте у .cursor/mcp.json. Реальний ключ не вбудовується в URL встановлення. Поточні десктопні версії використовують HTTP loopback callback; хмарні клієнти використовують точний затверджений URI https://www.cursor.com/agents/mcp/oauth/callback.

08

Codex CLI#

Для OAuth додайте сервер і увійдіть:

bash
codex mcp add v4v --url https://v4v.ai/api/mcp
codex mcp login v4v

Для API-ключа безпечно встановіть V4V_API_KEY у вашому середовищі, потім виконайте:

bash
codex mcp add v4v --url https://v4v.ai/api/mcp --bearer-token-env-var V4V_API_KEY
09

Gemini CLI#

Додайте віддалений сервер командою gemini mcp add --transport http v4v https://v4v.ai/api/mcp. Виконайте /mcp auth v4v у Gemini CLI для OAuth. Для налаштування API-ключа безпечно встановіть V4V_API_KEY і додайте сервер командою gemini mcp add --transport http --header "x-api-key: $V4V_API_KEY" v4v https://v4v.ai/api/mcp. CLI зберігає налаштований заголовок; зберігайте його налаштування приватними.

10

OpenCode#

Додайте віддалений сервер під mcp.v4v у opencode.json з type: "remote", url: "https://v4v.ai/api/mcp" та enabled: true. Виконайте opencode mcp auth v4v для OAuth. Сторінка підключення надає повний JSON і альтернативу з API-ключем через змінну середовища.

11

Інші клієнти MCP#

Оберіть сервер remote / Streamable HTTP і надайте:

НалаштуванняЗначення
Ім’яv4v
URLhttps://v4v.ai/api/mcp
Автентифікація (оберіть одну)x-api-key: YOUR_V4V_API_KEY або Authorization: Bearer YOUR_V4V_API_KEY

Формати конфігурації відрізняються залежно від клієнта. Налаштовуйте заголовок у секретних налаштуваннях клієнта, а не в повідомленні чату. Застарілі клієнти лише з SSE не підтримуються. Підтримувані нативні клієнти OAuth використовують HTTP callback на localhost або 127.0.0.1 з явним локальним портом. Реєстрація та авторизація точно прив’язують повний callback URL. Хостовані callback для Claude, ChatGPT, Cursor і VS Code затверджені; іншим хостованим клієнтам потрібні точні URL у MCP_OAUTH_REDIRECT_URIS.

12

Почніть з короткого брифу#

Для повного фільму або креативного перемонтажу запису узгодьте важливі відсутні рішення перед монтажем або оплачуваною роботою: мета, аудиторія, вихідний матеріал, формат, цільова тривалість, візуальне оформлення, субтитри, озвучення, музика та мови виводу. get_started приймає request_kind (production, creative_edit, targeted_edit) і підтверджені значення creative_brief; він повертає videoBrief.productionQuestions і readyForProduction. Повторно використовуйте надані відповіді та явні делегації. Точне обрізання або корекція потребує лише деталей, що стосуються цієї зміни. Автоматичне схвалення витрат не надає креативних відповідей. Ці правила спільні для V4V MCP і Open Video Kit 0.3.6.

Ви можете почати з запиту на кшталт:

Знайди модель для восьмисекундного вертикального відео моєї керамічної чашки. Використай це зображення продукту: https://example.com/mug.jpg. Покажи мені концепт і необхідні вхідні дані перед генерацією.

Якщо модель не вказана, асистент за замовчуванням має використовувати Google/Gemini Omni Flash v1.2 (video.gemini_omni_flash-1-2), перевірити її поточну схему та доступність за допомогою get_model, перевірити баланс і підготувати вхідні дані. Після вашого запиту на генерацію він подає завдання і перевіряє готовий результат. Це правило є першим в інструкціях ініціалізації MCP і повторюється в описах list_models, get_model і generate_lab. Пошук відеомоделей повертає default_video_model; вибрана модель має позначку default_for_unspecified_video: true. Явний вибір моделі або воркфлову Studio/масового виробництва має пріоритет.

Для звичайних відеозапитів без явно вказаної моделі надавайте перевагу generate_lab з video.gemini_omni_flash-1-2. Асистент не повинен просити користувача вибрати модель лише через її відсутність. Явний вибір моделі та явно запитані воркфлови Studio/масового виробництва мають пріоритет. get_model залишається обов’язковим перед вибором вхідних даних і параметрів; якщо бажана модель вимкнена, недоступна або непридатна, поясніть обмеження і запитайте про альтернативу замість того, щоб мовчки витрачати кредити деінде. Маршрутизація провайдера налаштовується V4V, а не є параметром генерації. Використовуйте generate_studio для явно запитаного воркфлову Studio; пошук зображень, аудіо, перекладу та чату не змінюється.

Промпт video_brief допомагає перетворити мету, аудиторію та формат у план кадрів. Ресурс v4v://guide пояснює воркфлов генерації вашому асистенту.

13

Доступні інструменти#

ІнструментПризначенняСтворює генерацію?
list_modelsПошук увімкнених моделей; за потреби фільтрація за зображенням, відео, аудіо або чатомНі
get_modelПерегляд вхідних даних, опцій і обмежень моделі; також працює model: "studio"Ні
describe_studioПошук поточних стилів Studio, тривалостей, форматів, якості, голосів і обмежень медіафайлівНі
list_productsПошук власних продуктів; повторно використовуйте їхні ID як Studio input.product_idНі
list_avatarsПошук власних і активних публічних аватарів; повторно використовуйте ID як Studio input.avatar_idНі
estimate_generationПеревірка й оцінка запиту LAB/Studio без рендерингу або резервування кредитівНі
get_balanceПеревірка доступних кредитів акаунтаНі
get_usageПошук останніх завдань генераціїНі
get_fileПерегляд власного референсного файлуНі
import_mediaЗбереження публічного URL медіафайлу до вашої медіатекиНі
create_upload_linkСтворення обмеженого HTTP-запиту на завантаження; посилання для браузера доступне як запасний варіантНі
get_uploadОтримання статусу завантаження та ID файлуНі
upload_mediaПрограмне вбудоване завантаження байтів; уникайте великих base64 у тексті моделіНі
generate_labСтворення з конкретною моделлюТак — витрачає кредити
generate_studioСтворення відео з продукту або креативного брифуТак — витрачає кредити
get_taskПеревірка статусу, ID проєкту, стабільних ID медіа та поновлюваних підписаних посиланьНі
refresh_task_resultsОновлення підписаних URL результатів без рендерингуНі
list_projectsПошук власних Studio, воркфловів, LAB і API-проєктів у черзі за назвою, джерелом або папкоюНі
rename_projectПерейменування власного проєкту або майбутнього проєкту завдання в черзіНі
list_project_foldersПерелік тих самих папок, що показані в робочому просторі ПроєктиНі
create_project_folderСтворення папки робочого просторуНі
rename_project_folderПерейменування папки зі збереженням її проєктівНі
move_projectПризначення власної папки або використання folder_id: null, щоб прибрати з папкиНі
generate_studio_variantsПостановка в чергу 2–3 креативних варіантів із використанням наявного бюджету й контролів масового виробництваТак — коли варіанти запускаються
promote_to_exampleЛише для адміністраторів прикладів: копіювання/оновлення прикладу власного проєкту з явною видимістюНі

Пошук Studio зчитує вибраний воркфлов і активні стилі з цього розгортання; він не містить жорстко закодованих семи назв стилів і не припускає, що кожен воркфлов має обмеження у десять секунд. get_model з model: "studio" є псевдонімом для describe_studio. Важливі інструкції також є в описах інструментів для клієнтів, які не можуть читати v4v://guide.

Схеми моделей надходять з того самого каталогу, що використовується V4V LAB. Запитуйте get_model перед вибором параметрів; необхідні посилання, тривалості та формати залежать від моделі.

14

Повторне використання контенту бібліотеки та попередній перегляд вартості#

Виконайте list_products або list_avatars (опційно offset і limit, максимум 100). За замовчуванням аватари мають source: "all"; доступні фільтри owned і public. Повернутий next_offset дорівнює null на останній сторінці. Публічні ID аватарів містять префікс public:; зберігайте цей префікс. Кожен запис містить photo_count; Studio використовує основне фото аватара. Повертаються лише ваші власні приватні записи бібліотеки.

Використовуйте input.product_id і input.avatar_id у generate_studio або estimate_generation. parameters.avatar також приймає повернений ID аватара і продовжує підтримувати ID файлу або публічний URL зображення. Обирайте або input.avatar_id, або parameters.avatar. Фото з медіатеки використовуються напряму без повторного завантаження. Явні назви продукту, опис або вхідні зображення переважають збережені значення продукту. Активні ID/назви стилів використовують їхні збережені креативні інструкції; невідомі або неактивні ID/назви стилів повертають INVALID_PARAMETER з allowed_values. Вільні креативні вказівки розміщуйте в input.prompt і обирайте активний пресет (або пропустіть стиль, щоб використати виявлений стиль за замовчуванням).

json
{
  "source": "studio",
  "input": {
    "product_id": "0123456789abcdef01234567",
    "avatar_id": "public:0123456789abcdef01234568",
    "prompt": "A short product review"
  },
  "parameters": {
    "duration": 10,
    "style": "Product Review"
  }
}

Надішліть це до estimate_generation. Він повертає credits_estimated, не резервує кредити і не створює завдання або рендер. Оцінка для Studio пропускає реєстрацію персонажів у провайдера, зокрема коли вибрано аватар. Публічні URL медіа можуть імпортуватися для перевірки. Оцінки можуть змінюватися залежно від вхідних даних/тарифів; оцінки для чату описують початкове резервування, а не остаточні витрати токенів або ліміт витрат. Для рендерингу видаліть source і подайте ті самі вхідні дані до generate_studio з новим idempotency_key.

15

Варіанти, назви проєктів і приклади#

generate_studio_variants приймає name, спільні input/parameters, обов’язковий max_credits, idempotency_key та variants, що містить два або три об’єкти з необов’язковими перевизначеннями input/parameters. Наприклад: variants: [{parameters: {style: "UGC"}}, {parameters: {style: "Product Review"}}]. Кожен варіант — це окрема платна спроба. Це обгортка над наявною чергою пакетів Studio: вона повертає batch_id, використовує get_studio_batch для результатів і ті самі елементи керування паузою/бюджетом/переробкою. Вона ніколи не обходить обмеження пропускної здатності.

Використовуйте rename_project з project_id, який повертається list_projects, генерацією або get_task, та project_name (обрізаний, 1–200 символів). Перейменування також оновлює заголовок завдання та історію LAB, зокрема коли проєкт ще очікує створення. Воно не змінює оригінальний хеш запиту idempotency.

Тільки адміністратори прикладів бачать promote_to_example. Він приймає власний project_id зі збереженим результатом, обов’язковий active та surfaces: ["dashboard", "studio", "landing"] (оберіть будь-який піднабір). studio відповідає наявному прапору видимості ProVid/Studio. active: false приховує приклад усюди незалежно від вибраних розділів. Результат включає visible_on, щоб було зрозуміло фактичну видимість. Публікація вимагає запиту користувача; цей інструмент не витрачає кредити на генерацію.

16

Організуйте наявні проєкти#

Використовуйте list_projects для пошуку наявних проєктів без генерації. Він включає Studio, воркфлови, історію LAB та API-проєкти в черзі. Необов’язкові фільтри: source: "all" | "studio" | "workflow" | "lab", q для буквального пошуку за назвою та folder_id для власної папки або "unfiled". Пропустіть фільтр папки, щоб побачити всі проєкти. І list_projects, і list_project_folders приймають offset (за замовчуванням 0) і limit (1–100, за замовчуванням 50); використовуйте next_offset, доки він не стане null.

Наприклад, щоб організувати затверджені результати кампанії:

  1. Викличте list_projects з {"q":"approved"} і виберіть потрібні проєкти.
  2. Викличте list_project_folders; повторно використайте потрібну папку або викличте create_project_folder з {"name":"Summer campaign"}.
  3. Викличте move_project для кожного вибраного project_id з поверненим folder_id.
  4. Викличте list_projects з цим folder_id, щоб перевірити вміст папки.

Використовуйте move_project з folder_id: null, щоб видалити проєкт із папки. rename_project_folder приймає folder_id та name. Імена папок мають містити 1–80 символів після обрізання та бути унікальними у вашому акаунті; дублікат повертає FOLDER_NAME_CONFLICT. Після невизначеної відповіді на створення перелічіть папки перед повторною спробою. Переміщення та перейменування безпечні для повторення і не витрачають кредити, не генерують медіафайли та не змінюють результати. Проєкти в черзі зберігають свої імена та папки, коли їх створює воркер. Ці операції не можуть отримати доступ до проєктів або папок іншого акаунта.

17

Медіафайли та генерація#

Референсні медіафайли можуть бути публічним URL або власним ID файлу V4V. Поле з назвою image_url також приймає ID файлу; використовуйте схему моделі, щоб вибрати точне поле введення.

Автоматичне завантаження з прикріплених та локальних файлів

Асистент може завантажити оригінальний файл самостійно, якщо його середовище виконання має доступ до цього розгортання V4V. Вам не потрібно копіювати API-ключ у чат або повторно вибирати той самий файл.

  1. Викличте create_upload_link. Незважаючи на назву, інструмент також повертає upload_request: POST URL, обмежений заголовок x-upload-token та назву multipart-поля file.
  2. З інструменту виконання асистента надішліть фактичні байти локального файлу на цей URL, використовуючи multipart/form-data. Нехай HTTP-клієнт встановить boundary і вимкніть перенаправлення. Не конвертуйте зображення й не виводьте base64 у розмову.
  3. Прочитайте file_id у відповіді та підтвердьте через get_upload за upload_id.
  4. Визначте схему вхідних даних моделі, передайте цей ID у відповідне поле медіа (наприклад, Topaz image_url) і надішліть запитану генерацію.
  5. Для кількох референсів повторіть процес з окремим слотом завантаження для кожного потрібного файлу.

Токен завантаження дійсний 15 хвилин, приймає один файл розміром до 20 МіБ з урахуванням обмежень сервера і не може читати вашу медіатеку або витрачати кредити на генерацію. Фактичні байти передаються через HTTP; MCP надає обмежену авторизацію та контролює генерацію.

Для середовища виконання, де результат інструменту доступний як slot, двійкове передавання виглядає так:

python
import requests

upload = slot["upload_request"]
with open(local_file_path, "rb") as source:
    response = requests.post(
        upload["url"],
        headers=upload["headers"],
        files={upload["file_field"]: (filename, source, content_type)},
        allow_redirects=False,
        timeout=120,
    )
if response.status_code != 200:
    raise RuntimeError(f"Upload failed: HTTP {response.status_code}")
file_id = response.json()["file_id"]

Дозвіл хоста завантаження в Claude

Підключення MCP та мережевий доступ у пісочниці — це окремі речі. host_not_allowed означає, що пісочниця не може надіслати двійкове завантаження, хоча виклики MCP працюють.

Дотримуйтесь інструкцій Claude Web → Дозволити автоматичне завантаження файлів вище: відкрийте Налаштування → Можливості → Список дозволених доменів, додайте v4v.ai, *.v4v.ai та *.v4vcdn.space і увімкніть вихідний мережевий доступ. Для розробки окремо додайте h4000.kitpes.com. Обмеження, керовані робочим простором, можуть вимагати, щоб ці зміни вніс адміністратор.

Асистент має припинити після першої відмови та пояснити необхідне налаштування, не повторювати спроби протягом кількох хвилин і не конвертувати файл у текст моделі. Почніть нову розмову після оновлення дозволів і оновіть інструменти конектора після оновлення сервера.

Необов’язковий резервний варіант через браузер

Якщо ви обираєте ручне завантаження, відкрийте upload_url, виберіть оригінальний файл і повідомте асистента, коли він буде готовий. Асистент отримає ідентифікатор файлу через get_upload. Це резервний варіант, а не обов’язковий крок, коли автоматичне HTTP-завантаження працює.

upload_media залишається для програмного пересилання байтів або дуже малих payload до 8 КіБ у закодованому вигляді. Його серверне обмеження 5 МіБ у декодованому вигляді не є практичним текстовим бюджетом для мовної моделі. Не змінюйте розмір і не перекодовувайте джерело лише для передавання, не виводьте великі рядки base64 і не перебирайте закодовані фрагменти в циклі.

REST-завантаження для більших файлів

Якщо середовище виконання асистента має вихідний мережевий доступ і безпечно налаштований API-ключ, воно може завантажувати через POST /api/v1/files, використовуючи multipart-поле file. Ключ конектора MCP не доступний автоматично для shell-інструментів.

bash
# V4V_BASE_URL is this deployment's origin, e.g. https://h4000.kitpes.com
curl "$V4V_BASE_URL/api/v1/files" \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -F "file=@/path/to/photo.png"

id у відповіді — це ідентифікатор файлу, який слід використовувати у вхідних даних генерації. Нехай curl встановлює boundary для multipart. Зберігайте облікові дані в безпечній конфігурації клієнта, а не в розмові.

Публічні URL

Використовуйте import_media, щоб зберегти доступний URL медіа для повторного використання, або передайте URL безпосередньо моделі. Не передавайте локальний шлях або URL пісочниці як публічний URL.

Приклад аргументів для generate_lab (замініть приклад ID на ID, отриманий після завантаження):

json
{
  "model": "image-upscale-topaz",
  "project_name": "Product detail — enlarged",
  "input": {
    "image_url": "0123456789abcdef01234567"
  },
  "parameters": {
    "upscale_factor": "2"
  },
  "idempotency_key": "product-detail-upscale-001"
}

Приклад аргументів для generate_studio:

json
{
  "project_name": "Ceramic mug — launch video",
  "input": {
    "product_name": "Ceramic mug",
    "product_description": "A handmade mug with a matte glaze",
    "product_images": [
      "https://example.com/mug.jpg"
    ],
    "prompt": "A calm product reveal in soft morning light"
  },
  "parameters": {
    "duration": 8,
    "aspect_ratio": "9:16"
  },
  "idempotency_key": "mug-launch-video-001"
}

Використовуйте новий idempotency_key для кожної навмисної генерації. Повторно використовуйте той самий ключ і аргументи при повторній спробі після мережевого збою. Повторне використання ключа з іншими вхідними даними повертає конфлікт.

18

Отримання результату#

Інструменти генерації негайно повертають task_id та project_id. Якщо ліміт одночасних завдань акаунта вичерпано, те саме завдання очікує з credits_reserved: 0, credits_estimated та деталями queue, що містять налаштований ліміт, п’ятисекундний інтервал перевірки й estimated_start_at: null. Час завершення передбачити неможливо. Не надсилайте іншу генерацію, щоб обійти очікування. Воркер резервує кредити, коли відкривається слот; якщо на той момент балансу недостатньо, завдання завершується помилкою на етапі допуску й надсилає свій налаштований webhook. Вони не тримають розмову відкритою до завершення рендерингу.

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6"
}

Передайте цей ID у get_task. Чекайте принаймні п’ять секунд між перевірками. Завдання може бути у станах queued, processing, completed, failed або cancelled.

Коли статус completed, results містить вбудований текст для чату або підписані URL для завантаження медіа. Асистент може ділитися цими URL з вами без потреби в браузерних cookie. Використовуйте get_task або refresh_task_results, якщо посилання втратило чинність. Результати медіа включають стабільний asset_id/file_id; передавайте file_id безпосередньо в майбутні поля медіа генерації замість копіювання URL, строк дії якого минає. Умови повторного використання наступного дня — це стабільний ID плюс поновлюване посилання, доки файл існує й доступ дозволено; сам URL може втратити чинність. Посилання залишаються підписаними; ніколи не видаляйте підпис і не виводьте непідписаний CDN-шлях. У разі будь-якого кінцевого статусу припиняйте опитування. Перевірка завдання не запускає другу генерацію. Завдання з помилкою повідомляють error.stage, brief_completed, retryable та рекомендований retry_after_seconds, якщо відомо, разом із фактичними credits_used. Завершений brief може зберігати списання навіть якщо генерація відео не вдалася. retryable: true означає потенційно тимчасову помилку; це не дає права на ще одну платну спробу. Якщо завдання повертає GENERATION_SERVICE_ERROR, сервіс моделі повідомив про внутрішню помилку. Не припускайте, що її спричинили роздільна здатність джерела або коефіцієнт масштабування, і не перемикайте моделі та не створюйте нові платні спроби автоматично. Поясніть помилку й очікуйте запитаної повторної спроби.

Генерації Лабораторії також з’являються в LAB → Old runs та Проєктах. Використання вашого API-ключа відображається у вашому профілі.

19

Вебхуки завершення#

generate_lab та generate_studio приймають callback_url, використовуючи наявну REST-доставку вебхуків і перевірку підпису. V4V надсилає task.completed або task.failed зі стабільним event_id, даними завдання, кредитами та результатами. Перевіряйте X-V4V-Timestamp та X-V4V-Signature за допомогою секрету підпису вебхука, показаного під час створення API-ключа, і усувайте дублікати за event_id. Не вставляйте секрети в чат. Повторні спроби доставки не створюють нових генерацій. URL зворотного виклику використовують ту саму перевірку зовнішньої мережі, що й REST. Масові та варіантні відправлення також приймають callback_url для підписаних пакетних подій; див. воркфлов моніторингу нижче. Див. Перевірка REST вебхуків.

20

Кредити та доступ#

Генерація використовує ваші звичайні кредити V4V. Для звичайних завдань LAB/Studio орієнтовна вартість резервується, коли є пропускна здатність; надлишкові завдання очікують без резервування. Невикористані кредити звільняються за тими ж правилами, що й REST API. Перегляд моделей, балансів, завдань і існуючих файлів не витрачає кредити на генерацію.

Кожен інструмент обмежений власником налаштованого ключа. Файли та завдання іншого акаунта недоступні. Відкличте ключ у вашому профілі, щоб вимкнути його MCP-підключення. Анотації інструментів позначають виклики, що створюють роботу та витрачають кредити, щоб ваш клієнт міг запропонувати звичні засоби підтвердження для інструментів.

21

Усунення несправностей#

СимптомЩо перевірити
Відсутні create_upload_link або upload_mediaОновіть або перепідключіть конектор MCP, щоб клієнт виявив оновлений список інструментів
HTTP 401Використовуйте дійсний, не відкликаний ключ у x-api-key або Authorization з префіксом Bearer ; видаліть конфліктні заголовки
HTTP 403Для браузерного клієнта його Origin має бути дозволений розгортанням
HTTP 405 у браузеріКінцева точка приймає MCP POST-запити; використовуйте MCP-клієнт
HTTP 406Клієнт має приймати і application/json, і text/event-stream
HTTP 429 / RATE_LIMIT_EXCEEDEDПерегляньте error.retryable та retry_after_seconds у JSON; обмеження вікна запитів також включають scope і limit. Зачекайте вказану затримку й повторно використайте той самий запит / ключ ідемпотентності для відхиленого запиту. Завдання, яке вже завершилося помилкою, залишається в кінцевому стані. Обмеження акаунта та ключа спільні з REST.
Результат інструменту має isError: trueПерегляньте структуровану помилку, виправте вхідні дані та уникайте сліпих повторних генерацій
Вхідні дані моделі відхиленоОновіть get_model і використовуйте його поточну схему
Завдання залишається в черзі або в обробціПродовжуйте перевіряти із затримкою; не надсилайте автоматично замінну генерацію

Сервіс використовує офіційний MCP TypeScript SDK та безстанний режим JSON-відповіді через Streamable HTTP. Інструменти з обмеженим часом очікування утримують індивідуальний запит відкритим до оновлення або тайм-ауту; вони не встановлюють постійний канал сповіщень. Клієнт узгоджує версію протоколу при підключенні.

Варіанти зображень GPT Image 2.5

Виявлення моделей включає текстові й візуальні варіанти Flare та Sunburst зі стандартними налаштуваннями Sunburst для image.text_to_image та ai.image_edit. Вони підтримують background, тарифи 1K/2K/4K (6/10/16 кредитів), промпти до 20 000 символів та до 16 зображень для редагування. Див. налаштування GPT Image 2.5 та приклади API, щоб дізнатися ідентифікатори варіантів і обмеження співвідношення сторін.

22

Відеомоделі Kling 4.0#

Чотири окремі вузли мають однакові механізми генерації та обробки результатів у Лабораторії, Воркфловах, API та MCP:

Ідентифікатор каталогуМодельТривалістьРоздільна здатність
video.kling_v40_refKling 4.0 Reference3–30 секунд720p / 1080p
video.kling_v40_keyKling 4.0 Keyframe3–30 секунд720p / 1080p
video.kling_v40_flash_refKling 4.0 Flash Reference3–20 секунд720p
video.kling_v40_flash_keyKling 4.0 Flash Keyframe3–20 секунд720p

Усі приймають обов’язковий prompt (до 8000 символів), цілочисельні duration, resolution та aspectRatio (auto, 16:9, 9:16, 1:1, 21:9; Flash Keyframe виключає auto). Усі можуть генерувати лише з тексту. Вхідні дані Reference є необов’язковими.

Моделі Reference приймають referenceImageUrls (до 10), referenceVideoUrls (до 5), elements (до 7, не більше 3 з відео) та keepOriginalSound. Іменований елемент має name, або imageUrls (2–4 зображення), або videoUrl (один 3–8-секундний кліп персонажа), необов’язкові tag, description (100 символів) та voiceUrl для голосу персонажа. Flash також приймає тип елемента type (image або video). Стандартний Reference додатково приймає voices: до 3 об’єктів з name та audioUrl. Flash натомість прив’язує голоси до елементів персонажів.

Максимум 15 сумарно зображень, референсних відео, елементів та окремих голосів; референсні відео плюс відеоелементи не можуть перевищувати 5. Кожне референсне відео має тривати 2–30 секунд (2–20 секунд для Flash), а їх сумарна тривалість разом із відеоелементами — не більше 30 секунд (20 секунд для Flash). Імена мають бути унікальними без урахування регістру, складатися з 1–20 китайських символів, літер, цифр або підкреслень; вбудовані імена референсів зарезервовані. Згадуйте надані референси як @image_1, @video_1 або їх оголошене @name. Неоголошені згадки відхиляються.

Моделі Keyframe використовують firstFrameUrl. Стандартний Keyframe також приймає впорядковані keyframeUrls (до 8 проміжних кадрів) та lastFrameUrl; для них потрібен перший кадр. Загальна кількість кадрів не може перевищувати min(duration + 1, 10). Flash Keyframe підтримує лише перший кадр. Згадуйте кадри як @first_frame, @keyframe_1, @last_frame. Результат на основі кадрів наслідує співвідношення сторін першого зображення.

Усі медіа-поля, включно з вкладеними елементами та голосами, приймають URL або власні V4V ідентифікатори файлів у API/MCP. Порти зображень/відео воркфлову використовують reference_image_urls / reference_video_urls або first_frame_url / keyframe_urls / last_frame_url; промпти використовують script-in. Стандартний Reference також приймає аудіо на voice_audio_urls, оголошене як @voice_1, @voice_2 тощо. Обидва виходи воркфлову є стандартними video / clips, придатними для існуючого рендерера та редактора. API/MCP повертають звичайне асинхронне завдання та завантажувані файли результатів; опитуйте завдання або використовуйте вебхуки завершення.

Затверджені базові тарифи в кредитах V4V за секунду, до адміністраторських перевизначень або наявних коригувань воркфловів. Ці тарифи застосовуються безпосередньо, без конвертації в USD або роздрібної націнки:

Модель720p, без відео720p, з відео1080p, без відео1080p, з відео
Стандартний Reference28.51742.525.5
Стандартний Keyframe28.5недоступно42.5недоступно
Flash Reference1711.3недоступнонедоступно
Flash Keyframe17недоступнонедоступнонедоступно

Приклади для 5-секундного відео:

Модель5 с без вихідного відео5 с з вихідним відео до 5 с
Стандартний Reference, 720p142.5 кредитів170 кредитів
Стандартний Reference, 1080p212.5 кредитів255 кредитів
Стандартний Keyframe, 720p / 1080p142.5 / 212.5 кредитівнедоступно
Flash Reference, 720p85 кредитів113 кредитів
Flash Keyframe, 720p85 кредитівнедоступно

Без відеовходу оплачувані секунди дорівнюють вихідним секундам. Із референсним відео або відеоелементом оплачувані секунди дорівнюють max(total input video seconds, output seconds) + output seconds за відповідним тарифом для відеовходу. Наприклад, 10-секундний 1080p Standard Reference з 15 секундами вхідного відео — це 25 оплачуваних секунд, 637.5 кредитів до коригувань. Дробові кредити зберігаються; повна вартість округлюється один раз до двох десяткових знаків. Якщо тривалість входу невідома, для консервативної оцінки використовується максимальна дозволена тривалість вхідного відео для моделі; сервер перевіряє фактичну тривалість джерел перед списанням. Запитуйте актуальну оцінку з тими самими вхідними даними, що й для генерації. В адміністративній панелі для кожного вузла доступні окремі тарифи за роздільною здатністю та відеовходом. Старі вузли Kling зберігають свої поточні ціни та налаштування.

json
{
  "model": "video.kling_v40_key",
  "input": {
    "prompt": "Move from @first_frame to @keyframe_1 and finish at @last_frame",
    "firstFrameUrl": "https://example.com/start.png",
    "keyframeUrls": [
      "https://example.com/middle.png"
    ],
    "lastFrameUrl": "https://example.com/end.png"
  },
  "parameters": {
    "duration": 5,
    "resolution": "1080p",
    "aspectRatio": "16:9"
  }
}

Використовуйте це тіло запиту з generate_lab у MCP або POST /api/v1/lab у HTTP. Для оцінки додайте "source": "lab" та використовуйте estimate_generation у MCP або POST /api/v1/generation/quote у HTTP. Завжди спочатку отримуйте дані про вибрану модель через get_model або GET /api/v1/models/{id}. Застосовуються стандартні авторизація генерації, перевірки балансу, ключі ідемпотентності, зворотні виклики та відшкодування в разі невдачі.

23

GPT-6 Astra чат#

Використовуйте list_models з {"type":"chat"}, потім get_model з {"model":"chat.gpt_6_astra"} для перегляду поточних вхідних даних, тарифів на токени та округлення. Надсилайте через generate_lab:

json
{
  "model": "chat.gpt_6_astra",
  "input": {
    "prompt": "Explain this idea in three sentences."
  },
  "parameters": {
    "reasoningEffort": "low",
    "webSearch": false,
    "stream": false
  },
  "idempotency_key": "astra-question-001"
}

Optional input.imageUrls accepts up to 12 public URLs or owned file IDs. Text-only requests use string input upstream; images use the model’s multimodal message array. Optional input.functionTools accepts a JSON string of function definitions; web search must be off when functions are present. Function selection is automatic, and completed task results include function_calls for the caller to handle. The model node does not execute functions. Poll get_task using the returned task ID. Completed results entries have type: "text", text, usage, credits and incomplete instead of a download URL.

Чат спочатку резервує 1 кредит. Остаточна вартість визначається за фактичними вхідними, кешованими та вихідними токенами, округлюється вгору до цілого кредиту й має мінімум 1 кредит. Будь-яка сума понад резервування списується після відповіді; початкове резервування не є лімітом витрат. Тарифи на токени публікує get_model. Повторно використовуйте той самий ключ ідемпотентності та аргументи для мережевих повторів; не надсилайте автоматично іншу платну генерацію після помилки.

Для чатів та генерації з оплатою за використання estimate_generation також повертає credits_range.min та credits_range.max у кредитах V4V, з урахуванням націнки та поточних коригувань цін. Представляйте це як приблизний діапазон. Його assumptions описують ілюстративні сценарії використання; фактична вартість може виходити за межі діапазону, а is_spending_cap — false. credits_estimated та initial_reservation_estimated залишаються окремою оцінкою початкового резервування. Цей перегляд не резервує кредити і не запускає генерацію.

24

Поточні моделі зображень і чатів#

Omni Flash 1.2 is the default for an unspecified video request; 1.1 remains available by explicit selection. Use get_model for image.text_to_image or ai.image_edit to discover GPT Image 2.6 Flare, Sunburst and Economy variants. Pass parameters.outputFormat and respect allowed_by_variant: Flare/Sunburst text-to-image support PNG/JPEG/WebP/GIF/SVG; their image-to-image variants support PNG/JPEG/WebP; Economy text supports PNG/GIF and Economy image supports PNG. Output downloads preserve GIF frames and SVG vector bytes. SVG conversion usage is included in final billing.

Nano Banana 2.1 (parameters.variant: "nano-banana-v2.1") підтримує 1K/2K/4K та до 10 референсів. Читайте pricing_by_variant для поточного режиму нарахування. Генерація через Google/Vertex тарифікується за фактичними вхідними, кешованими вхідними, вихідними токенами зображення, вихідними текстовими токенами та токенами мислення, включно з націнкою; інші маршрути використовують налаштований тариф на зображення. Gemini 4 Argon (chat.gemini_4_argon) включає токени мислення в тарифікацію за використанням. Використовуйте estimate_generation для показу приблизних діапазонів кредитів; початкове резервування та діапазон є окремими від остаточного використання й не є лімітами витрат. Ніколи не вигадуйте параметри маршрутизації й не змінюйте адміністративні налаштування без повідомлення.

25

Масові відео продуктів у Студії#

Використовуйте generate_studio_bulk, коли потрібні відео для списку продуктів. Приймає від 1 до 300 елементів і негайно повертає batch_id. Використовує звичайний баланс кредитів облікового запису та спільну чергу генерації V4V з REST та веб-застосунком.

json
{
  "name": "Autumn product videos",
  "input": {
    "prompt": "Show three benefits in a calm product reveal"
  },
  "parameters": {
    "duration": 8,
    "aspect_ratio": "9:16"
  },
  "max_credits": 600,
  "test_count": 5,
  "items": [
    {
      "sku": "MUG-01",
      "product_id": "0123456789abcdef01234567"
    },
    {
      "sku": "BAG-02",
      "product_url": "https://shop.example/products/bag?variant=blue"
    },
    {
      "sku": "LAMP-03",
      "input": {
        "product_name": "Desk lamp",
        "product_images": [
          "https://shop.example/lamp.jpg"
        ]
      },
      "parameters": {
        "style": "TV Spot"
      }
    }
  ],
  "idempotency_key": "autumn-products-001"
}

Вхідні дані елемента та параметри перевизначають спільні налаштування; решту заповнюють стандартні налаштування Студії. Надавайте власні ідентифікатори продуктів, публічні URL сторінок продуктів або підготовлені дані й медіафайли продукту. Використовуйте налаштування, які підтримує поточна модель Студії в цьому розгортанні. Пропустіть test_count, щоб обробити весь список. З test_count: 5 перші п’ять елементів (або всі елементи, якщо їх менше п’яти) запускаються до того, як пакет стане на паузу для перегляду.

ІнструментПризначенняВикористовує кредити генерації?
generate_studio_bulkСтворення пакету відео продуктів з обов’язковим бюджетом кредитівТак, при запуску кожного елемента
list_studio_batchesПерелік останніх пакетів облікового записуНі
get_studio_batchЧитання посторінкового прогресу, ID завдань елементів, результатів та стабільного state_tokenНі
wait_studio_batchОчікування змін, завершення, паузи або скасування; за замовчуванням 25 секундНі
control_studio_batchpause, resume, cancel, retry_failed, rework або restart; необов’язковий max_credits збільшує сумарний бюджетВідновлення та нові спроби можуть використовувати кредити

DIRECTOR_REQUEST_FAILED ідентифікує відхилення текстового запиту AI Director; REFERENCE_MEDIA_UNAVAILABLE вказує на проблему зчитування його файлів посилань. Пояснюйте невдалий етап і повідомляйте ID завдання; ніколи не припускайте, що це означає невдачу запиту на генерацію відео або автоматично не створюйте іншу платну спробу.

Публічні URL-адреси товарів eBay підтримують резервний імпорт через захищений браузер. Якщо магазин все ще відхиляє імпорт, надішліть власний product_id або підготовлені деталі/зображення товару. IMPORT_FAILED виникає до платного допуску і містить відому причину імпорту; PREPARATION_FAILED вказує на пізнішу помилку підготовки. Невдала спроба залишається кінцевою. Коли користувач запитує повторну спробу, викликайте control_studio_batch з action: "retry_failed" та новим idempotency_key; за бажанням вкажіть індекси елементів з нуля item_indexes. Для виправлених вхідних даних або навмисного перероблення використовуйте action: "rework" з items: [{task_id: "task_…", input: {prompt: "New direction"}}] (або використовуйте index: 1 замість task_id). Використовуйте action: "restart" лише коли користувач запитує всі елементи знову, включно з успішними. Ці три дії вимагають нового ключа для кожної навмисної операції; повторно використовуйте той самий ключ і аргументи при мережевих помилках. resume не повторює невдалі спроби.

Щоб переробити лише ті результати, які вам не подобаються, виберіть їхні поточні items[].task_id і викличте control_studio_batch з action: "rework", цими ID в items та новим idempotency_key. Не вносіть зміни до вхідних даних, щоб повторно виконати той самий бриф. Вибрані поточні результати очищуються негайно, і той самий пакет відновлює обробку; інші завершені елементи залишаються без змін. items[].results завжди описує останню цільову версію, тоді як attempts зберігає старіші результати. Застарілий замінений ID завдання повертає BATCH_ITEM_VERSION_CHANGED; перечитайте пакет перед новою навмисною переробкою.

Моніторинг партії через браузерний конектор Claude

Вебхук надсилає HTTP-запит реальному приймачу. Він не дає цьому MCP-з’єднанню способу перезапустити бездіяльну розмову браузера Claude. Ніколи не вигадуйте URL зворотного виклику і не обіцяйте майбутнє повідомлення чату після завершення розмови.

Під час воркфлову партії за запитом користувача Claude має автоматично моніторити:

  1. Зберігайте batch_id та state_token з generate_studio_bulk, generate_studio_variants або get_studio_batch.
  2. Викликайте wait_studio_batch з batch_id, after_state, встановленим на цей токен, та wait_seconds: 25 для браузерних конекторів. За потреби використовуйте пагінацію через offset і limit (за замовчуванням 50, максимум 100).
  3. Сервер повертає відповідь при значущій зміні партії, завершенні, паузі, скасуванні або по закінченню часу очікування. Серцебиття робітника та термін дії підписів результатів не змінюють токен. У відповіді міститься оновлена сторінка партії, changed, timed_out, stop_reason і next_action.
  4. Поки status дорівнює running, продовжуйте чекати з отриманим токеном без прохання користувача «перевірити знову». Повідомляйте про корисні етапи, а не про кожен тайм-аут без змін. Тайм-аут не означає помилку або скасування генерації. Не надсилайте заміну партії.
  5. При completed повідомляйте про результати та помилки. При paused пояснюйте waiting_reason і чекайте рішення користувача. Ніколи не відновлюйте автоматично, не збільшуйте бюджет і не повторюйте платні спроби. cancelled також завершує цей цикл моніторингу.

Тут використовується серверне довготривале опитування в межах активного воркфлову інструмента. Якщо Claude завершує свій хід, користувач закриває розмову або клієнт накладає обмеження часу виконання, пакет усе одно продовжує виконуватися, але це з’єднання не може гарантувати нове повідомлення в чаті. Скасування/відключення очікування лише припиняє спостереження, а не пакет. Перевірка або очікування не витрачає кредити генерації.

wait_seconds приймає значення від 1 до 240 секунд. Claude Code підтримує автоматичне фонове виконання довгих викликів MCP у останніх версіях; для 240-секундного очікування налаштуйте timeout сервера щонайменше на 300000 мілісекунд і дозвольте запит через тайм-аути проксі. Браузерні конектори повинні використовувати стандартні 25 секунд. Див. Claude Code long tool calls. Ця поведінка специфічна для клієнта і не гарантує пробудження браузера.

Вебхуки партії для зовнішніх приймачів

Передайте callback_url під час створення масового пакета або варіантів. Застосовуються наявний секрет підпису вебхуків API-ключа та перевірка X-V4V-Timestamp / X-V4V-Signature. Адреса callback фіксується ідемпотентним запитом на створення; повторно використовуйте той самий URL і аргументи після мережевих помилок.

Робітник фіксує значущі знімки стану й доставляє події batch.updated, batch.completed, batch.paused та batch.cancelled. Події містять стабільні event_id, batch_id, batch_revision, observed_at, state_token, статус, лічильники та загальні суми кредитів. result_lookup вказує на get_studio_batch для пагінованих файлів і деталей завдань; тіла вебхуків не містять URL-адрес результатів, строк дії яких спливає. Проміжні переходи можуть об’єднуватися між циклами робітника.

Доставка використовує надійну outbox-чергу з орендами й обмеженою кількістю повторних спроб. Повторна доставка має той самий ID події й те саме навантаження; підписи оновлюються для кожної спроби. Приймачі мають дедуплікувати події та витримувати доставку поза порядком, а за потреби отримувати поточний стан пакета. Постійні HTTP-помилки припиняють доставку; для тимчасових збоїв інтервал між спробами збільшується. Повільний приймач вебхука не блокує робітника генерації/допуску. Пауза, скасування з активною роботою та пізніші запитані перезапуски/переробки й надалі генерують оновлення. Доставка ніколи не запускає іншу платну спробу.

Для періодичних ручних перевірок статусу викликайте get_studio_batch не частіше ніж раз на п’ять секунд; для активного моніторингу агентів краще використовувати wait_studio_batch. Окремі спроби використовують звичайний інструмент get_task для підписаних посилань на завантаження. Ці інструменти продовжують обробку на сервері без відкритої розмови або вкладки браузера.

Черги масових операцій резервують лише оцінку наступного допущеного елемента. max_credits обмежує витрачені кредити плюс активні резервування. Недостатній баланс або бюджет призупиняє нові запуски; після запиту користувача викликайте control_studio_batch з action: "resume", за потреби збільшуючи max_credits. Паузування або скасування дозволяє активним спробам завершитися. Скасовані пакети не можна відновити, але можна явно перезапустити або переробити термінальні елементи після завершення допущеної роботи. Вибрані елементи мають бути в термінальному стані (BATCH_ITEMS_ACTIVE); активні або невизначені запити до провайдера блокують повтори (GENERATION_UNRESOLVED). NO_FAILED_ITEMS означає, що останніх невдалих елементів не залишилося. Історія, результати та накопичені витрати зберігаються в усіх операціях; лічильники та статус елементів використовують лише останні цільові версії. Нові версії використовують ті самі черги та атрибуцію в Журналі кредитів. За бажанням зміни вхідних даних/параметрів для всієї операції накладаються поверх попереднього запиту, а перевизначення для переробки окремих елементів мають пріоритет. Збережений пробний етап усе одно вимагає явного відновлення; перезапуск його прибирає. Див. REST-контракт для обмежень запитів/історії та повних прикладів. Повторно використовуйте той самий idempotency_key і аргументи після мережевої помилки; ніколи не створюйте інший пакет, щоб обійти очікування в черзі.

Запити на генерацію ділять максимум 10 активних слотів між акаунтами та процесами застосунку. Звичайна генерація має пріоритет; масові операції використовують вільні ресурси в межах глобальних і користувацьких обмежень, визначених адміністратором. Втрачені відповіді провайдера утримують слот для узгодження і ніколи не запускають автоматичний дубльований платний запит. Події кредитів API і MCP маркуються окремо в Журналах кредитів адміністратора.

Цей реліз надає генерацію та індивідуальні завантаження через API/MCP. Ширші можливості Студії для масових операцій, завантаження CSV, затвердження результатів і ZIP-експорту залишаються майбутньою роботою. Оновіть список інструментів вашого MCP-конектора після розгортання, щоб виявити нові інструменти для пакетної обробки. Див. REST bulk contract для полів, семантики бюджету та помилок.

26

Відеоредактор#

Редактор за адресою /video-editor дозволяє вам і вашому помічнику працювати над тією самою збереженою багатошаровою монтажною шкалою. Він підтримує відео, зображення/логотипи, вихідне аудіо, незалежні музичні/голосові доріжки, текст, синхронізовані субтитри, обрізання, розділення, швидкість, гучність, затухання та нотатки для перегляду дублів. Браузер забезпечує інтерактивний перегляд і локальний експорт MP4/WebM. Відкрийте Відеоредактор для інтерактивного редагування; інструменти та обмеження описані нижче.

Почніть з get_editor_guide (також доступний як ресурс v4v://video-editor). Оновіть список інструментів конектора після розгортання.

Для повноцінної фабрики контенту прочитайте get_factory_guide / v4v://factory. create_factory_run, list_factory_runs, get_factory_run та submit_factory_stage зберігають дев’ять ролей із точними повторами операцій і окремими ревізіями запуску/проєкту. prepare_factory_review повертає реальні захоплені зображення, get_factory_frame знову їх зчитує, а preview_factory_audio повертає виміряний WAV-фрагмент. Перевіряйте кожен захоплений кадр і переглядайте рух/мовлення перед винесенням оцінки. repair_factory_run дозволяє не більш як дві корекції; release_factory_run ставить у чергу, а потім перевіряє повний приватний експорт до медіатеки, редагований ZIP, обкладинку і REVIEW.md. Ці інструменти вимагають володіння проєктом; записи потребують OAuth читання + запису, без дозволу на генерацію або списання кредитів. Платна генерація сцен залишається окремою бюджетованою операцією. Див. Ukrainian factory contract для HTTP-маршрутів, відновлення та виміряних і наданих рецензентом доказів.

ІнструментПризначення
get_editor_guideКонтракт монтажної шкали, воркфлов редагування та приклад порожньої монтажної шкали
get_motion_guideВерсійований API руху, актуальні схеми, нативні/HTML-приклади, одиниці часу/геометрії та життєвий цикл; також v4v://motion-api
get_editor_troubleshootingВерсійовані рекомендації з відновлення для актуальних помилок; також v4v://troubleshooting; читання ніколи не виконує відновлення або повторну спробу
get_project_transfer_guideЛокальна/V4V ZIP-сумісність, бінарні запити, дозволи та відновлення; також v4v://project-transfer
export_editor_bundleПідготувати обмежений бінарний запит на завантаження проєкту на поточній ревізії; виконати його для отримання фактичного ZIP
import_editor_bundleПідготувати бінарне завантаження ZIP з {}, потім відновити новий проєкт за transfer_id; без base64 у тексті моделі
get_editor_capabilitiesАктуальні формати, середовища виконання, локальні/спільні операції та опціональні сервіси
get_creative_library / search_creative_libraryВиявити встановлений спільний реєстр креативних ресурсів
get_creative_itemТочна схема одного елемента, оригінальний приклад, шляхи прев’ю, ліцензія та обмеження
get_style_format_guideФормат пакета спільноти лише з даними; той самий вміст, що й v4v://style-format
create_style_exampleІмпортувати новий редагований приклад стилю та оригінальний медіафайл в акаунт; без кредитів моделі
apply_styleПопередній перегляд з dry_run=true, потім застосувати на тій самій ревізії; блокування та ручні перевизначення зберігаються
check_editor_projectСтруктурний/медійний огляд P0/P1; окремо перевірити фактичні кадри та аудіо
list_editor_projectsЗнайти власні/спільні проєкти редактора, фільтрувати scope та читати рівні доступу
create_editor_projectСтворити порожній проєкт або перевірену монтажну шкалу
get_editor_projectПрочитати монтажну шкалу, ревізію та поновлювані URL медіа
update_editor_projectЗберегти повну монтажну шкалу на очікуваній ревізії
edit_editor_projectЗастосувати атомарні операції з кліпами/шарами/підписами на очікуваній ревізії
propose_editor_silence_cutsВиміряти фактичне вихідне аудіо та запропонувати доповнені тихі інтервали без редагування; явно застосувати переглянуті remove_time_ranges на тій самій ревізії для зсуву всіх доріжок
propose_editor_audio_duckingВиміряти фактичні голосові/музичні доріжки та запропоновану автоматизацію; перевірити RMS до/після, потім явно застосувати повернені set_audio_envelope на тій самій ревізії
get_safe_area_guideВерсійовані редакційні профілі призначення та власна схема; також v4v://safe-areas
inspect_editor_textВиміряти збережений нативний/анімаційний/HTML-текст із вбудованими шрифтами та повідомити про виявлене переповнення, перекриття та проблеми читабельності
propose_editor_text_fitЗапропонувати розмір шрифту статичного тексту без зміни слів, часу або збереженого проєкту
propose_editor_scene_layoutЗапропонувати явні межі анімаційного/HTML-контенту та мінімальний розмір шрифту з профілю безпечної зони; переглянути та застосувати повернені set_scene_layout
list_editor_mediaШукати власні медіафайли в медіатеці за типом і назвою
get_editor_mediaПеревірити тривалість, розміри та URL відтворення власного джерела
preview_editor_projectПовернути до шести фактичних скомпонованих JPEG-кадрів для візуальної перевірки
get_editor_text_stylesВиявити пресети тексту/підписів, контури, рух та реакцію на звук
quote_editor_captionsПроцитувати транскрипцію мовлення джерела без генерації
transcribe_editor_mediaПочати транскрипцію мовлення; витрачає звичайні кредити акаунта
get_editor_captionsПрочитати прогрес транскрипції та часові мітки джерела
append_editor_audioДодати впорядковані ID аудіомедіафайлів до розблокованого шару з опціональними паузами
export_editor_projectПоставити в чергу/відновити MP4, WebM, MP3 або MP4 зі статичною обкладинкою; негайно повернути export_id
get_editor_exportОпитувати статус/етап і отримати завершений медіафайл медіатеки з поновленими посиланнями
get_editor_project_sharingВласник: перелічити співавторів і повернути приватне посилання на проєкт
share_editor_project_with_userВласник: запросити за email або змінити доступ для читання/запису, опціонально повідомити email
remove_editor_project_accessВласник: відкликати доступ співавтора за ID користувача
transfer_editor_project_ownershipВласник: явно передати іншому акаунту V4V за email
share_editor_projectОпублікувати публічне посилання на поточне експортоване відео за явним запитом

API руху та відновлення

Починаючи з Kit 0.1.31, get_motion_guide та get_editor_troubleshooting приймають {} і точно відповідають своїм JSON-ресурсам. Обидва містять version та engineVersion; виявляйте інструменти поточного сервера після розгортання. Їхній OAuth-скоуп V4V — v4v:read. Читання цих ресурсів не редагує, не рендерить, не повторює спроби та не резервує кредити.

Посібник з руху містить актуальні зареєстровані схеми, нативні та HTML-приклади add_clip, детермінований життєвий цикл prepare / renderAt / dispose, локальний час сцени та правила дробової геометрії. У новому порожньому проєкті застосуйте приклади операцій на збереженій ревізії та перегляньте секунди 1 і 5. У наявних проєктах свідомо адаптуйте ID доріжок/кліпів і розміщення. Приймаються лише зареєстровані JSON-сцени; монтажна шкала не встановлює довільний HTML або скрипти. Перевірте фактичні кадри та експортований рух перед прийняттям.

Використовуйте засоби усунення несправностей із фактичним кодом помилки та збереженим станом. CONFLICT означає перезавантаження зі збереженням одночасних змін; відсутність медіа вимагає авторизованого реального джерела; відсутність шрифтів потребує явного відновлення. Перевірте наявну спробу експорту/кадру після невідомої відповіді. Читання рецепта відновлення ніколи не авторизує нову покупку, обхід дозволів або перезапуск скасованої операції.

Виміряні пропозиції макету та аудіо

Профілі safe-area — це редакційні настанови з версіями, а не офіційні гарантії платформи. set_safe_area_profile зберігає настанову без зміни відрендерених пікселів. propose_editor_scene_layout використовує її, щоб запропонувати явний motion.layout; перегляньте applicable і звіт, а потім застосуйте повернуті ним операції через edit_editor_project у тій самій ревізії. layout:null скасовує це налаштування. Подальша зміна настанови не перерозміщує вміст автоматично. inspect_editor_text вибирає зразки реальних гліфів/DOM-боксів; текст у вбудованих медіафайлах, обрізання з поворотом, контраст поверх відеоряду, повний рух і прослуховування залишаються завданнями для перевірки.

Для музики під голосом викликайте propose_editor_audio_ducking з фактичними project_id, revision, неперетинними voice_clip_ids та music_clip_ids, а також опціональними options. За замовчуванням ціль — запас 12 дБ RMS між голосом і музикою, виявлення активності на −40 дБFS та обмеження послаблення до 30 дБ. Сервіс змішує вибрані джерела з їхніми фактичними обрізками, швидкістю, гучністю та затуханнями; він також заново міксує й вимірює запропоновану музику. Перевірте базовий comparison, виміряний after, targetMet, попередження та інтервали фраз, прослухайте, потім явно застосуйте повернені operations через edit_editor_project на тій самій ревізії.

Вибрана музична автоматизація замінюється, а не накопичується; базове підсилення й затухання зберігаються. Криві переносні в ZIP і слідують за музичним кліпом. Перераховуйте після зміни часу/рівня голосу, джерел або розміщення музики. До 500 голосових і 20 музичних кліпів, 100 МіБ на джерело V4V, 512 МіБ загалом та 64 кліпи, що перетинаються, на вікно аналізу; також застосовуються обмеження ресурсів і швидкості. Доступ на читання дозволяє пропозиції, а їх застосування вимагає доступу на запис. Ані вимірювання, ані локальне редагування не витрачають кредити. RMS і виявлена амплітуда не доводять розбірливості; пропозиції тихих вирізів так само потребують прослуховування перед редагуванням зі зсувом усіх доріжок.

Портативний ZIP через V4V MCP

Прочитайте get_project_transfer_guide / v4v://project-transfer. Обидва хости використовують однаковий вміст .v4v.zip: версійований bundle.json та оригінальні байти assets/<sha256>. Лише локальний Kit приймає аргумент directory; V4V явно відхиляє локальні шляхи файлової системи.

Експорт: викличте export_editor_bundle з project_id та поточною revision, потім виконайте його download_request з точним обмеженим заголовком і збережіть фактичну бінарну відповідь. Інструмент підготував запит, але ще не створив файл. Завантаження повторно перевіряє акаунт/ключ/OAuth, доступ до проєкту/медіа та ревізію. Відповідь містить X-Content-SHA256; порівняйте завантажені байти. Якщо проєкт змінився, знову прочитайте його ревізію та свідомо запросіть інший експорт.

Імпорт: викличте import_editor_bundle з {}, виконайте POST оригінальних байтів ZIP за допомогою поверненого upload_request (application/zip, не multipart), потім викличте import_editor_bundle з його transfer_id. Це створює новий проєкт, перевіряє/досліджує джерела та переназначає вкладені ID медіафайлів. Після втрати підтвердження відновіть той самий трансфер: завершений імпорт повертає наявний проєкт. Перерваний імпорт може відновити свою прострочену оренду за оригінальними байтами; інший файл вимагає нового трансферу. Ніколи не вигадуйте дані файлу й не вставляйте великий base64 у контекст моделі. Клієнти без доступу до бінарних файлів можуть використовувати в Студії Open project ZIP.

Облікові дані трансферу діють 15 хвилин; квитанції залишаються доступними для відновлення сім днів. Токени мають міститися в заголовку поверненого запиту, а не в URL, монтажних шкалах чи публічних повідомленнях. Імпорт вимагає OAuth читання + запису; експорт — читання та поточного доступу до проєкту. ZIP і розпакований вміст обмежені 100 МіБ; застосовуються два трансфери на процес, обмежені тіла запитів, оренди та обмеження швидкості на користувача/запит. Імпорт/експорт не виконує генерацію, публічний спільний доступ або сповіщення. Права спільного доступу акаунта та облікові дані моделей не передаються в ZIP. Повторно відкрийте повернений проєкт і перевірте фактичні медіа/кадри перед передаванням.

Приватний спільний доступ до проекту через MCP

Асистент може завершити приватний спільний доступ без потреби просити користувача працювати в браузері. Якщо бракує email V4V отримувача або рівня доступу для читання/запису, запитайте це, а потім виконайте:

json
{
  "name": "share_editor_project_with_user",
  "arguments": {
    "project_id": "169000000000000000000002",
    "email": "collaborator@example.com",
    "access": "write",
    "notify_by_email": true
  }
}

Використовуйте notify_by_email: true лише якщо користувач попросив email-сповіщення; за замовчуванням — false. Поверніть project_link, щоб користувач міг надіслати його, і точно повідомте emailNotification: failed означає, що доступ надано, але email не надіслано. Посилання на проєкт вимагає запрошеного акаунта; користувачі, які не ввійшли в систему, входять і повертаються до того самого проєкту. Відеоекспорт, генерація або кредити на генерацію не потрібні.

get_editor_project_sharing перелічує співавторів та їхні userId, email і рівень доступу. Змінюйте права через share_editor_project_with_user; відкликайте доступ для користувача зі списку через remove_editor_project_access і його user_id. Передавайте право власності лише тоді, коли користувач явно попросив про це й надав email нового власника. Попередній власник втрачає доступ; інші співавтори та посилання на джерела зберігаються. Усі виклики керування вимагають права власності на проект; OAuth-мутації додатково вимагають v4v:write.

share_editor_project залишається окремою дією: вона публікує готове експортоване відео на публічній сторінці спільного доступу. Не використовуйте її для приватних запрошень співавторів. Оновіть/перепідключіть конектор MCP після розгортання, щоб виявити нові інструменти та інструкції.

Ідентифікатори проектів редактора відрізняються від ідентифікаторів проектів генерації Studio/Lab. Використовуйте list_editor_projects, а не list_projects, щоб їх знайти. Генерація залишається доступною через наявні інструменти виявлення моделей, оцінки та generate_lab. file_id завершеного медіафайлу можна напряму використовувати як assetId на монтажній шкалі. Розпізнавання мовлення також доступне як type: "subtitle"; віддавайте перевагу ai.gemini_3_5_transcribe (Gemini 3.5 Transcribe). Результати завершеного API-завдання містять текст, SRT, VTT та синхронізовані cues/words у секундах джерела. Спеціалізовані інструменти транскрипції редактора спрощують використання наявного джерела з медіатеки.

Типовий запит агента:

Створити 20-секундний вертикальний фільм із кліпів у моїй медіатеці. Переглянути репрезентативні кадри та замінити спотворений дубль новою генерацією після показу її вартості. Обрізати кліпи, додати мій логотип, тиху фонову музику, озвучення та синхронізовані підписи. Зберегти готове відео в медіатеці та надати мені посилання для завантаження.

Асистент повинен:

  1. Ознайомитися з інструкцією, знайти проект і вихідні медіафайли та перевірити тривалість і відтворення.
  2. Створити або відредагувати монтажну шкалу, використовуючи її поточну ревізію. Додати логотип як зображення на верхньому візуальному шарі та озвучення/музику на аудіошари. Оригінальні медіафайли не змінюються.
  3. Використати preview_editor_project для перевірки вибраних моментів кадру. Встановити review: "keep" або "replace" для кліпу та записати причину в note. Кадри не дають змоги оцінити якість руху чи звуку; перевіряйте також відтворення джерела.
  4. Виявити/оцінити запитані моделі, згенерувати заміни з унікальними ключами ідемпотентності та дочекатися завершення з отриманням їхніх file_id. Замінити джерело вибраного кліпу та обмежити його обрізку/тривалість межами нового джерела.
  5. Оцінити вартість/транскрибувати оригінальне джерело озвучення, опитувати з інтервалом не менше п’яти секунд, потім додати cues з sourceClipId для врахування обрізки та швидкості. Перевірити текст транскрипції. Надання наявних синхронізованих cues не коштує кредитів.
  6. Надіслати поточну ревізію через export_editor_project; опитувати get_editor_export з інтервалом щонайменше п’ять секунд, поки завдання в черзі/під час рендерингу. Відключений запит MCP не скасовує завдання. Успіх означає лише статус completed з assetId та URL для завантаження; перевіряйте помилки перед явною повторною спробою з retry_failed: true. Створюйте посилання для спільного доступу лише за запитом.

Приклад цільового редагування після get_editor_project:

json
{
  "project_id": "PROJECT_ID_FROM_CREATE",
  "revision": 3,
  "operations": [
    {
      "type": "update_clip",
      "clipId": "shot-1",
      "changes": {
        "trimStart": 1.5,
        "duration": 3,
        "volume": 0.25,
        "review": "keep"
      }
    },
    {
      "type": "split_clip",
      "clipId": "shot-2",
      "time": 7,
      "newClipId": "shot-2b"
    },
    {
      "type": "add_captions",
      "sourceClipId": "voice-1",
      "cues": [
        {
          "start": 0.2,
          "end": 2.1,
          "text": "A new perspective."
        }
      ]
    }
  ]
}

start/duration використовують секунди монтажної шкали, trimStart — секунди джерела, а time розділення — це абсолютний час на монтажній шкалі. Перед обрізкою прочитайте фактичну тривалість медіафайлу. add_clip приймає кліп з унікальним id, trackId, kind, assetId, start та duration; інші поля мають значення за замовчуванням. Текст використовує kind: "text" і поле text замість медіафайлу. Типи треків: visual, audio або text. add_track, update_track, remove_track та reorder_tracks керують шарами. Треки рендеряться в порядку масиву, останній — поверх інших. Перекривайте візуальні шари та використовуйте фейди для розчинення.

Сервер відхиляє недоступні медіафайли, невідповідні типи медіа, недійсні обрізки та застарілі ревізії. При конфлікті ревізій прочитайте нову версію і повторно застосуйте потрібні зміни. Не перезаписуйте роботу іншого редактора. Відкриті чисті браузерні редактори автоматично підхоплюють зміни агента; локально змінені чернетки зберігають свої зміни і показують конфлікти.

Інспекція кадрів агентом і експорт WebM візуальної монтажної шкали вимагають Playwright Chromium у розгортанні. Ці експорти підтримують до двох хвилин і 300 МБ вихідних медіафайлів та повертають збережений WebM; повторний експорт тієї самої ревізії повторно використовує наявний медіафайл. Експорт через браузер підтримує десятихвилинні монтажні шкали й пропонує MP4, якщо пристрій має кодеки H.264/AAC. Якщо рендеринг не вдається, повідомте про помилку та посилання на редактор; не заявляйте про успішний експорт. Редагування/рендеринг монтажної шкали не витрачає кредитів моделі; генерація/транскрипція — так. Спільний доступ створює посилання, видиме кожному, хто має це посилання.

27

Gemini text-to-voice#

Використовуйте list_models з type="audio", потім get_model для ai.gemini_3_8_flash_tts або ai.gemini_3_8_flash_lite_tts. Обидві моделі генерують одноголосе WAV-аудіо з тексту до 10 000 озвучуваних символів:

json
{
  "model": "ai.gemini_3_8_flash_tts",
  "input": {
    "text": "Welcome! <short pause> Let’s get started."
  },
  "parameters": {
    "voice": "Kore",
    "style": "Warm and friendly"
  },
  "idempotency_key": "unique-intentional-generation-id"
}

Read get_model.voices for each preset’s exact id, gender, description and free preview_url. Send the selected ID as parameters.voice; omit metadata and preview URLs from generation arguments. Check the balance and call estimate_generation with source="lab" first, then call generate_lab. Read get_task for owned audio file IDs and signed download links. Delivery instructions belong in style; they are not spoken. Flash focuses on expressive narration, Flash-Lite on efficient generation. Provider selection is managed in admin settings, not through an MCP parameter. ElevenLabs text-to-voice is temporarily disabled.

28

Стилізований текст, підписи та транскрипція Google#

get_editor_text_styles повертає 14 пресетів підписів, 6 пресетів заголовків і fontCatalog з 12 вбудованих шрифтів плюс 4 застарілі системні псевдоніми. Кожен пресет підписів реагує на справжні часові мітки слів. Використовуйте category і use, щоб вибрати стиль: word-pop (Creator punch), caption-marker (Lime marker), caption-underline, editorial (Podcast panel), caption-soft, caption-outline або neon-pulse (Neon glow), а також інші стилі руху слів. Заголовки мають власні пресети: title-clean, title-condensed, title-magazine, title-tech, title-sticker та cinema-gold. Нові підписи за замовчуванням — 100 px, великі літери, Montserrat, по три слова на фразу. Використовуйте один послідовний стиль підписів і комплементарний стиль заголовків, сильний контраст і безпечні поля. Наявні збережені монтажні шкали зберігають свої налаштування до повторної стилізації. Див. повний каталог типографіки.

Віддавайте перевагу вбудованим ID fontFamily: inter, montserrat, manrope, oswald, rubik, roboto-condensed, unbounded, nunito, playfair-display, roboto-slab, jetbrains-mono, comfortaa. Вони підтримують латиницю та українську кирилицю й завантажуються з V4V перед рендерингом у прев’ю та в обох шляхах експорту. fontCatalog.weights показує підтримуваний діапазон для кожної родини. Застарілі sans, impact, serif та mono залежать від системних шрифтів. Ніколи не ігноруйте помилку завантаження шрифту й не заявляйте про успішний експорт.

Текстові кліпи приймають strokeWidth (0–24 пікселі виводу), strokeColor, color, fontFamily (ID з каталогу), fontWeight (400/500/600/700/800/900, обмежений підтримуваним діапазоном шрифту), textBackground, backgroundColor, backgroundOpacity, accentColor, textAnimation, activeWordEffect (none, color, pop, shake, swing, spin, box, underline, glow), activeWordColor (колір переднього плану маркера), letterSpacing (-0.06–0.2 em), lineHeight (0.9–1.8), textShadow, shadowColor, shadowBlur, shadowOffsetY, backgroundFit (box або text), backgroundRadius, textTransform (none, uppercase), fontSize, animationIntensity (0–1), audioReactive та необов’язковий audioSourceClipId. Анімації: none, fade, slide, pop, float, shake, pulse, color-cycle та karaoke. audioReactive: true використовує фактичну гучність аудіо, включно з обрізкою, швидкістю, фейдами, гучністю та вимкненими/прихованими треками. Воно відстежує всі чутні джерела, якщо не вказано ID кліпу-джерела; музичні біти не виявляються. Прев’ю, перемотування, локальний експорт і серверний експорт використовують цей рендерер.

Використовуйте edit_editor_project з { "type": "apply_text_style", "clipIds": ["caption-1", "caption-2"], "stylePreset": "creator-pop" } для стилізації кількох підписів. Тонке налаштування через update_clip. add_captions приймає stylePreset, maxWordsPerCaption (1–8, за замовчуванням 3) та words для cues, наприклад { "text": "Hello", "start": 1.2, "end": 1.6 }. Слова cues використовують секунди джерела, а sourceClipId вирівнює їх з обрізкою, швидкістю та позицією на часовій шкалі. Для окремого текстового кліпу wordTimings використовує секунди відносно цього кліпу. Ефекти для слів виділяють і анімують лише слово, що вимовляється в цей час; зберігайте справжні часові мітки. Великі літери змінюють відтворення без переписування оригінального тексту чи таймінгів. SRT містить лише таймінги cues, тому ніколи не вигадуйте таймінги слів на основі SRT.

Для транскрипції виконайте list_models з type: "subtitle", потім get_model з model: "ai.gemini_3_5_transcribe". Оцініть через estimate_generation і надішліть той самий запит через generate_lab:

json
{
  "model": "ai.gemini_3_5_transcribe",
  "input": {
    "audioUrl": {
      "file_id": "OWNED_AUDIO_ID"
    }
  },
  "parameters": {
    "language_code": "auto",
    "diarize": false
  },
  "idempotency_key": "transcribe-unique-request"
}

Альтернативно надайте videoUrl з посиланням на власне відео. Виберіть рівно одне джерело тривалістю до 15 хвилин. Підключений службовий обліковий запис Google обробляє автентифікацію. Не надавайте облікові дані провайдера або параметри маршрутизації. Опитуйте get_task для отримання results з type: "subtitle"; зберігайте його cues та таймінги слів для підписів редактора. Google наразі позначає часові мітки слів як експериментальні, тому перевіряйте точність транскрипції. Інструменти оцінки вартості/транскрипції редактора тепер за замовчуванням використовують цю модель. Застарілий ai.speech_to_text залишається окремим; адміністратори можуть приховувати його незалежно. Невдалі платні запити повертають кошти через звичайний життєвий цикл завдання і не повинні автоматично повторюватися як нова покупка.

Завершіть воркфлов підписів у редакторі

Транскрибування файлу не вставляє підписи в проект редактора. Для існуючого фільму:

  1. Прочитати get_editor_project і визначити вихідний кліп та його assetId.
  2. Якщо у вас уже є успішний результат підписів generate_lab / get_task для цього джерела, повторно використайте його cues і переходьте безпосередньо до вставки на кроці 4; відео file_id або друга транскрипція не потрібні. Інакше виконайте quote_editor_captions, потім transcribe_editor_media з цим asset_id, language: "auto" (або кодом BCP-47) та унікальним idempotency_key. Повторно використовуйте цей ключ після тайм-ауту мережі.
  3. Опитуйте get_editor_captions з інтервалом щонайменше п’ять секунд. При failed повідомте про error і зупиніться. Нова платна спроба вимагає запиту користувача.
  4. При succeeded переконайтеся, що cues непорожній, отримайте останню ревізію проекту й передайте ці точні cues в edit_editor_project з type: "add_captions", sourceClipId вихідного кліпу, stylePreset: "word-pop" та maxWordsPerCaption: 3 (або інший запитаний пресет слів).
  5. Перевірте нові текстові кліпи в збереженій монтажній шкалі та попередній перегляд у фактичний момент появи підпису. Перевірте точність тексту. Зміну джерела під час транскрипції або обрізку без накладання мовлення потрібно повідомити; не заявляйте про успішну вставку. Повторно використовуйте завершені cues для вирішення конфліктів редагування без повторної генерації.

Зберігайте всі повернені часові мітки слів, включно з однаковими початковими/кінцевими зміщеннями для коротких слів. Перейменуйте накладення через update_clip / changes.name; змінюйте видимі слова через changes.text. Перейменуйте його шар через update_track / changes.name. Зберігайте ідентифікатори та поважайте заблоковані шари.

Транскрипція Gemini коштує щонайменше 1 кредит за запит, включно з короткими кліпами; оцінюйте поточну ціну за тривалістю перед генерацією. JSON підписів містить time_unit: "seconds", плоский масив words та cues[].words, кожне слово має text, start, end та необов’язковий speaker_id. Використовуйте ці слова для караоке та іншого синхронізованого стилізування. SRT має лише таймінги рядків. Lab може переглядати синхронізовані слова та копіювати/завантажувати JSON або SRT. Відеоредактор приймає JSON напряму через Підписи → Імпорт SRT або JSON; виберіть один із великих пресетів для слів і використовуйте Властивості кліпу → Слова та таймінги для корекції окремих слів без видалення їх таймінгів. Виправлення MCP повинні передавати і changes.text, і повний виправлений changes.wordTimings; зміна лише тексту очищує застарілі таймінги.

Щоб скоротити існуючий шар з таймінгом субтитрів без повторної генерації, використовуйте:

json
{
  "project_id": "EDITOR_PROJECT_ID",
  "revision": 3,
  "operations": [
    {
      "type": "reflow_captions",
      "trackId": "CAPTION_TRACK_ID",
      "maxWordsPerCaption": 3
    }
  ]
}

Використовуйте фактичну поточну ревізію та ID шару. Це зберігає справжній таймінг слів, стиль і шар, а також повертає оновлену монтажну шкалу з новими ID кліпів. Застосуйте спільний пресет слів до цих ID за допомогою apply_text_style. У браузері використовуйте Властивості кліпу → Слова та таймінги → Слів на підпис → Розділити цей шар на короткі підписи, потім Текст і вигляд → стиль → Застосувати стиль до шару. Рядки SRT не можна точно розбити на слова з таймінгом без транскрипції.

Аудіокниги: збирайте голоси, встановлюйте теги, експортуйте MP3 або MP4 з обкладинкою

MCP 1.15.0 додає той самий воркфлов Аудіо й аудіокниги, доступний у відеоредакторі. Прочитайте get_editor_guide для audiobookTimeline або прочитайте поточний проєкт перед редагуванням. Установіть timeline.mode на audiobook для таймлайна до 7,200 секунд (дві години), 1,000 кліпів і 24 шари. Режим відео зберігає своє обмеження в ten-minute/500-clip.

  1. Знайдіть наявні записи через list_editor_media / get_editor_media або завантажте/імпортуйте їх. Генеруйте нове мовлення лише за запитом, використовуючи виявлення моделі, оцінку кредитів і наявні інструменти Gemini TTS. Редактор збирає записи; він не вгадує мовця для кожного рядка.
  2. Додайте аудіошар для кожного оповідача, діалогу, музики або ефектів за потреби. Використовуйте append_editor_audio з упорядкованими asset_ids, track_id, поточною revision і необов’язковим gap_seconds (0–60). Це додає повні кліпи до цього шару без пропусків через округлення кадрів. Імена файлів не сортуються, а остання частина не обрізається для підгонки. Для перекриттів або індивідуального таймінгу використовуйте наявні операції з кліпами. Обрізки, швидкість, гучність, затухання, вимкнення і приховані шари впливають на мікс; зміна швидкості змінює тональність.
  3. Збережіть теги, бітрейт і обкладинку через edit_editor_project, наприклад:
json
{
  "project_id": "<project ID>",
  "revision": 3,
  "operations": [
    {
      "type": "set_audio_settings",
      "mode": "audiobook",
      "settings": {
        "metadata": {
          "title": "Розділ перший",
          "artist": "Олена та Андрій",
          "album": "Книга пригод",
          "albumArtist": "Назва видавництва",
          "composer": "Ім’я автора",
          "year": "2026",
          "track": "1/12",
          "genre": "Audiobook",
          "comment": "",
          "copyright": ""
        },
        "coverAssetId": "<accessible image asset ID>",
        "bitrateKbps": 128
      }
    }
  ]
}

settings замінює збережені аудіоналаштування: зберігайте поля, які користувач не просив змінювати. Усі теги — рядки. artist указує оповідачів/виконавців, composer може вказувати автора, album ідентифікує книгу, year — чотири цифри, а track — номер або номер/загальна кількість. Не вигадуйте кредити чи авторські права. Якщо назва порожня, використовується назва проєкту. MP3 містить теги Unicode ID3v2.3 і, якщо вибрано, зображення обкладинки APIC. Зображення вбудовується у файл, а не посилається за URL. MP3 може не мати обкладинки; MP4 з обкладинкою вимагає її. Бітрейти: 96, 128 (за замовчуванням), 192, 256 або 320 кбіт/с.

  1. Надішліть export_editor_project зі збереженою ревізією та format: "mp3" або format: "mp4-cover". Запитуйте обидва формати, якщо потрібні обидва файли. Кожен проєкт/ревізія/формат має власне постійне завдання, тому один формат ніколи не замінює інший. Опитуйте get_editor_export з інтервалом щонайменше п’ять секунд, доки не отримаєте completed або failed. Етапи включають завантаження медіа, мікшування аудіо з прогресом, кодування та збереження. Відключений клієнт не скасовує завдання; повторне надсилання відновлює його. Для невдалих завдань потрібен явний retry_failed: true.
  2. Підтвердіть status: "completed", assetId та підписані посилання для завантаження/відтворення. Перевірте фінальний мікс, тривалість, запитані теги та зображення перед повідомленням про завершення. MP3 зберігається як аудіо медіафайл у Бібліотеці; MP4 з обкладинкою — як відео медіафайл. Перевірка кадрів сама по собі не може підтвердити аудіо або метадані. Публічний інструмент для обміну відео не призначений для MP3; приватна спільна робота над проєктом залишається доступною.

Формат mp4-cover відображає одну підігнану обкладинку на фоні проєкту протягом усього аудіо. Візуальні кліпи часової шкали, текст і субтитри виключені з цього формату. Щоб відобразити їх, використовуйте наявний MCP експорт format: "webm" (за замовчуванням, до двох хвилин) або браузерний експорт MP4/WebM (до десяти хвилин).

Аудіоекспорти доступні лише власнику, не потребують кредитів за генерацію і вимагають постійного воркера редактора, а також FFmpeg/ffprobe з libmp3lame і libx264. Chromium не потрібен для цих двох форматів. Обмеження: 1 GB вихідних файлів, 300 MB на експортований файл, 64 сегменти аудіокліпів на 30-секундне вікно мікшування. Використовуйте нижчий бітрейт або розділіть більшу книгу на частини. Налаштування та посилання на обкладинку зберігаються на монтажній шкалі, перевіряються за ревізією та успадковують дозволи на медіа проєкту після надання спільного доступу або передачі права власності. У цьому релізі не додано маркери розділів, клонування голосу або автоматичне призначення мовця.

Спільна галерея стилів і набори

/video-editor/gallery і панель Дизайну показують ті самі 30 оригінальних власних наборів стилів, що й локальний Kit. Кожен містить п’ять редагованих сцен, 12-секундне беззвучне прев’ю, оригінальну марковану ілюстрацію, промпт, рубрику та хеш-маніфест. Це демонстрація багаторазового використання сімейства сцен, а не фактична рекламна кампанія продукту. Шляхи прев’ю з get_creative_item відносні до /api/video-editor/creative-assets/; вони містять лише оригінальні вбудовані матеріали, ніколи не містять медіа з облікового запису.

create_style_example імпортує реальне вихідне зображення в Бібліотеку власника, який увійшов у систему, і переназначає ID медіа на монтажній шкалі. Використовує v4v:write без кредитів за генерацію. apply_style(dry_run=true) також вимагає права редагування і поточної ревізії, повідомляє про змінені/заблоковані/непідтримувані кліпи і нічого не записує. Застосуйте з тими самими параметрами й ревізією після перегляду плану. Застосування до вибраних сцен змінює вхідний перехід цих сцен; час кліпів і аудіо залишається фіксованим.

Обмежений бюджет генерації Open Video Kit

create_generation_budget створює незмінний спільний ліміт без списання; get_generation_budget показує фактичні витрати й резервування, а close_generation_budget назавжди закриває можливість нових дозволів. Для підтримуваних медіафайлів estimate_generation повертає підписаний quote_token, дійсний протягом п’яти хвилин. Передавайте budget_id, max_credits і quote_token разом у поточний generate_lab / generate_studio; idempotency_key є обов’язковим. Точне повторення прийнятого запиту не запускає другу генерацію. Паралельні резервування враховуються на сервері; чат із тарифікацією за токенами не входить до цього сценарію. Бюджет не є окремим дозволом користувача на витрачання кредитів. Детальний контракт і перевірки: Cloud Kit.

Приватні референсні стилі (Open Video Kit 0.1.24)

get_reference_guide / v4v://reference-style документує спільний воркфлов. analyze_reference_style приймає стабільний reference_id, власний медіафайл Бібліотеки (source: { type: "asset", assetId }) або явний публічний URL video|image|page. Повертає виміряні палітри, орієнтовні межі/ритм і фактичні часові позначки кадрів; get_reference_frame повертає PNG-вміст. Перевірте всі записані кадри перед review_reference_style, що вимагає оригінальних правил типографіки/макета/руху/переходу/ритму, повних токенів, обмежень рецензента та часових/SHA-256 посилань. get_reference_profile повертає приватний портативний JSON. apply_reference_style за замовчуванням виконує пробний запуск; застосування вимагає поточної ревізії власного проєкту, включно з нульовою ревізією. Референсні відеоматеріали ніколи не вбудовуються в монтаж або ZIP.

Інструменти читання вимагають v4v:read; аналіз/рецензування/застосування — v4v:read і v4v:write. Вони не потребують v4v:generate і не витрачають кредити за генерацію. Файли доказів референсів/фабрики V4V зашифровані з використанням ключів для кожного об’єкта, які зберігаються лише в маніфестах бази даних у межах облікового запису власника, а приватні файли заблоковані для загальної видачі медіа. Під час доступу перевіряється право власності на оригінальний референсний медіафайл у Бібліотеці. Див. Українську реалізацію та обмеження.

Геометричні маски кліпів і багатошаровий паралакс

Kit 0.1.32 adds clipMasks and layeredParallax capability flags. Search kind=effect for mask-circle, mask-ellipse, or mask-rounded-rect, then read get_creative_item for the actual schema and limits. Apply set_mask through edit_editor_project at the saved revision with write access; mask:null clears it. The mask's x/y/width/height are clip-relative fractions and its bounds must remain inside the clip box. It follows rotation/scale/keyframes, clips after effects and before transitions, and does not change audio. Locked layers and audio-only targets reject the operation.

get_motion_guide.schemas.mask і recipes.parallax спільні з локальною Студією. Останній із них забезпечує редагований двошаровий рух за допомогою звичайних позиційних кейфреймів. Переглядайте фактичні кадри; це не автоматична оцінка глибини. Спільні елементи керування GUI знаходяться в Дизайн → Ефекти. ZIP зберігає маски; перевірка тексту повертає TEXT_MASK_REVIEW, оскільки перевірки меж не гарантують читабельність усередині кривої маски. Див. спільний двомовний контракт.

29

Творчі колекції та планування агента#

Дизайн → Бібліотеки надає 28 редагованих вбудованих композицій, включно з колажем, безперервним рухом камери, пружними панелями, намальованими персонажами, субтитрами, демонстраціями продукту та послідовностями запуску. Kit 0.3.7 також містить десять оригінальних стилів, п’ять растрових ефектів і п’ятнадцять переходів. Тринадцять шейдерних переходів вимагають WebGL і виводять до 4096 пікселів на сторону.

Використовуйте get_reviewed_library_guide (ресурс v4v://reviewed-libraries) для точних схем, ліцензій джерел і обмежень. search_library_references і get_library_reference надають доступ до 456 записів метаданих референсів; це не встановлені виконувані шаблони. plan_library_scene доступний лише для читання і повертає операції для edit_editor_project на поточній ревізії. Використовуйте власні медіа Бібліотеки або зареєстровані локальні медіа проєкту; оригінальні локальні байти залишаються на пристрої користувача. Перевіряйте фактичні відрендерені кадри після редагування.

Планування з ШІ зберігає проєкт і готує редагований запит Video Factory. Воно не надсилає команду, не витрачає кредити, не завантажує оригінали й не авторизує генерацію. Агент уточнює важливі відсутні творчі рішення перед редагуванням. Власний рендеринг не потребує сервісу генерації; необов’язкові платні дії зберігають наявні кошториси та явне схвалення. Не ввімкнено жодного інсталятора, довільного HTML/JavaScript, виконуваної музики або засобу читання локальної історії. Перевірка джерел/ліцензій і оригінальні еквіваленти постачаються у версійній документації Kit.

Якість монтажу та докази

Прочитайте get_montage_quality_guide / v4v://montage-quality для спільних правил смаку та чесних обмежень щодо доказів. plan_montage_beats визначає вирівняні по кадрах візуальні склейки з реального таймінгу слів; plan_compact_captions групує 1–3 слова без вигадування часових позначок. analyze_ui_regions вимірює межі власних скріншотів; rectify_ui_region створює окреме зображення з виправленою перспективою з поверненого ідентифікатора відбитка/регіону. detect_media_scenes вимірює візуальні переходи у вихідному вікні до 600 секунд. Ці операції зберігають джерело і не генерують платне медіа.

compare_narration_transcript вимагає завершеного власного транскрипту run_id точного audio_asset_id; він порівнює фактичний транскрипт із script і необов’язковими підтвердженими іменами. Текст ASR не встановлює наголос чи природну подачу. Купуйте транскрипцію або повторний дубль лише через звичайний процес авторизації з кошторисом.

preview_editor_project приймає до 12 фактичних часових позначок кадрів; contact_sheet: true повертає одне зображення для перегляду. Режим браузера Factory виконує перевірку/виправлення на пристрої користувача і зберігає оригінали локально. Зовнішні виклики MCP, що використовують лише браузерний оригінал, отримують BROWSER_REQUIRED; для цих браузерних операцій використовуйте відкритого агента Factory. Нові команди Factory записують окремі відповіді для перевірки змісту й завершеності за вісьмома явними питаннями щодо доказів. Невідомі докази не проходять перевірку.

Невдалі результати get_task включають error.provider_error, очищену причину від сервісу моделі, та error.provider: "managed". Відомі помилки містять hint та retryable; тимчасові обмеження швидкості/тайм-аути також повертають retry_after_seconds: 60. Ознайомтеся з причиною перед зміною запиту або запитом іншої платної спроби. Невідомі помилки зберігають очищену причину без припущення, що повторна спроба буде успішною. REST-відповіді завдань і підписані зворотні виклики task.failed використовують ті самі поля; див. діагностику невдалих генерацій.