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

​
Процес подачі заявки

Щоб використовувати API, спочатку потрібно перейти на сторінку API генерації відео Veo та подати заявку на відповідну послугу. Після переходу на сторінку натисніть кнопку «Acquire», як показано на малюнку: Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід. Після входу або реєстрації ви автоматично повернетеся на поточну сторінку. При першій подачі заявки вам буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей API.

​
Основне використання

Спочатку потрібно ознайомитися з основними способами використання, а саме: введенням підказки prompt, дії action, масиву зображень для початкових і кінцевих кадрів image_urls та моделі model, щоб отримати оброблений результат. Спочатку потрібно просто передати поле action, значення якого буде text2video. Воно містить три основні дії: створення відео з тексту (text2video), створення відео з зображення (image2video), отримання відео 1080p (get1080p). Потім потрібно ввести модель model, наразі основними є моделі veo2, veo2-fast, veo3, veo31, veo31-fast, veo31-fast-ingredients та veo3-fast, деталі наведені нижче:

Ми можемо бачити, що тут налаштовані заголовки запиту, включаючи:
  • accept: формат відповіді, який ви хочете отримати, тут вказується application/json, тобто формат JSON.
  • authorization: ключ для виклику API, після подачі заявки його можна вибрати зі списку.
Також налаштовано тіло запиту, яке включає:
  • model: модель для генерації відео, основні з яких: veo2, veo2-fast, veo3, veo31, veo31-fast, veo31-fast-ingredients та veo3-fast.
  • action: дія для цього завдання генерації відео, що включає три основні дії: створення відео з тексту (text2video), створення відео з зображення (image2video), отримання відео 1080p (get1080p).
  • image_urls: при виборі дії створення відео з зображення image2video потрібно завантажити посилання на зображення для початкових і кінцевих кадрів, максимум три зображення.
  • resolution: вибір роздільної здатності для згенерованого відео, модель veo31 підтримує 4k, інші моделі не підтримують, всі моделі підтримують 1080p та gif роздільну здатність, якщо це значення не передано, за замовчуванням використовується 720p, основні варіанти: 1080p, gif, 4k.
  • prompt: підказка.
  • callback_url: URL для отримання результатів.

​
📌 Підсумок опису моделей

Назва моделіПідтримувані режимиПравила введення зображень
veo2-fastСтворення відео з тексту (без зображень)
Створення відео з зображення (з зображеннями)		Підтримує лише 1 зображення → режим початкового кадру
veo3-fastСтворення відео з тексту (без зображень)
Створення відео з зображення (з зображеннями)		1 зображення → режим початкового кадру
3 зображення → режим початкового та кінцевого кадру
veo31-fastСтворення відео з тексту (без зображень)
Створення відео з зображення (з зображеннями)		1 зображення → режим початкового кадру
3 зображення → режим початкового та кінцевого кадру
veo31-fast-ingredients❌ Створення відео з тексту (не підтримується)
✅ Обов’язкове злиття кількох зображень (необхідно передати зображення)		1-3 зображення → режим злиття кількох зображень (максимум 3 зображення)
veo2Створення відео з тексту (без зображень)
Створення відео з зображення (з зображеннями)		1 зображення → режим початкового кадру
3 зображення → режим початкового та кінцевого кадру
veo3Створення відео з тексту (без зображень)
Створення відео з зображення (з зображеннями)		1 зображення → режим початкового кадру
3 зображення → режим початкового та кінцевого кадру
veo31Створення відео з тексту (без зображень)
Створення відео з зображення (з зображеннями)		1 зображення → режим початкового кадру
3 зображення → режим початкового та кінцевого кадру

​
🔑 Опис ключових правил

  1. Загальна логіка:
    • Без введення зображень → автоматично активується режим створення відео з тексту.
    • З введенням зображень → активується режим створення відео з зображення (конкретна дія визначається кількістю зображень).
  2. Типи режиму створення відео з зображення:
    • Режим початкового кадру (1 зображення): початковий кадр фіксується як введене зображення.
    • Режим початкового та кінцевого кадру (2 зображення): початковий та кінцевий кадри фіксуються як введені зображення.
    • Режим злиття кількох зображень (1-3 зображення): підтримується лише veo31-fast-ingredients, зливає вміст кількох зображень для створення відео.
  3. Класифікація режимів:
    • Швидкісний режим: veo2-fast, veo3-fast, veo31-fast, veo31-fast-ingredients.
    • Якісний режим: veo2, veo3, veo31 (вища якість генерації).

​
⚠️ Зверніть увагу

  • Єдиний обов’язковий режим з введенням зображень: veo31-fast-ingredients обов’язково вимагає введення зображень (1-3 зображення), інакше не зможе працювати.
  • Обмеження на кількість зображень:
    • Окрім veo31-fast-ingredients, інші моделі підтримують максимум 3 зображення для введення.
