# Seedance 2.5 API

Référence API complète des modèles de génération vidéo Seedance 2.5 de ByteDance.

## Variantes du modèle

Cette API prend en charge trois variantes :

| Modèle | ID | Description |
|-------|----|-------------|
| **Seedance 2.5 Text to Video** | `seedance-v2.5-text-to-video` | Génération vidéo de haute qualité à partir de texte |
| **Seedance 2.5 Image to Video** | `seedance-v2.5-image-to-video` | Génération vidéo à partir de la première image ou des première et dernière images |
| **Seedance 2.5 Reference to Video** | `seedance-v2.5-reference-to-video` | Génération vidéo guidée par des images, vidéos et pistes audio de référence |

## Comparaison rapide

| Fonctionnalité | Texte vers vidéo | Image vers vidéo | Références vers vidéo |
|---------|---------------|----------------|--------------------|
| Durée | 4-30 secondes | 4-30 secondes | 4-30 secondes |
| Résolutions | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| Format d’image | Obligatoire | Non pris en charge | Obligatoire |
| Média obligatoire | Aucun | Première image | Aucun |
| Médias facultatifs | Aucun | Dernière image | Images, vidéos et audio |

### Formats d’image pris en charge

Texte vers vidéo et Références vers vidéo prennent en charge :

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

Image vers vidéo ne prend pas en charge le paramètre `aspect_ratio`.

### Résolutions disponibles

| Résolution | Description |
|------------|-------------|
| `480p` | Définition standard |
| `720p` | Haute définition |
| `1080p` | Full HD |

## Seedance 2.5 Text to Video

### Point de terminaison

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

### Paramètres de requête

#### Obligatoires

| Paramètre | Type | Description |
|-----------|------|-------------|
| `model_name` | string | Doit être `"seedance-v2.5-text-to-video"` |
| `prompt` | string | Prompt de génération vidéo |
| `resolution` | string | Résolution de sortie : `"480p"`, `"720p"` ou `"1080p"` |
| `duration` | integer | Durée vidéo en secondes entières (4-30), par pas de 1 |
| `aspect_ratio` | string | Format d’image de la vidéo : `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` ou `"3:4"` |

#### Facultatifs

| Paramètre | Type | Description |
|-----------|------|-------------|
| `sound` | boolean | Générer ou non du son. Valeur par défaut : `true` |

### Exemple de requête

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

### Paramètres de requête

#### Obligatoires

| Paramètre | Type | Description |
|-----------|------|-------------|
| `model_name` | string | Doit être `"seedance-v2.5-image-to-video"` |
| `prompt` | string | Prompt de génération vidéo |
| `resolution` | string | Résolution de sortie : `"480p"`, `"720p"` ou `"1080p"` |
| `duration` | integer | Durée vidéo en secondes entières (4-30), par pas de 1 |
| `image_url` | string | URL de la première image |

#### Facultatifs

| Paramètre | Type | Description |
|-----------|------|-------------|
| `image_end_url` | string | URL facultative de la dernière image |
| `sound` | boolean | Générer ou non du son. Valeur par défaut : `true` |

> N’incluez pas `aspect_ratio` dans les requêtes Image vers vidéo. Ce modèle ne prend pas en charge ce paramètre.

### Exemple de requête

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

### Paramètres de requête

#### Obligatoires

| Paramètre | Type | Description |
|-----------|------|-------------|
| `model_name` | string | Doit être `"seedance-v2.5-reference-to-video"` |
| `prompt` | string | Prompt de génération vidéo. Rédigez un prompt standard sans marqueurs, ou utilisez la fonction de référence @ (AT) avec `<<<image_N>>>`, `<<<video_N>>>` et `<<<audio_N>>>` pour référencer explicitement des éléments des tableaux de médias correspondants |
| `resolution` | string | Résolution de sortie : `"480p"`, `"720p"` ou `"1080p"` |
| `duration` | integer | Durée vidéo en secondes entières (4-30), par pas de 1 |
| `aspect_ratio` | string | Format d’image de la vidéo : `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` ou `"3:4"` |

#### Médias de référence

Tous les médias de référence sont facultatifs. Les requêtes contenant uniquement des images, des vidéos ou de l’audio, ainsi que celles sans média de référence, sont prises en charge. Sans références, il est recommandé d’utiliser Texte vers vidéo.

