> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Інструкція з інтеграції API генерації відео SeeDance > ByteDance Seedance Video Generation 集成指南 - XHuoAPI У цьому документі буде представлено інструкцію з інтеграції API генерації відео SeeDance, який дозволяє генерувати офіційні відео SeeDance за допомогою введення користувацьких параметрів. ## Процес подачі заявки Щоб використовувати API, спочатку потрібно перейти на сторінку [API генерації відео SeeDance](https://api.xhuoapi.ai/documents/seedance-videos) для подачі заявки на відповідну послугу. Після переходу на сторінку натисніть кнопку «Acquire», як показано на малюнку: ![](https://cdn.xhuoapi.ai/q6ytrc.png) Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід. Після входу або реєстрації ви будете автоматично повернені на поточну сторінку. При першій подачі заявки вам буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей 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», щоб провести тестування, як показано на малюнку, і ми отримали наступний результат: ```json theme={null} { "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.xhuoapi.ai/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 виглядає так: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/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` (старий спосіб, слабка перевірка, при помилці автоматично використовуються значення за замовчуванням). Повний список параметрів наведено нижче: | Внутрішній параметр | Відповідне поле | Опис | Діапазон значень | | ------------------- | ----------------- | --------------------------- | ------------------------------------------------------------- | | `--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` | > **Рекомендована практика**: безпосередньо використовувати відповідні верхні поля в тілі запиту (такі як `resolution`, `ratio` тощо) для режиму сильної перевірки, при помилці заповнення параметрів буде повернуто чітке повідомлення про помилку, що полегшує виявлення проблем. ## Генерація відео з аудіо `doubao-seedance-1-5-pro-251215` підтримує генерацію відео з аудіо за допомогою параметра `generate_audio`: ```json theme={null} { "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. Відповідний код: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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.xhuoapi.ai/v1/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.xhuoapi.ai/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` для зв'язку. ```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.xhuoapi.ai/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, вводячи підказки та посилання на зображення для створення відео. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.