> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iacrea.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Vidéo Auto (workflow)

> Documentation complète du workflow de génération automatique de vidéo + polling de statut

# API Vidéo Auto (workflow)

Cette API permet de générer automatiquement une vidéo à partir d’une annonce (description + images), en s’appuyant sur l’IA pour :

* sélectionner **jusqu’à 5** images pertinentes (selon le nombre fourni)
* générer un texte court par image
* lancer la génération des clips vidéo pour chaque image
* assembler / rendre la vidéo finale

Le workflow se fait en **2 endpoints** :

* **1) POST** `"/api/video-editor/generate/video/auto"` : démarre la génération et renvoie un `id`
* **2) GET** `"/api/video-editor/generate/video/auto/{id}"` : permet de suivre l’avancement

## Authentification

Toutes les requêtes doivent inclure l’en-tête :

* `x-api-key: VOTRE_API_KEY`

## 1) Démarrer une génération

<ParamField path="POST /api/video-editor/generate/video/auto" />

### En-têtes

<ParamField header="x-api-key" type="string" required>
  Votre clé API IACrea
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Doit être `application/json`
</ParamField>

### Corps de requête

<ParamField body="image_urls" type="array" required>
  Tableau d’URLs d’images (format URL). **Minimum 1**.
</ParamField>

<ParamField body="description" type="string" required>
  Description textuelle de l’annonce (minimum 10 caractères). La langue détectée
  est utilisée pour les textes générés.
</ParamField>

<ParamField body="format" type="string">
  Format de la vidéo : `"landscape" | "portrait" | "square"`. Défaut :
  `"landscape"`.
</ParamField>

<ParamField body="colors" type="array">
  Deux couleurs `[background, text]` (ex : `["#1a1a2e", "#ffffff"]`). Optionnel.
</ParamField>

<ParamField body="font" type="string">
  Police (ex : `"Inter"`). Optionnel.
</ParamField>

<ParamField body="music" type="string">
  Musique (identifiant interne / valeur attendue par votre implémentation).
  Optionnel.
</ParamField>

<ParamField body="displayLogo" type="boolean">
  Afficher un logo sur la vidéo. Défaut : `false`.
</ParamField>

<ParamField body="logoUrl" type="string">
  URL du logo (nécessaire si `displayLogo=true`). Optionnel.
</ParamField>

<ParamField body="webhookUrl" type="string">
  URL appelée par IACrea quand la vidéo est **DONE** (voir section Webhook).
  Optionnel.
</ParamField>

### Réponses

#### 201 — Démarré

<ResponseField name="id" type="string">
  Identifiant de la génération auto. À utiliser dans le endpoint de suivi `GET
      /api/video-editor/generate/video/auto/{id}`.
</ResponseField>

<ResponseField name="status" type="string">
  Statut initial, typiquement `"PENDING"`.
</ResponseField>

<ResponseField name="generatedContent" type="array">
  Liste des clips / séquences en cours de génération (un élément par image
  sélectionnée). Chaque élément contient `id`, `url`, `effect`, `format`,
  `category`, `text`, `status`.
</ResponseField>

<ResponseField name="analysis" type="object">
  Résultat de l’analyse IA (sélections).
</ResponseField>

<ResponseField name="creditsTotal" type="number">
  Crédits restants.
</ResponseField>

<ResponseField name="creditsUsed" type="number">
  Crédits utilisés.
</ResponseField>

#### 400 — Validation error

Renvoyé si le corps de requête est invalide (ex : `image_urls` vide, URL invalide, description trop courte, etc.).

#### 401 — Unauthorized

Renvoi si `x-api-key` manquant ou invalide.

#### 500 — Server error

Erreur serveur (ex : échec d’analyse IA, erreur interne).

### Exemple (curl)

```bash theme={null}
curl --request POST \
  --url 'https://iacrea.com/api/video-editor/generate/video/auto' \
  --header 'x-api-key: VOTRE_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image_urls": [
      "https://exemple.com/1.jpg",
      "https://exemple.com/2.jpg"
    ],
    "description": "Appartement lumineux avec terrasse, proche centre-ville.",
    "format": "landscape",
    "webhookUrl": "https://votre-app.com/webhooks/iacrea/video-auto"
  }'
```

## 2) Suivre une génération (polling)

<ParamField path="GET /api/video-editor/generate/video/auto/{id}" />

### En-têtes

<ParamField header="x-api-key" type="string" required>
  Votre clé API IACrea
</ParamField>

### Réponses (principales)

Ce endpoint est **idempotent** et peut être appelé régulièrement (polling). Il renvoie un objet JSON avec un champ `status` et, selon le statut, des champs additionnels.

#### 200 — `status: "GENERATING_VIDEO"`

La génération des clips (séquences) est en cours. Retourne aussi les crédits et `generatedContent`.

#### 200 — `status: "START_RENDERING_VIDEO"`

Toutes les séquences sont prêtes et le rendu final démarre.

* `progress: 0`

#### 200 — `status: "RENDERING_VIDEO"`

Rendu final en cours.

* `progress`: nombre entre 0 et 1 (ou 0–100 selon votre implémentation côté client, à afficher tel quel).

#### 200 — `status: "DONE"`

Vidéo finale disponible.

* `url`: URL de la vidéo
* `generatedContent`: détails des séquences
* `creditsTotal`, `creditsUsed`

#### 200 — `status: "PENDING"`

État transitoire. Peut aussi être renvoyé lorsqu’une séquence est en erreur et qu’une régénération est relancée côté serveur.

#### 4xx/5xx

* `401` si API key manquante/invalide
* `404` si `id` inexistant
* `500` en cas d’erreur serveur

### Exemple (curl)

```bash theme={null}
curl --request GET \
  --url 'https://iacrea.com/api/video-editor/generate/video/auto/ID_RETOURNE_PAR_LE_POST' \
  --header 'x-api-key: VOTRE_API_KEY'
```

## Webhook (optionnel)

Si `webhookUrl` est fourni au moment du `POST`, IACrea appellera votre endpoint quand la vidéo finale est prête :

* Méthode : `POST`
* Header : `Content-Type: application/json`
* Body :

```json theme={null}
{
  "id": "ID_DE_LA_GENERATION",
  "status": "DONE",
  "url": "https://...mp4"
}
```

### Recommandations d’intégration

* **Polling** : appelez `GET /api/video-editor/generate/video/auto/{id}` toutes les 2–5 secondes jusqu’à `DONE` (ou `ERROR`).
* **Timeout** : prévoyez un timeout côté client (ex : 10–20 minutes) selon la durée de rendu.
* **Résilience** : si vous recevez `"PENDING"` après avoir déjà vu `"GENERATING_VIDEO"`, continuez le polling : le serveur peut relancer des séquences en erreur.