Перейти до основного вмісту
Цей документ представить інтеграційну інструкцію для Wan Videos Generation API, яка дозволяє генерувати офіційні відео Tongyi Wanxiang за допомогою введення користувацьких параметрів.

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

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

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

Спочатку потрібно ознайомитися з основними способами використання, а саме: введенням підказки prompt, дії action, посиланням на зображення першого кадру image_url та моделлю model, щоб отримати оброблений результат. Спочатку потрібно просто передати поле action, значення якого буде text2video. Воно містить дві дії: створення відео з тексту (text2video) та створення відео з зображення (image2video). Потім потрібно ввести модель model, наразі основними є моделі wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v, деталі наведені нижче:

Ми можемо бачити, що тут налаштовані заголовки запиту, включаючи:
  • accept: формат відповіді, який ви хочете отримати, тут вказано application/json, тобто формат JSON.
  • authorization: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.
Також налаштовано тіло запиту, яке включає:
  • model: модель для створення відео, основні з яких wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v.
  • action: дія для завдання створення відео, основні три дії: створення відео з тексту (text2video), створення відео з зображення (image2video). Для створення відео з тексту наразі підтримується лише модель wan2.6-t2v, для створення відео з зображення підтримуються моделі wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash.
  • image_url: при виборі дії створення відео з зображення image2video необхідно завантажити посилання на зображення першого кадру, наразі підтримуються моделі wan2.6-i2v, wan2.6-i2v-flash.
  • reference_video_urls: необов’язковий параметр для створення відео з зображення, що вказує на посилання на відео для генерації, наразі підтримується модель wan2.6-r2v.
  • size: вказує роздільну здатність створеного відео, формат ширина*висота. Значення за замовчуванням та доступні значення залежать від параметра моделі, детальні правила можна знайти в документації.
  • duration: тривалість створеного відео, підтримуються 5, 10, 15.
  • shot_type: необов’язковий параметр, що вказує тип кадру для створення відео, тобто чи складається відео з одного безперервного кадру чи з кількох змінних кадрів. Умови дії: діє лише коли “prompt_extend”: true. Пріоритет параметрів: shot_type > prompt. Наприклад, якщо shot_type встановлено на “single”, навіть якщо prompt містить “створити відео з кількома кадрами”, модель все одно виведе відео з одним кадром, детальні правила можна знайти в документації.
  • negative_prompt: необов’язковий параметр, зворотна підказка, що описує те, що не бажано бачити у відео, може обмежити вміст відео. Підтримує китайську та англійську мови, довжина не перевищує 500 символів, частина, що перевищує, буде автоматично обрізана. Приклад значень: низька роздільна здатність, помилка, найгірша якість, низька якість, дефекти, зайві пальці, погані пропорції тощо.
  • resolution: вказує рівень роздільної здатності створеного відео, використовується для налаштування чіткості відео (загальна кількість пікселів). Модель автоматично масштабує до близької загальної кількості пікселів відповідно до вибраного рівня роздільної здатності, співвідношення сторін відео намагатиметься зберегти таке ж, як у вхідного зображення img_url, більше пояснень дивіться в документації.
  • audio_url: URL аудіофайлу, модель використовуватиме це аудіо для створення відео. Спосіб використання дивіться в документації.
  • audio: чи генерувати відео з аудіо. Пріоритет параметрів: audio > audio_url. Коли audio=false, навіть якщо передано audio_url, вихід все ще буде беззвучним відео, і оплата буде розрахована як за беззвучне відео, значення за замовчуванням - true.
  • prompt_extend: чи включити розумне переписування prompt. При включенні використовується велика модель для розумного переписування введеного prompt. Для коротших prompt ефект генерації значно покращується, але це збільшує час виконання, значення за замовчуванням - true.
  • prompt: підказка.
  • callback_url: URL, на який потрібно повернути результати.
Після вибору ви можете побачити, що праворуч також згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Try», щоб провести тестування, як показано на малюнку, ми отримали наступний результат: 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
У повернутому результаті є кілька полів, описаних нижче:
  • success: статус завдання створення відео.
  • task_id: ID завдання створення відео.
  • video_url: посилання на відео, створене в рамках завдання.
  • state: статус завдання створення відео.
Ми отримали задовільну інформацію про відео, нам потрібно лише отримати створене відео Tongyi Wanxiang за посиланням video_url у результаті. Крім того, якщо ви хочете згенерувати відповідний код інтеграції, ви можете просто скопіювати його, наприклад, код CURL виглядає так: 
curl -X POST 'https://api.acedata.cloud/wan/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "wan2.6-t2v",
  "prompt": "Astronauts shuttle from space to volcano",
  "duration": 5
}'

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

Якщо ви хочете створити відео на основі референсного зображення або відео, ви можете встановити параметр action на image2video, а також ввести посилання на референсне зображення або відео. Далі вам потрібно заповнити наступні підказки для налаштування створення відео, щоб вказати такі дані:
  • model: модель для створення відео, основні моделі: wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v.
  • image_url: коли вибрано дію створення відео з зображення image2video, потрібно завантажити посилання на перше референсне зображення, наразі підтримуються лише моделі wan2.6-i2v, wan2.6-i2v-flash.
  • reference_video_urls: під час створення відео з зображення, опціонально, вказати посилання на референсне відео для створення, наразі підтримується лише модель wan2.6-r2v.
  • prompt: підказка.
Приклад заповнення:

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

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

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

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

payload = {
    "action": "image2video",
    "model": "wan2.6-i2v",
    "prompt": "Astronauts shuttle from space to volcano",
    "duration": 5,
    "image_url": "https://cdn.acedata.cloud/r9vsv9.png",
    "callback_url": "https://www.baidu.com/"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Клікнувши на виконання, ви можете побачити результат, як показано нижче: 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
Як видно, вміст результату збігається з наведеним вище, що реалізує функцію розширення відео.

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

Оскільки час генерації API Wan 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/, відкривши цей сайт, ви отримаєте Webhook URL, як показано на малюнку: Скопіюйте це URL, і ви зможете використовувати його як Webhook, приклад тут: https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Далі ми можемо встановити поле callback_url на вказаний Webhook URL, одночасно заповнивши відповідні параметри, конкретний вміст, як показано на малюнку:

Клікнувши на виконання, ви можете відразу отримати результат, як показано нижче: 
{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
Через деякий час ви можете спостерігати результати створення відео на https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, як показано на малюнку: Вміст такий: 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
Як видно, у результаті є поле 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 Wan Videos Generation для створення відео за допомогою введення підказок та першого референсного зображення. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої технічної підтримки.