Перейти до документації
v4v.Документація розробникаПОПЕРЕДНЯ ВЕРСІЯВаші ключі API ↗
У ЦЬОМУ ПОСІБНИКУ
АутентифікаціяПошук моделей ЛабораторіїСубтитри з часовими позначкамиОстанні моделі генераціїВідеомоделі Kling 4.0GPT-6 Astra чатLAB з зовнішнім зображеннямЗавантаження приватних медіафайлівСтудія з зовнішніми або приватними медіафайламиЗавдання та кредитиПерейменування та організація проєктівІдемпотентністьПідписані зворотні викликиПомилки та обмеженняМасова генерація Студії (API і MCP)
Доступно для тестування
Попередній перегляд з прямим доступом
API reference · v1

Створюйте за допомогою API V4V.

Створюйте зображення, відео та аудіо у власних застосунках. Один API-ключ. Ваші наявні кредити V4V.

Почати →Завантажити OpenAPI ↓
КІНЦЕВА ТОЧКАhttps://v4v.ai/api/v1
cURL
curl https://v4v.ai/api/v1/models \
  -H "Authorization: Bearer $V4V_API_KEY"
01

Аутентифікація#

Створіть іменований ключ у Профілі → API Keys. Збережіть секрет API та секрет підпису вебхука при їх появі; вони показуються лише один раз. Можна створювати та відкликати кілька ключів незалежно. Секрети ключів зберігаються у вигляді хешів SHA-256.

Надсилайте Authorization: Bearer v4v_live_… з кожним запитом API. Зберігайте цей ключ на сервері, поза браузерними додатками та системами контролю версій. Відкликання блокує майбутні запити; вже прийняті генерації продовжуються.

Базова URL-адреса: https://v4v.ai/api/v1.

02

Пошук моделей Лабораторії#

GET /models перелічує поточні ідентифікатори моделей Лабораторії, їхній увімкнений стан, вхідні дані, параметри, значення за замовчуванням, умови та обмеження. GET /models/{model} описує одну модель. Ідентифікатори та схеми походять із того самого каталогу й тих самих значень за замовчуванням, які використовує Лабораторія. Конфігурація Студії окрема.

Назви моделей у наведених нижче прикладах є фактичними ідентифікаторами каталогу. Використовуйте виявлення, щоб знайти моделі, які наразі увімкнені у вашому обліковому записі. Імена полів специфічні для моделі: зберігайте імена, повернені під час виявлення, включно з camelCase, такими як aspectRatio або referenceImageUrls. Значення вибору — рядки; також приймаються числові значення для числових опцій вибору. Поля можна передавати або у вхідних даних, або в параметрах, але не одночасно. Невідомі поля відхиляються. Моделі з вибором версій мають parameters.variant; використовуйте значення та значення за замовчуванням, повернені під час виявлення.

bash
curl https://v4v.ai/api/v1/models \
  -H "Authorization: Bearer $V4V_API_KEY"
03

Субтитри з часовими позначками#

Знайдіть ai.speech_to_text з типом subtitle. Надішліть ID власного медіафайлу або підтримувану URL-адресу у input.audioUrl або input.videoUrl до POST /lab; необов’язкові параметри включають language_code (наприклад, uk, en або auto) та diarize. Оцінка базується на тривалості оригінального джерела. Транскрипція витрачає звичайні кредити облікового запису.

Завершене завдання повертає results[].type: "subtitle", транскрипт text, srt та редаговані cues з start, end у секундах і text. Успішне тихе введення може мати порожній список позначок. Для монтажу використовуйте інструменти MCP Відеоредактора для вирівнювання цих позначок із обрізкою, швидкістю та позицією на часовій шкалі вихідного кліпу.

04

Останні моделі генерації#

Omni Flash 1.2 (video.gemini_omni_flash-1-2) — рекомендована модель для відеозапитів без явного зазначення моделі. Лабораторія показує її першою; Omni Flash 1.1 залишається доступною в розділі More та за наявним ідентифікатором. Поточні параметри дізнавайтеся через GET /models/{model}. Версія 1.2 підтримує генерацію та редагування тривалістю 3–15 секунд; інтерполяція першого/останнього кадру обмежена 10 секундами. Спільні тарифи на 4/6/8/10 секунд відповідають налаштованим цінам 1.1. Для цін використовуйте поточне виявлення моделі та оцінки, а не зберігайте це співвідношення як постійне правило.

Обирайте GPT Image 2.6 через parameters.variant у image.text_to_image або ai.image_edit. Використовуйте parameters.outputFormat з цими точними можливостями варіантів:

ВаріантФормати виводу
gpt-image-2.6-flare-textpng, jpeg, webp, gif, svg
gpt-image-2.6-sunburst-textpng, jpeg, webp, gif, svg
gpt-image-2.6-flare-imgpng, jpeg, webp
gpt-image-2.6-sunburst-imgpng, jpeg, webp
gpt-image-2.6-economy-textpng, gif
gpt-image-2.6-economy-imgpng

parameters_schema.outputFormat.allowed_by_variant є визначальним джерелом. Flare/Sunburst розраховуються за фактичним використанням вводу/виводу; використання конвертації SVG включається до остаточного підсумку. Economy доступний лише для 1K з тарифікацією за зображення. Завантаження зберігають кадри GIF і байти векторного SVG; завантаження SVG використовують доставку як вкладення.