| Paramètre | Type | Description |
|-----------|------|-------------|
| `images` | string[] | 0-30 URL d’images de référence ; voir les limites des médias ci-dessous |
| `videos` | string[] | 0-10 URL de vidéos de référence au format MP4 ou MOV ; chaque vidéo doit durer 2-30 secondes, pour une durée totale maximale de 30 secondes |
| `audios` | string[] | 0-10 URL audio de référence au format WAV ou MP3 ; chaque fichier doit durer 2-30 secondes et ne pas dépasser 15 MB, pour une durée totale maximale de 30 secondes |

#### Marqueurs de référence @ (AT)

La fonction de référence @ (AT) relie les médias de référence au prompt à l’aide de marqueurs numérotés `<<<...>>>`. La numérotation commence à `1` indépendamment pour chaque type de média et suit l’ordre du tableau correspondant :

| Marqueur | Valeur référencée |
|-------------|------------------|
| `<<<image_1>>>` | `images[0]` |
| `<<<image_2>>>` | `images[1]` |
| `<<<video_1>>>` | `videos[0]` |
| `<<<audio_1>>>` | `audios[0]` |

Par exemple, si la première image sert de référence pour un personnage et la deuxième pour une scène, utilisez `<<<image_1>>>` pour le personnage et `<<<image_2>>>` pour la scène dans `prompt`. Chaque marqueur doit désigner un élément existant dans le tableau correspondant.

#### Facultatifs

| Paramètre | Type | Description |
|-----------|------|-------------|
| `sound` | boolean | Générer ou non du son. Valeur par défaut : `true` |

### Exemple de requête

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

### Exemple de requête Références vers vidéo avec @ (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']
}
```

## Limites des médias

Ces limites s’appliquent aux premières et dernières images ainsi qu’aux médias de référence des modèles de cette page.

| Média | Formats | Limites |
|-------|---------|--------|
| Images | JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF | Chaque image doit faire moins de 30 MB ; largeur et hauteur de 300-6000 px chacune ; rapport largeur/hauteur de 0.4-2.5 |
| Vidéos | MP4, MOV | Maximum 200 MB chacune ; largeur et hauteur de 300-6000 px chacune ; rapport largeur/hauteur de 0.4-2.5 ; fréquence d’images de 24-60 FPS |
| Audio | WAV, MP3 | Maximum 15 MB par fichier |
| Corps de requête | — | Maximum 64 MB |

L’audio et les vidéos de référence ont chacun une limite de durée totale indépendante de 30 secondes. Leurs nombres sont indépendants : jusqu’à 30 images, 10 vidéos et 10 extraits audio. Ajouter des vidéos ne réduit pas le nombre d’images autorisé.

Tous les modèles utilisent `720p` par défaut, mais `resolution` doit tout de même être fourni. Le son est activé par défaut avec `true` ; ni ce réglage ni l’audio de référence ne modifient le prix.

## Format de réponse

### Réponse initiale

Tous les modèles renvoient un `task_id` pour l’interrogation périodique :

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

### Réponse à l’interrogation

Interrogez `GET /api/v1/video/{taskId}` pour vérifier l’état :

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

### Valeurs d’état

- `submitted`: Tâche acceptée, en attente de traitement
- `processing`: Génération vidéo en cours
- `succeed`: Génération vidéo terminée
- `failed`: Échec de la génération vidéo

## Temps de traitement

Le temps de traitement dépend de la durée, de la résolution et de la file d’attente actuelle.

Interrogez l’API toutes les 5-10 secondes pour vérifier l’état.

## Bonnes pratiques

1. **Paramètres obligatoires** : fournissez toujours `resolution` et `duration`, ainsi que `aspect_ratio` pour Texte vers vidéo et Références vers vidéo
2. **Format d’Image vers vidéo** : n’envoyez pas `aspect_ratio` pour les requêtes Image vers vidéo
3. **Vidéos de référence** : les vidéos sont facultatives ; la durée de chaque vidéo et la durée totale doivent respecter les limites documentées
4. **Images de référence** : les images sont facultatives, indépendamment des vidéos et de l’audio ; envoyez jusqu’à 30 URL d’images prises en charge
5. **Audio de référence** : chaque extrait doit durer 2-30 secondes et ne pas dépasser 15 MB, pour une durée totale maximale de 30 secondes
6. **Ordre des références** : organisez `images`, `videos` et `audios` dans l’ordre voulu et référencez-les de manière cohérente dans le prompt
7. **Son** : omettez `sound` pour utiliser la valeur par défaut `true`, ou définissez-le sur `false` pour désactiver le son généré