Інструкція з інтеграції API генерації відео SeeDance

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

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

Щоб використовувати API генерації відео SeeDance, спочатку перейдіть до консолі Ace Data Cloud, щоб отримати ваш API Token, зберігши його для подальшого використання.

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

📘 Повна документація: API генерації відео SeeDance →

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

Спочатку розглянемо основний спосіб використання, а саме введення підказки content.text, типу content.type=text та моделі model, щоб отримати оброблений результат. Конкретний зміст наведено нижче:

Ми бачимо, що тут налаштовані заголовки запиту, включаючи:

accept: формат відповіді, який ви хочете отримати, тут вказано application/json, тобто формат JSON.
authorization: ключ для виклику API, який можна вибрати з випадаючого списку після подачі заявки.

Також налаштовано тіло запиту, яке включає:

model: модель для генерації відео.
- Серія Seedance 1.x: doubao-seedance-1-0-pro-250528, doubao-seedance-1-0-pro-fast-251015, doubao-seedance-1-5-pro-251215, doubao-seedance-1-0-lite-t2v-250428, doubao-seedance-1-0-lite-i2v-250428.
- Серія Seedance 2.0 (підтримує багатофункціональні посилання на персонажів та аудіо/відео): doubao-seedance-2-0-260128 (стандарт), doubao-seedance-2-0-fast-260128 (швидкий), doubao-seedance-2-0-mini-260615 (легкий).
- Seedance 2.5: doubao-seedance-2-5-260628, підтримує тривалість до 30 секунд, чисті аудіо посилання, більше матеріалів, редагування відео та продовження.
content: масив вхідного контенту, type може бути text (підказка), image_url (посилання на зображення), audio_url (посилання на аудіо), video_url (посилання на відео). Зображення можна вказати за допомогою role: first_frame (перша рамка) / last_frame (остання рамка) / reference_image (посилання на персонажа / об’єкт).
resolution: вихідна роздільна здатність, доступні варіанти 480p / 720p / 1080p / 4k. 2.5 підтримує 480p, 720p, 1080p; 2.0 Fast/Mini підтримує 480p, 720p; 2.0 Standard підтримує до 4k.
ratio: співвідношення сторін, доступні варіанти 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
duration: тривалість відео (секунди, ціле число). Серія 1.0 2–12; 1.5 Pro 4–12; серія 2.0 4–15; 2.5 4–30. 1.5/2.x підтримує -1 (автоматична тривалість).
seed: випадкове насіння, ціле число, від -1 до 4294967295.
camerafixed: чи фіксувати камеру, true / false.
watermark: чи додавати водяний знак, true / false.
generate_audio: чи генерувати відео з аудіо, true / false, підтримується Seedance 1.5 Pro та серією 2.x.
return_last_frame: чи повертати URL останньої рамки відео в результатах.
omni_reference_task_type: тільки 2.5; auto / reference / edit / extend.
output_format: тільки 2.5; mp4 / mov, за замовчуванням mp4.
tools: тільки 2.5; наразі підтримується web_search для онлайн-пошуку, можна обмежити кількість результатів, кількість ключових слів та джерела пошуку.
priority: 2.5 доступний пріоритет завдання, ціле число 0–9, за замовчуванням 0.
safety_identifier: стабільний анонімний ідентифікатор кінцевого користувача довжиною до 64 символів; використовуйте хеш або внутрішній анонімний ID, не передавайте ім’я, електронну пошту або номер телефону.
execution_expires_after: час тайм-ауту завдання (секунди), діапазон 3600–259200.
callback_url: адреса асинхронного зворотного виклику, після налаштування API негайно повертає task_id, а результати будуть надіслані на цю адресу після завершення завдання.
async: необов’язковий, якщо встановити true, інтерфейс негайно повертає task_id, не потрібно надавати callback_url, потім результати можна отримати через відповідний інтерфейс запиту завдань.

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

Натисніть кнопку «Спробувати», щоб провести тестування, як показано на малюнку, ми отримали наступний результат:

{
  "success": true,
  "task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8",
  "trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752",
  "data": {
    "task_id": "7e4e1773-510a-4a73-9ab4-98dd1a0b2a7f",
    "status": "succeeded",
    "model": "doubao-seedance-2-0-fast-260128",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152.mp4"
  }
}

