Увійдіть через OAuth 2.1 або підключіться за допомогою API-ключа. Знаходьте моделі, створюйте з референсними медіафайлами, збирайте багатошаровий монтаж і додавайте готові відео, зображення та аудіо у свою розмову.
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-ключа
Відкрийте свій профіль V4V і створіть ключ у розділі API Keys.
Збережіть секрет API у безпечних налаштуваннях клієнта MCP.
Додайте сервер із заголовком x-api-key: YOUR_V4V_API_KEY або Authorization: Bearer YOUR_V4V_API_KEY.
Підключіться та почніть із get_balance або list_models.
Надсилайте один заголовок автентифікації. Якщо надіслано обидва, вони повинні містити однаковий ключ; конфліктні або некоректні облікові дані повертають HTTP 401. Значення x-api-key — це сам ключ без префікса Bearer . Обидва формати заголовків API-ключа використовують однакові дозволи, кредити, ліміти запитів і відкликання ключа.
Клієнти з API-ключем продовжують використовувати ті самі заголовки та дозволи. Клієнти OAuth входять у свій існуючий обліковий запис V4V через браузер. Ніколи не вставляйте ключ або токен у розмову з асистентом або не комітьте їх у репозиторій.
Add https://v4v.ai/api/mcp as a remote Streamable HTTP server in your assistant.
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.
Your assistant opens V4V in your browser. Sign in to the V4V account whose credits and library you want to use.
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.
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-ключ у сумісному клієнті.
OAuth спершу має бути увімкнено на розгортанні V4V. Дозволи облікового запису та робочого простору в ChatGPT визначають, чи доступне користувацьке підключення MCP.
Відкрийте ChatGPT Plugins → Personal, оберіть Add (або +), потім Add custom MCP server (назва може відрізнятися залежно від облікового запису).
Введіть V4V і URL сервера https://v4v.ai/api/mcp.
Оберіть OAuth та динамічну реєстрацію клієнта (DCR). Залиште Client ID і Client Secret порожніми; V4V автоматично реєструє публічного клієнта PKCE. Ця версія підтримує DCR, а не CIMD.
Підключіться та увійдіть у свій наявний обліковий запис V4V.
На екрані дозволів V4V перегляньте обліковий запис і хост зворотного виклику. Усі три дозволи обов’язкові: читання облікового запису, редагування/завантаження та генерація з кредитами. Три прапорці вибрані та заблоковані. Оберіть Accept all permissions для підключення або Cancel для відмови; часткова згода не підтримується.
Поверніться до ChatGPT і встановіть плагін, якщо буде запропоновано. У Personal plugins відкрийте меню з трьома крапками V4V і оберіть Manage.
Відкрийте рядок Permission. Для викликів інструментів без затвердження оберіть Allow all tools. Генерації все одно використовують ваші кредити V4V, тому перед початком запитайте оцінку.
Почніть нову розмову, оберіть + → Plugins → V4V (або згадайте його з @) і запитайте Check my V4V balance.
Інструкція зі скріншотами ChatGPT проходить усі вісім екранів. Крок із деталями підключення має кнопки копіювання для назви плагіна, опису та URL сервера поточного розгортання, а також опційне завантаження іконки V4V.
Приклад:
Створіть три вертикальні концепції продуктового відео 9:16 за цим посиланням на продукт. Спочатку покажіть концепції та оцінку кредитів. Чекайте на моє схвалення перед початком генерації.
Асистент використовує наявні інструменти discovery, estimate_generation і generate_studio_variants. Оцінки не запускають рендеринг і не резервують кредити, але можуть імпортувати медіафайли для перевірки, тому потрібен дозвіл на редагування. Платні інструменти застосовують дозвіл на генерацію на сервері. Дозвіл — це доступ до облікового запису, а не схвалення окремого творчого завдання: однак перед авторизацією рендерингу все одно переглядайте запитані концепції та бюджет. Контроль пакетних max_credits і ідемпотентності залишається в силі.
Токени доступу діють максимум одну годину. Токени оновлення змінюються при кожному використанні, а підключення закінчується через 30 днів. Підключіться знову, коли воно закінчиться або знадобляться додаткові дозволи. У Профіль V4V → Підключення асистента переглядайте використання, відключайте асистента або відкривайте його секрет підпису вебхука для вашого приймача. Не вставляйте секрет підпису в чат.
Відключення блокує нові запити інструментів, оновлення токена та невикористані посилання для завантаження. Уже подані завдання продовжують виконання за існуючими правилами черги та кредитів; відключення не скасовує і не повертає їх. Раніше видані підписані посилання на медіафайли зберігають звичайний термін дії.
Завантаження файлів із середовища виконання ChatGPT залежить від мережевого доступу та доступу до вкладень у цьому середовищі. Обмежене посилання для завантаження в браузері залишається доступним як резервний варіант. Саме лише підключення MCP не гарантує автоматичного передавання вкладень.
Відкрийте Add to Claude.
Форма відкриється з попередньо заповненими ім’ям V4V і URL сервера продуктивного середовища. Для розробки або іншого розгортання використовуйте сторінку підключення,
яка заповнює URL відповідного розгортання. Якщо вхід у Claude очищує форму,
відкрийте посилання знову після входу.
Перегляньте попередньо заповнені назву та URL, потім оберіть Continue.
Claude автоматично перевіряє сервер. Залиште виявлені налаштування Sign in now і Register automatically та оберіть Add; інші налаштування змінювати не потрібно. Залиште Client ID і Client Secret порожніми, без API-ключа або заголовків запиту.
На сторінці конектора оберіть Connect та увійдіть у V4V.
Перегляньте свій обліковий запис і всі три необхідні дозволи, потім оберіть Accept all permissions. Підключення не витрачає кредити.
У розділі Tool permissions → Read-only tools відкрийте Custom поруч із назвою групи та оберіть Always allow.
Прокрутіть до 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. Додайте конектор
Open Add to Claude, or open Customize → Connectors → Add → Custom web connector.
Set Name to V4V.
Set MCP server URL to https://v4v.ai/api/mcp.
Under Authentication, select No sign-in.
Click Add header and enter:
Налаштування заголовка
Значення
Назва
x-api-key
Значення
Ваш API-ключ V4V, точно як скопійовано
Натисніть Add / Connect і зачекайте на завершення підключення.
Використовуйте ключ лише в x-api-key, без префікса Bearer . No sign-in пропускає OAuth; заголовок усе одно автентифікує кожен запит до V4V. Залиште Client ID і Client Secret порожніми.
3. Дозвольте інструменти
Відкрийте Менеджер конекторів Claude.
Виберіть новий конектор V4V.
Відкрийте Дозволи інструментів і дозвольте всі інструменти V4V.
Переконайтеся, що create_upload_link, get_upload, get_model і generate_lab доступні та увімкнені.
Після додавання або оновлення інструментів V4V оновіть інструменти конектора або перепідключіть його перед початком нової розмови.
4. Дозвольте автоматичне завантаження файлів
Відкрийте Settings → Capabilities.
Увімкніть Code execution and file creation і Allow network egress, якщо вони вимкнені.
У 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 у чат і подати запит на генерацію. Вам не потрібно повторно завантажувати файл на окремій сторінці браузера, якщо мережевий доступ дозволено.
Запустіть сервер, перегляньте запит щодо довіри та завершіть вхід у V4V, коли VS Code відкриє ваш браузер. Увімкніть інструменти, які хочете використовувати в чаті агента.
Альтернатива з API-ключем
Для чату редактора додайте наступне до .vscode/mcp.json. VS Code запросить ключ і приховає введення. Залиште заповнювач у файлі.
Запустіть сервер із конфігурації MCP і увімкніть його інструменти у вашій сесії чату. Перед дозволом витрачати кредити перегляньте виклик інструменту генерації.
Для інших середовищ агента VS Code дотримуйтесь поточних посилань на конфігурацію MCP для підтримуваного розташування конфігурації цього середовища.
Використовуйте /mcp всередині Claude Code для перевірки з’єднання. Реєстрація зберігає налаштований заголовок у локальній конфігурації клієнта; захистіть цей файл і не додавайте його до системи контролю версій. Див. керівництво MCP для Claude Code щодо області конфігурації та керування ключами.
На сторінці підключення оберіть вхід через V4V або API-ключ і
натисніть Встановити в Cursor. Перегляньте встановлення в Cursor перед підтвердженням.
OAuth відкриває вхід у браузері; налаштування API-ключа встановлює заповнювач,
який ви локально замінюєте у .cursor/mcp.json. Реальний ключ не вбудовується в URL встановлення.
Поточні десктопні версії використовують HTTP loopback callback; хмарні клієнти
використовують точний затверджений URI https://www.cursor.com/agents/mcp/oauth/callback.
Додайте віддалений сервер під mcp.v4v у opencode.json з type: "remote",
url: "https://v4v.ai/api/mcp" та enabled: true. Виконайте
opencode mcp auth v4v для OAuth. Сторінка підключення
надає повний JSON і альтернативу з API-ключем через змінну середовища.
Оберіть сервер remote / Streamable HTTP і надайте:
Налаштування
Значення
Ім’я
v4v
URL
https://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.
Для повного фільму або креативного перемонтажу запису узгодьте важливі відсутні рішення перед монтажем або оплачуваною роботою: мета, аудиторія, вихідний матеріал, формат, цільова тривалість, візуальне оформлення, субтитри, озвучення, музика та мови виводу. 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 пояснює воркфлов генерації вашому асистенту.
Пошук увімкнених моделей; за потреби фільтрація за зображенням, відео, аудіо або чатом
Ні
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 перед вибором параметрів; необхідні посилання, тривалості та формати залежать від моделі.
Виконайте 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 і обирайте активний пресет (або пропустіть стиль, щоб використати виявлений стиль за замовчуванням).
Надішліть це до estimate_generation. Він повертає credits_estimated, не резервує кредити і не створює завдання або рендер. Оцінка для Studio пропускає реєстрацію персонажів у провайдера, зокрема коли вибрано аватар. Публічні URL медіа можуть імпортуватися для перевірки. Оцінки можуть змінюватися залежно від вхідних даних/тарифів; оцінки для чату описують початкове резервування, а не остаточні витрати токенів або ліміт витрат. Для рендерингу видаліть source і подайте ті самі вхідні дані до generate_studio з новим idempotency_key.
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, щоб було зрозуміло фактичну видимість. Публікація вимагає запиту користувача; цей інструмент не витрачає кредити на генерацію.
Використовуйте 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.
Наприклад, щоб організувати затверджені результати кампанії:
Викличте list_projects з {"q":"approved"} і виберіть потрібні проєкти.
Викличте list_project_folders; повторно використайте потрібну папку або викличте create_project_folder з {"name":"Summer campaign"}.
Викличте move_project для кожного вибраного project_id з поверненим folder_id.
Викличте list_projects з цим folder_id, щоб перевірити вміст папки.
Використовуйте move_project з folder_id: null, щоб видалити проєкт із папки. rename_project_folder приймає folder_id та name. Імена папок мають містити 1–80 символів після обрізання та бути унікальними у вашому акаунті; дублікат повертає FOLDER_NAME_CONFLICT. Після невизначеної відповіді на створення перелічіть папки перед повторною спробою. Переміщення та перейменування безпечні для повторення і не витрачають кредити, не генерують медіафайли та не змінюють результати. Проєкти в черзі зберігають свої імена та папки, коли їх створює воркер. Ці операції не можуть отримати доступ до проєктів або папок іншого акаунта.
Референсні медіафайли можуть бути публічним URL або власним ID файлу V4V. Поле з назвою image_url також приймає ID файлу; використовуйте схему моделі, щоб вибрати точне поле введення.
Автоматичне завантаження з прикріплених та локальних файлів
Асистент може завантажити оригінальний файл самостійно, якщо його середовище виконання має доступ до цього розгортання V4V. Вам не потрібно копіювати API-ключ у чат або повторно вибирати той самий файл.
Викличте create_upload_link. Незважаючи на назву, інструмент також повертає upload_request: POST URL, обмежений заголовок x-upload-token та назву multipart-поля file.
З інструменту виконання асистента надішліть фактичні байти локального файлу на цей URL, використовуючи multipart/form-data. Нехай HTTP-клієнт встановить boundary і вимкніть перенаправлення. Не конвертуйте зображення й не виводьте base64 у розмову.
Прочитайте file_id у відповіді та підтвердьте через get_upload за upload_id.
Визначте схему вхідних даних моделі, передайте цей ID у відповідне поле медіа (наприклад, Topaz image_url) і надішліть запитану генерацію.
Для кількох референсів повторіть процес з окремим слотом завантаження для кожного потрібного файлу.
Токен завантаження дійсний 15 хвилин, приймає один файл розміром до 20 МіБ з урахуванням обмежень сервера і не може читати вашу медіатеку або витрачати кредити на генерацію. Фактичні байти передаються через HTTP; MCP надає обмежену авторизацію та контролює генерацію.
Для середовища виконання, де результат інструменту доступний як slot, двійкове передавання виглядає так:
Підключення 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, отриманий після завантаження):
{
"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 для кожної навмисної генерації. Повторно використовуйте той самий ключ і аргументи при повторній спробі після мережевого збою. Повторне використання ключа з іншими вхідними даними повертає конфлікт.
Інструменти генерації негайно повертають 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-ключа відображається у вашому профілі.
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 вебхуків.
Генерація використовує ваші звичайні кредити V4V. Для звичайних завдань LAB/Studio орієнтовна вартість резервується, коли є пропускна здатність; надлишкові завдання очікують без резервування. Невикористані кредити звільняються за тими ж правилами, що й REST API. Перегляд моделей, балансів, завдань і існуючих файлів не витрачає кредити на генерацію.
Кожен інструмент обмежений власником налаштованого ключа. Файли та завдання іншого акаунта недоступні. Відкличте ключ у вашому профілі, щоб вимкнути його MCP-підключення. Анотації інструментів позначають виклики, що створюють роботу та витрачають кредити, щоб ваш клієнт міг запропонувати звичні засоби підтвердження для інструментів.
Оновіть або перепідключіть конектор 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, щоб дізнатися ідентифікатори варіантів і обмеження співвідношення сторін.
Чотири окремі вузли мають однакові механізми генерації та обробки результатів у Лабораторії, Воркфловах, API та MCP:
Ідентифікатор каталогу
Модель
Тривалість
Роздільна здатність
video.kling_v40_ref
Kling 4.0 Reference
3–30 секунд
720p / 1080p
video.kling_v40_key
Kling 4.0 Keyframe
3–30 секунд
720p / 1080p
video.kling_v40_flash_ref
Kling 4.0 Flash Reference
3–20 секунд
720p
video.kling_v40_flash_key
Kling 4.0 Flash Keyframe
3–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, з відео
Стандартний Reference
28.5
17
42.5
25.5
Стандартний Keyframe
28.5
недоступно
42.5
недоступно
Flash Reference
17
11.3
недоступно
недоступно
Flash Keyframe
17
недоступно
недоступно
недоступно
Приклади для 5-секундного відео:
Модель
5 с без вихідного відео
5 с з вихідним відео до 5 с
Стандартний Reference, 720p
142.5 кредитів
170 кредитів
Стандартний Reference, 1080p
212.5 кредитів
255 кредитів
Стандартний Keyframe, 720p / 1080p
142.5 / 212.5 кредитів
недоступно
Flash Reference, 720p
85 кредитів
113 кредитів
Flash Keyframe, 720p
85 кредитів
недоступно
Без відеовходу оплачувані секунди дорівнюють вихідним секундам. Із референсним відео або відеоелементом оплачувані секунди дорівнюють 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}. Застосовуються стандартні авторизація генерації, перевірки балансу, ключі ідемпотентності, зворотні виклики та відшкодування в разі невдачі.
Використовуйте 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 залишаються окремою оцінкою початкового резервування. Цей перегляд не резервує кредити і не запускає генерацію.
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 для показу приблизних діапазонів кредитів; початкове резервування та діапазон є окремими від остаточного використання й не є лімітами витрат. Ніколи не вигадуйте параметри маршрутизації й не змінюйте адміністративні налаштування без повідомлення.
Використовуйте generate_studio_bulk, коли потрібні відео для списку продуктів. Приймає від 1 до 300 елементів і негайно повертає batch_id. Використовує звичайний баланс кредитів облікового запису та спільну чергу генерації V4V з REST та веб-застосунком.
Вхідні дані елемента та параметри перевизначають спільні налаштування; решту заповнюють стандартні налаштування Студії. Надавайте власні ідентифікатори продуктів, публічні URL сторінок продуктів або підготовлені дані й медіафайли продукту. Використовуйте налаштування, які підтримує поточна модель Студії в цьому розгортанні. Пропустіть test_count, щоб обробити весь список. З test_count: 5 перші п’ять елементів (або всі елементи, якщо їх менше п’яти) запускаються до того, як пакет стане на паузу для перегляду.
Інструмент
Призначення
Використовує кредити генерації?
generate_studio_bulk
Створення пакету відео продуктів з обов’язковим бюджетом кредитів
Так, при запуску кожного елемента
list_studio_batches
Перелік останніх пакетів облікового запису
Ні
get_studio_batch
Читання посторінкового прогресу, ID завдань елементів, результатів та стабільного state_token
Ні
wait_studio_batch
Очікування змін, завершення, паузи або скасування; за замовчуванням 25 секунд
Ні
control_studio_batch
pause, 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 має автоматично моніторити:
Зберігайте batch_id та state_token з generate_studio_bulk, generate_studio_variants або get_studio_batch.
Викликайте wait_studio_batch з batch_id, after_state, встановленим на цей токен, та wait_seconds: 25 для браузерних конекторів. За потреби використовуйте пагінацію через offset і limit (за замовчуванням 50, максимум 100).
Сервер повертає відповідь при значущій зміні партії, завершенні, паузі, скасуванні або по закінченню часу очікування. Серцебиття робітника та термін дії підписів результатів не змінюють токен. У відповіді міститься оновлена сторінка партії, changed, timed_out, stop_reason і next_action.
Поки status дорівнює running, продовжуйте чекати з отриманим токеном без прохання користувача «перевірити знову». Повідомляйте про корисні етапи, а не про кожен тайм-аут без змін. Тайм-аут не означає помилку або скасування генерації. Не надсилайте заміну партії.
При 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 для полів, семантики бюджету та помилок.
Редактор за адресою /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
Процитувати транскрипцію мовлення джерела без генерації
Прочитати прогрес транскрипції та часові мітки джерела
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 отримувача або рівня доступу для читання/запису, запитайте це, а потім виконайте:
Використовуйте 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-секундний вертикальний фільм із кліпів у моїй медіатеці. Переглянути репрезентативні кадри та замінити спотворений дубль новою генерацією після показу її вартості. Обрізати кліпи, додати мій логотип, тиху фонову музику, озвучення та синхронізовані підписи. Зберегти готове відео в медіатеці та надати мені посилання для завантаження.
Асистент повинен:
Ознайомитися з інструкцією, знайти проект і вихідні медіафайли та перевірити тривалість і відтворення.
Створити або відредагувати монтажну шкалу, використовуючи її поточну ревізію. Додати логотип як зображення на верхньому візуальному шарі та озвучення/музику на аудіошари. Оригінальні медіафайли не змінюються.
Використати preview_editor_project для перевірки вибраних моментів кадру. Встановити review: "keep" або "replace" для кліпу та записати причину в note. Кадри не дають змоги оцінити якість руху чи звуку; перевіряйте також відтворення джерела.
Виявити/оцінити запитані моделі, згенерувати заміни з унікальними ключами ідемпотентності та дочекатися завершення з отриманням їхніх file_id. Замінити джерело вибраного кліпу та обмежити його обрізку/тривалість межами нового джерела.
Оцінити вартість/транскрибувати оригінальне джерело озвучення, опитувати з інтервалом не менше п’яти секунд, потім додати cues з sourceClipId для врахування обрізки та швидкості. Перевірити текст транскрипції. Надання наявних синхронізованих cues не коштує кредитів.
Надіслати поточну ревізію через export_editor_project; опитувати get_editor_export з інтервалом щонайменше п’ять секунд, поки завдання в черзі/під час рендерингу. Відключений запит MCP не скасовує завдання. Успіх означає лише статус completed з assetId та URL для завантаження; перевіряйте помилки перед явною повторною спробою з retry_failed: true. Створюйте посилання для спільного доступу лише за запитом.
Приклад цільового редагування після get_editor_project:
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. Якщо рендеринг не вдається, повідомте про помилку та посилання на редактор; не заявляйте про успішний експорт. Редагування/рендеринг монтажної шкали не витрачає кредитів моделі; генерація/транскрипція — так. Спільний доступ створює посилання, видиме кожному, хто має це посилання.
Використовуйте list_models з type="audio", потім get_model для
ai.gemini_3_8_flash_tts або ai.gemini_3_8_flash_lite_tts.
Обидві моделі генерують одноголосе WAV-аудіо з тексту до 10 000 озвучуваних символів:
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.
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:
Альтернативно надайте videoUrl з посиланням на власне відео. Виберіть рівно одне джерело тривалістю до 15 хвилин. Підключений службовий обліковий запис Google обробляє автентифікацію. Не надавайте облікові дані провайдера або параметри маршрутизації. Опитуйте get_task для отримання results з type: "subtitle"; зберігайте його cues та таймінги слів для підписів редактора. Google наразі позначає часові мітки слів як експериментальні, тому перевіряйте точність транскрипції. Інструменти оцінки вартості/транскрипції редактора тепер за замовчуванням використовують цю модель. Застарілий ai.speech_to_text залишається окремим; адміністратори можуть приховувати його незалежно. Невдалі платні запити повертають кошти через звичайний життєвий цикл завдання і не повинні автоматично повторюватися як нова покупка.
Завершіть воркфлов підписів у редакторі
Транскрибування файлу не вставляє підписи в проект редактора. Для існуючого фільму:
Прочитати get_editor_project і визначити вихідний кліп та його assetId.
Якщо у вас уже є успішний результат підписів generate_lab / get_task для цього джерела, повторно використайте його cues і переходьте безпосередньо до вставки на кроці 4; відео file_id або друга транскрипція не потрібні. Інакше виконайте quote_editor_captions, потім transcribe_editor_media з цим asset_id, language: "auto" (або кодом BCP-47) та унікальним idempotency_key. Повторно використовуйте цей ключ після тайм-ауту мережі.
Опитуйте get_editor_captions з інтервалом щонайменше п’ять секунд. При failed повідомте про error і зупиніться. Нова платна спроба вимагає запиту користувача.
При succeeded переконайтеся, що cues непорожній, отримайте останню ревізію проекту й передайте ці точні cues в edit_editor_project з type: "add_captions", sourceClipId вихідного кліпу, stylePreset: "word-pop" та maxWordsPerCaption: 3 (або інший запитаний пресет слів).
Перевірте нові текстові кліпи в збереженій монтажній шкалі та попередній перегляд у фактичний момент появи підпису. Перевірте точність тексту. Зміну джерела під час транскрипції або обрізку без накладання мовлення потрібно повідомити; не заявляйте про успішну вставку. Повторно використовуйте завершені 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; зміна лише тексту очищує застарілі таймінги.
Щоб скоротити існуючий шар з таймінгом субтитрів без повторної генерації, використовуйте:
Використовуйте фактичну поточну ревізію та 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.
Знайдіть наявні записи через list_editor_media / get_editor_media або завантажте/імпортуйте їх. Генеруйте нове мовлення лише за запитом, використовуючи виявлення моделі, оцінку кредитів і наявні інструменти Gemini TTS. Редактор збирає записи; він не вгадує мовця для кожного рядка.
Додайте аудіошар для кожного оповідача, діалогу, музики або ефектів за потреби. Використовуйте append_editor_audio з упорядкованимиasset_ids, track_id, поточною revision і необов’язковим gap_seconds (0–60). Це додає повні кліпи до цього шару без пропусків через округлення кадрів. Імена файлів не сортуються, а остання частина не обрізається для підгонки. Для перекриттів або індивідуального таймінгу використовуйте наявні операції з кліпами. Обрізки, швидкість, гучність, затухання, вимкнення і приховані шари впливають на мікс; зміна швидкості змінює тональність.
Збережіть теги, бітрейт і обкладинку через edit_editor_project, наприклад:
settings замінює збережені аудіоналаштування: зберігайте поля, які користувач не просив змінювати. Усі теги — рядки. artist указує оповідачів/виконавців, composer може вказувати автора, album ідентифікує книгу, year — чотири цифри, а track — номер або номер/загальна кількість. Не вигадуйте кредити чи авторські права. Якщо назва порожня, використовується назва проєкту. MP3 містить теги Unicode ID3v2.3 і, якщо вибрано, зображення обкладинки APIC. Зображення вбудовується у файл, а не посилається за URL. MP3 може не мати обкладинки; MP4 з обкладинкою вимагає її. Бітрейти: 96, 128 (за замовчуванням), 192, 256 або 320 кбіт/с.
Надішліть export_editor_project зі збереженою ревізією та format: "mp3" або format: "mp4-cover". Запитуйте обидва формати, якщо потрібні обидва файли. Кожен проєкт/ревізія/формат має власне постійне завдання, тому один формат ніколи не замінює інший. Опитуйте get_editor_export з інтервалом щонайменше п’ять секунд, доки не отримаєте completed або failed. Етапи включають завантаження медіа, мікшування аудіо з прогресом, кодування та збереження. Відключений клієнт не скасовує завдання; повторне надсилання відновлює його. Для невдалих завдань потрібен явний retry_failed: true.
Підтвердіть 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, оскільки перевірки меж не гарантують читабельність усередині кривої маски. Див. спільний двомовний контракт.
Дизайн → Бібліотеки надає 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
використовують ті самі поля; див. діагностику невдалих генерацій.