Інструкція з інтеграції 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.0)».
content: масив вхідного контенту, type може бути text (підказка), image_url (посилальна картинка), audio_url (посилання на аудіо, 2.0), video_url (посилання на відео, 2.0). Зображення можна вказати за допомогою role: first_frame (перша рамка) / last_frame (остання рамка) / reference_image (посилання на обличчя / персонаж / об’єкт).
resolution: вихідна роздільна здатність, доступні варіанти 480p / 720p / 1080p (стандартна модель 2.0 також підтримує 4k; швидка / міні версії 2.0 підтримують максимум 720p).
ratio: співвідношення сторін, доступні варіанти 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
duration: тривалість відео (секунди), для 1.x в межах 2–12, для 2.0 в межах 2–15.
seed: випадкове насіння, ціле число, від -1 до 4294967295.
camerafixed: чи фіксувати камеру, true / false.
watermark: чи додавати водяний знак, true / false.
generate_audio: чи генерувати відео з аудіо, true / false, тільки doubao-seedance-1-5-pro-251215 підтримується.
return_last_frame: чи повертати URL останньої рамки відео в результатах.
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":"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
`--fps`	`framespersecond`	Частота кадрів	Підтримується лише `24`
`--seed`	`seed`	Випадкове насіння	-1 до 4294967295
`--cf`	`camerafixed`	Чи фіксувати камеру	`true` / `false`
`--wm`	`watermark`	Чи додати водяний знак	`true` / `false`

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

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

doubao-seedance-1-5-pro-251215 підтримує генерацію відео з аудіо через параметр generate_audio:

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

Інші моделі не підтримують цей параметр, передача його буде проігнорована.

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

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

Увага: image_url не підтримує пряме передавання у форматі рядка (наприклад, "image_url": "https://..."), обов’язково використовуйте формат об’єкта "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) підтримує передачу «реальних / персонажних» референсних матеріалів: додайте в content елемент з type рівним image_url, role рівним reference_image, щоб використовувати фотографії людей як референс, модель буде зберігати риси обличчя цієї особи у згенерованому відео, таким чином «поміщаючи» ту ж людину в абсолютно нові сцени, дії або кадри.

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

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

Лише Seedance 2.0 серії моделі підтримують reference_image; моделі 1.x будь ласка, використовуйте first_frame / last_frame (перша та остання рамка відео).
reference_image не може використовуватися разом з first_frame / last_frame, обирайте один з варіантів.
Максимальна кількість мультимедійних посилань: image_url не більше 9 зображень; 2.0 також підтримує audio_url (роль reference_audio, максимум 3 записи) та video_url (роль reference_video, максимум 3 записи).
Рекомендується використовувати одиночні, фронтальні, чіткі, без перешкод фотографії для посилань, чим чіткіше обличчя, тим вища схожість.

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

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

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

Проксі

Advanced

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

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

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

Опис параметрів в рядку

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

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

Генерація відео з зображення на першому та останньому кадрі

Обличчя та персонажі (Seedance 2.0)

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

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

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

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

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

Висновок

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

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

​Опис параметрів в рядку

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

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

​Генерація відео з зображення на першому та останньому кадрі

​Обличчя та персонажі (Seedance 2.0)

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

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

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

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

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

​Висновок

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

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

Опис параметрів в рядку

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

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

Генерація відео з зображення на першому та останньому кадрі

Обличчя та персонажі (Seedance 2.0)

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

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

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

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

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

Висновок