У повернутому результаті є кілька полів, описаних нижче:

success, статус завдання генерації відео на даний момент.
task_id, ID завдання генерації відео на даний момент.
trace_id, ID відстеження генерації відео на даний момент.
data, список результатів завдання генерації відео на даний момент.
- task_id, ID завдання генерації відео на сервері на даний момент.
- video_url, посилання на відео завдання генерації відео на даний момент.
- status, статус завдання генерації відео на даний момент.
  - model, модель, що використовується для генерації відео.

Ми отримали задовільну інформацію про відео, і нам потрібно лише отримати згенероване відео SeeDance за посиланням на відео в data результату. Крім того, якщо ви хочете згенерувати відповідний код інтеграції, ви можете просто скопіювати його, наприклад, код CURL виглядає так:

curl -X POST 'https://api.acedata.cloud/seedance/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "content": [{"type":"text","text":"Біла керамічна чашка для кави на глянцевій мармуровій стільниці з м'яким ранковим світлом з вікна. Камера повільно обертається на 360 градусів навколо чашки, пар ніжно піднімається."}],
  "model": "doubao-seedance-2-0-fast-260128",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}'

Опис параметрів

У content[].text в кінці підказки можна передати параметри генерації у формі --parameter value (старий спосіб, слабка перевірка, при помилці автоматично використовується значення за замовчуванням). Повний список параметрів наведено нижче:

Внутрішній параметр	Відповідне поле	Опис	Діапазон значень
`--rs`	`resolution`	Роздільна здатність виходу	`480p` / `720p` / `1080p`
`--rt`	`ratio`	Співвідношення сторін	`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`
`--dur`	`duration`	Тривалість відео (секунди)	2–12
`--frames`	`frames`	Кількість кадрів відео	Цілі числа, що задовольняють 25+4n з [29, 289] ( тільки 1.0 серія підтримує )
`--fps`	`framespersecond`	Частота кадрів	Підтримується лише `24`
`--seed`	`seed`	Випадкове насіння	-1 до 4294967295
`--cf`	`camerafixed`	Чи фіксувати камеру	`true` / `false`
`--wm`	`watermark`	Чи додавати водяний знак	`true` / `false`

Рекомендована практика: безпосередньо використовувати відповідні верхні поля (такі як resolution, ratio тощо) у тілі запиту для режиму сильної перевірки, при помилці параметрів буде повернуто чітке повідомлення про помилку, що полегшує виявлення проблем.

Генерація відео з аудіо

Seedance 1.5 Pro та 2.x серії підтримують генерацію відео з аудіо через параметр generate_audio:

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "Дівчина тримає лисицю, вітер розвіває її волосся, ви можете почути звук вітру"
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 5
}

Серія 1.0 не підтримує цей параметр.

Seedance 2.5 Генерація, редагування та продовження в усіх режимах

doubao-seedance-2-5-260628 підтримує 480p / 720p / 1080p, 4–30 секунд або автоматичну тривалість, а також підвищує максимальну кількість матеріалів до 30 зображень, 10 відео та 10 аудіо (всього не більше 50). 2.5 також підтримує передачу лише аудіо, без вимоги одночасної передачі зображень або відео. Звичайна генерація в усіх режимах може пропустити omni_reference_task_type, встановивши його на auto, або явно встановити на reference. Для редагування та продовження відео необхідно передати reference_video:

{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {"type": "text", "text": "Замініть небо на теплий захід сонця, зберігаючи об'єкт і рух камери."},
    {"type": "video_url", "role": "reference_video", "video_url": {"url": "https://cdn.acedata.cloud/input.mp4"}}
  ],
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "output_format": "mov"
}

reference: необхідно передати принаймні одне reference_image, reference_video або reference_audio; 2.5 підтримує лише передачу аудіо.
edit: необхідно використовувати ratio: adaptive та duration: -1; тривалість виходу розраховується за фактичним результатом.
extend: необхідно використовувати ratio: adaptive; duration може бути 4–30 або -1.
auto: модель автоматично вибирає генерацію, редагування або продовження на основі підказок і матеріалів.
Якщо тип завдання не відповідає матеріалам або підказкам, завдання зазнає невдачі та поверне помилку параметра, яку можна локалізувати; будь ласка, відкоригуйте відповідно до наведених вище обмежень і повторно надішліть.

