> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Інструкція з інтеграції API генерації відео SeeDance
> ByteDance Seedance Video Generation API guide - Ace Data Cloud
У цьому документі буде представлено інструкцію з інтеграції API генерації відео SeeDance, який дозволяє генерувати офіційні відео SeeDance за допомогою введення користувацьких параметрів.
## Процес подачі заявки
Щоб використовувати API генерації відео SeeDance, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications), щоб отримати ваш API Token, зберігши його для подальшого використання.
Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, де ви зможете зареєструватися та увійти. Після завершення ви будете автоматично повернені на цю сторінку.
**Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу.** Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно протестувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс на [консолі](https://platform.acedata.cloud/console/coin).
> 📘 Повна документація: [API генерації відео SeeDance →](https://platform.acedata.cloud/documents/seedance-videos)
## Основне використання
Спочатку розглянемо основний спосіб використання, а саме введення підказки `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`, потім через відповідний інтерфейс запиту завдань можна опитувати результати.
Після вибору ви можете помітити, що праворуч також згенеровано відповідний код, як показано на малюнку:
Натисніть кнопку «Спробувати», щоб провести тестування, як показано на малюнку, ми отримали наступний результат:
```json theme={null}
{
"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 виглядає так:
```shell theme={null}
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`:
```json theme={null}
{
"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.
Відповідний код:
```python theme={null}
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` як підказку.
Відповідний код:
```python theme={null}
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: Збереження зовнішності персонажа в крупному плані
Передайте фотографію обличчя, щоб персонаж усміхався та махав рукою в камеру. Відповідний код:
```python theme={null}
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)
```
Повернене значення виглядає так, персонаж у згенерованому відео відповідає фотографії:
```json theme={null}
{
"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` полягає в тому, що вона зберігає **особистість персонажа**, тоді як сцена, одяг, дії повністю визначаються підказками. Нижче використовується та ж сама фотографія обличчя, щоб персонаж у бежевому пальті йшов осіннім парком:
```json theme={null}
{
"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
}
```
Повернене значення виглядає так, зовнішність персонажа зберігається, а сцена змінюється на осінній парк:
```json theme={null}
{
"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` для зв'язування.
```json theme={null}
{
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}
```
Коли завдання завершено, вміст, надісланий на `callback_url`, виглядає так:
```json theme={null}
{
"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`: Внутрішня помилка сервера, щось пішло не так на сервері.
### Приклад відповіді з помилкою
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Висновок
Завдяки цьому документу ви дізналися, як використовувати API генерації відео SeeDance через підказки, зображення посилань, а також обличчя / персонажі Seedance 2.0 для створення відео. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої технічної підтримки.