> ## 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`; для `fast` / `mini` 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` | Количество кадров видео | Целые числа, удовлетворяющие 25+4n в диапазоне \[29, 289] |
| `--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": "Девочка держит лису, ветер развивает ее волосы, слышен звук ветра"
}
],
"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. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.