Генерація відео з першого кадру

Якщо ви хочете згенерувати відео, спочатку параметр content повинен містити елемент з type, що дорівнює image_url, поле image_url повинно бути у форматі об’єкта: {"url": "https://..."} або у форматі Base64 {"url": "data:image/png;base64,..."}.

Примітка: image_url не підтримує пряме введення у форматі рядка (наприклад, "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"), обов’язково використовуйте об’єктний формат "image_url": {"url": "https://..."}, інакше буде повернено помилку 400.

Відповідний код:

import requests

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

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

payload = {
    "content": [
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
            }
        },
        {
            "type": "text",
            "text": "Дівчина тримає лисицю на руках. Вона відкриває очі і ніжно дивиться в камеру, в той час як лисиця ласкаво тримає її у відповідь. Коли камера повільно віддаляється, її волосся ніжно розвівається вітром. --ratio adaptive  --dur 5"
        }
    ],
    "model": "doubao-seedance-1-0-pro-250528"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Клікнувши на виконання, ви можете відразу отримати результат, як показано нижче:

{
  "success": true,
  "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
  "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4",
  "data": {
    "task_id": "cgt-20251222072003-x2259",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}

Можна побачити, що згенерований ефект є відео, створеним на основі зображення, результат схожий на вищезазначений.

Генерація відео з перших і останніх кадрів

Якщо ви хочете згенерувати відео з перших і останніх кадрів, спочатку параметр content повинен містити тип image_url, і відповідно потрібно встановити role на first_frame та last_frame, щоб вказати наступний вміст:

role: вказує на перший або останній кадр.
image_url
- url посилання на зображення Одночасно content також потрібно ввести тип text як підказку.

Відповідний код:

import requests

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

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

payload = {
   "model": "doubao-seedance-1-0-pro-250528",
    "content": [
         {
            "type": "text",
            "text": "360-градусний знімок"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
            },
            "role": "first_frame"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
            },
            "role": "last_frame"
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Натисніть “Запустити”, і ви відразу отримаєте результат, як показано нижче:

{
  "success": true,
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
  "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
  "data": {
    "task_id": "cgt-20251222073134-54qcw",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}

Можна побачити, що згенерований ефект - це відео з персонажем, результат схожий на вищезазначене.

Персонажі та мультимедійні посилання (Seedance 2.0)

Seedance 2.0 серія (doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-0-mini-260615) підтримує reference_image, reference_audio та reference_video. Можна використовувати власні або ліцензовані матеріали для збереження узгодженості персонажа, об’єкта, дій, руху камери, звуку та ритму.

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

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

Лише Seedance 2.0 серія моделей підтримує reference_image; моделі 1.x слід використовувати first_frame / last_frame (перші та останні кадри відео).
Перший кадр відео, перший та останній кадри відео та повномасштабні посилання - це три взаємовиключні сценарії: first_frame / last_frame не можна змішувати з reference_image / reference_video / reference_audio.
Якщо ви хочете вказати перші та останні кадри в повномасштабних посиланнях, позначте зображення як reference_image і вкажіть у підказці “зображення 1 як перший кадр” або “зображення 2 як останній кадр”; якщо потрібно строго зафіксувати перші та останні кадри, використовуйте лише first_frame / last_frame.
Максимальна кількість мультимедійних посилань: image_url максимум 9 зображень; 2.0 також підтримує audio_url (роль reference_audio, максимум 3 записи) та video_url (роль reference_video, максимум 3 записи).
Вимоги до матеріалів для аудіо посилань (audio_url): формати wav / mp3; тривалість однієї записи 2~15 секунд, максимум 3 записи та загальна тривалість не більше 15 секунд; одна запис не більше 15 МБ. Перевищення тривалості призведе до невдачі на етапі обробки матеріалів.
Вимоги до матеріалів для відео посилань (video_url): формати mp4 / mov; тривалість однієї записи 2~15 секунд, максимум 3 записи та загальна тривалість не більше 15 секунд.
Рекомендується використовувати одиночні, фронтальні, чіткі, без перешкод фотографії для посилань, чим чіткіше обличчя, тим вища схожість.

Приклад 1: збереження зовнішності персонажа

Передайте фотографію обличчя, щоб персонаж дивився в камеру, усміхався та махав рукою. Відповідний код:

import requests

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

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

payload = {
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
        {
            "type": "text",
            "text": "Жінка дивиться в камеру, дає теплу природну усмішку і махає рукою, м'яке студійне освітлення, ніжний рух камери вперед."
        },
        {
            "type": "image_url",
            "role": "reference_image",
            "image_url": {
                "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
            }
        }
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Повернений результат виглядає так, персонаж у згенерованому відео зберігає схожість з референсним зображенням:

{
  "success": true,
  "task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a",
  "trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4",
  "data": {
    "task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
  }
}

Приклад 2: помістіть ту ж саму людину в нову сцену

Сила reference_image полягає в тому, що вона зберігає лише ідентичність персонажа, тоді як сцена, одяг, дії повністю визначаються підказкою. Нижче використовується те ж саме зображення обличчя, щоб персонаж у бежевому пальто йшов парком восени:

{
  "model": "doubao-seedance-2-0-fast-260128",
  "content": [
    {
      "type": "text",
      "text": "Та сама жінка в бежевому пальто йде через сонячний осінній парк, золоті листя падають навколо неї, вона м'яко усміхається в камеру, кінематографічний слід."
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

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

{
  "success": true,
  "task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157",
  "trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614",
  "data": {
    "task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5
  }
}

💡 Якщо ви хочете, щоб персонажі точно відтворювали композицію на фотографії (а не «іншу сцену з тією ж людиною»), ви можете використовувати first_frame (перша рамка відео), щоб відео починалося з цього зображення.

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

Оскільки час генерації API SeeDance Videos Generation є досить тривалим (приблизно 1-2 хвилини), ви можете використовувати асинхронний режим через поле callback_url, щоб уникнути тривалого зайняття HTTP-з’єднання. Загальний процес: клієнт ініціює запит, вказуючи callback_url, API негайно повертає відповідь, що містить task_id; після завершення завдання платформа надсилає результати у форматі POST JSON на callback_url, результати також містять task_id для зв’язку.

{
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}

Коли завдання завершено, вміст, що надсилається на callback_url, виглядає наступним чином:

{
  "success": true,
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
  "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
  "data": {
    "task_id": "cgt-20251222073134-54qcw",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}

Поле 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 Seedance Videos Generation для генерації відео з тексту, початкових і кінцевих кадрів та мультимодальних посилань, а також як використовувати Seedance 2.5 для редагування або подовження відео. Сподіваємося, цей документ допоможе вам завершити інтеграцію API; якщо у вас є питання, будь ласка, зверніться до технічної підтримки.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

Coding

Інструкція з інтеграції API генерації відео SeeDance

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

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

Опис параметрів

Генерація відео з аудіо

Seedance 2.5 Генерація, редагування та продовження в усіх режимах

Генерація відео з першого кадру

Генерація відео з перших і останніх кадрів

Персонажі та мультимедійні посилання (Seedance 2.0)

Приклад 1: збереження зовнішності персонажа

Приклад 2: помістіть ту ж саму людину в нову сцену

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

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

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

Висновок

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

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

​Опис параметрів

​Генерація відео з аудіо

​Seedance 2.5 Генерація, редагування та продовження в усіх режимах

​Генерація відео з першого кадру

​Генерація відео з перших і останніх кадрів

​Персонажі та мультимедійні посилання (Seedance 2.0)

​Приклад 1: збереження зовнішності персонажа

​Приклад 2: помістіть ту ж саму людину в нову сцену

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

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

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

​Висновок

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

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

Опис параметрів

Генерація відео з аудіо

Seedance 2.5 Генерація, редагування та продовження в усіх режимах

Генерація відео з першого кадру

Генерація відео з перших і останніх кадрів

Персонажі та мультимедійні посилання (Seedance 2.0)

Приклад 1: збереження зовнішності персонажа

Приклад 2: помістіть ту ж саму людину в нову сцену

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

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

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

Висновок