# API AI Clipping

> Soumettez une vidéo longue et recevez des clips viraux générés par IA avec horodatages, titres, descriptions et hashtags.

## API AI Clipping

Soumettez une vidéo de n'importe quelle durée et recevez tous les clips viraux classés par potentiel viral. Chaque clip inclut des horodatages de début/fin détectés automatiquement, des titres, descriptions et hashtags générés par IA. L'API fonctionne pour tous les contenus, des vidéos courtes aux vidéos de plusieurs heures. Si l'export est activé, la réponse inclut également des liens de téléchargement des vidéos rendues pour chaque clip, avec un recadrage automatique optionnel (AI Reframe) qui maintient le sujet principal centré, et des overlays de sous-titres animés pour des vidéos courtes plus engageantes.

Vous pouvez publier les clips générés par AI Clipping directement sur des comptes sociaux connectés. Consultez l'[API de Publication sur les Réseaux Sociaux](https://wayin.ai/fr/api-docs/social-media-publishing/) pour connecter des comptes et créer des tâches de publication.

## Sources Vidéo Prises en Charge

L'API accepte les URLs des plateformes suivantes : YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble et plus encore.

Vous pouvez également découper [des fichiers vidéo locaux que vous téléversez](https://wayin.ai/fr/api-docs/upload/) — le téléversement local nécessite un [abonnement **Starter** ou supérieur](https://wayin.ai/pricing/).

---

## Soumettre une Tâche de Découpage

Soumettez une nouvelle tâche de découpage AI depuis une URL de vidéo.

```
POST https://wayinvideo-api.wayin.ai/api/v2/clips
```

### Corps de la Requête

Lors du rendu des clips, vous pouvez activer des fonctionnalités telles que les **Sous-titres Animés**, l'**AI Reframe** et des overlays de texte **AI Hook** optionnels. Avec l'AI Reframe, le système détecte le sujet principal dans le cadre, le maintient centré, optimise le recadrage selon le format choisi et sélectionne la mise en page la plus adaptée selon la structure de la scène. Ces fonctionnalités sont contrôlées par des paramètres dont les noms commencent par `enable_` (voir le tableau ci-dessous).

| Paramètre | Type | Obligatoire | Défaut | Description |
|-----------|------|-------------|--------|-------------|
| `video_url` | string | Oui | — | L'URL de la vidéo source. Pour les fichiers téléversés localement, utilisez l'identifiant de fichier retourné par l'[API Upload](https://wayin.ai/fr/api-docs/upload/). |
| `project_name` | string | Non | `""` | Un nom personnalisé pour cette tâche |
| `source_lang` | string | Non | `null` | Langue source de la vidéo (voir [Langues prises en charge](https://wayin.ai/fr/api-docs/supported-languages/)). Si `null`, le système détecte automatiquement la langue d'origine. |
| `target_lang` | string | Non | `null` | Langue cible pour le contenu de sortie, y compris les titres des clips, descriptions et sous-titres (voir [Langues prises en charge](https://wayin.ai/fr/api-docs/supported-languages/)). Si `null`, la langue de sortie correspond à `source_lang`. |
| `target_duration` | string | Non | `DURATION_0_90` | Plage de durée attendue pour chaque clip de sortie. Valeurs autorisées : `DURATION_0_30` (0–30 s), `DURATION_0_90` (0–90 s), `DURATION_30_60` (30–60 s), `DURATION_60_90` (60–90 s), `DURATION_90_180` (90–180 s), `DURATION_180_300` (180–300 s). |
| `limit` | number | Non | `null` | Nombre maximum de clips à retourner, classés par score de viralité du plus élevé au plus bas. Si `null` ou omis, tous les clips sont retournés. |
| `enable_export` | boolean | Non | `false` | Voir ci-dessous. Si `false`, seuls les plages temporelles, titres et descriptions des clips sont retournés (sans rendu) ; si `true`, les clips sont rendus immédiatement et chaque clip inclut un lien d'export. Vous pouvez également exporter ultérieurement avec des styles différents via la section Ré-exporter des clips existants. |
| `resolution` | string | Non | `SD_480` | Résolution de sortie : `SD_480`, `HD_720`, `FHD_1080`, `QHD_2K`, `UHD_4K`. Utilisé uniquement quand `enable_export` est `true`. |
| `enable_caption` | boolean | Non | `false` | Ajouter des sous-titres animés lors du rendu. Utilisé uniquement quand `enable_export` est `true`. Si `true`, `caption_display` et `cc_style_tpl` prennent effet ; si `false`, l'export n'a pas de sous-titres animés. |
| `caption_display` | string | Non | `original` | Mode de sous-titres : `both`, `original`, `translation`. Utilisé uniquement quand `enable_export` et `enable_caption` sont tous deux `true`. |
| `cc_style_tpl` | string | Non | `temp-7` | ID du modèle de style de sous-titres (voir [Styles de sous-titres](https://wayin.ai/fr/api-docs/subtitles-style/)). Utilisé uniquement quand `enable_export` et `enable_caption` sont tous deux `true`. |
| `enable_ai_hook` | boolean | Non | `false` | Ajouter un texte d'accroche généré automatiquement au début ou à la fin de chaque clip rendu. Utilisé uniquement quand `enable_export` est `true`. Si `true`, `ai_hook_script_style` et `ai_hook_position` prennent effet ; si `false`, aucun AI Hook n'est ajouté. |
| `ai_hook_script_style` | string | Non | `serious` | Style du texte d'accroche généré. Valeurs autorisées : `serious`, `casual`, `informative`, `conversational`, `humorous`, `parody`, `inspirational`, `dramatic`, `empathetic`, `persuasive`, `neutral`, `excited`, `calm`. Utilisé uniquement quand `enable_export` et `enable_ai_hook` sont tous deux `true`. |
| `ai_hook_position` | string | Non | `beginning` | Position du texte d'accroche généré. Valeurs autorisées : `beginning`, `end`. Utilisé uniquement quand `enable_export` et `enable_ai_hook` sont tous deux `true`. |
| `enable_ai_reframe` | boolean | Non | `false` | Activer l'AI Reframe. Utilisé uniquement quand `enable_export` est `true`. Si `true`, `ratio` est obligatoire ; si `false`, la vidéo est exportée avec son format d'origine inchangé. |
| `ratio` | string | Oui si `enable_ai_reframe` est `true` | — | Format d'image : `RATIO_9_16`, `RATIO_1_1`, `RATIO_4_5`, `RATIO_16_9`. Utilisé uniquement quand `enable_export` est `true`, et obligatoire quand `enable_ai_reframe` est `true`. |
| `reframe_layout` | string | Non | `Auto` | Mise en page AI Reframe. Utilisé uniquement quand `enable_export` et `enable_ai_reframe` sont tous deux `true`. Par défaut `Auto` : le modèle choisit la meilleure mise en page pour le cadre (omettez le champ ou passez une chaîne vide pour le même comportement). Si défini sur une autre valeur autorisée pour le `ratio` choisi, le recadrage utilise cette mise en page fixe. Voir la section Valeurs de mise en page Reframe. |
| `enable_more_results` | boolean | Non | `false` | Si `true`, le modèle produit un plus grand nombre de clips. Disponible uniquement avec un abonnement **Enterprise** ([Plans d'abonnement](https://wayin.ai/wayinvideo/settings/plan)). |
| `enable_express_mode` | boolean | Non | `false` | Si `true`, active le **Mode Express** : les **Crédits API** facturés pour la tâche sont réduits de moitié par rapport au tarif standard. Disponible uniquement avec un abonnement **Enterprise** ([Plans d'abonnement](https://wayin.ai/wayinvideo/settings/plan)). |

### Valeurs de mise en page Reframe

Les valeurs `reframe_layout` autorisées dépendent du `ratio`. `Auto` est toujours autorisé (par défaut) ; omettre le champ ou passer une chaîne vide a le même comportement. Passez les noms de mise en page **exactement** comme indiqué ci-dessous (sensible à la casse et aux espaces).

| `ratio` | Valeurs `reframe_layout` autorisées |
|---------|-------------------------------------|
| `RATIO_16_9` | `Auto`, `Full`, `Fit`, `Grid 4`, `Split 2`, `Trio`, `PiP`, `OTS`, `Screen First` |
| `RATIO_9_16` | `Auto`, `Full`, `Fit`, `Grid 4`, `Split 2`, `Trio`, `PiP`, `Screen First`, `Gameplay A`, `Gameplay B` |
| `RATIO_1_1` | `Auto`, `Full`, `Fit`, `Grid 4`, `Trio` |
| `RATIO_4_5` | `Auto`, `Full`, `Fit`, `Grid 4`, `Split 2`, `Trio`, `PiP`, `Screen First`, `Gameplay A`, `Gameplay B` |

**Comportement de `enable_export`**

- Si `enable_export` est vide ou `false`, l'API retourne uniquement les plages temporelles des clips, titres, descriptions et métadonnées associées. Aucun rendu n'est effectué et il n'y a pas de liens d'export dans le résultat. Les paramètres `ratio`, `reframe_layout`, `resolution`, `caption_display`, `enable_caption`, `cc_style_tpl`, `enable_ai_hook`, `ai_hook_script_style`, `ai_hook_position` et `enable_ai_reframe` n'ont aucun effet lors de la création de la tâche. Vous pouvez ultérieurement rendre les clips sélectionnés via la section Ré-exporter des clips existants.
- Si `enable_export` est `true`, ces paramètres prennent effet, chaque clip est rendu immédiatement, et le résultat inclut un lien de téléchargement pour chaque clip. Le traitement peut être plus long car chaque clip est rendu.

<div class="tabs" data-labels="Avec export|Sans export" data-group="export-mode"></div>

Le corps de la requête définit `enable_export` à `true`. Les clips sont rendus ; chaque clip inclut un `export_link`.

**Requête**

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=example",
    "project_name": "sample project name",
    "target_duration": "DURATION_30_60",
    "enable_export": true,
    "resolution": "HD_720",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

**Réponse de soumission**

```json
{
  "data": {
    "id": "proj_xyz789",
    "name": "sample project name",
    "status": "CREATED"
  }
}
```

<div class="tab-divider"></div>

Le corps de la requête omet `enable_export` ou le définit à `false`. Seules les plages temporelles, titres, descriptions et tags des clips sont retournés ; pas de rendu, pas de liens d'export.

**Requête**

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=example",
    "project_name": "sample project name",
    "target_duration": "DURATION_30_60"
  }'
```

**Réponse de soumission**

```json
{
  "data": {
    "id": "proj_abc123",
    "name": "sample project name",
    "status": "CREATED"
  }
}
```

<div class="tabs-end"></div>

| Champ | Type | Description |
|-------|------|-------------|
| `id` | string | Identifiant unique de la tâche |
| `name` | string | Nom de la tâche |
| `status` | string | Statut de traitement : `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |

---

## Exemples

Scénarios courants d'AI Clipping. Remplacez `YOUR_API_KEY` par une clé issue du [Tableau de bord API](https://wayin.ai/wayinvideo/api-dashboard).

### Découper une vidéo YouTube en clips viraux

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://www.youtube.com/watch?v=EXAMPLE"}'
```

### Découper l'enregistrement d'un webinaire en shorts verticaux 9:16 avec sous-titres

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "target_duration": "DURATION_30_60",
    "enable_export": true,
    "resolution": "HD_720",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

### Découper un podcast en shorts les mieux classés

Utile pour les contenus longs où vous ne voulez conserver que les clips au plus fort potentiel viral.

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "limit": 5,
    "target_duration": "DURATION_60_90",
    "enable_export": true,
    "resolution": "HD_720",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

---

## Récupérer les Résultats de Découpage

Récupérez le statut de la tâche et les clips. Interrogez cet endpoint jusqu'à ce que `status` soit `SUCCEEDED`.

> **Résultats incrémentiels :** Lorsque `status` est `ONGOING`, chaque appel retourne les clips générés jusqu'à présent — vous pouvez commencer à traiter les résultats partiels immédiatement. Lorsque `status` passe à `SUCCEEDED`, la réponse contient l'ensemble complet des clips.

```
GET https://wayinvideo-api.wayin.ai/api/v2/clips/results/{id}
```

### Paramètres de Chemin

| Paramètre | Type | Obligatoire | Description |
|-----------|------|-------------|-------------|
| `id` | string | Oui | L'ID de tâche retourné par l'endpoint de soumission |

### Exemple de Requête

```bash
curl -X GET https://wayinvideo-api.wayin.ai/api/v2/clips/results/proj_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2"
```

<div class="tabs" data-labels="Avec export|Sans export" data-group="export-mode"></div>

Lorsque la tâche a été soumise avec **`enable_export: true`**, chaque clip inclut un `export_link` pour la vidéo rendue :

```json
{
  "data": {
    "id": "proj_xyz789",
    "name": "sample project name",
    "status": "SUCCEEDED",
    "expire_at": 1741824000000,
    "cost_usage": 120.0,
    "clips": [
      {
        "idx": 0,
        "title": "sample title",
        "begin_ms": 15000,
        "end_ms": 75000,
        "thumbnail": "https://cdn.example.com/thumb/clip_001.jpg",
        "tags": ["insight", "analysis"],
        "desc": "sample description",
        "score": 81,
        "export_link": "https://cdn.example.com/export/clip_001.mp4"
      },
      {
        "idx": 1,
        "title": "sample title 2",
        "begin_ms": 120000,
        "end_ms": 195000,
        "thumbnail": "https://cdn.example.com/thumb/clip_002.jpg",
        "tags": ["tips", "summary"],
        "desc": "sample description",
        "score": 76,
        "export_link": "https://cdn.example.com/export/clip_002.mp4"
      }
    ]
  }
}
```

<div class="tab-divider"></div>

Lorsque la tâche a été soumise **sans** `enable_export` (ou avec `enable_export: false`), les clips n'incluent pas `export_link` :

```json
{
  "data": {
    "id": "proj_abc123",
    "name": "sample project name",
    "status": "SUCCEEDED",
    "expire_at": 1741824000000,
    "cost_usage": 120.0,
    "clips": [
      {
        "idx": 0,
        "title": "sample title",
        "begin_ms": 15000,
        "end_ms": 75000,
        "thumbnail": "https://cdn.example.com/thumb/clip_001.jpg",
        "tags": ["insight", "analysis"],
        "desc": "sample description",
        "score": 81
      },
      {
        "idx": 1,
        "title": "sample title 2",
        "begin_ms": 120000,
        "end_ms": 195000,
        "thumbnail": "https://cdn.example.com/thumb/clip_002.jpg",
        "tags": ["tips", "summary"],
        "desc": "sample description",
        "score": 76
      }
    ]
  }
}
```

<div class="tabs-end"></div>

### Champs de la Réponse

| Champ | Type | Description |
|-------|------|-------------|
| `id` | string | Identifiant unique de la tâche |
| `name` | string | Nom de la tâche |
| `status` | string | `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |
| `error_message` | string | Raison de l'erreur (présent uniquement quand `status` est `FAILED`) |
| `expire_at` | integer | Horodatage d'expiration en millisecondes (epoch). Après cette date, la tâche expire et les résultats ne peuvent plus être récupérés via l'endpoint des résultats. La durée d'expiration dépend de votre plan d'abonnement. Consultez la page [Plans d'abonnement](https://wayin.ai/wayinvideo/settings/plan) pour plus de détails. `-1` signifie que le résultat n'expire pas tant qu'un abonnement payant est actif. À la fin de l'abonnement payant, le résultat est conservé un mois de plus, puis il expire. |
| `cost_usage` | number | Crédits API consommés pour cette requête |
| `clips` | array | Liste d'objets clip (voir ci-dessous). Quand `status` est `ONGOING`, contient les clips générés jusqu'à présent (résultats partiels) ; quand `status` est `SUCCEEDED`, contient tous les clips (résultats finaux). |

### Objet Clip

| Champ | Type | Description |
|-------|------|-------------|
| `idx` | integer | Index du clip (basé sur 0, classé par potentiel viral) |
| `title` | string | Titre du clip généré par IA |
| `begin_ms` | number | Temps de début en millisecondes |
| `end_ms` | number | Temps de fin en millisecondes |
| `thumbnail` | string | URL de l'image miniature |
| `tags` | string[] | Hashtags générés par IA |
| `desc` | string | Description générée par IA |
| `score` | number | Score de potentiel viral (0–100, plus élevé est mieux) |
| `export_link` | string | URL de téléchargement de la vidéo rendue (quand `enable_export` est true). Un nouveau lien est généré à chaque appel de l'endpoint des résultats. Chaque lien expire après 24 heures — veuillez télécharger la vidéo avant expiration. Si le lien a expiré, appelez à nouveau l'endpoint des résultats pour en obtenir un nouveau. |

---

## Ré-exporter des Clips Existants

Si vous souhaitez rendre des clips ultérieurement ou les ré-exporter avec un style de sous-titres différent, un format d'image, un AI Hook, des overlays ou d'autres paramètres d'export, utilisez l'[API Clips Export](https://wayin.ai/fr/api-docs/clips-export/).

Pour les projets AI Clipping, passez l'`id` de tâche retourné par `POST /api/v2/clips` comme `project_id` dans la requête d'export.


---

## FAQ

### Quelle est la durée maximale d'une vidéo ?

Il n'y a pas de limite stricte — l'API est conçue pour des contenus de plusieurs heures comme les podcasts, les livestreams gaming et les webinaires. Les limites de taille de fichier ne s'appliquent qu'aux [téléversements locaux](https://wayin.ai/fr/api-docs/upload/) ; les sources via URL ne sont pas plafonnées.

### Comment les clips sont-ils classés ?

Chaque clip est noté selon son potentiel viral — complétude narrative, force du hook, pics émotionnels et signaux d'engagement. Utilisez le paramètre `limit` pour ne conserver que les N clips les mieux notés.

### Puis-je obtenir des clips sans les rendre ?

Oui. Omettez `enable_export` (ou définissez-le à `false`) pour ne recevoir que les horodatages, titres, descriptions et tags. Rendez ensuite les clips sélectionnés via l'[API Clips Export](https://wayin.ai/fr/api-docs/clips-export/).

### Quels formats d'image AI Reframe prend-il en charge ?

`RATIO_9_16` (TikTok / Reels / Shorts), `RATIO_1_1` (feed Instagram), `RATIO_4_5` (portrait Instagram) et `RATIO_16_9` (paysage). Voir la section Valeurs de mise en page Reframe pour les options de mise en page par format.

### Depuis quelles plateformes puis-je découper ?

YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble et plus encore, ainsi que les fichiers téléversés localement (`mp4`, `mov`, `webm`, `avi`).