Процес подання заявки
Щоб використовувати Gemini Videos Generation API, спочатку отримайте ваш API Token у консолі Ace Data Cloud і збережіть його для подальшого використання.
Якщо ви ще не увійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу із запрошенням зареєструватися та увійти, після завершення ви автоматично повернетеся на поточну сторінку.
Один API Token дозволяє викликати всі сервіси платформи, не потрібно подавати заявку окремо для кожного сервісу. Під час першого отримання надається безкоштовний ліміт, який можна використати для безкоштовного тестування; коли ліміту недостатньо, ви можете поповнити загальний баланс у консолі.
📘 Повна документація: Gemini Videos Generation API →
Базове використання
Спочатку розглянемо базовий спосіб використання: введіть підказкуprompt, модель model і співвідношення сторін aspect_ratio, після чого можна згенерувати відповідне відео.
Тут можна побачити, що ми налаштували Request Headers, зокрема:
accept: формат результату відповіді, який ви бажаєте отримати; тут вказаноapplication/json, тобто формат JSON.authorization: ключ для виклику API, після отримання його можна безпосередньо вибрати зі спадного списку.
prompt: текстова підказка, що описує вміст відео, яке потрібно згенерувати, обов’язково.model: модель для генерації відео, наразі підтримується лишеomni-flash, за замовчуванням такожomni-flash.aspect_ratio: співвідношення сторін згенерованого відео, доступні16:9(горизонтальне) або9:16(вертикальне), за замовчуванням16:9.resolution: необов’язкова вихідна роздільна здатність, доступні720pабо1080p, за замовчуванням720p.image_urls: необов’язковий масив посилань на референсні зображення, що використовується для спрямування генерації відео; порожні елементи буде проігноровано. Під час використанняvideo_urlsдля редагування відео цей параметр є обов’язковим (щонайменше одне зображення).video_urls: необов’язковий масив посилань на референсні відео (максимум 1), що використовується для редагування відео / відеореференсу; у разі надання потрібно одночасно надати щонайменше однеimage_urls.callback_url: адреса асинхронного зворотного виклику; після налаштування API негайно повернеtask_id, а після завершення завдання надішле результат POST-запитом на цю адресу.async: необов’язково, якщо встановленоtrue, інтерфейс негайно повернеtask_id, без необхідності надаватиcallback_url, після чого результат можна отримати шляхом опитування відповідного інтерфейсу запиту завдань.
success: чи був успішним цей запит на генерацію відео.task_id: ID цього завдання генерації відео.trace_id: ID відстеження цього запиту, що використовується для усунення проблем.data: список результатів згенерованих відео.id: унікальний ідентифікатор згенерованого відео.video_url: адреса посилання на згенероване відео (null, колиstateмає значенняpending).state: статус завдання генерації відео; можливі значенняpending/succeeded/failed.aspect_ratio: співвідношення сторін цього відео, узгоджене з параметрами запиту.prompt: підказка, використана для генерації цього відео.
started_at, finished_at, elapsed (витрачений час, секунди) та cost (вартість цього списання, в одиницях Credit) тощо.
Нам потрібно лише отримати згенероване відео за адресою посилання video_url у результаті data.
Відповідний код CURL такий:
Генерація відео із зображення
Якщо ви хочете генерувати відео на основі референсних зображень, ви можете передати одне або кілька посилань на зображення вimage_urls, щоб спрямувати генерацію відео:
Редагування відео / еталонне відео (вхідне відео, згенероване відео)
Підтримується безпосередній сценарій «ввести відео й згенерувати нове відео»: передайте посилання на еталонне відео (не більше 1) уvideo_urls і одночасно надайте принаймні одне еталонне зображення в image_urls, а потім опишіть бажаний ефект редагування (змінити стиль, замінити сцену, додати або видалити елементи тощо) за допомогою prompt.
Нижче наведено повний реальний приклад — перетворення відео сонячного пляжу на зимову сцену з рясним снігопадом зі збереженням розташування пляжу, пальм і човна. Редагування відео займає доволі багато часу (у цьому прикладі близько 6,5 хвилини), тому його асинхронно надсилають через async: true:
task_id:
task_id як id для опитування Gemini Tasks API. Після завершення завдання можна отримати згенероване нове відео (це фактичний результат, повернений у цьому прикладі):
resolution на 1080p (інші параметри залишаються без змін).
Підказка: посилання на вхідні/вихідні медіафайли в прикладах є реальними результатами генерації. Посилання на відео та зображення, згенеровані платформою, мають обмежений термін зберігання й після його закінчення стануть недійсними. Після отримання результату своєчасно завантажте та збережіть його у власному сховищі.
Увага: можна надати не більше 1 референсного відео; також у разі наданняvideo_urlsнеобхідно надати щонайменше одне зображенняimage_urls, інакше буде повернуто таку помилку параметрів:
Асинхронний зворотний виклик
Генерація відео потребує певного часу на обробку. Якщо ви не бажаєте підтримувати тривале з’єднання в очікуванні, можна передатиcallback_url. У такому разі API одразу поверне task_id, а після завершення завдання надішле остаточний результат методом POST на цю адресу:
Запит результату завдання
Якщо використано асинхронний зворотний виклик або ви бажаєте самостійно перевірити стан завдання, через Gemini Tasks API (POST https://api.acedata.cloud/gemini/tasks) можна запитати найновіший стан і результат завдання за task_id. У тілі запиту передайте task_id, повернений під час створення відео, як id:
response.data збігається зі структурою під час синхронної генерації (під час генерації state має значення pending, а video_url — null):
Обробка помилок
Якщо під час запиту виникає проблема, API повертає відповідний код помилки та опис. Нижче наведено поширені помилки:400: некоректні параметри запиту, наприклад відсутнійpromptабо значенняaspect_ratioє недійсним.401: помилка автентифікації — токен недійсний або не відповідає API.403: недостатньо коштів або запит відхилено через перевірку вмісту.500: помилка сервісу або збій генерації.