Nano Banana 2.1 використовує parameters.variant: "nano-banana-v2.1" у тих самих модулях зображень, із підтримкою до 10 референсів і виходом 1K/2K/4K. Поточний режим оплати публікується у . Генерація Google/Vertex розраховується за перевіреним вводом, кешованим вводом, вихідним зображенням, текстовим виводом і токенами міркувань, з урахуванням націнки та з одноразовим округленням загального результату вгору. Компонент вихідного зображення приблизно становить 11/16/36 кредитів V4V для 1K/2K/4K до врахування вводу та міркувань. Лабораторія та оцінки показують приблизний діапазон; початкове резервування відокремлене від остаточної вартості. Для інших маршрутів використовується налаштований тариф за зображення. Маршрутизацією й далі керує V4V; не передавайте параметр маршрутизації.

05

Відеомоделі 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 китайських символів, літер, цифр або підкреслень; вбудовані імена референсів зарезервовані. Згадуйте надані референси як , або їх оголошене . Неоголошені згадки відхиляються.

06

GPT-6 Astra чат#

Отримайте відомості про chat.gpt_6_astra через GET /models/chat.gpt_6_astra (slug: gpt-6-astra). Це тип chat, і він повертає текст. Виявлення моделі включає ставки за токени та правило округлення.

json
{
  "model": "chat.gpt_6_astra",
  "input": {
    "prompt": "Explain what is in this image.",
    "imageUrls": [
      "https://example.com/image.png"
    ]
  },
  "parameters": {
    "reasoningEffort": "high",
    "webSearch": true,
    "stream": false
  }
}

Send this body to POST /lab. Images are optional; up to 12 URLs or owned file IDs are accepted. Text-only requests use string input upstream; image requests use an array of message content. Reasoning effort: low, medium, high, xhigh (default low). Web search and streaming default to false. Streamed responses are returned as a completed task after generation finishes.

Щоб запропонувати функцію, передайте input.functionTools як JSON-рядок, що містить 1–10 визначень із type: "function", name, description та parameters (об’єкт JSON Schema). Встановіть parameters.webSearch у false. У зовнішньому запиті використовується tool_choice: "auto"; запити функцій повертаються у results[].function_calls для обробки вашим додатком. Вузол моделі не виконує функції й не продовжує розмову з результатом функції.

Чат резервує 1 кредит перед входом у чергу. Це мінімальне резервування, а не фіксована ціна чи ліміт витрат. Ставки за 1M токенів: вхід 560, кешований вхід 56, запис кешу 700, вивід 2,800 кредитів. Загальна вартість токенів округлюється вгору один раз до цілого кредиту, мінімальна плата — 1. Після відповіді будь-яка додаткова плата списується атомарно з доступного балансу. Якщо балансу недостатньо, завдання завершується з помилкою, а невикористане резервування звільняється.

Для чатів і зображень з оплатою за використання, кінцева точка оцінки також повертає credits_range з min, max, assumptions, includes_markup: true, is_estimate: true та is_spending_cap: false. Відображайте це як приблизний діапазон у кредитах V4V. Він включає поточну націнку та коригування цін. Це ілюстративні сценарії використання; фактична вартість може виходити за межі діапазону. та описують початкове резервування окремо. Діапазон не змінює розрахунок фактичного використання і не дає змоги встановити жорсткий бюджет.

07

LAB з зовнішнім зображенням#

Медіавходи приймають зовнішню URL-адресу або ID файлу V4V у тому самому полі. Масиви можуть містити обидва типи. URL-адреси повинні повертати фактичні медіафайли без браузерних кукі або інтерактивного входу. Рекомендуються HTTPS та підписані URL з достатньою тривалістю дії. V4V перевіряє і копіює зовнішні медіафайли перед генерацією; внутрішні мережеві URL та небезпечні перенаправлення відхиляються.

bash
curl https://v4v.ai/api/v1/lab \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: product-edit-001' \
  -d '{"model":"ai.image_edit","input":{"prompt":"Place this product on a marble counter","referenceImageUrls":["https://example.com/product.jpg"]},"parameters":{"variant":"nano-banana-2","aspectRatio":"9:16","resolution":"2K"}}'
08

Завантаження приватних медіафайлів#

POST /files приймає поле file у форматі multipart/form-data. Підтримуються зображення, відео та аудіо, з урахуванням обмежень моделей. За замовчуванням ліміт завантаження — 100 MiB, додатково обмежений лімітом завантаження сховища в розгортанні та лімітом проксі. Файли мають містити медіадані, які можна декодувати; для перевірки аудіо/відео на сервері потрібен ffprobe.

bash
curl https://v4v.ai/api/v1/files \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -F 'file=@product.png'
json
{
  "id": "6aa962444bd1dd7ab65bc6b6",
  "type": "image",
  "content_type": "image/png",
  "size": 123456
}

Використовуйте повернений ID напряму, без префікса file_. GET /files/{id} повертає метадані вашого файлу без списання кредитів.

json
{
  "model": "ai.image_edit",
  "input": {
    "prompt": "Create a studio product photograph",
    "referenceImageUrls": [
      "6aa962444bd1dd7ab65bc6b6",
      "https://example.com/side.jpg"
    ]
  },
  "parameters": {
    "variant": "nano-banana-2"
  }
}
09

Студія з зовнішніми або приватними медіафайлами#

POST /studio використовує той самий вибраний воркфлов Студії, підготовку, виконання моделі, множник ціни та знижку підписки, що й інтерфейс Студії.

