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

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

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

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

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

Ми бачимо, що тут налаштовані заголовки запиту, включаючи:
  • accept: формат відповіді, який ви хочете отримати, тут вказано application/json, тобто формат JSON.
  • authorization: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.
Крім того, налаштовано тіло запиту, яке включає:
  • model: модель для генерації відео, доступні значення: 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.
  • content: масив вхідного контенту, type може бути text або image_url.
  • resolution: вихідна роздільна здатність, доступні 480p / 720p / 1080p.
  • ratio: співвідношення сторін, доступні 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: тривалість відео (секунди), діапазон 2–12.
  • seed: випадкове насіння, ціле число, від -1 до 4294967295.
  • camerafixed: чи фіксувати камеру, true / false.
  • watermark: чи додавати водяний знак, true / false.
  • generate_audio: чи генерувати відео з аудіо, true / false, тільки doubao-seedance-1-5-pro-251215 підтримується.
  • service_tier: режим інференції, default (онлайн) або flex (офлайн, ціна 50% від онлайн).
  • return_last_frame: чи повертати URL останнього кадру відео в результатах.
  • execution_expires_after: час тайм-ауту завдання (секунди), діапазон 3600–259200.
  • callback_url: адреса асинхронного зворотного виклику, після налаштування API негайно повертає task_id, а при завершенні завдання результати будуть надіслані на цю адресу.
Після вибору ви також можете побачити згенерований код праворуч, як показано на малюнку:

Натисніть кнопку «Try», щоб провести тестування, як показано на малюнку, і ми отримали наступний результат: 
{
  "success": true,
  "task_id": "ec22ae22-0140-4033-8c86-a48b536da595",
  "trace_id": "1cc87db0-8ee5-4436-969b-35cc571a9fd5",
  "data": {
    "task_id": "cgt-20251222005129-62fhb",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/f592800a-b87c-4705-8796-cbb8018cae35.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}
У повернутому результаті є кілька полів, описаних нижче:
  • 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": [{"text":"A kitten yawning at the camera. --rs 720p --rt 16:9 --dur 5 --fps 24 --wm true --seed 11 --cf false","type":"text"}],
  "model": "doubao-seedance-1-0-pro-250528"
}'

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

У кінці підказки content[].text ви можете передати параметри генерації у формі --parameter value (старий спосіб, слабка перевірка, при помилці автоматично використовуються значення за замовчуванням). Повний список параметрів наведено нижче:
Внутрішній параметрВідповідне полеОписДіапазон значень
--rsresolutionВихідна роздільна здатність480p / 720p / 1080p
--rtratioСпіввідношення сторін16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive
--durdurationТривалість відео (секунди)2–12
--framesframesКількість кадрів відео[29, 289] з цілими числами, що задовольняють 25+4n
--fpsframespersecondЧастота кадрівПідтримується лише 24
--seedseedВипадкове насіння-1 до 4294967295
--cfcamerafixedЧи фіксувати камеруtrue / false
--wmwatermarkЧи додавати водяний знакtrue / false
Рекомендована практика: безпосередньо використовувати відповідні верхні поля в тілі запиту (такі як resolution, ratio тощо) для режиму сильної перевірки, при помилці заповнення параметрів буде повернуто чітке повідомлення про помилку, що полегшує виявлення проблем.

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

doubao-seedance-1-5-pro-251215 підтримує генерацію відео з аудіо за допомогою параметра 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
}
Інші моделі не підтримують цей параметр, переданий після буде проігноровано.

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

Якщо ви хочете виконати завдання генерації відео з зображення, спочатку параметр 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"
    }
}
Можна побачити, що згенерований ефект є відео, створеним з персонажами, результат схожий на вищезазначений.

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

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