Після вибору ви також можете побачити відповідний код з правого боку, як показано на малюнку:

Натисніть кнопку «Try», щоб провести тестування, як показано на малюнку, і ми отримаємо наступний результат: 
{
  "success": true,
  "task_id": "dd01fc69-e1f7-4b68-aa8c-463f6b748d11",
  "trace_id": "9906dac0-1516-41dc-9fe3-067ca1ba8269",
  "data": [
    {
      "id": "253eedc47f1c4eb2a370ed2312168f4b",
      "video_url": "https://platform.cdn.acedata.cloud/veo/dd01fc69-e1f7-4b68-aa8c-463f6b748d11.mp4",
      "created_at": "2025-07-25 16:07:43",
      "complete_at": "2025-07-25 16:10:28",
      "state": "succeeded"
    }
  ]
}
Повернені результати містять кілька полів, описаних нижче:
  • success，на цей момент статус завдання на створення відео.
  • task_id，на цей момент ID завдання на створення відео.
  • data，на цей момент результат завдання на створення відео.
    • id，на цей момент ID відео завдання на створення відео.
    • video_url，на цей момент посилання на відео завдання на створення відео.
    • created_at，на цей момент час створення завдання на створення відео.
    • complete_at，на цей момент час завершення завдання на створення відео.
    • state，на цей момент статус завдання на створення відео.
Можна побачити, що ми отримали задовільну інформацію про відео, нам лише потрібно отримати з результату data посилання на відео, щоб отримати згенероване відео Veo. Крім того, якщо ви хочете згенерувати відповідний код для інтеграції, ви можете просто скопіювати його, наприклад, код CURL виглядає так: 
curl -X POST 'https://api.acedata.cloud/veo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "veo2",
  "prompt": "Біла керамічна чашка з кавою на блискучій мармуровій стільниці з ранковим світлом з вікна. Камера повільно обертається на 360 градусів навколо чашки, зупиняючись на мить біля ручки."
}'

​
Функція створення відео з зображень

Якщо ви хочете створити відео на основі зображень початкового та кінцевого кадру, ви можете встановити параметр action на image2video і ввести масив посилань на зображення початкового та кінцевого кадру image_urls. Далі нам потрібно заповнити наступний крок, щоб розширити підказки для налаштування створення відео, можна вказати такі параметри:
  • model：модель для створення відео, основні варіанти: veo2, veo2-fast, veo3 та veo3-fast.
  • image_urls：коли вибирається дія створення відео image2video, потрібно завантажити посилання на зображення початкового та кінцевого кадру.
  • prompt：підказка.
Приклад заповнення виглядає так:

Після заповнення автоматично згенерувався код, як показано нижче:

Відповідний код на Python: 
import requests

url = "https://api.acedata.cloud/veo/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "image2video",
    "model": "veo2",
    "prompt": "Нехай танцює",
    "image_urls": ["https://cdn.acedata.cloud/7p1jhy.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Клікнувши на виконання, можна побачити результат, як показано нижче: 
{
  "success": true,
  "task_id": "98e309f3-35bc-438d-8cb3-4015fc864b87",
  "trace_id": "8bc68066-36de-41ef-ae5e-b7d61ff6aee8",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.acedata.cloud/veo/98e309f3-35bc-438d-8cb3-4015fc864b87.mp4",
      "created_at": "2025-07-25 16:13:07",
      "complete_at": "2025-07-25 16:16:12",
      "state": "succeeded"
    }
  ]
}
Можна побачити, що вміст результату збігається з попереднім, що реалізує функцію створення відео з зображень.

​
Функція отримання відео 1080p

Якщо ви хочете отримати 1080p для вже згенерованого відео Veo, ви можете встановити параметр action на get1080p і ввести ID відео, для якого потрібно отримати 1080p. ID відео отримується на основі базового використання, як показано на малюнку нижче:

Тоді можна побачити, що ID відео: 
"id": "59f12222b1fa4fbe9331ff2400ad1583"
Зверніть увагу, що тут video_id відео є ID згенерованого відео. Якщо ви не знаєте, як згенерувати відео, ви можете звернутися до попереднього базового використання для створення відео.
Далі нам потрібно заповнити наступний крок, щоб розширити підказки для налаштування створення відео, можна вказати такі параметри:
  • model：модель для створення відео, основні варіанти: veo2, veo2-fast, veo3 та veo3-fast.
  • video_id：ID відео для отримання 1080p.
Приклад заповнення виглядає так:

Після заповнення автоматично згенерувався код, як показано нижче:

Клікнувши на виконання, можна побачити результат, як показано нижче: 
{
  "success": true,
  "task_id": "47a51cfe-2e24-4aba-93b3-546c2dc52984",
  "trace_id": "a8922eec-6f50-4f77-8104-00ded071d59d",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.acedata.cloud/veo/47a51cfe-2e24-4aba-93b3-546c2dc52984.mp4",
      "created_at": "2025-07-25 16:13:07",
      "complete_at": "2025-07-25 16:16:12",
      "state": "succeeded"
    }
  ]
}
Можна побачити, що вміст результату збігається з попереднім, що реалізує функцію отримання відео 1080p.

​
Генерація відео з вказаними розмірами

Якщо ви хочете вказати розміри для створення відео Veo, ви можете встановити параметр aspect_ratio на бажані розміри. Далі нам потрібно заповнити наступний крок, щоб розширити підказки для налаштування створення відео, можна вказати такі параметри:
  • model：модель для створення відео, основні варіанти: veo2, veo2-fast, veo3 та veo3-fast.
  • aspect_ratio：розмір відео, наразі підтримуються: 16:9, 16:9, 3:4, 4:3, 1:1, за замовчуванням 16:9.
  • translation：чи включити автоматичний переклад підказок, за замовчуванням false. Приклад заповнення виглядає так:

Після заповнення автоматично згенерувався код, як показано нижче:

Клікнувши на виконання, можна побачити результат, як показано нижче: 
{
  "success": true,
  "task_id": "d2b93290-ab0e-4d20-ae45-60c062a32687",
  "trace_id": "9834e64d-c8fe-43ae-8114-ee2b5f93d886",
  "data": [
    {
      "id": "fc667e7d3b8f44beaa61a3c339af0e50",
      "video_url": "https://platform.cdn.acedata.cloud/veo/d2b93290-ab0e-4d20-ae45-60c062a32687.mp4",
      "created_at": "2025-08-24 20:09:06",
      "complete_at": "2025-08-24 20:10:45",
      "state": "succeeded"
    }
  ]
}
Можна побачити, що результати відповідають наведеному вище, що також реалізує функцію генерації відео заданого розміру.

​
Асинхронний зворотний виклик

Оскільки час генерації API Veo Videos Generation відносно тривалий, приблизно 1-2 хвилини, якщо API довго не відповідає, HTTP запит буде постійно підтримувати з’єднання, що призведе до додаткових витрат системних ресурсів, тому цей API також надає підтримку асинхронних зворотних викликів. Загальний процес такий: коли клієнт ініціює запит, додатково вказується поле callback_url, після ініціації API запиту, API відразу поверне результат, що містить інформацію про поле task_id, яке представляє поточний ID завдання. Коли завдання завершено, результат генерації відео буде надіслано на вказаний клієнтом callback_url у форматі POST JSON, в якому також міститься поле task_id, таким чином результати завдання можна пов’язати за ID. Далі ми розглянемо приклад, щоб зрозуміти, як саме це працює. По-перше, Webhook зворотний виклик - це сервіс, який може приймати HTTP запити, розробники повинні замінити його на URL свого власного HTTP сервера. Для зручності демонстрації використовується публічний веб-сайт з прикладом Webhook https://webhook.site/, відкривши цей сайт, ви отримаєте URL Webhook, як показано на малюнку: Скопіюйте цей URL, і ви зможете використовувати його як Webhook, приклад тут - https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc. Далі ми можемо налаштувати поле callback_url на вказаний вище URL Webhook, одночасно заповнивши відповідні параметри, конкретний зміст, як показано на малюнку:

Натиснувши “Запустити”, можна помітити, що відразу отримано результат, як показано нижче: 
{
  "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"
}
Почекавши деякий час, ми можемо спостерігати результати генерації відео на https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc, як показано на малюнку: Зміст такий: 
{
  "success": true,
  "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
  "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
  "data": [
    {
      "id": "2f43ceed37944b4d836e1a1899dad0a1",
      "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
      "created_at": "2025-07-25 17:19:20",
      "complete_at": "2025-07-25 17:21:45",
      "state": "succeeded"
    }
  ]
}
Можна побачити, що в результаті є поле task_id, інші поля схожі на наведені вище, за допомогою цього поля можна реалізувати зв’язок завдань.

​
Обробка помилок

При виклику API, якщо виникає помилка, API поверне відповідний код помилки та інформацію. Наприклад:
  • 400 token_mismatched: Неправильний запит, можливо, через відсутні або недійсні параметри.
  • 400 api_not_implemented: Неправильний запит, можливо, через відсутні або недійсні параметри.
  • 401 invalid_token: Неавторизовано, недійсний або відсутній токен авторизації.
  • 429 too_many_requests: Занадто багато запитів, ви перевищили ліміт запитів.
  • 500 api_error: Внутрішня помилка сервера, щось пішло не так на сервері.

​
Приклад відповіді з помилкою

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Висновок

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