json
{
  "input": {
    "product_name": "Example Product",
    "product_description": "Lightweight everyday backpack",
    "product_images": [
      "https://example.com/front.jpg",
      "6aa962444bd1dd7ab65bc6b6"
    ],
    "prompt": "Show the product in everyday use"
  },
  "parameters": {
    "duration": 10,
    "aspect_ratio": "9:16",
    "style": "UGC",
    "language": "en",
    "avatar": null
  },
  "callback_url": "https://partner.example/webhooks/v4v"
}

Для повністю приватного процесу з медіафайлами спочатку завантажте кожне зображення продукту через POST /files, потім вставте повернені ID у input.product_images. Так само завантажуйте аватар, аудіо та відеореференси.

Студія приймає product_id (власний збережений продукт), avatar_id (власний або активний публічний аватар медіатеки, підтримується префікс public:), product_name, product_description, prompt, product_images, reference_images, avatar_media, audio та video. Кожне медіаполе приймає референси; масиви підтримують кілька файлів. parameters.avatar приймає ID аватара медіатеки, одну URL-адресу зображення або ID файлу, або null. Обирайте або input.avatar_id, або parameters.avatar. Явно задані поля продукту мають пріоритет над налаштуваннями медіатеки. Активні імена/ID стилів застосовують збережені інструкції стилю. Невідомі, неактивні та порожні значення стилю повертають 422 INVALID_PARAMETER, field: "parameters.style" та error.allowed_values, що містить активні ID/імена. Пропустіть стиль, щоб використати поточний стиль за замовчуванням (UGC, якщо активний, інакше перший активний пресет). Параметри також включають style, language, voice, placement, duration, aspect_ratio та quality.

Міграція для клієнтів, які раніше передавали вільний текст у parameters.style: перенесіть цей творчий напрямок у input.prompt і оберіть активний стиль із MCP (або пропустіть стиль для поточного за замовчуванням). Неправильно написаний стиль більше не стає користувацьким стилем.

10

Завдання та кредити#

Генерація повертає HTTP 202 після перевірки вводу та, коли є доступна потужність, резервування кредитів, не чекаючи генерації:

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6",
  "status": "queued",
  "credits_reserved": 20,
  "created_at": "2026-09-15T18:00:00Z"
}

Необов’язкова назва проєкту

Обидва POST /lab і POST /studio приймають project_name на верхньому рівні, поруч з input, parameters та callback_url:

json
{
  "project_name": "Summer campaign — product photo",
  "model": "image-upscale-topaz",
  "input": {
    "image_url": "https://example.com/product.png"
  },
  "parameters": {
    "upscale_factor": "2"
  }
}

Назва після обрізання (1–200 символів, не порожня) стає заголовком у Проєктах і, для LAB, в Old runs. Якщо її не вказано, використовується наявний заголовок за замовчуванням. Відповідь завдання містить project_name та project_id. Зміна назви з тим самим ключем ідемпотентності спричиняє конфлікт, так само як і зміна вхідних даних генерації.

Статус завдання

Сервер оновлює статус генерації у фоновому режимі. Опитування повертає останній збережений status: queued, processing, completed, failed або cancelled. Поки завдання має статус queued або processing, показуйте індикатор завантаження. Коли status — completed, читайте текст чату з results[].text або завантажуйте медіафайли з results. Для failed перевірте error (включно з неуспішним stage, brief_completed, retryable та рекомендованим retry_after_seconds, якщо відомо) і credits_used. Успішне створення короткого опису може зберігати пов’язане з ним списання, якщо рендеринг не вдався; тимчасова підказка повторної спроби не запускає і не дозволяє нову платну спробу. cancelled також є кінцевим статусом.

Вебхуки є необов’язковими. Без callback_url повторюйте наступний запит кожні 3–5 секунд, доки status не стане completed, failed або cancelled:

bash
curl "$V4V_BASE_URL/api/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $V4V_API_KEY"
11

Перейменування та організація проєктів#

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

Метод і шляхПризначення
GET /projectsЗнайти проєкти Студії, воркфловів і LAB, включно із завданнями API в черзі
PATCH /projects/{project_id}Перейменувати проєкт і/або перемістити його до папки
GET /project-foldersПерелік папок робочого простору
POST /project-foldersСтворити папку з {"name":"Summer campaign"}
PATCH /project-folders/{folder_id}Перейменувати папку з {"name":"Autumn campaign"}

Обидві кінцеві точки списку приймають offset (за замовчуванням 0) і limit (1–100, за замовчуванням 50), повертаючи total і next_offset (null на останній сторінці). Проєкти сортуються від найновіших до найстаріших зі стабільним розв’язанням однакових значень за ID; папки сортуються за назвою. Фільтри проєктів: source=all|studio|workflow|lab, q (буквальний пошук за назвою без урахування регістру, до 200 символів) і folder_id (ID папки, що належить вам, або unfiled для проєктів без папки). Пропустіть folder_id, щоб включити всі папки.

GET /projects повертає projects з полями project_id, project_name, source, folder_id (рядок або null), status, created_at і updated_at. Статус відображає оригінальну історію проєкту або LAB; для статусу генерації використовуйте GET /tasks/{task_id}. Використовуйте повернутий project_id для оновлень; спадкові записи LAB без проєкту використовують свій ID запуску LAB. повертає з полями , , , і .

12

Ідемпотентність#

Надсилайте Idempotency-Key (1–200 символів) під час надсилання запитів LAB або Студії. Той самий акаунт, значення ключа, ендпоінт і JSON-вміст повертають оригінальне завдання, зокрема й через різні API-ключі цього акаунта. Порядок властивостей об’єкта ігнорується. Повторне використання ключа з іншим вмістом повертає HTTP 409 IDEMPOTENCY_CONFLICT. Якщо оригінальний запит ще перевіряється, HTTP 409 REQUEST_IN_PROGRESS просить повторити запит із тим самим ключем. Відхилене надсилання залишається пов’язаним із ключем; виправте його, використовуючи новий ключ.

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

