# Seedance 2.5 API

Referensi API lengkap untuk model pembuatan video Seedance 2.5 dari ByteDance.

## Varian Model

API ini mendukung tiga varian model:

| Model | ID | Deskripsi |
|-------|----|-------------|
| **Seedance 2.5 Text to Video** | `seedance-v2.5-text-to-video` | Pembuatan video berkualitas tinggi dari teks |
| **Seedance 2.5 Image to Video** | `seedance-v2.5-image-to-video` | Pembuatan video dari bingkai pertama atau bingkai pertama dan terakhir |
| **Seedance 2.5 Reference to Video** | `seedance-v2.5-reference-to-video` | Pembuatan video yang dipandu gambar, video, dan audio referensi |

## Perbandingan Singkat

| Fitur | Teks ke Video | Gambar ke Video | Referensi ke Video |
|---------|---------------|----------------|--------------------|
| Rentang Durasi | 4-30 detik | 4-30 detik | 4-30 detik |
| Opsi Resolusi | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| Rasio Aspek | Wajib | Tidak didukung | Wajib |
| Media Wajib | Tidak ada | Gambar bingkai pertama | Tidak ada |
| Media Opsional | Tidak ada | Gambar bingkai terakhir | Gambar, video, dan audio |

### Rasio Aspek yang Didukung

Teks ke Video dan Referensi ke Video mendukung:

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

Gambar ke Video tidak mendukung parameter `aspect_ratio`.

### Opsi Resolusi

| Resolusi | Deskripsi |
|------------|-------------|
| `480p` | Definisi standar |
| `720p` | Definisi tinggi |
| `1080p` | Full HD |

## Seedance 2.5 Text to Video

### Titik Akhir

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

### Parameter Permintaan

#### Wajib

| Parameter | Tipe | Deskripsi |
|-----------|------|-------------|
| `model_name` | string | Harus `"seedance-v2.5-text-to-video"` |
| `prompt` | string | Prompt pembuatan video |
| `resolution` | string | Resolusi keluaran: `"480p"`, `"720p"`, atau `"1080p"` |
| `duration` | integer | Durasi video dalam detik bulat (4-30), dengan langkah 1 |
| `aspect_ratio` | string | Rasio aspek video: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, atau `"3:4"` |

#### Opsional

| Parameter | Tipe | Deskripsi |
|-----------|------|-------------|
| `sound` | boolean | Apakah suara dibuat. Nilai default `true` |

### Contoh Permintaan

```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

### Parameter Permintaan

#### Wajib

| Parameter | Tipe | Deskripsi |
|-----------|------|-------------|
| `model_name` | string | Harus `"seedance-v2.5-image-to-video"` |
| `prompt` | string | Prompt pembuatan video |
| `resolution` | string | Resolusi keluaran: `"480p"`, `"720p"`, atau `"1080p"` |
| `duration` | integer | Durasi video dalam detik bulat (4-30), dengan langkah 1 |
| `image_url` | string | URL gambar bingkai pertama |

#### Opsional

| Parameter | Tipe | Deskripsi |
|-----------|------|-------------|
| `image_end_url` | string | URL gambar bingkai terakhir yang opsional |
| `sound` | boolean | Apakah suara dibuat. Nilai default `true` |

> Jangan sertakan `aspect_ratio` dalam permintaan Gambar ke Video. Model ini tidak mendukung parameter tersebut.

### Contoh Permintaan

```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

### Parameter Permintaan

#### Wajib

| Parameter | Tipe | Deskripsi |
|-----------|------|-------------|
| `model_name` | string | Harus `"seedance-v2.5-reference-to-video"` |
| `prompt` | string | Prompt pembuatan video. Tulis prompt biasa tanpa penanda, atau gunakan fitur referensi @ (AT) secara opsional dengan `<<<image_N>>>`, `<<<video_N>>>`, dan `<<<audio_N>>>` untuk merujuk item dari array media terkait secara eksplisit |
| `resolution` | string | Resolusi keluaran: `"480p"`, `"720p"`, atau `"1080p"` |
| `duration` | integer | Durasi video dalam detik bulat (4-30), dengan langkah 1 |
| `aspect_ratio` | string | Rasio aspek video: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, atau `"3:4"` |

#### Media Referensi

Semua media referensi bersifat opsional. Permintaan hanya gambar, hanya video, hanya audio, serta tanpa media referensi didukung. Untuk pembuatan tanpa referensi, Teks ke Video disarankan.

