# Seedance 2.5 API

Полный справочник API моделей генерации видео Seedance 2.5 от ByteDance.

## Варианты модели

API поддерживает три варианта модели:

| Модель | ID | Описание |
|-------|----|-------------|
| **Seedance 2.5 Text to Video** | `seedance-v2.5-text-to-video` | Высококачественная генерация видео по тексту |
| **Seedance 2.5 Image to Video** | `seedance-v2.5-image-to-video` | Генерация видео по первому кадру либо по первому и последнему кадрам |
| **Seedance 2.5 Reference to Video** | `seedance-v2.5-reference-to-video` | Генерация видео на основе референсных изображений, видео и аудио |

## Краткое сравнение

| Возможность | Текст в видео | Изображение в видео | Референсы в видео |
|---------|---------------|----------------|--------------------|
| Диапазон длительности | 4-30 секунд | 4-30 секунд | 4-30 секунд |
| Варианты разрешения | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| Соотношение сторон | Обязательно | Не поддерживается | Обязательно |
| Обязательные материалы | Нет | Изображение первого кадра | Нет |
| Необязательные материалы | Нет | Изображение последнего кадра | Изображения, видео и аудио |

### Поддерживаемые соотношения сторон

Текст в видео и Референсы в видео поддерживают:

`21:9`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`

Изображение в видео не поддерживает параметр `aspect_ratio`.

### Варианты разрешения

| Разрешение | Описание |
|------------|-------------|
| `480p` | Стандартная чёткость |
| `720p` | Высокая чёткость |
| `1080p` | Full HD |

## Seedance 2.5 Text to Video

### Конечная точка

```
POST /api/v1/video/task
```

### Параметры запроса

#### Обязательные

| Параметр | Тип | Описание |
|-----------|------|-------------|
| `model_name` | string | Должно быть `"seedance-v2.5-text-to-video"` |
| `prompt` | string | Промпт для генерации видео |
| `resolution` | string | Разрешение результата: `"480p"`, `"720p"` или `"1080p"` |
| `duration` | integer | Длительность видео в целых секундах (4-30), с шагом 1 |
| `aspect_ratio` | string | Соотношение сторон видео: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` или `"3:4"` |

#### Необязательные

| Параметр | Тип | Описание |
|-----------|------|-------------|
| `sound` | boolean | Нужно ли генерировать звук. По умолчанию `true` |

### Пример запроса

```javascript
const response = await fetch('https://api.flaq.ai/api/v1/video/task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model_name: 'seedance-v2.5-text-to-video',
    prompt: 'A golden retriever running through a sunlit meadow',
    resolution: '720p',
    duration: 8,
    aspect_ratio: '16:9',
    sound: true
  })
});

const { data } = await response.json();
const taskId = data.task_id;
```

## Seedance 2.5 Image to Video

### Параметры запроса

#### Обязательные

| Параметр | Тип | Описание |
|-----------|------|-------------|
| `model_name` | string | Должно быть `"seedance-v2.5-image-to-video"` |
| `prompt` | string | Промпт для генерации видео |
| `resolution` | string | Разрешение результата: `"480p"`, `"720p"` или `"1080p"` |
| `duration` | integer | Длительность видео в целых секундах (4-30), с шагом 1 |
| `image_url` | string | URL изображения первого кадра |

#### Необязательные

| Параметр | Тип | Описание |
|-----------|------|-------------|
| `image_end_url` | string | Необязательный URL изображения последнего кадра |
| `sound` | boolean | Нужно ли генерировать звук. По умолчанию `true` |

> Не включайте `aspect_ratio` в запросы Изображение в видео. Эта модель не поддерживает данный параметр.

### Пример запроса

```javascript
{
  model_name: 'seedance-v2.5-image-to-video',
  image_url: 'https://example.com/first-frame.jpg',
  image_end_url: 'https://example.com/last-frame.jpg',
  prompt: 'Camera slowly pulls back to reveal the full landscape',
  resolution: '720p',
  duration: 8,
  sound: true
}
```

## Seedance 2.5 Reference to Video

### Параметры запроса

#### Обязательные