13

Підписані зворотні виклики#

Надайте необов’язковий публічний callback_url. V4V надсилає task.completed або task.failed з полями завдання, списком результатів і стабільним event_id. Зворотні виклики мають заголовки X-V4V-Timestamp і X-V4V-Signature: v1=<hex>. Перевіряйте за допомогою секрету підпису вебхука, показаного при створенні API-ключа.

Підпис — це HMAC-SHA256 для часової позначки, літеральної крапки й точного необробленого тіла запиту. Відхиляйте застарілі часові позначки (наприклад, старші за п’ять хвилин) і порівнюйте підписи в сталий час.

javascript
import crypto from 'node:crypto';
const expected = crypto.createHmac('sha256', webhookSecret)
  .update(`${timestamp}.${rawBody}`).digest('hex');
const valid = /^v1=[a-f0-9]{64}$/.test(signature)
  && Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
  && crypto.timingSafeEqual(Buffer.from(signature.slice(3), 'hex'), Buffer.from(expected, 'hex'));

Швидко повертайте відповідь 2xx. Доставка відбувається принаймні один раз: уникайте дублювання за event_id. Збої мережі, тайм-аути, HTTP 408/429 і відповіді 5xx повторюються з експоненційним збільшенням інтервалу, починаючи з 30 секунд і максимум до однієї години, до 12 спроб за замовчуванням. Інші неуспішні відповіді, включно з перенаправленнями, припиняють доставку. Повторні спроби ніколи не створюють генерацій і не списують кредити. Опитуйте статус завдання, якщо доставка зворотного виклику вичерпана.

Зворотні виклики пакетів Студії

POST /studio/batches також приймає необов’язковий callback_url. Застосовується та сама перевірка підписаного зворотного виклику. Події: batch.updated, batch.completed, batch.paused і batch.cancelled зі стабільними event_id, batch_id, batch_revision, observed_at, state_token, лічильниками та сумами кредитів. Для перегляду поточних пагінованих результатів використовуйте GET /studio/batches/{batch_id}. Події містять компактні знімки замість URL завантаження, що спливають; проміжні зміни можуть об’єднуватися між циклами виконавця.

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

14

Помилки та обмеження#

Помилки мають єдину структуру:

json
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Allowed values: 5, 10.",
    "field": "parameters.duration"
  }
}

HTTP 400/422 означає недійсні вхідні дані або параметри; 401 — недійсний/скасований ключ; 402 — недостатньо кредитів; 403 — вимкнені моделі або відмовлений доступ; 404 — недоступні моделі/файли/завдання; 409 — конфлікт ідемпотентності або триває перевірка; 429 — обмеження швидкості/конкурентності; 500 — внутрішня помилка; 503 — тимчасова недоступність сервісу. Коди помилок включають INVALID_API_KEY, INSUFFICIENT_CREDITS, MODEL_NOT_FOUND, MODEL_DISABLED, INVALID_INPUT, INVALID_PARAMETER, INVALID_MEDIA_URL, MEDIA_NOT_ACCESSIBLE, UNSUPPORTED_MEDIA_TYPE, MEDIA_TOO_LARGE, FILE_NOT_FOUND, FILE_ACCESS_DENIED, RATE_LIMIT_EXCEEDED, GENERATION_FAILED, GENERATION_SERVICE_ERROR і SERVICE_UNAVAILABLE. GENERATION_SERVICE_ERROR позначає зареєстровану внутрішню помилку сервісу моделі; це не означає, що розмір вхідних даних або параметри були недійсними. Відсутні та недоступні ID файлів мають спільну відповідь 404, щоб уникнути розкриття файлів інших акаунтів.

Default limits are 120 requests per minute per key, 10 generation submissions per minute per account, and 3 concurrent accepted generations per account. Every HTTP 429 includes error.retryable and a positive integer error.retry_after_seconds; the HTTP Retry-After header uses the same value. Request-window errors also return reason: "request_rate_limit", the configured limit, and a public scope (key, generation, bulk, mcp-upload-link or mcp-upload), without internal account/key IDs. The retry delay is the rounded-up time remaining in the minute window, not always 60 seconds. MCP tool errors preserve these fields in their JSON even when HTTP headers are unavailable. Account contention uses its own reason: "account_busy" and one-second delay. Generation capacity is handled separately by the durable queue; wait for the accepted task rather than resubmitting it.

json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded. Retry after 18 seconds.",
    "reason": "request_rate_limit",
    "scope": "key",
    "limit": 120,
    "retryable": true,
    "retry_after_seconds": 18
  }
}

Для відмов у вікні запиту (до створення завдання) зачекайте вказану затримку і повторно використайте той самий ключ ідемпотентності та аргументи. Відповідь, що ідентифікує вже неуспішне завдання, є кінцевою для цього завдання. Це не дозволяє ще одну платну спробу після кінцевої відмови генерації.

15

Масова генерація Студії (API і MCP)#

Масова генерація доступна через API і MCP. В інтерфейсі Студії поки що немає окремого робочого простору для масової генерації. Надсилайте до 300 продуктів в одному JSON-запиті. Кожен елемент створює один воркфлов Студії з власним завданням, збереженим воркфловом/налаштуваннями, результатами та обліком кредитів. Імпорт продуктів і завантаження референсів відбуваються у фоновому режимі; недійсний елемент завершується помилкою окремо, а решта елементів продовжує обробку.

