Перейти до основного вмісту
Цей документ представить інтеграційну інструкцію для Grok Videos Generation API, який може генерувати відео Grok Imagine (xAI) за допомогою текстових підказок, вхідних зображень та необов’язкових референсних зображень.

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

Щоб використовувати Grok Videos Generation API, спочатку перейдіть до консолі Ace Data Cloud для отримання вашого API Token, зберігайте його для подальшого використання. Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід, після чого ви будете автоматично повернені на цю сторінку. Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу. Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно протестувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс в консолі.
📘 Повна документація: Grok Videos Generation API →

Опис моделей

За допомогою model можна вибрати одну з наступних чотирьох публічних моделей. Їхні можливості та способи тарифікації наведено нижче:
  • grok-imagine-video-1.5-fast:reverse (за замовчуванням): підтримує генерацію відео з тексту (передається лише prompt) і генерацію відео із зображення (передається image_url), тривалість 6–30 секунд, тарифікація за тривалістю за рівнями; найдешевший варіант.
  • grok-imagine-video:reverse: підтримує генерацію відео з тексту та зображення, тривалість 1–15 секунд, тарифікація за секундами результату.
  • grok-imagine-video:official: підтримує генерацію відео з тексту та зображення, тривалість 1–15 секунд, тарифікація за секундами результату, вища якість зображення.
  • grok-imagine-video-1.5:official: підтримує лише генерацію відео із зображення, обов’язково потрібно передати image_url, тривалість 1–15 секунд, підтримує до 1080p, тарифікація за секундами результату.

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

Спочатку ознайомтеся з основним способом використання, введіть підказку prompt, модель model та інші параметри, щоб згенерувати відповідне відео. Ми налаштували заголовки запиту, включаючи:
  • accept: формат відповіді, який ви хочете отримати, тут вказано application/json, тобто формат JSON.
  • authorization: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.
Також налаштовано тіло запиту, включаючи:
  • prompt: текстова підказка, що описує вміст відео, яке потрібно згенерувати. Обов’язково для відео, згенерованого з тексту; необов’язково при передачі image_url.
  • model: модель для генерації відео, можна вибрати grok-imagine-video-1.5-fast:reverse (за замовчуванням), grok-imagine-video:reverse, grok-imagine-video:official або grok-imagine-video-1.5:official.
  • image_url: посилання на вхідне зображення для відео, згенерованого з зображення. Обов’язково, коли model є grok-imagine-video-1.5:official.
  • reference_image_urls: масив необов’язкових посилань на референсні зображення, які використовуються для направлення стилю або вмісту відео.
  • aspect_ratio: співвідношення сторін для згенерованого відео, можна вибрати 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3.
  • resolution: вихідна роздільна здатність, можна вибрати 480p (за замовчуванням), 720p або 1080p.
  • duration: тривалість згенерованого відео (секунди). grok-imagine-video-1.5-fast:reverse має діапазон 6–30, інші моделі - 1–15, за замовчуванням 6. Рекомендується використовувати 6 секунд або 10 секунд, ці два стандартні часи є відносно стабільними.
  • callback_url: адреса асинхронного зворотного виклику, після налаштування API негайно поверне task_id, а після завершення завдання результат буде надіслано на цю адресу.
  • async: необов’язково, якщо встановити в true, інтерфейс негайно поверне task_id, не потрібно надавати callback_url, потім через відповідний інтерфейс запиту завдань можна опитувати для отримання результатів.
Натисніть кнопку «Спробувати», щоб протестувати, отримані результати будуть схожі на такі:
У відповіді є кілька полів, описаних нижче:
  • success: чи була успішною запит на генерацію відео.
  • task_id: ID завдання на генерацію відео.
  • trace_id: ID відстеження запиту, використовується для усунення неполадок.
  • data: список результатів згенерованого відео.
    • id: унікальний ідентифікатор згенерованого відео.
    • video_url: адреса посилання на згенероване відео.
    • state: стан завдання на генерацію відео, можливі значення pending / succeeded / failed.
Нам потрібно лише отримати згенероване відео за адресою video_url з результату data. Відповідний код CURL виглядає так:
Відповідний код Python виглядає так:

Відео, згенероване з зображення

Якщо ви хочете згенерувати відео на основі вхідного зображення, ви можете передати image_url. При використанні grok-imagine-video-1.5:official це поле обов’язкове:

Направлення за допомогою референсних зображень

Якщо ви хочете використовувати одне або кілька референсних зображень для направлення стилю або вмісту відео, ви можете передати масив посилань на зображення в reference_image_urls:

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

Відео генерація потребує певного часу обробки. Якщо ви не хочете підтримувати довге з’єднання в очікуванні, ви можете передати callback_url, у цьому випадку API негайно поверне task_id, а після завершення завдання надішле остаточний результат на цю адресу:
Негайно повернуті результати виглядають так:

Запит результатів завдання

Якщо ви використовували асинхронний зворотний виклик або хочете активно перевірити статус завдання, ви можете через Grok Tasks API (POST https://api.acedata.cloud/grok/tasks) за task_id перевірити останній статус та результати завдання.

Опис тарифікації

Спосіб тарифікації цієї послуги визначається параметром model:
  • grok-imagine-video-1.5-fast:reverse: тарифікація за тривалістю за рівнями, незалежно від роздільної здатності — для 6–10 секунд, 11–20 секунд і 21–30 секунд діють різні цінові рівні.
  • grok-imagine-video:reverse: тарифікація за «секундами результату», загальна вартість = ціна за одиницю × duration.
  • grok-imagine-video:official і grok-imagine-video-1.5:official: тарифікація за «секундами результату»; що вища роздільна здатність, то вища ціна за одиницю. За офіційні моделі стягується плата навіть у разі невдалого проходження модерації вмісту.
Актуальні ціни дивіться на сторінці тарифів. За невдалі запити плата не стягується, і вони не витрачають безкоштовну квоту.

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

Коли запит має проблеми, API поверне відповідний код помилки та опис, найбільш поширені з них:
  • 400: параметри запиту некоректні, наприклад, у відео без тексту відсутній prompt, або grok-imagine-video-1.5:official без image_url, або duration виходить за межі (для grok-imagine-video-1.5-fast:reverse 6–30, для інших моделей 1–15).
  • 401: невдала аутентифікація, токен недійсний або не відповідає API.
  • 403: недостатньо коштів, або підказка потрапила під перевірку контенту і була відхилена.
  • 429: запити занадто часті, будь ласка, спробуйте пізніше.
  • 500: невдала генерація відео або аномалія в сервісі.