| Параметр | Тип | Описание |
|-----------|------|-------------|
| `model_name` | string | Должно быть `"seedance-v2.5-reference-to-video"` |
| `prompt` | string | Промпт для генерации видео. Напишите обычный промпт без плейсхолдеров или используйте функцию ссылок @ (AT) с `<<<image_N>>>`, `<<<video_N>>>` и `<<<audio_N>>>` для явного указания элементов соответствующих массивов материалов |
| `resolution` | string | Разрешение результата: `"480p"`, `"720p"` или `"1080p"` |
| `duration` | integer | Длительность видео в целых секундах (4-30), с шагом 1 |
| `aspect_ratio` | string | Соотношение сторон видео: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` или `"3:4"` |

#### Референсные материалы

Все референсные материалы необязательны. Поддерживаются запросы только с изображениями, только с видео, только с аудио и без референсов. Для генерации без референсов рекомендуется Текст в видео.

| Параметр | Тип | Описание |
|-----------|------|-------------|
| `images` | string[] | 0-30 URL референсных изображений; см. ограничения материалов ниже |
| `videos` | string[] | 0-10 URL референсных видео в формате MP4 или MOV; длительность каждого видео — 2-30 секунд, суммарная длительность — не более 30 секунд |
| `audios` | string[] | 0-10 URL референсного аудио в формате WAV или MP3; каждый файл должен длиться 2-30 секунд и занимать не более 15 MB, суммарная длительность — не более 30 секунд |

#### Плейсхолдеры ссылок @ (AT)

Функция @ (AT) связывает референсные материалы с промптом с помощью пронумерованных плейсхолдеров `<<<...>>>`. Нумерация начинается с `1` независимо для каждого типа материалов и соответствует порядку в его массиве:

| Плейсхолдер | Значение по ссылке |
|-------------|------------------|
| `<<<image_1>>>` | `images[0]` |
| `<<<image_2>>>` | `images[1]` |
| `<<<video_1>>>` | `videos[0]` |
| `<<<audio_1>>>` | `audios[0]` |

Например, если первое изображение служит референсом персонажа, а второе — сцены, используйте в `prompt` `<<<image_1>>>` для персонажа и `<<<image_2>>>` для сцены. Каждый плейсхолдер должен указывать на существующий элемент соответствующего массива.

#### Необязательные

| Параметр | Тип | Описание |
|-----------|------|-------------|
| `sound` | boolean | Нужно ли генерировать звук. По умолчанию `true` |

### Пример запроса

```javascript
{
  model_name: 'seedance-v2.5-reference-to-video',
  prompt: 'Use image one for the subject, video one for the movement, and audio one for the atmosphere',
  resolution: '720p',
  duration: 8,
  aspect_ratio: '16:9',
  sound: true,
  images: ['https://example.com/subject-reference.jpg'],
  videos: ['https://example.com/motion-reference.mp4'],
  audios: ['https://example.com/atmosphere-reference.mp3']
}
```

### Пример запроса Референсы в видео с @ (AT)

```javascript
{
  model_name: 'seedance-v2.5-reference-to-video',
  prompt: 'Place the explorer from <<<image_1>>> in the environment from <<<image_2>>>, following the camera movement in <<<video_1>>> and speaking with the reference voice from <<<audio_1>>>',
  resolution: '720p',
  duration: 10,
  aspect_ratio: '16:9',
  sound: true,
  images: [
    'https://example.com/explorer-reference.jpg',
    'https://example.com/environment-reference.png'
  ],
  videos: ['https://example.com/camera-movement-reference.mp4'],
  audios: ['https://example.com/voice-reference.mp3']
}
```

## Ограничения материалов

Эти ограничения применяются к изображениям первого и последнего кадров и референсным материалам моделей на этой странице.

| Материал | Форматы | Ограничения |
|-------|---------|--------|
| Изображения | JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF | Каждое изображение меньше 30 MB; ширина и высота — каждая 300-6000 px; отношение ширины к высоте — 0.4-2.5 |
| Видео | MP4, MOV | Не более 200 MB каждое; ширина и высота — каждая 300-6000 px; отношение ширины к высоте — 0.4-2.5; частота кадров — 24-60 FPS |
| Аудио | WAV, MP3 | Не более 15 MB каждый файл |
| Тело запроса | — | Не более 64 MB |

Для референсного аудио и видео действуют отдельные ограничения суммарной длительности — по 30 секунд. Количество также учитывается независимо: до 30 изображений, 10 видео и 10 аудиофрагментов. Добавление видео не уменьшает допустимое количество изображений.

Все модели по умолчанию используют `720p`, но `resolution` всё равно необходимо передавать. Переключатель звука по умолчанию равен `true`; ни он, ни референсное аудио не влияют на цену.

## Формат ответа

### Первоначальный ответ

Все модели возвращают `task_id` для периодического опроса:

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "{task_id}",
    "response_url": "https://api.flaq.ai/api/v1/video/{task_id}",
    "task_status": "submitted"
  }
}
```

### Ответ при опросе

Опрашивайте `GET /api/v1/video/{taskId}` для проверки статуса:

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "{task_id}",
    "response_url": "https://api.flaq.ai/api/v1/video/{task_id}",
    "task_status": "succeed",
    "task_status_msg": null,
    "task_result": {
      "credit": 0.2,
      "videos": [
        {
          "url": "https://example.com/generated-video.mp4"
        }
      ]
    }
  }
}
```

### Значения статуса

- `submitted`: Задача принята и ожидает обработки
- `processing`: Идёт генерация видео
- `succeed`: Генерация видео завершена
- `failed`: Генерация видео не удалась

## Время обработки

Время обработки зависит от длительности, разрешения и текущего состояния очереди.

Проверяйте статус каждые 5-10 секунд.

## Рекомендации

1. **Обязательные параметры**: всегда передавайте `resolution` и `duration`, а для Текст в видео и Референсы в видео также `aspect_ratio`
2. **Соотношение сторон Изображение в видео**: не отправляйте `aspect_ratio` в запросах Изображение в видео
3. **Референсные видео**: видео необязательны; длительность каждого видео и их суммарная длительность должны соответствовать указанным ограничениям
4. **Референсные изображения**: изображения необязательны независимо от видео и аудио; отправляйте до 30 URL изображений поддерживаемых форматов
5. **Референсное аудио**: каждый фрагмент должен длиться 2-30 секунд и занимать не более 15 MB, общая длительность — не более 30 секунд
6. **Порядок референсов**: располагайте `images`, `videos` и `audios` в нужном порядке и последовательно ссылайтесь на них в промпте
7. **Звук**: пропустите `sound`, чтобы использовать значение по умолчанию `true`, или задайте `false` для отключения генерации звука