Студія, LAB, REST, MCP, Shopify та генерація аватарів використовують спільну постійну чергу сервера з абсолютним лімітом у 10 активних запитів на генерацію для цього розгортання. Очікування результату генерації займає слот. Завершена генерація звільняє цей слот навіть під час збереження файлу. Звичайні запити мають пріоритет над масовими; масові використовують доступну потужність з урахуванням глобальних обмежень адміністратора на масові запити та обмежень на акаунт. За замовчуванням дозволено 2 одночасні масові воркфлови та 1 на акаунт. Кілька пакетів одного акаунта ділять це обмеження. Обробка продовжується без відкритого браузера або опитування клієнтом.

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

POST /api/v1/studio/batches — повертає HTTP 202. Обов’язково вкажіть заголовок Idempotency-Key довжиною від 1 до 200 символів. Повторно використовуйте той самий ключ і ідентичний JSON після переривання мережі. Змінене тіло з тим самим ключем повертає HTTP 409; прийняття ніколи не створює другий пакет для повторної спроби.

bash
curl "$V4V_BASE_URL/api/v1/studio/batches" \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: autumn-catalogue-001' \
  --data '{
    "name": "Autumn catalogue",
    "max_credits": 600,
    "input": { "prompt": "Show three benefits of this product in a calm reveal" },
    "parameters": { "duration": 8, "aspect_ratio": "9:16", "quality": "720p" },
    "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_description": "Adjustable warm light",
          "product_images": ["https://shop.example/lamp.jpg"]
        },
        "parameters": { "style": "TV Spot" }
      }
    ]
  }'

Використовуйте тривалість, формат і якість, підтримувані поточним воркфловом Студії вашого розгортання, як для POST /api/v1/studio. У прикладі бюджет становить 600 кредитів для трьох 8-секундних кліпів Omni 720p: 3 × 180 = 540 кредитів, залишаючи 60 кредитів запасу. Три 10-секундні кліпи у 720p використовують 675 кредитів; у 1080p — 990, а у 4K — 1 980, без урахування тарифікації за референсне відео, додаткових кроків або повторних спроб. Завжди отримуйте актуальні оцінки для точних вхідних даних перед вибором бюджету пакета.

V4V / API reference · v1Створюйте те, що хочеться дивитися.
pricing_by_variant

Gemini 4 Argon (chat.gemini_4_argon) також доступний через Лабораторію, воркфлови та API/MCP. Його використання вводу, кешованого вводу, виводу та токенів міркувань розраховується після відповіді. Поточні ціни, дати запуску та коригування ставок переглядайте у виявленні моделі.

@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}. Застосовуються стандартні авторизація генерації, перевірки балансу, ключі ідемпотентності, зворотні виклики та відшкодування в разі невдачі.

credits_estimated
initial_reservation_estimated

GET /tasks/{task_id} та зворотні виклики завершення повертають вбудований текст без необхідності медіафайлу:

json
{
  "status": "completed",
  "credits_reserved": 3,
  "credits_used": 3,
  "results": [
    {
      "type": "text",
      "text": "The image shows…",
      "incomplete": false,
      "function_calls": [],
      "usage": {
        "input_tokens": 4443,
        "uncached_input_tokens": 4443,
        "cached_input_tokens": 0,
        "cache_write_tokens": 0,
        "output_tokens": 47
      },
      "credits": 3
    }
  ]
}

credits_reserved відображає розширене резервування після розрахунку. incomplete: true означає, що досягнуто ліміт виводу; спожиті токени все одно оплачені. Повторне опитування або повторна спроба з тим самим ключем ідемпотентності не створює додаткових витрат.

describe_studio

Вибраний воркфлов визначає обмеження. ProVid підтримує 4–15 цілих секунд, 480p/720p/1080p та співвідношення 9:16, 16:9, 1:1, 4:5, 4:3, 3:4, 21:9, adaptive. OmniVid підтримує 4/6/8/10 секунд, 360p/720p/1080p/4k та 9:16 або 16:9. Нові запити OmniVid Studio за замовчуванням мають 720p і 10 секунд, якщо не вказано явні налаштування. Неприпустимі параметри повертають помилку валідації. Також діють обмеження на комбінації медіа. OmniVid підтримує ID аудіореференсів у LAB, але не приймає сирі файли аудіореференсів у Студії; непідтримувані референси повертають помилку валідації.

Після завершення читайте текстові результати безпосередньо; завантажуйте медіафайли з results[].url. Поки згенеровані файли зберігаються, завдання залишається в статусі processing; успішна генерація сама по собі не означає завершення. Повторюйте запит статусу, щоб оновити прострочені URL для завантаження. Опитування не запускає нову генерацію і не списує кредити.

Опитуйте GET /tasks/{task_id} або надайте URL зворотного виклику. Статус може бути queued, processing, completed, failed або cancelled. Для опитування потрібен API-ключ того самого облікового запису, що й у завдання.

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6",
  "source": "lab",
  "status": "completed",
  "credits_used": 18,
  "results": [
    {
      "type": "video",
      "url": "https://v4v.ai/api/v1/results/…",
      "content_type": "video/mp4",
      "size": 18392832,
      "expires_at": "2026-09-16T00:00:00Z"
    }
  ]
}

