Інструкція з інтеграції SeeDance Videos Generation API

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

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

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

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

📘 Повна документація: SeeDance Videos Generation API →

Базове використання

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

Тут можна побачити, що ми налаштували Request Headers, зокрема:

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

Також налаштовано Request Body, зокрема:

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, а після завершення завдання надсилає результат методом POST на цю адресу.
async: необов’язково; якщо встановити true, інтерфейс негайно повертає task_id, не потрібно надавати callback_url, після чого результат отримується шляхом опитування через відповідний інтерфейс запиту завдань.

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

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

{
  "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://cdn.acedata.cloud/assets/examples/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152-102bf9f98e35.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":"A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."}],
  "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`	Кількість кадрів відео	Ціле число в межах [29, 289], що задовольняє 25+4n (підтримується лише серією 1.0)
`--fps`	`framespersecond`	Частота кадрів	Підтримується лише `24`
`--seed`	`seed`	Випадкове зерно	Від -1 до 4294967295
`--cf`	`camerafixed`	Чи фіксувати камеру	`true` / `false`
`--wm`	`watermark`	Чи додавати водяний знак	`true` / `false`

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

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

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

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "A girl holds a fox, the wind blows her hair, you can hear the sound of the wind"
    }
  ],
  "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": "Replace the sky with a warm sunset while preserving the subject and camera motion."},
    {"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": "A girl holds a fox in her arms. She opens her eyes and gazes tenderly at the camera, while the fox affectionately holds her back. As the camera slowly pulls away, her hair is gently blown by the wind. --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-degree shot"
        },
        {
            "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.
Максимальна кількість мультимодальних посилань: до 9 image_url; 2.0 також підтримує audio_url (role — reference_audio, до 3 записів) і video_url (role — 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": "The woman looks at the camera, gives a warm natural smile and waves her hand, soft studio lighting, gentle camera push-in."
        },
        {
            "type": "image_url",
            "role": "reference_image",
            "image_url": {
                "url": "https://cdn.acedata.cloud/assets/examples/nanobanana/8e075897-0f50-4443-8500-666751791c6c-4346f66287c0.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://cdn.acedata.cloud/assets/examples/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf-a56b2736a4e0.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": "The same woman wearing a beige coat walks through a sunny autumn park, golden leaves falling around her, she smiles softly at the camera, cinematic tracking shot."
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://cdn.acedata.cloud/assets/examples/nanobanana/8e075897-0f50-4443-8500-666751791c6c-4346f66287c0.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://cdn.acedata.cloud/assets/examples/seedance/44f47593-556b-4fda-afa5-7a71eefcd228-2161efa5dd09.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5
  }
}

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

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

Оскільки API генерації відео SeeDance має тривалий час генерації (приблизно 1–2 хвилини), можна використовувати асинхронний режим через поле callback_url, щоб уникнути тривалого утримання HTTP-з’єднання. Загальний процес: клієнт зазначає callback_url під час надсилання запиту, API негайно повертає відповідь, що містить task_id; після завершення завдання платформа надсилає результат генерації на callback_url у вигляді POST JSON, і результат також містить 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"
}

Висновок

За допомогою цього документа ви вже дізналися, як використовувати Seedance Videos Generation API для генерації відео з тексту, генерації з початковим і кінцевим кадрами та мультимодальними референсами, а також як використовувати Seedance 2.5 для редагування або подовження відео. Сподіваємося, цей документ допоможе вам завершити інтеграцію API; якщо виникнуть запитання, зверніться до технічної підтримки.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

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

Coding

Інші посібники

Інструкція з інтеграції SeeDance Videos Generation API

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

Базове використання

Опис вбудованих параметрів

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

Повномодальна генерація, редагування та продовження Seedance 2.5

Перший кадр відео із зображення

Перший і останній кадри відео із зображення

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

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

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

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

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

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

Висновок

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

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

​Опис вбудованих параметрів

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

​Повномодальна генерація, редагування та продовження Seedance 2.5

​Перший кадр відео із зображення

​Перший і останній кадри відео із зображення

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

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

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

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

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

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

​Висновок

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

Базове використання

Опис вбудованих параметрів

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

Повномодальна генерація, редагування та продовження Seedance 2.5

Перший кадр відео із зображення

Перший і останній кадри відео із зображення

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

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

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

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

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

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

Висновок