| Parameter | Tipe | Deskripsi |
|-----------|------|-------------|
| `images` | string[] | 0-30 URL gambar referensi; lihat Batas Media di bawah |
| `videos` | string[] | 0-10 URL video referensi dalam format MP4 atau MOV; setiap video harus berdurasi 2-30 detik, dengan durasi gabungan maksimal 30 detik |
| `audios` | string[] | 0-10 URL audio referensi dalam format WAV atau MP3; setiap audio harus berdurasi 2-30 detik dan berukuran maksimal 15 MB, dengan durasi total tidak melebihi 30 detik |

#### Penanda Referensi @ (AT)

Fitur referensi @ (AT) menghubungkan media referensi ke prompt melalui penanda bernomor `<<<...>>>`. Penomoran dimulai dari `1` secara terpisah untuk setiap jenis media dan mengikuti urutan array terkait:

| Penanda | Nilai yang dirujuk |
|-------------|------------------|
| `<<<image_1>>>` | `images[0]` |
| `<<<image_2>>>` | `images[1]` |
| `<<<video_1>>>` | `videos[0]` |
| `<<<audio_1>>>` | `audios[0]` |

Misalnya, jika gambar pertama adalah referensi karakter dan gambar kedua adalah referensi adegan, gunakan `<<<image_1>>>` untuk karakter dan `<<<image_2>>>` untuk adegan di `prompt`. Setiap penanda harus merujuk ke item yang ada dalam array terkait.

#### Opsional

| Parameter | Tipe | Deskripsi |
|-----------|------|-------------|
| `sound` | boolean | Apakah suara dibuat. Nilai default `true` |

### Contoh Permintaan

```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']
}
```

### Contoh Permintaan Referensi ke Video dengan @ (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']
}
```

## Batas Media

Batas ini berlaku untuk gambar bingkai pertama, gambar bingkai terakhir, dan media referensi pada model di halaman ini.

| Media | Format | Batas |
|-------|---------|--------|
| Gambar | JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF | Setiap gambar harus kurang dari 30 MB; lebar dan tinggi masing-masing 300-6000 px; rasio lebar terhadap tinggi 0.4-2.5 |
| Video | MP4, MOV | Maksimal 200 MB per video; lebar dan tinggi masing-masing 300-6000 px; rasio lebar terhadap tinggi 0.4-2.5; laju bingkai 24-60 FPS |
| Audio | WAV, MP3 | Maksimal 15 MB per audio |
| Isi permintaan | — | Maksimal 64 MB |

Audio referensi dan video referensi masing-masing memiliki batas durasi gabungan terpisah sebesar 30 detik. Jumlahnya juga independen: hingga 30 gambar, 10 video, dan 10 klip audio. Menambahkan video tidak mengurangi jumlah gambar yang diizinkan.

Semua model menggunakan `720p` secara default, tetapi `resolution` tetap wajib diberikan. Sakelar suara memiliki nilai default `true`; sakelar ini maupun audio referensi tidak mengubah harga.

## Format Respons

### Respons Awal

Semua model mengembalikan `task_id` untuk pemeriksaan berkala:

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

### Respons Pemeriksaan Berkala

Periksa `GET /api/v1/video/{taskId}` secara berkala untuk melihat status:

```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"
        }
      ]
    }
  }
}
```

### Nilai Status

- `submitted`: Tugas diterima dan menunggu pemrosesan
- `processing`: Pembuatan video sedang berlangsung
- `succeed`: Pembuatan video selesai
- `failed`: Pembuatan video gagal

## Waktu Pemrosesan

Waktu pemrosesan bergantung pada durasi, resolusi, dan kondisi antrean saat ini.

Periksa status setiap 5-10 detik.

## Praktik Terbaik

1. **Parameter Wajib**: selalu berikan `resolution` dan `duration`, serta `aspect_ratio` untuk Teks ke Video dan Referensi ke Video
2. **Rasio Gambar ke Video**: jangan kirim `aspect_ratio` untuk permintaan Gambar ke Video
3. **Video Referensi**: video bersifat opsional; durasi setiap video dan durasi gabungannya harus berada dalam batas yang didokumentasikan
4. **Gambar Referensi**: gambar bersifat opsional secara independen dari video dan audio; kirim hingga 30 URL gambar yang didukung
5. **Audio Referensi**: setiap klip audio harus berdurasi 2-30 detik dan maksimal 15 MB, dengan durasi gabungan tidak melebihi 30 detik
6. **Urutan Referensi**: susun `images`, `videos`, dan `audios` sesuai urutan yang diinginkan dan rujuk secara konsisten dalam prompt
7. **Suara**: hilangkan `sound` untuk menggunakan nilai default `true`, atau tetapkan `false` untuk menonaktifkan suara yang dihasilkan