Кожен медіарезультат містить стабільні значення asset_id і file_id. Використовуйте file_id у подальших медіавходах генерації. Відповіді також містять project_id. Список результатів підтримує кілька зображень, відео та аудіофайлів. Посилання на результати підписані і доступні без файлів cookie V4V або автентифікації. Повторно отримуйте статус завдання, щоб оновити прострочені посилання. Гарантія повторного використання — це стабільний ID файлу плюс поновлюваний підписаний URL, доки збережений файл існує і доступ дозволений; це не незмінний публічний URL. Щоб повторно використати результат наступного дня, знову отримайте той самий ID завдання/файлу і завантажте через новий URL. Будь-хто, хто має посилання на результат, може ним користуватися до закінчення терміну дії.

Для окремих запитів LAB/Студії оцінені кредити резервуються, якщо доступна ємність акаунта. Якщо налаштований ліміт одночасних завдань вичерпано (за замовчуванням 3), запит повертає те саме стале завдання в черзі з нульовими credits_reserved, credits_estimated і queue, що містить limit, retry_after_seconds: 5 і estimated_start_at: null. Виконавець допускає завдання, що очікують, без повторного надсилання. Він атомарно резервує кредити, коли звільняється слот; недостатній баланс у цей момент призводить до помилки завдання на stage: "admission" і планує його вебхук. Повторно використовуйте оригінальний ключ ідемпотентності після мережевих помилок; не створюйте інше завдання, щоб обійти очікування. Для пакетної обробки оцінка кожного елемента резервується лише тоді, коли цей елемент допускається до запуску. Витрати на генерацію списуються з цього резерву. Витрати на неуспішну генерацію повертаються за наявним механізмом відшкодування; невикористані зарезервовані кредити вивільняються після завершення або помилки. Успішні кроки в частково неуспішному воркфлові Студії зберігають свої звичайні списання. Виявлення, опитування, пошук файлів, зворотні виклики та повторні спроби зворотних викликів не тарифікуються як генерація.

GET /balance повертає поточну кількість доступних кредитів. GET /usage повертає останні 100 запитів на генерацію для акаунта. Профіль показує кількість запитів/генерацій за весь час і остаточно списані кредити для кожного ключа, а також недавню історію завдань. Завантаження залишаються в медіатеці LAB користувача і можуть бути видалені там.

GET /project-folders
folders
folder_id
name
color
created_at
updated_at
bash
# Discover projects and folders.
curl -H "Authorization: Bearer $V4V_API_KEY" \
  'https://v4v.ai/api/v1/projects?source=studio&limit=50'
curl -H "Authorization: Bearer $V4V_API_KEY" \
  'https://v4v.ai/api/v1/project-folders'

# Supply real IDs returned by the list endpoints.
curl -X PATCH "https://v4v.ai/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $V4V_API_KEY" -H 'Content-Type: application/json' \
  -d '{"project_name":"Summer campaign — approved","folder_id":"YOUR_FOLDER_ID"}'

Оновлення проєкту приймає project_name (після обрізання пробілів, 1–200 символів), folder_id або обидва. Надішліть {"folder_id":null}, щоб вилучити проєкт із папки. Пропущені поля залишаються без змін. Відповідь містить project_id і оновлені поля. Перейменування та переміщення також оновлюють відповідне завдання API й історію LAB; завдання в черзі зберігають організацію, коли їхні проєкти створюються.

Назви папок обрізаються, мають містити 1–80 символів і бути унікальними в межах акаунта. Створення повертає HTTP 201; перейменування — 200, в обох випадках із наведеними вище полями папки. Перейменування зберігає ID папки та її проєкти. Дублікат назви повертає 409 FOLDER_NAME_CONFLICT; недійсні поля — 422 INVALID_INPUT; недоступні проєкти або папки — 404 PROJECT_NOT_FOUND або FOLDER_NOT_FOUND. Після неоднозначної відповіді на створення папки спочатку отримайте список папок перед повторною спробою.

Відповіді пакетів містять state_token, який змінюється при значущому прогресі або керуванні і залишається стабільним, коли оновлюються лише підписані URL. MCP додатково надає wait_studio_batch для обмеженого очікування на сервері під час активної розмови; див. MCP моніторинг.

FieldMeaning
nameОбов’язкова назва пакета, 1–200 символів
max_creditsОбов’язковий додатний бюджет кредитів; витрачені кредити разом з активними резервуваннями ніколи не можуть його перевищувати
input, parametersНеобов’язкові спільні поля Студії, з тими самими назвами, що й в одному запиті Студії
itemsОбов’язковий масив із 1–300 об’єктів продуктів
items[].skuНеобов’язкове клієнтське посилання, не більше 200 символів
items[].product_idНеобов’язковий ID бібліотеки продуктів, що належить цьому обліковому запису
items[].product_urlНеобов’язкова публічна сторінка продукту для імпорту; параметри варіанта/запиту зберігаються, за винятком eBay tracking, який канонізується
items[].input, items[].parametersПеревизначення елемента; пріоритет: елемент → пакет → типові значення Студії
test_countНеобов’язкове значення 5; обробляє лише перші п’ять елементів, а потім очікує явного відновлення

Використовуйте ідентифікатор із бібліотеки продуктів, URL сторінки продукту або дані/зображення продукту в input. Якщо вказані і product_id, і URL, використовується продукт із бібліотеки. Вхідні поля, явно задані клієнтом, мають пріоритет над імпортованими значеннями. Референсні медіафайли копіюються у власне сховище тим самим сервісом, що й для одиночних генерацій через API. Імпорт сторінок продуктів через API використовує обмежені публічні HTTP-запити з перевіреними переадресаціями. Посилання на лістинги eBay також мають захищений резервний варіант через браузер. Магазин усе одно може відхилити імпорт або вимагати вхід; у такому разі надайте власний product_id або підготовлені дані/зображення продукту. Ліміт тіла запиту — 1 MiB. Надсилайте списки продуктів у форматі JSON; завантаження CSV-файлів не входить до цього випуску API.

У відповіді містяться batch_id, status, total_items, max_credits, credits_used, credits_committed, лічильники та перша сторінка елементів. Початкове прийняття не резервує кредити для всього пакета. Завдання можуть з’явитися на наступному циклі виконавця, тому прийнятий елемент спочатку може мати порожній масив attempts.

Прогрес і результати

  • GET /api/v1/studio/batches?offset=0&limit=50 перелічує пакети цього облікового запису.
  • GET /api/v1/studio/batches/{batch_id}?offset=0&limit=50 повертає прогрес елементів. Пагінація відбувається за індексом елемента з нуля, а максимальний розмір сторінки — 100.
  • Кожен елемент містить index, необов’язковий sku, статус і attempts. Спроба містить звичайний task_id, version, credits_used і статус; завершені спроби містять підписані URL-адреси результатів.
  • GET /api/v1/tasks/{task_id} отримує одну спробу та оновлює її підписані посилання на результати. Застосовуються звичайні правила власності завдань для ключів, що належать одному обліковому запису.

Елемент зі статусом IMPORT_FAILED зазнав невдачі до допуску до платної генерації. Повідомлення про помилку вказує на заблоковану сторінку eBay/безпеки, якщо це відомо, і пропонує повторну спробу або підготовлені дані продукту. PREPARATION_FAILED вказує на неочікуваний збій підготовки генерації після імпорту; при зверненні до підтримки вкажіть task_id. Помилки валідації/медіафайлів зберігають свої специфічні коди. Інші елементи продовжують обробку. Кожна невдала спроба є кінцевою: resume її не повторює. Після виправлення введених даних або розгортання виправлення використовуйте retry_failed або rework нижче, щоб створити нову спробу в тому ж пакеті. Повторне використання оригінального ключа створення повертає оригінальний пакет; воно не запускає його повторно.

DIRECTOR_REQUEST_FAILED means the AI Director's text-model request was rejected before it could produce a video brief. REFERENCE_MEDIA_UNAVAILABLE identifies an unreadable, unsupported or oversized Director reference image. Report the task_id to support; do not treat either error as a video-generation failure or automatically spend credits on another attempt. Saved account images are sent directly from storage to the Director as binary image inputs, so this stage does not need anonymous CDN access.

Опитуйте не частіше ніж раз на п’ять секунд. Пакет повідомляє completed, коли всі його елементи досягли кінцевого статусу; перевіряйте лічильники та окремі помилки, оскільки завершення може включати невдалі елементи. Елемент, утримуваний п’ятиелементним зразком, повідомляє waiting_for_sample. Зразок призупиняється зі статусом TEST_REVIEW_REQUIRED після того, як його спроби досягнуть стабільного стану.

Пауза, відновлення, скасування та збільшення бюджету

POST /api/v1/studio/batches/{batch_id}:

json
{
  "action": "pause"
}
json
{
  "action": "resume",
  "max_credits": 1000
}
json
{
  "action": "cancel"
}

Пауза та скасування запобігають майбутнім запускам. Спроби, які вже допущені до запуску, зберігають свої резервування і завершуються нормально. Відновлення продовжує решту після зразка, поповнення балансу або збільшення бюджету. Бюджети можна лише збільшувати. Скасування зупиняє решту елементів. Ці дії є ідемпотентними, доки запитуваний стан пакета не змінюється; скасований пакет не може resume, але може явно restart або rework кінцеві елементи.

Повторити невдалі спроби, переробити елементи або перезапустити пакет

Використовуйте той самий ендпоінт POST /api/v1/studio/batches/{batch_id}. Ці дії створюють нові, потенційно платні спроби і вимагають нового заголовка Idempotency-Key (1–200 символів) для кожної навмисної операції. Повторно використовуйте цей ключ та ідентичний JSON після переривання мережі. Змінене тіло запиту повертає IDEMPOTENCY_CONFLICT. Ключі для цих операцій обмежені обліковим записом і пакетом, окремо від створення пакета. Ліміт тіла запиту — 1 MiB.

ДіяЩо виконується
retry_failedЛише елементи, у яких остання спроба зазнала невдачі. Необов’язковий item_indexes вибирає підмножину; пропустіть його для всіх невдач.
reworkВибрані кінцеві елементи, зокрема успішні або скасовані. Обов’язкові записи items ідентифікують рівно один index з нуля або поточний task_id, а також необов’язкові product_id, product_url, input або parameters.
restartКожен елемент, зокрема успішні, з новою спробою. Спочатку дочекайтеся завершення допущеної роботи. Обмеження зразка знімається.
bash
curl "$V4V_BASE_URL/api/v1/studio/batches/$BATCH_ID" \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: catalogue-retry-1" \
  -d '{"action":"retry_failed","max_credits":800}'

Щоб виправити лише один продукт без повторної генерації успішних елементів:

json
{
  "action": "rework",
  "items": [
    {
      "index": 1,
      "product_url": "https://www.ebay.de/itm/227541601859",
      "input": {
        "prompt": "A slow close-up of the bag and its details."
      },
      "parameters": {
        "duration": 8
      }
    }
  ]
}

Щоб переробити результати, які вам не подобаються, скопіюйте їх поточний items[].task_id з відповіді пакета. Ви можете зберегти ті ж вхідні дані або надати новий промпт:

json
{
  "action": "rework",
  "items": [
    {
      "task_id": "task_0123456789abcdef01234567"
    },
    {
      "task_id": "task_abcdef0123456789abcdef01",
      "input": {
        "prompt": "Slower close-up, softer lighting"
      }
    }
  ]
}

Використовуйте наявний URL пакета та новий операційний Idempotency-Key. Пакет повертається у стан running, вибрані елементи стають queued, а їхні поля верхнього рівня task_id/results/error очищаються, доки нова спроба не буде матеріалізована/завершена. Інші завершені елементи залишаються без змін. Попередній результат зберігається лише в історії attempts; споживачі повинні відображати items[].results для поточного результату. Для кожного запису дозволено рівно один із index або task_id. Чужий/непов’язаний task повертає TASK_NOT_FOUND; task із уже заміненої версії повертає BATCH_ITEM_VERSION_CHANGED (409), тому застарілі вибори не можуть непомітно повторно запустити новіший результат. Повторне відтворення прийнятого ключа безпечне навіть після того, як вибраний task став історичним.

Для повного повторного запуску надішліть {"action":"restart"} з новим ключем. Усі три дії приймають необов’язкові зміни input та parameters для всієї операції, а також збільшення max_credits. Зміни об’єднуються з попереднім запитом цього елемента; зміни на рівні елемента мають пріоритет. Зміна product_id або product_url очищує попередню альтернативу. Раніші знімки запитів і результати залишаються без змін. Наступні повторні спроби успадковують останні прийняті виправлення і готують новий воркфлов.

Вибрані спроби мають бути кінцевими. BATCH_ITEMS_ACTIVE (409) означає, що робота все ще в черзі/допущена/в обробці, вибраний елемент для повторної спроби не зазнав невдачі або іншу повторну спробу щойно прийнято. Для повного перезапуску скасуйте очікуючу роботу і дочекайтеся завершення допущених спроб. GENERATION_UNRESOLVED (409) блокує повторні спроби, поки попередній запит генерації в черзі, виконується, надсилається або його стан невизначений; спочатку узгодьте його результат. NO_FAILED_ITEMS (409) означає, що немає нічого для повторної спроби. Повторні спроби та переробка явно запускають обробку, включно з іншими очікуючими елементами в цьому пакеті; наявне обмеження п’ятиелементного зразка зберігається, якщо resume або restart його не знімають.

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

Відповіді зберігають кожну спробу в items[].attempts, кожна з власним завданням/проектом і зростаючою version (номери можуть пропускатися). items[].version, статус елемента та counts описують останню призначену версію; нова версія спочатку звітує як queued навіть до матеріалізації завдання. credits_used включає всі версії. Пакет завершується лише тоді, коли остання версія кожного елемента є кінцевою. Повторені операції ніколи не запускають додаткові спроби. Зберігається до 100 операцій зі створення версій і 8 МіБ накопичених змін на пакет; BATCH_HISTORY_LIMIT (409) вимагає нового пакета при заповненні.

INSUFFICIENT_CREDITS або BUDGET_EXCEEDED призупиняють нові запуски. Додавання кредитів на рахунок не відновлює пакет автоматично: явно викличте resume. Допуск бюджету та резервування облікового запису є атомарними в межах відповідних документів MongoDB, тому одночасні воркери не можуть перевищити бюджет пакета або списати одну й ту саму спробу двічі. Набір реплік MongoDB не потрібен.

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

Журнали кредитів

Адміністратори можуть фільтрувати журнали кредитів за API або MCP. Записи містять ім’я/ID API-ключа, ID завдання/проєкту/джоба, джерело генерації та маркери масового пакета/елемента/версії, де це застосовно. Секрети ключів ніколи не журналюються.

Резервування та розрахунки є аудиторськими подіями з нульовою зміною кредитів; метадані фіксують зарезервовану суму. Списання та повернення відображають фактичну зміну кредитів рівно один раз. balanceAfter — це доступний баланс рахунку, який не включає непогашені резервування. Історичні списання через API відновлюються зі збережених квитанцій завдань без повторного списання з рахунку; якщо історичний доступний баланс неможливо відновити, адміністративний інтерфейс повідомляє про це.

Діагностика невдалого генерування

Невдалі REST-завдання, результати MCP get_task та підписані зворотні виклики task.failed містять об’єкт помилки. message — це резюме V4V; provider_error зберігає причину від сервісу моделі з прихованими обліковими даними, приватною маршрутизацією та мережевими локаціями. provider використовує публічний псевдонім маршрутизації managed.

json
{
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Generation failed. Unused credits and failed generation charges have been released.",
    "stage": "generation",
    "retryable": false,
    "provider": "managed",
    "provider_error": "The model is currently unable to process speech edits. If you think this was an error, send feedback.",
    "hint": "Remove speech from the reference video or use still images."
  }
}

Відмови з міркувань безпеки, редагування мовлення та непідтримувані тривалості/роздільні здатності вимагають зміни запиту. Обмеження швидкості та тайм-аути включають retryable: true, retry_after_seconds: 60 та підказку для відновлення. Невідомі причини залишаються доступними без вигаданого діагнозу чи рекомендації повторної спроби. Ці поля опускаються, якщо діагностика сервісу моделі відсутня. Старі невдалі завдання доповнюються, поки їх запис про невдачу воркфлову залишається доступним. Студія та Лабораторія показують однакову очищену причину та надсилають її як GA4 generation_failed.reason (з урахуванням існуючого обмеження аналітики в 120 символів).

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