# Kartoon — documentation complète (générée le 2026-10-10)


<!-- ===== Démarrage rapide (https://docs.kartoon.io/#/demarrage) ===== -->

# Démarrage rapide

Kartoon transforme une idée écrite en **vidéo animée prête à poster** : histoire, personnages, images, animation, voix,
doublage et montage. Tout ce que fait le site se fait aussi **par API**, avec une clé.

## 1. Créer une clé

Sur **kartoon.io/api** (offre Business, ou administrateur) : *Créer une clé*, choisir ses autorisations, copier la clé.
Elle commence par `kx_live_` et ne s'affiche **qu'une fois**.

```bash
export KARTOON_API_KEY="kx_live_…"
```

## 2. Vérifier le compte

```bash
curl https://kartoon.io/api/v1/account -H "Authorization: Bearer $KARTOON_API_KEY"
```

```json
{ "id": "…", "plan": "studio", "credits_remaining": 202500,
  "credits_per_second_by_engine": { "2": 100, "1.5": 100, "2.5": 320 }, "max_parallel": 10, "max_quality": "4k" }
```

## 3. Choisir un modèle

```bash
curl https://kartoon.io/api/v1/models -H "Authorization: Bearer $KARTOON_API_KEY"
```

| `model` | Moteur | Prix | Pour |
|---|---|---|---|
| `seedance-2.5` *(défaut)* | Kartoon 2.5 | 320 crédits/s | le meilleur jeu d'acteur, les pubs, les plans longs |
| `kling-3` | Kartoon 2.0 | 100 crédits/s | moins cher, image très nette (4K selon l'offre) |
| `wan-3-prime` | Kartoon 1.5 | 100 crédits/s | pipeline 2.5 avec clips Wan 3.0 Prime |

## 4. Lancer une vidéo

```bash
curl -X POST https://kartoon.io/api/v1/videos \
  -H "Authorization: Bearer $KARTOON_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Un chat qui découvre la neige pour la première fois","duration":20,"language":"French","model":"seedance-2.5"}'
```

Réponse `202` en quelques secondes :

```json
{ "id": "g1791700000000api3f2a1c", "kind": "video", "status": "queued", "model": "seedance-2.5",
  "resolution": "1080p", "credits_estimated": 6400, "status_url": "/api/v1/videos/g1791700000000api3f2a1c" }
```

## 5. Suivre, puis télécharger

Une génération prend en général **13 à 27 minutes**. Interroger toutes les 30 à 60 s :

```bash
curl https://kartoon.io/api/v1/videos/g1791700000000api3f2a1c -H "Authorization: Bearer $KARTOON_API_KEY"
```

Quand `status` vaut `done`, `video.mp4_url` est un MP4 1080p H.264 signé (valable 3 h au moins), prêt pour
Instagram, TikTok ou un site. La vidéo est aussi dans **Mes vidéos** sur le site.

## 6. Une pub pour un produit

Ajoutez `product` (nom, description, 1 à 4 photos https) ou `product_id` (produit déjà dans la bibliothèque) : c'est une
pub du **Marketing Studio**.

```json
{ "prompt": "Voix off : français. Une maman débordée découvre le produit.", "duration": 30,
  "product": { "name": "Somnia", "description": "Gummies sommeil", "photos": ["https://…/somnia.jpg"] } }
```

## Pour aller plus loin

- [Référence de l'API](#/api) — chaque route, chaque champ, chaque erreur.
- [Guide pour agents IA](#/agent) — tout ce qu'un agent doit savoir pour piloter Kartoon seul.
- [Tout le site par API](#/site) — les 81 routes du site, au nom du compte.
- [Architecture](#/architecture) — comment Kartoon est construit, de bout en bout.
- Pour un LLM : [llms-full.txt](/llms-full.txt) — toute la doc en un seul fichier texte.


<!-- ===== Référence de l'API (https://docs.kartoon.io/#/api) ===== -->

# API Kartoon v1

Lancer et suivre des vidéos Kartoon par programme (agent de croissance, intégrations des clients Business).
Mise en service le 6 octobre 2026. Code : `app/api/v1/`, clés : `lib/cles-api.ts`, tables : migration `0034_api_v1.sql`.

- **Adresse** : `https://kartoon.io/api/v1`
- **Authentification** : `Authorization: Bearer kx_live_…` (ou `x-api-key: kx_live_…`)
- **Format** : JSON. Une erreur a toujours la forme `{ "error": { "code": "…", "message": "…" } }`.
- **Coût** : une génération lancée par l'API coûte exactement comme sur le site, au tarif du modèle choisi
  (`seedance-2.5` : 320 crédits par seconde ; `kling-3` et `wan-3-prime` : 100), réservés au lancement, réglés à la
  durée réelle, rendus si la génération échoue.

## Tout le site : `/api/v1/site/<route>`

Au-delà des routes ci-dessous, **toute action du site** (projets, scripts, plans, régénération, doublage, export, persos,
éléments, univers, produits, pubs de référence, likes, remix, séries, compte…) s'appelle par
`https://kartoon.io/api/v1/site/<route>` avec la même clé, au nom du compte, exactement comme ses clics.
Catalogue complet, généré depuis le code : [Tout le site par API](#/site).

## Clés

Créées depuis **Compte → API** (offre Business et administrateurs). La clé n'est affichée **qu'une fois** ; Kartoon
n'en garde que l'empreinte. Une clé ouvre le compte et ses crédits : la garder côté serveur, la révoquer au moindre
doute (effet en moins d'une minute). 10 clés actives au plus par compte.

Routes de gestion (session du site connectée, **jamais** une clé — c'est la page kartoon.io/api qui les appelle) :

| Route | Rôle |
|---|---|
| `GET /api/v1/keys` | les clés du compte (préfixe, 4 derniers caractères, autorisations, expiration, dernière utilisation) |
| `POST /api/v1/keys` `{ "name", "scopes"?, "expires_in_days"? }` | crée une clé ; `scopes` absent = toutes les autorisations ; `expires_in_days` 1-3650 ou `"never"` |
| `POST /api/v1/keys/{id}/rotate` `{ "grace_hours"? }` | nouvelle valeur (rendue une fois), mêmes réglages ; l'ancienne reste valable `grace_hours` (0-72, défaut 24) |
| `DELETE /api/v1/keys/{id}` | révoque (effet en moins d'une minute) ; `?remove=1` supprime une clé déjà révoquée |

### Autorisations (`scopes`)

| Autorisation | Ouvre |
|---|---|
| `generations:write` | `POST /videos`, et via `/site` : produce, projets, régénérations, doublage, séries, remix, scripts, plans |
| `library:read` | toutes les lectures (`GET`) : vidéos, modèles, persos, produits, Instagram, `/site` en lecture |
| `library:write` | les écritures de bibliothèque (likes, Instagram, WhatsApp, le reste de `/site`) |
| `assets:write` | `POST /products`, et via `/site` : persos, éléments, univers, produits, références, envois de fichiers |
| `credits:read` | `GET /account`, et via `/site` : crédits |

Une requête hors des autorisations de la clé reçoit `403 scope_required` avec `scope` = l'autorisation qui manque.

## Limites

| Opération | Limite par clé |
|---|---|
| `POST /videos` | 10 par minute |
| lectures (`GET`) | 120 par minute |
| générations simultanées | celles de l'offre (Business : 10) — au-delà, elles attendent leur tour |
| `POST /instagram/accounts/{id}/reels` | 10 par minute (et le quota d'Instagram : publications par API sur 24 h glissantes) |
| `GET /instagram/accounts/{id}`, `…/media` | 60 par minute ; `…/media?insights=1` : 6 par minute |
| `GET /instagram/posts/{id}/insights` | 30 par minute |

## `GET /account`

Le compte de la clé.

```json
{ "id": "…", "plan": "studio", "credits_remaining": 202500, "credits_per_second": 100, "max_parallel": 10, "max_quality": "4k" }
```

## `GET /models` — les modèles au choix

```json
{ "default": "seedance-2.5", "data": [
  { "id": "seedance-2.5", "engine": "2.5", "name": "Kartoon 2.5 — Seedance 2.5", "video_model": "bytedance/seedance-2.5/reference-to-video",
    "resolutions": ["720p", "1080p"], "default_resolution": "1080p", "native_audio": true, "credits_per_second": 320, "best_for": "…" },
  { "id": "kling-3", "engine": "2", "credits_per_second": 100, "…": "…" },
  { "id": "wan-3-prime", "engine": "1.5", "credits_per_second": 100, "…": "…" } ] }
```

- **`seedance-2.5`** (défaut) — Kartoon 2.5 : clips Seedance 2.5 en mode références (fiches des persos jointes à chaque
  clip), plans enchaînés jusqu'à 30 s en une seule prise, meilleur jeu et synchro labiale. Les pubs tournent ici.
- **`kling-3`** — Kartoon 2.0 : clips Kling 3 de 3 à 10 s ; en `1080p`, 4K native pour les offres Pro et Business ;
  `720p` = le plus rapide et le moins cher.
- **`wan-3-prime`** — Kartoon 1.5 : le pipeline 2.5 avec des clips Wan 3.0 Prime, dialogues dans la langue d'origine.

## `GET /characters?universe=…`

Les persos de la bibliothèque du compte (créés sur le site, ou repris de la communauté) : `id`, `name` (le nom exact à
donner dans `POST /videos` → `characters`), `universe`, `source` (`own` / `community`), `description`, `videos` (nombre de
vidéos où il a joué), `image_url`. Plusieurs persos du même nom : `POST /videos` prend celui qui a joué dans le plus de vidéos
(la réponse 202 liste les persos retenus sous `characters`) ; donner l'`id` pour en viser un précis.

## `POST /products` — ajouter un produit à la bibliothèque

`{ "name": "…", "description": "…", "url": "https://…", "photos": ["https://…"] }` (1 à 4 photos) → `201` avec son `id`.
Le produit rejoint « Produits » du Marketing Studio et se réutilise ensuite dans `POST /videos` par son id ou son nom
exact (`product_id`). 20 par minute.

## `GET /products`

Les produits de la bibliothèque (page Marketing Studio). Leur `id` sert à lancer une pub.

```json
{ "data": [ { "id": "5de3c66b040b", "name": "Fitmo", "description": "…", "photos": 2 } ] }
```

## `POST /videos` — lancer

| Champ | Type | Défaut | Rôle |
|---|---|---|---|
| `prompt` | texte (3-3000) | — | la demande, comme dans le studio |
| `duration` | entier 3-300 (s) | 30 | durée visée (et facturée) |
| `aspect` | `9:16`, `16:9`, `1:1`, `4:5`, … | `9:16` | format |
| `language` | `auto`, `French`, `English`, … | `auto` | langue (auto = celle du prompt) |
| `style` | `pixar`, `clay`, `animal`, … | `pixar` | univers |
| `model` | `seedance-2.5`, `kling-3`, `wan-3-prime` | `seedance-2.5` | modèle vidéo (`GET /models`) |
| `engine` | `2.5`, `2`, `1.5` | — | ancien nom du choix de moteur (`2.5` = seedance-2.5, `2` = kling-3, `1.5` = wan-3-prime) ; avec `model`, ils doivent concorder |
| `resolution` | `1080p`, `720p` | `1080p` | définition |
| `voice` | `narrator`, `dialogue`, `mix`, `none` | lu dans le prompt, sinon choisi par l'IA | **pubs** : voix off, persos qui parlent, les deux (scènes narrées + scènes dialoguées), ou aucune parole |
| `characters` | liste de noms (1-6) | — | **persos de ta bibliothèque** (`GET /characters`), par leur **nom exact** (ou id) ; la vidéo prend leur univers (`style` ignoré) ; 2 au plus dans une pub. Nom inconnu : `404 character_not_found` avec `available` |
| `product_id` | texte | — | **pub** pour un produit de la bibliothèque : son **id ou son nom exact** (`GET /products`) |
| `product` | `{ name, description, photos: [https…] }` | — | **pub** pour un produit fourni (1-4 photos) |

Sans produit : une vidéo (histoire). Avec `product_id` ou `product` : une pub (Marketing Studio).

Réponse **202** dès que la génération est partie (quelques secondes) :

```json
{ "id": "ad1791300000000api3f2a1c", "kind": "ad", "status": "queued", "model": "seedance-2.5", "resolution": "1080p",
  "credits_estimated": 9600, "status_url": "/api/v1/videos/ad1791300000000api3f2a1c" }
```

**La voix d'une pub, sans le champ `voice`** : le moteur lit le prompt. « Voix off : français » (ou des lignes `VO : "…"`)
→ voix off, dite **mot pour mot** si le texte est écrit ; « les persos parlent », « que des dialogues » ou des répliques
écrites `Nom : "…"` → dialogues ; voix off **et** persos qui parlent → `mix` ; « pub muette », « sans parole »,
« Voix off : aucune » → rien. Sinon l'IA choisit ce qui vend le mieux le produit.

Refus (rien n'est débité) : `400 invalid_request`, `402 insufficient_credits` (avec `credits_remaining` et
`credits_needed`), `403 style_reserved`, `404 product_not_found`, `429 rate_limited`, `503 voices_unavailable`,
`422 generation_refused`.

## `GET /videos/{id}` — suivre

```json
{
  "id": "…", "status": "running", "progress": 46, "step": "🎬 Animation 2/5", "created_at": "…",
  "video_id": null, "error": null, "warning": null, "video": null
}
```

`status` : `queued` (en file), `running`, `done`, `error`. Une génération dure en général 13 à 27 minutes : interroger
toutes les 30 à 60 s suffit. Terminée :

```json
{
  "id": "…", "status": "done", "progress": 100, "video_id": "a8e2e46f-…",
  "video": {
    "id": "a8e2e46f-…", "title": "…", "duration_s": 21.7, "width": 1080, "height": 1920,
    "mp4_url": "https://…", "original_url": "https://…", "thumbnail_url": "https://…",
    "urls_expire_at": "…"
  }
}
```

- `mp4_url` : copie **1080p H.264** (≤ 8 Mbit/s, démarrage rapide) — celle à donner à Instagram, TikTok ou un site.
  Si elle n'est pas encore prête, c'est l'original (la copie se fabrique en fond).
- `original_url` : le fichier d'origine (jusqu'en 4K).
- Adresses signées, valables **3 h au moins** (`urls_expire_at`) : redemander l'état pour en avoir de nouvelles.
- Échec : `status: "error"`, `error.message`, et `error.credits_refunded` quand les crédits ont été rendus.
- `warning` : la vidéo est publiée **mais** le moteur signale un défaut — par exemple un doublage raté (voix restées en
  anglais). À vérifier avant de publier la vidéo ailleurs. `null` sinon.

La vidéo apparaît aussi dans **Mes vidéos** du compte, comme une génération faite sur le site.

## `GET /videos?limit=20` — historique

Les générations lancées par l'API (100 au plus, les plus récentes d'abord) : `id`, `status`, `progress`, `video_id`,
`error`, `created_at`. Les adresses de téléchargement : `GET /videos/{id}`.

## Instagram

Publier les vidéos Kartoon en Reels sur des comptes Instagram, et lire ce qui marche. Mise en service le 7 octobre 2026.
Code : `app/api/v1/instagram/`, `lib/instagram.ts`, `lib/instagram-boucles.ts` ; tables : migration `0037_instagram.sql`.

- **Connexion** : sur le site, **Compte → Instagram** (offre Business et administrateurs), par la page d'autorisation
  d'Instagram (OAuth « Instagram Login »). Compte **professionnel** exigé (Créateur ou Business). L'API ne voit jamais
  un jeton Instagram : il est stocké chiffré et rafraîchi par le serveur (60 jours, renouvelé 15 jours avant la fin).
- **Tant que l'app Meta n'est pas validée par Meta** (accès standard), seuls les comptes ajoutés à l'app dans son tableau
  de bord (rôle « testeur Instagram ») peuvent se connecter.
- Un compte dont Instagram refuse le jeton passe en `reconnect_required` (code `409`) : le reconnecter depuis la page.
- **Par Ayrshare (depuis le 7 octobre 2026, dès que `AYRSHARE_API_KEY` est posée)** : la connexion passe par la page de
  liaison d'Ayrshare (on s'y connecte avec ses identifiants Instagram ; pas d'app Meta à créer). Un compte Instagram =
  un « profil » Ayrshare (offre Launch : 10). `provider` vaut alors `ayrshare` (sinon `meta`). Même API, mêmes routes ;
  en plus : les statistiques du compte (`/analytics`) et les « trial reels » (`trial`). `lib/ayrshare.ts`,
  `lib/instagram-fournisseur.ts`, migration `0038`.

### `GET /instagram/accounts`

Les comptes connectés : `id` (à utiliser dans les routes), `instagram_user_id`, `provider` (`meta` ou `ayrshare`), `username`, `name`, `account_type`,
`profile_picture_url`, `followers_count`, `status` (`active` ou `reconnect_required`), `token_expires_at`,
`last_error`, `connected_at`.

### `GET /instagram/accounts/{id}`

Le compte lu **en direct** chez Instagram (abonnés recopiés), plus `media_count` et
`publishing_quota` : `{ "used": 3, "limit": 100, "window_hours": 24 }` (`null` si Instagram ne l'a pas donné).

### `POST /instagram/accounts/{id}/reels` — publier

```json
{ "video_id": "…", "caption": "Le chat découvre la neige ❄️ #chat", "share_to_feed": true, "cover_offset_ms": 1500 }
```

| Champ | Défaut | Valeurs |
|---|---|---|
| `video_id` | — (obligatoire) | une vidéo de ce compte Kartoon (`video.id` de `GET /videos/{id}`), de 3 s à 15 min |
| `caption` | `""` | 2 200 caractères, 30 hashtags et 20 mentions au plus (limites d'Instagram) |
| `share_to_feed` | `true` | le Reel apparaît aussi dans la grille du profil |
| `cover_offset_ms` | Instagram choisit | image de couverture : instant de la vidéo, en millisecondes |
| `allow_duplicate` | `false` | `true` pour republier une vidéo déjà publiée sur ce compte (sinon `409 already_posted`) |
| `trial` | `false` | « Trial reel » : montré d'abord aux **non-abonnés** seulement (A/B tests). Comptes `ayrshare` seulement (sinon `422 trial_not_supported`) |
| `trial_graduation` | `auto` | `auto` : Instagram le partage seul aux abonnés s'il marche (dans les 72 h) ; `manual` : à faire dans l'app |

**Plafond** : 20 publications par compte sur 24 h glissantes (`KARTOON_IG_POSTS_JOUR`), en cours et publiées comptées —
au-delà, `429 daily_post_limit` avec `used` et `limit`. Instagram, lui, plafonne à 50.

Réponse immédiate `202` : le post (forme ci-dessous) avec `status: "publishing"` et `status_url`. La publication tourne
sur le serveur : copie 1080p H.264 de la vidéo, envoi à Instagram avec l'étiquette **« contenu IA »** d'Instagram,
traitement par Instagram (1 à 15 min), publication. Un redémarrage du serveur ne la perd pas et ne la publie jamais deux
fois. Refus : `404 video_not_found`, `409 already_posted` (avec `post_id`), `422 video_not_allowed`,
`429 instagram_quota_reached`, `409 reconnect_required`.

### `GET /instagram/posts/{id}` — suivre un Reel

```json
{
  "id": "…", "account_id": "…", "video_id": "…", "status": "published",
  "caption": "…", "share_to_feed": true, "cover_offset_ms": 1500, "ai_label": true,
  "instagram_media_id": "1789…", "permalink": "https://www.instagram.com/reel/…", "published_at": "2026-10-07T…",
  "error": null, "warning": null, "video_duration_s": 20,
  "metrics": { "views": 12840, "reach": 9120, "likes": 611, "comments": 23, "shares": 88, "saved": 41,
               "total_interactions": 763, "ig_reels_avg_watch_time": 7400, "ig_reels_video_view_total_time": 95016000,
               "reels_skip_rate": 38.5 },
  "metrics_at": "2026-10-08T…",
  "indicators": { "hook_rate": 61.5, "avg_watch_ratio": 37, "views_per_reach": 1.41,
                  "shares_per_1000_views": 6.9, "saves_per_1000_views": 3.2 },
  "snapshots": [ { "age_hours": 24, "taken_at": "…", "metrics": { … }, "indicators": { … } } ],
  "snapshot_schedule_hours": [24, 48, 168, 720],
  "created_at": "2026-10-07T…"
}
```

- `status` : `publishing` → `published`, ou `error` (`error.message` dit pourquoi : vidéo refusée par Instagram,
  traitement trop long, compte à reconnecter…).
- `ai_label` : l'étiquette « contenu IA » a-t-elle été posée (`null` avant l'envoi à Instagram).
- **Relevés automatiques** : 24 h, 48 h, 7 jours et 30 jours après la publication (`snapshots`). Instagram consolide
  ses chiffres jusqu'à 48 h.
- **Indicateurs** (l'API d'Instagram ne donne pas de courbe de rétention) :
  - `hook_rate` ≈ % de vues **non** passées avant 3 s (`100 − reels_skip_rate`) ;
  - `avg_watch_ratio` ≈ temps moyen regardé ÷ durée de la vidéo, en % (au-delà de 100 % : relectures) ;
  - `views_per_reach` : vues par compte touché (relectures, partages) ;
  - `shares_per_1000_views`, `saves_per_1000_views`.
- Une métrique qu'Instagram ne fournit pas (encore) pour ce compte est simplement absente de `metrics`.
  ⚠️ L'unité de `ig_reels_avg_watch_time` n'est pas documentée par Meta : millisecondes supposées, à confirmer sur les
  premiers relevés réels.

### `GET /instagram/posts/{id}/insights`

Relit **maintenant** les statistiques chez Instagram ; rend le post à jour. `409 not_published` avant la publication.

### `GET /instagram/posts?account_id=…&status=…&limit=20&before=…`

Les Reels publiés par Kartoon (100 au plus par page, les plus récents d'abord), même forme que ci-dessus sans
`snapshots`. `status` : `publishing`, `published` ou `error`. Page suivante : `before` = `created_at` du dernier.

### `GET /instagram/accounts/{id}/media?limit=25&after=…&insights=1`

Toutes les publications du compte, y compris celles faites **hors de Kartoon** (la matière de l'analyse des anciennes
vidéos) : `id`, `caption`, `media_type`, `media_product_type` (`REELS`, `FEED`…), `permalink`, `timestamp`,
`like_count`, `comments_count`, `thumbnail_url`, et `kartoon_post_id` / `kartoon_video_id` quand c'est Kartoon qui
l'a publiée. `insights=1` : `metrics` et `indicators` de chaque Reel, lus en direct (25 par page au plus ;
`metrics_error` si Instagram n'a pas répondu pour l'un d'eux). Page suivante : `after` = `next_cursor` (`null` à la fin).

### `GET /instagram/accounts/{id}/analytics?daily=1&history=30`

Comptes `ayrshare` seulement. Les statistiques du **compte**, lues en direct : `followersCount`, `followsCount`,
`mediaCount`, `reachCount`, `viewsCount`, `shareCount`, `likeCount`, `commentsCount`, et la démographie
(`audienceGenderAge`, `audienceCountry`, `audienceCity`, et leurs variantes `…EngagedAudienceDemographics` — Instagram
ne les donne qu'à partir de 100 abonnés). `daily=1` : séries jour par jour. `history=N` : les N derniers relevés
quotidiens gardés par Kartoon (un par jour et par compte, automatiquement) — la courbe de croissance. 6 appels par
minute au plus.

### `POST /instagram/accounts/{id}/ayrshare` — tout le reste d'Ayrshare

Comptes `ayrshare` seulement. Relais vers l'API d'Ayrshare (https://www.ayrshare.com/docs) pour ce compte :
`{ "method": "GET", "path": "/comments/…", "query": {…}, "body": {…} }` → `{ "ok": true, "ayrshare": <réponse> }`.
Chemins permis : `/comments`, `/messages`, `/analytics`, `/history`, `/media`, `/hashtags`, `/brand` (écoute de marques :
comptes concurrents), `/generate` (transcription, sentiment…), `/links`, `/validate`, et en lecture seule `/user`,
`/post`, `/automations`. Publier passe toujours par `…/reels` (plafond, suivi) ; `/profiles` et l'écriture sur `/post`
sont refusés (`403 path_not_allowed`). Une erreur d'Ayrshare revient en `ayrshare_error` avec `ayrshare_code`. 60 appels par minute.

### `GET /instagram/accounts/{id}/archive?type=…&since=…&before=…&limit=100`

Comptes `ayrshare`. **Tout ce qu'Ayrshare a rendu sur le compte, recopié chez Kartoon** (rien n'est perdu, même si
Ayrshare ou Instagram l'oublient) : `type` = `message` (messages privés reçus et envoyés, toutes les heures),
`commentaire` (commentaires et réponses des publications de moins de 30 jours, toutes les 6 h), `media` (toutes les
publications du compte, même hors Kartoon, toutes les 6 h), `stats_media` (statistiques COMPLÈTES de chaque publication
de moins de 30 jours, une par jour : clé `<id>:<AAAA-MM-JJ>`). Réponse : `{ type, data: [{ key, at, first_seen_at,
updated_at, data }] }`, des plus récents aux plus anciens ; page suivante : `before` = `at` du dernier. 500 par page au
plus.

Les relevés automatiques d'un Reel (`GET /instagram/posts/{id}` → `snapshots`) portent aussi `raw` : la réponse
complète d'Ayrshare à ce moment-là et les commentaires du Reel. Les relevés quotidiens du compte (`/analytics?history=N`)
portent en plus `_quotidien` (séries jour par jour), `_abonnes_en_ligne` (heures où les abonnés sont connectés) et
`_compte` (état du compte, quota).

### `POST /agent/whatsapp` — écrire dans le groupe WhatsApp de l'équipe

`{ "account_id": "<compte Instagram Kartoon>", "text": "…" }` → le texte part dans le groupe WhatsApp relié à ce compte
(page admin `/admin-whatsapp.html`, passerelle `lib/whatsapp.ts`). `404 no_group` si aucun groupe n'est relié,
`503 whatsapp_unavailable` si le numéro est déconnecté. 20 par minute. C'est la route du bref de l'agent de croissance
et de ses réponses à l'équipe (les messages de l'équipe le réveillent : `lib/agent-pont.ts`).

### Erreurs propres à Instagram

| Code | Statut | Sens |
|---|---|---|
| `account_not_found` | 404 | compte inconnu, déconnecté, ou d'un autre compte Kartoon |
| `reconnect_required` | 409 | Instagram refuse le jeton : reconnecter le compte depuis la page Compte → Instagram |
| `instagram_rate_limited` | 429 | Instagram limite les appels pour ce compte : réessayer plus tard |
| `instagram_refused` | 422 | Instagram a refusé la demande (`message` et `instagram_code` d'Instagram) |
| `instagram_unavailable` | 503 | Instagram ne répond pas : réessayer |

## Exemple

```bash
curl -X POST https://kartoon.io/api/v1/videos \
  -H "Authorization: Bearer $KARTOON_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Un chat qui découvre la neige pour la première fois","duration":20,"language":"French"}'
```

## À venir

Webhook de fin de génération (plus besoin d'interroger), analyse d'une vidéo (transcription, hook, structure).


<!-- ===== Guide pour agents IA (https://docs.kartoon.io/#/agent) ===== -->

# Guide pour agents IA

Ce guide s'adresse à un **agent** (Claude, GPT, un script autonome…) qui reçoit une clé Kartoon et doit produire,
suivre et publier des vidéos **sans humain**. Il dit ce que Kartoon sait faire, comment le lui demander, ce que ça coûte,
combien de temps ça prend, et comment réagir à chaque réponse. La référence exhaustive des champs est dans
[Référence de l'API](#/api).

> **Version texte pour un LLM** : `https://docs.kartoon.io/llms-full.txt` contient toute cette documentation en un
> seul fichier. Donnez-la en contexte à votre agent.

## 1. Le modèle mental

- **Une génération = un film fini.** Vous donnez une idée (le *prompt*) ; Kartoon écrit le script, crée les persos,
  dessine les images de départ, anime chaque plan, enregistre les voix, double, monte, et publie la vidéo dans
  **Mes vidéos** du compte. Vous ne pilotez pas les étapes : vous pilotez l'**intention**.
- **Deux sortes** : une **vidéo** (une histoire, un sketch, un épisode) — ou une **pub** dès qu'un produit est donné
  (`product` ou `product_id`) : le Marketing Studio écrit alors une publicité pour ce produit.
- **C'est long et ça coûte** : 13 à 27 minutes par génération ; de 100 à 320 crédits par seconde de vidéo. Ne lancez
  jamais « pour voir » en boucle.
- **Asynchrone** : `POST /videos` répond en quelques secondes (`202` + un `id`), puis vous interrogez
  `GET /videos/{id}` jusqu'à `done` ou `error`.
- **Tout le site est appelable** : au-delà des routes `/api/v1/*` documentées, `/api/v1/site/<route>` relaie n'importe
  quelle action du site au nom du compte (régénérer un plan, doubler une vidéo, créer un perso…). Voir [Tout le site](#/site).

## 2. Ce que l'agent peut faire

| Besoin | Appel |
|---|---|
| Connaître son budget, son offre, ses générations en parallèle | `GET /account` |
| Choisir un modèle et son prix | `GET /models` |
| Lancer une vidéo ou une pub | `POST /videos` |
| Suivre et récupérer le MP4 | `GET /videos/{id}` |
| Retrouver ce qui a été lancé (après un redémarrage de l'agent) | `GET /videos?limit=50` |
| Lister / créer les produits | `GET /products`, `POST /products` |
| Utiliser des persos récurrents (mascotte, héros de série) | `GET /characters` puis `characters: ["Nom exact"]` |
| Publier en Reel Instagram, lire les statistiques | `/instagram/*` |
| Tout le reste du site (régénérer un plan, doubler, séries, persos…) | `/site/<route>` |

## 3. La boucle de base

```js
const API = "https://kartoon.io/api/v1";
const H = { Authorization: `Bearer ${process.env.KARTOON_API_KEY}`, "Content-Type": "application/json" };

// 1. budget
const compte = await (await fetch(`${API}/account`, { headers: H })).json();

// 2. lancer
const r = await fetch(`${API}/videos`, { method: "POST", headers: H, body: JSON.stringify({
  prompt: "Un chat qui découvre la neige pour la première fois. Voix off : français, ton tendre.",
  duration: 20, language: "French", model: "seedance-2.5", aspect: "9:16",
}) });
const lancement = await r.json();
if (r.status !== 202) throw new Error(`${lancement.error.code} : ${lancement.error.message}`);

// 3. attendre (30-60 s entre deux lectures)
let etat;
do {
  await new Promise((ok) => setTimeout(ok, 45_000));
  etat = await (await fetch(`${API}/videos/${lancement.id}`, { headers: H })).json();
} while (etat.status === "queued" || etat.status === "running");

// 4. résultat
if (etat.status === "done") console.log(etat.video.mp4_url, etat.warning);
else console.log("échec", etat.error); // crédits rendus : etat.error.credits_refunded
```

## 4. Budget et coût

- Coût = **durée × tarif du modèle** : `seedance-2.5` 320 crédits/s, `kling-3` et `wan-3-prime` 100 crédits/s.
  Une vidéo de 30 s en `seedance-2.5` = 9 600 crédits.
- Les crédits sont **réservés au lancement** (`credits_estimated`), puis **réglés à la durée réelle** (quelques
  secondes de plus ou de moins), et **rendus** si la génération échoue.
- Avant de lancer : `credits_remaining ≥ durée × credits_per_second`. Sinon `402 insufficient_credits`
  (avec `credits_needed`) — rien n'est débité.
- **Parallèle** : `max_parallel` générations en même temps (Business : 10). Au-delà, elles attendent leur tour
  (`status: "queued"`), elles ne sont pas refusées.

## 5. Bien écrire le prompt

Le prompt est lu par un scénariste IA (Claude). Il suit le client **à la lettre** : tout ce qui est écrit est respecté,
tout ce qui ne l'est pas est inventé au mieux.

**Les bons réflexes**
- **Dire l'histoire, pas la technique** : qui, où, ce qui arrive, la chute. « Une mamie qui se bat contre son robot
  aspirateur et finit par l'adopter » vaut mieux que « plan large, travelling ».
- **Donner le ton** : drôle, tendre, absurde, dramatique, confession intime…
- **Découper si vous avez une idée précise** : `[0-4s — HOOK] …`, `[4-14s] …` — chaque temps garde sa scène.
- **Écrire les mots s'ils comptent** : une voix off écrite (`VO : "…"`) est dite **mot pour mot** ; une réplique
  `Léa : "…"` est dite par Léa.
- **La langue** : `language: "French"` (ou laisser `auto` : la langue du prompt). Les voix sont tournées puis doublées
  dans la langue demandée.

**La voix d'une pub** (le champ `voice` force le choix ; sinon le prompt décide) :

| Vous écrivez | Résultat |
|---|---|
| `Voix off : français` ou des lignes `VO : "…"` | voix off (personne ne parle à l'écran) |
| « les persos parlent », « que des dialogues », des répliques `Nom : "…"` | dialogues joués à l'image |
| voix off **et** persos qui parlent | `mix` : scènes narrées + scènes dialoguées |
| « pub muette », « sans parole », `Voix off : aucune` | aucune parole, seulement l'ambiance |

**Durée** : 3 à 300 s. Une pub de 20-60 s est le format qui marche ; une vidéo histoire de 20-90 s.
**Format** : `9:16` (Reels, TikTok, Shorts) par défaut ; `16:9`, `1:1`, `4:5`… disponibles.
**Univers** (`style`) : `pixar` (film animé 3D, défaut), `clay` (pâte à modeler), `disney2d` (conte de fées), `yarn`
(tout en laine), `barbie` (poupées glamour), `toybrick` (briques à emboîter), `blockverse` (Minecraft), `lowpoly`
(low poly cinéma). Des univers personnalisés du compte s'ajoutent (voir `/site/studio/universes`).

## 6. Pubs : le produit

- **Produit fourni** : `product: { name, description, photos: ["https://…"] }` (1 à 4 photos, https, accessibles
  publiquement). Le produit est dessiné **d'après ses photos** (forme, couleurs, étiquette).
- **Produit de la bibliothèque** : `POST /products` une fois, puis `product_id: "<id ou nom exact>"` à chaque pub.
- **Une photo avec un visage humain** (mannequin, influenceur) peut être refusée par le modèle vidéo : préférez des
  photos du produit seul.
- La description doit dire **ce que fait le produit et pour qui** : c'est la matière de l'argumentaire.

## 7. Persos récurrents

`GET /characters` liste les persos du compte (créés sur le site ou repris de la communauté). Donnez leur **nom exact**
dans `characters` (6 au plus ; 2 dans une pub) : ils jouent dans la vidéo, avec leur visage et leur univers (le `style`
est alors ignoré). Un nom inconnu → `404 character_not_found` avec la liste `available`. Plusieurs persos du même nom →
celui qui a joué dans le plus de vidéos ; donnez l'`id` pour en viser un précis.

## 8. Suivre une génération

`GET /videos/{id}` → `status` : `queued` → `running` (`progress` 0-100, `step` lisible : « 🖼️ Scènes 3/9 »,
« 🎬 Animation 2/5 », « 🎬 Montage ») → `done` ou `error`.

- **Cadence** : toutes les 30 à 60 s. Pas plus souvent (120 lectures/min par clé au plus).
- **`done`** : `video.mp4_url` (1080p H.264, ≤ 8 Mbit/s — à donner aux réseaux), `video.original_url` (jusqu'en 4K),
  `thumbnail_url`. Adresses **signées 3 h au moins** : relisez l'état pour en avoir de fraîches, ne les stockez pas.
- **`warning`** non nul : la vidéo est livrée mais un défaut est signalé (ex. doublage raté, voix restées en anglais).
  À vérifier avant de publier ailleurs.
- **`error`** : `error.message` dit pourquoi ; `error.credits_refunded` si les crédits sont rendus.
- **Une mise à jour du serveur ne perd pas la génération** : elle reprend seule. Un `running` qui stagne quelques
  minutes n'est pas un échec.

## 9. Erreurs et quoi faire

| Statut / code | Sens | Réaction de l'agent |
|---|---|---|
| `400 invalid_request` | champ invalide (`message` dit lequel) | corriger la requête, ne pas réessayer telle quelle |
| `401 unauthorized` | clé absente, inconnue, révoquée ou expirée | s'arrêter, prévenir un humain |
| `402 insufficient_credits` | budget insuffisant | réduire la durée, passer à `kling-3`, ou attendre une recharge |
| `403 scope_required` | la clé n'a pas l'autorisation (`scope`) | s'arrêter, demander une clé avec cette autorisation |
| `403 style_reserved` | univers réservé | prendre un univers public |
| `404 product_not_found` / `character_not_found` | nom inexact | choisir dans `available` |
| `409 conflict` | identifiant déjà pris | relancer (nouvel identifiant) |
| `422 generation_refused` | le moteur a refusé la demande (contenu, prompt vide…) | reformuler |
| `429 rate_limited` | trop d'appels | attendre une minute |
| `503 voices_unavailable` / `unavailable` | service momentanément indisponible | réessayer dans 5-10 min |

**Jamais de double lancement** : si `POST /videos` expire côté agent (réseau), ne relancez pas à l'aveugle — lisez
`GET /videos?limit=10` : la génération est peut-être partie.

## 10. Publier sur Instagram

1. Un humain connecte le compte Instagram une fois (kartoon.io → Compte → Instagram).
2. `GET /instagram/accounts` → l'`id` du compte.
3. `POST /instagram/accounts/{id}/reels` `{ "video_id": "<video.id>", "caption": "…" }` → `202`, puis
   `GET /instagram/posts/{postId}` jusqu'à `published` (1 à 15 min).
4. Statistiques relevées seules à 24 h, 48 h, 7 j, 30 j (`snapshots`) ; `hook_rate`, `avg_watch_ratio`,
   `shares_per_1000_views` pour juger ce qui marche.

20 Reels par compte et par 24 h au plus. L'étiquette « contenu IA » d'Instagram est posée automatiquement.

## 11. Aller plus loin avec `/site`

Tout ce qu'un utilisateur fait en cliquant : `https://kartoon.io/api/v1/site/<route>` (même méthode, même corps que
le site). Exemples utiles :

- régénérer un plan raté d'une vidéo : `/site/plans/{id}/regenerate` ;
- doubler une vidéo existante dans une autre langue : `/site/studio/dub` ;
- créer un perso à partir d'une description ou de photos : `/site/characters/generate` ;
- lister les univers disponibles : `/site/studio/universes`.

Le catalogue complet, généré depuis le code, est dans [Tout le site par API](#/site). Les routes sensibles (mot de
passe, paiement, suppression du compte, administration) n'y sont pas.

## 12. Règles d'or pour un agent autonome

1. **Lire le budget avant chaque lancement**, et ne jamais dépasser ce qu'un humain a fixé.
2. **Un lancement = une intention claire.** Mieux vaut une vidéo bien briefée que trois essais vagues.
3. **Attendre `done`** avant de publier ; vérifier `warning`.
4. **Garder les `id`** (génération, vidéo, post) : tout se retrouve avec eux.
5. **Ne jamais exposer la clé** (logs, prompts, messages) : elle ouvre le compte et ses crédits.
6. **Réagir aux codes, pas aux messages** : les `message` sont en français et peuvent changer ; les `code` sont stables.


<!-- ===== Tout le site par API (https://docs.kartoon.io/#/site) ===== -->

# API Kartoon — tout le site (`/api/v1/site/<route>`)

Généré par `scripts/generer-doc-api-site.mjs` le 2026-10-10 — ne pas éditer à la main.

Chaque action du site s'appelle par l'API, **au nom du compte de la clé**, exactement comme ses clics : mêmes règles,
mêmes crédits, même flux en direct (SSE) pour les générations. Même authentification que l'API v1
(`Authorization: Bearer kx_live_…`). La méthode, les paramètres d'adresse et le corps passent tels quels ; la réponse
revient telle quelle. Les routes dédiées et stables de l'API v1 ([Référence de l'API](#/api)) restent à préférer quand elles existent
(`/videos`, `/characters`, `/products`, `/instagram/…`).

Exemple : `GET https://kartoon.io/api/v1/site/characters/library` = la page « Mes personnages ».

Bloquées : mot de passe et sessions, paiements et plan, RIB et versements d'affiliation, suppression du compte,
administration, routes internes du moteur. 120 appels par minute.

## Routes (81)

### `POST` /api/v1/site/account/avatar

> POST /api/account/avatar — bouton « Changer la photo » de /compte.
> La photo va dans le bucket public, et son URL est ecrite dans `profiles.avatar_url`.
> POURQUOI LA BASE ET PLUS SEULEMENT LES METADONNEES : `user_metadata.avatar_url` est REECRIT
> par Google a CHAQUE connexion OAuth. La photo televersee y survivait jusqu'a la deconnexion,
> puis disparaissait au profit de la photo du compte Google. La colonne `profiles.avatar_url`
> (migration 0015), elle, n'appartient qu'a nous. Les metadonnees restent mises a jour en
> second : elles n'ont plus valeur de verite, mais elles evitent un clignotement le temps que
> /api/me bascule sur la colonne.

### `PATCH · DELETE` /api/v1/site/account

> (pas de description dans le code)

### `GET · POST` /api/v1/site/affiliation/conditions

> (pas de description dans le code)

### `GET` /api/v1/site/affiliation

> (pas de description dans le code)

### `PATCH · DELETE` /api/v1/site/characters/{id}

> PATCH /api/characters/:id — édite un perso CUSTOM (RLS bloque les persos univers).
> La modif n'impacte que les futures vidéos : les anciennes gardent leur snapshot.
>
> DELETE /api/characters/:id — supprime un perso CUSTOM (univers protégés par RLS). */

### `GET` /api/v1/site/characters/casting

> GET /api/characters/casting[?univers=] — items SÉLECTIONNABLES pour le casting, À PLAT.
> Chaque perso = 1 item, + 1 item par variante (posés juste après leur perso de base →
> le front les affiche côte à côte). Inclut les persos commu piqués. Filtre univers optionnel.

### `POST · GET · DELETE` /api/v1/site/characters/generate

> POST /api/characters/generate — lance la génération d'un perso EN TÂCHE DE FOND (survit au départ
>   de la page). Body : { id, mode, name, desc, style, gender, photos, refImages, count? }.
>   Renvoie { id, status, kind } immédiatement — le job continue côté serveur.
>   • count absent ou 1 (comportement historique) : 1 image, puis le perso est ENREGISTRÉ en base.
>   • count 2..3 (page Personnages, sept. 2026 : « 3 propositions, tu gardes la bonne ») : le job
>     génère `count` PROPOSITIONS et n'enregistre RIEN ; la page enregistre celle que l'utilisateur
>     garde via POST /api/characters/save, puis retire le job (DELETE ?id=).
>   Débit identique dans les deux cas : CREDIT_COST.characterCreate par job, remboursé si le job
>   échoue (_charJob.ts). 402 → { error, code:"NO_CREDITS", balance, cost }.
>   L'id du body identifie le JOB (dédup double-clic, poll, DELETE) ; la clé du DÉBIT, elle, est
>   tirée par le serveur à chaque lancement : un id déjà utilisé est refusé (409), il ne peut plus
>   servir à rejouer une génération à 0 crédit.
> GET  /api/characters/generate?cost=1 → { cost, proposals } (public : c'est un tarif).
> GET  /api/characters/generate?list=1  → { jobs:[{id, meta}], proposals:[{id, meta, proposals}],
>   failed:[{id, meta, error, creditsRembourses}] } : jobs ENCORE en cours (reconnexion au
>   (re)chargement), propositions terminées pas encore choisies, et ÉCHECS pas encore retirés —
>   sans ces derniers, un perso raté page fermée ne laissait aucune trace au retour.
> GET  /api/characters/generate?id=<id> → { status, kind, character?, proposals?, error? } — poll.
> DELETE /api/characters/generate?id=<id> → retire un job TERMINÉ de ce compte (propositions traitées).

### `PATCH · DELETE` /api/v1/site/characters/library/{id}

> PATCH  /api/characters/library/[id] — renomme un perso de MA librairie (user_characters).
> DELETE /api/characters/library/[id] — le supprime (ses variantes suivent en cascade FK).
>
> Créées pour la page Personnages (design v2) : les cartes offrent Renommer / Supprimer.
> NB : la route legacy /api/characters/[id] vise l'ancienne table `characters` et ne
> touche PAS la librairie — d'où ces routes dédiées. RLS (uc_owner_all) borne déjà
> l'accès au propriétaire ; le .eq("user_id") est une ceinture supplémentaire.

### `GET` /api/v1/site/characters/library

> GET /api/characters/library[?univers=] — « Mes personnages » : persos créés + persos
> piqués de la commu, FUSIONNÉS. Chaque carte : portrait, nom, univers, compteurs
> (versions · vidéos), et un flag source ("own" | "community") pour le badge commu.
> Filtre univers OPTIONNEL (pas de tri imposé).

### `GET · POST` /api/v1/site/characters

> GET /api/characters — persos univers (read-only) + persos custom de l'user. */
>
> POST /api/characters — crée un perso custom (mutable, owner only). */

### `POST` /api/v1/site/characters/save

> POST /api/characters/save { job, index, name } — ENREGISTRE dans « Mes personnages » la proposition que l'utilisateur
> garde parmi celles d'un job « propose » (POST /api/characters/generate avec count 2-3). Annoncée par
> app/api/characters/generate/route.ts et _charJob.ts depuis septembre, jamais écrite : aucune page n'utilisait encore
> les propositions. Le Marketing Studio d'Amir (01/10/2026, fenêtre « Nouvel avatar ») en montre trois, on en garde une
> (ou plusieurs) avec « Enregistrer » puis un nom.
>
> Rien n'est débité ici : le job a été payé à son lancement. On n'enregistre que ce que CE compte a généré (charJob filtre
> par propriétaire), et une même proposition ne crée qu'un seul perso : la renvoyer renomme celui déjà créé.
> Les propositions vivent une heure (KEEP_PROPOSALS_MS) ; au-delà, le job est purgé et la demande échoue proprement.

### `GET` /api/v1/site/characters/surprise

> GET /api/characters/surprise[?style=] — « Surprends-moi » : description de perso aléatoire
> pour débloquer la création « inventer de zéro ». Renvoie { name, desc } (look pur, pas de personnalité).

### `GET` /api/v1/site/credits

> GET /api/credits — solde de crédits du user (pour l'anneau autour de l'avatar).
> Renvoie le solde + le plan + le plafond du plan (pour calculer la jauge de l'anneau).

### `GET` /api/v1/site/explorer/feed

> GET /api/explorer/feed — payload de la page d'accueil Explorer.
> Renvoie : à la une (featured), récentes, plus likées, et par univers.
> VIDÉOS PRIVÉES (18/09/2026, demande du propriétaire) : le fil ne montre QUE les vidéos du compte connecté.
> Avant, c'était le fil de toute la communauté (RLS « using true ») ; la politique videos_read_owner
> verrouille aussi côté base, ce filtre serveur est la ceinture avec les bretelles. Sans compte : fil vide.

### `GET` /api/v1/site/explorer/my-personas

> GET /api/explorer/my-personas — persos de la communauté que J'AI sauvegardés.
> Renvoyés au MÊME format que /api/studio/library (le picker studio peut les fusionner) :
> views.front = URL Storage publique → utilisable directement comme image + comme réf
> (le pipeline produce sait télécharger une réf en http://).

### `POST · DELETE` /api/v1/site/explorer/personas/{id}/save

> POST   /api/explorer/personas/[id]/save  → 410 (import retiré le 18/09/2026)
> DELETE /api/explorer/personas/[id]/save  → le retire
> Par-utilisateur (RLS). On NE touche PAS à la library.json globale du studio.

### `GET` /api/v1/site/explorer/personas/stars

> GET /api/explorer/personas/stars — « stars de la commu » RETIRÉES le 18/09/2026 : les persos sont
> privés, chaque compte ne voit que les siens (migration 0026). Liste vide gardée pour les pages en cache.

### `GET` /api/v1/site/explorer/series/{id}

> GET /api/explorer/series/[id] — une série + ses épisodes (ordre croissant),
> avec le DERNIER épisode (latest) et le PLUS VU (biggest) → points d'entrée du lien viral.
> ⚠️ Plus « publique » depuis les vidéos privées (18/09/2026, 0025 : RLS videos_read_owner) : on ne lit
> que SES séries ; celle d'un autre compte répond « introuvable ».

### `POST` /api/v1/site/explorer/videos/{id}/like

> POST /api/explorer/videos/[id]/like — like / unlike (toggle) au nom de l'utilisateur.
> Utilise le RPC atomique toggle_video_like (pose/retire la ligne + maj le compteur).

### `GET` /api/v1/site/explorer/videos/{id}/remix

> GET /api/explorer/videos/[id]/remix — données pour REMIXER une vidéo (lien viral).
> Renvoie le brief d'origine + le casting → le studio peut pré-remplir l'idée et les persos.
> ⚠️ Plus « publique » depuis les vidéos privées (18/09/2026, 0025 : RLS videos_read_owner) : on ne
> remixe que SES vidéos ; le lien d'une vidéo d'un autre compte répond « introuvable ».

### `GET · PATCH · DELETE` /api/v1/site/explorer/videos/{id}

> GET /api/explorer/videos/[id] — détail d'une vidéo publiée + casting + état « liké ».
> ⚠️ Plus « publique » depuis les vidéos privées (18/09/2026, 0025 : RLS videos_read_owner) : le détail
> n'est servi qu'à son propriétaire (et aux admins, cf. GET). Si l'utilisateur est connecté, on renvoie aussi `liked`.

### `POST` /api/v1/site/explorer/videos/{id}/view

> POST /api/explorer/videos/[id]/view — incrémente le compteur de vues.
> PUBLIC (les vues comptent aussi pour les visiteurs non connectés). RPC bump_video_view.

### `GET` /api/v1/site/explorer/videos

> GET /api/explorer/videos — liste filtrable + paginée (pour « voir tout » / scroll infini).
> Params : sort=recent|likes|views, univers=fruit|pixar|animal|clay, q=<recherche titre>,
>          limit (≤50, défaut 24 ; ≤1000 en vue admin), offset (défaut 0), mine=1 (MES vidéos, filtrées SERVEUR).
> Réponse : { videos, count, limit, offset, has_more, next_offset, … } — chaque vidéo porte `own` (elle est au compte
> qui lit ; false seulement dans la vue admin, sur les vidéos des AUTRES comptes : ni renommables ni supprimables).
> VIDÉOS PRIVÉES (18/09/2026) : avec ou sans mine=1, on ne liste JAMAIS les vidéos des autres comptes —
> seulement celles du compte connecté (l'admin garde sa vue d'exploitation via mine=1). Sans compte : liste vide.

### `GET` /api/v1/site/explorer/vitrine

> GET /api/explorer/vitrine?videos=8&persos=5 — la VITRINE publique (06/10/2026, page des tarifs : « des vidéos random en
> bas, des personnages random en haut »).
>
> PUBLIQUE : aucune session. Depuis le 18/09 tout est privé (vidéos, persos, bucket) et /api/explorer/videos répond vide à un
> visiteur ; ici on lit par le client service_role et on FILTRE nous-mêmes : seulement les vidéos et les persos des
> FONDATEURS (les adresses admin, lib/admin.ts), jamais une pub (is_ad : les photos du produit d'un client), jamais un compte
> client, jamais un perso fait d'après une PHOTO (origin « photo » : le visage d'une vraie personne), jamais un univers masqué
> ou réservé aux admins. Rien d'identifiant ne sort (ni creator_id ni nom de compte), seulement des adresses SIGNÉES du
> stockage (copies légères : mini-copie 8 s pour la tuile, copie 1080p pour la visionneuse, vignette), comme
> /api/explorer/videos — et JAMAIS l'original. Tirage AU HASARD à chaque appel ; le lot (≤ 150 vidéos, ≤ 150 persos) est
> relu toutes les 2 minutes et GARDÉ tel quel si la relecture échoue (une panne passagère ne vide pas la page). Aucune copie
> n'est fabriquée depuis ici (un visiteur anonyme ne déclenche pas de ffmpeg) : une vidéo sans mini-copie ni vignette est
> simplement écartée du tirage.

### `DELETE` /api/v1/site/instagram/comptes/{id}

> DELETE /api/instagram/comptes/{id} — déconnecte un compte Instagram de CE compte Kartoon : le jeton est effacé, la ligne
> reste (historique des posts). Session obligatoire. Pour retirer aussi l'accès côté Instagram : Paramètres → Apps et
> sites web, dans l'application Instagram.

### `GET` /api/v1/site/instagram/comptes

> GET /api/instagram/comptes — les comptes Instagram connectés au compte Kartoon de la session (page Compte, onglet
> Instagram), sans aucun jeton. `configured` : l'app Meta est-elle branchée ; `allowed` : offre Business ou admin.

### `GET` /api/v1/site/me

> GET /api/me — profil de l'user courant (crédits, plan, identité). */

### `GET` /api/v1/site/media/{path…}

> GET /api/media/<chemin> — fichier du bucket, réservé à son propriétaire (18/09/2026).
> Vérifie la session puis renvoie (302) une URL signée courte : lecture et seek vidéo passent
> par le CDN de Supabase, pas par la machine Fly. ?w=<largeur> = vignette redimensionnée,
> ?download=<nom> = téléchargement, ?lecture=1 = copie légère de lecture d'une vidéo (lib/lecture.ts),
> ?vignette=1 = mini-copie des vignettes qui jouent dans les grilles (8 s, 360 px, muette).
> univers/ reste public (couvertures du catalogue).

### `POST` /api/v1/site/plans/{id}/regenerate

> POST /api/plans/:id/regenerate — re-roll de la vidéo d'un SHOT.
> Phase 1 : mock (la vraie génération Kling vient en Phase 4).

### `POST` /api/v1/site/plans/{id}/reorder

> POST /api/plans/:id/reorder — monte/descend un SHOT dans sa scène (swap shot_number). */

### `PUT · DELETE` /api/v1/site/plans/{id}

> PUT /api/plans/:id — édite un SHOT (cadrage, réplique, durée, prompt visuel). */
>
> DELETE /api/plans/:id — supprime un SHOT. */

### `POST` /api/v1/site/plans/{id}/startframe

> POST /api/plans/:id/startframe — (re)génère la start frame d'un SHOT.
> Accepte un refinement optionnel (panel "Détails"). Passe le shot en "framed".

### `POST` /api/v1/site/projects/{id}/frames

> POST /api/projects/:id/frames
> 1 start frame PAR SHOT (+ end frame si needs_end_frame), via planShotFrame qui
> consomme les MASTERS (P2). PAS de vidéo (P4b).
> Ordre des références (documenté, cf. planShotFrame) :
>   [ décor master (ANCRE) → master(s) perso présents → frame du shot N-1 ].
> SEED déterministe par shot, nourri par les seeds des masters → frame rejouable.
> Garde-fou coût : compte les appels nano + coût estimé (~0,15 $/image) en live.

### `POST` /api/v1/site/projects/{id}/generate

> POST /api/projects/:id/generate
> Phase 1 : STUB d'orchestration par SHOT. La vraie génération vidéo (Kling v3 pro,
> end frame, slot audio) est branchée en Phase 4. Ici, en mock, chaque shot reçoit
> un placeholder et passe son cycle de vie generating → generated → selected.

### `GET · DELETE` /api/v1/site/projects/{id}

> GET /api/projects/:id — projet + script + scenes (→ shots) + casting dispo. */
>
> DELETE /api/projects/:id — supprime le projet (cascade scripts → scenes → shots). */

### `POST` /api/v1/site/projects/{id}/script

> POST /api/projects/:id/script
> Cerveau scène → SHOTS : génère le script découpé, PERSISTE scenes + shots.
> Les start frames ne sont PAS générées ici (Phase 3) → shots en statut "pending".
> Crée un job d'orchestration "frames" (queued). Débite les crédits.

### `GET · POST` /api/v1/site/projects

> GET /api/projects — liste des projets de l'user (récents d'abord). */
>
> POST /api/projects — création d'un projet.
> Le mode (pub/histoire) est DÉDUIT de la présence d'un produit (pas de toggle).

### `POST` /api/v1/site/script/plot-twist

> POST /api/script/plot-twist — réécrit le plot twist via une instruction (IA).
> Body : { plotTwist, instruction }. Réutilise askClaude. (L'édition 100% manuelle = côté front.)

### `POST` /api/v1/site/script/save

> POST /api/script/save — sauvegarde les modifs du script (plot twist + dialogues édités à la main).
> Met à jour engine/script.json ; si on édite une unité de projet (.current_part.json présent),
> répercute aussi dans story_scripts. NE régénère RIEN (édition manuelle directe).
>
> Éditeur plan par plan (refonte du 11/09/2026) : `remove:[n…]` SUPPRIME des plans (scène retirée
> du script + frame<n>.png / scene<n>.mp4 effacés), puis les plans restants sont renumérotés 1..N
> avec le même renommage en 2 phases que le réordonnancement. Le montage final ne change qu'au
> prochain produce?resume=1 (régénération d'un plan) : cette route ne relance rien.
> 26/09/2026 (audit) : les médias d'un plan changent de numéro — ou disparaissent — AVEC leurs caches (vignettes, aperçu,
> repérage des répliques : _apercu.ts) ; l'ordre et les suppressions ne sont refusés que si CETTE vidéo est occupée
> (génération, régénération, export), plus pour une génération d'une autre vidéo du compte.

### `POST` /api/v1/site/studio/ad-product

> POST /api/studio/ad-product — dépose le PRODUIT d'une pub (Marketing Studio) AVANT de lancer
> la génération. Les photos (data URLs) ne passent pas dans la query GET du SSE → on les écrit ICI
> sur disque (refs de l'espace du compte : engine/u/<compte>/refs/ad-<gid>-*.jpg) + un manifest
> engine/ad-products/<gid>.json que le job de production (produce?mode=ad&gid=…) lira à SON
> démarrage (fichiers scopés par gid → deux pubs en file ne se clobbent pas).
> Body : { gid, name, desc?, photos: [dataURL | /api/media/… | https…], media?: [idem] }
>     ou { gid, produitId } (01/10/2026) : un produit de la bibliothèque du compte (/api/studio/produits), copié tel quel.
> /api/media/<chemin> (26/09/2026, audit) : forme des images de la bibliothèque depuis le bucket privé (un portrait mis
> dans la barre par « Ajouter comme référence ») — lu par la clé serveur UNIQUEMENT si le fichier est au compte
> (../ref-images/_images-du-compte.ts, mêmes règles que GET /api/media). Avant, l'URL publique du bucket d'un AUTRE compte
> passait par fetchMedia et sa photo était copiée ; une adresse extérieure partait en fetch nu depuis la machine de prod.

### `POST` /api/v1/site/studio/cast-from-library

> POST /api/studio/cast-from-library — caste une vidéo depuis la librairie DB.
> Body : { items: [{ characterId, variantId?, source? ("own"|"community") }] }.
> Résout chaque perso (image du perso ou de la variante choisie) et écrit le characters.json
> de l'espace du compte (ref = URL publique, téléchargée par le pipeline produce). → le casting
> devient « plug ».
>
> NB : on renvoie la liste des univers présents pour info, mais on n'IMPOSE PAS la contrainte
> d'univers (volontairement non bloquante, comme décidé).

### `POST` /api/v1/site/studio/charge

> POST /api/studio/charge — DÉBITE réellement les crédits au moment du « confirmer ».
> Le front l'appelle juste avant de lancer la prod, ou avant un doublage en langues payantes.
> (Le coût est d'abord affiché via /api/studio/cost et /api/studio/dub-cost.)
>
>   Body production : { kind:"production", units?, duree? }
>   Body doublage   : { kind:"dub", langs? }  ou  { kind:"dub", extra? }
>
> Débit via le RPC spend_credits (SECURITY DEFINER) : impossible de s'auto-créditer,
> solde insuffisant → 402. Ne touche PAS au pipeline (prod/doublage = leurs routes).

### `GET` /api/v1/site/studio/charimg

> GET /api/studio/charimg?f=<filename> — sert une image de perso importé depuis
> engine/refs (symlinké sur /data en prod). Sanitize : basename seul, pas de "..".
> Sert au runtime (contrairement à /public qui n'est figé qu'au build).

### `GET` /api/v1/site/studio/cost

> GET /api/studio/cost?duree=&units=&format= — coût en crédits AVANT lancement.
> Renvoie : coût par unité + total, le solde du user, et s'il peut se le permettre.
> PUBLIC (26/09/2026, audit) : c'est un TARIF, le même pour tous — un visiteur recevait 401 et les pages n'avaient plus
> de prix à afficher. Sans session : le coût seul, `balance`/`affordable` à null et `connecte: false` (la page s'en sert
> pour proposer la connexion au moment de lancer, comme elle le faisait sur le 401).

### `GET` /api/v1/site/studio/dub-cost

> GET /api/studio/dub-cost?langs=3  (ou ?extra=2) — coût des langues SUP de doublage.
> La langue principale est incluse ; chaque langue en plus est payante.

### `GET` /api/v1/site/studio/dub

> GET /api/studio/dub?video=... — SSE.
> Lance `node dub.js <out du compte>/<video>` (résolu dans l'espace du compte),
> streame les logs, et à la fin émet event:done {file:"<base>_fr.mp4"}.

### `GET` /api/v1/site/studio/dubbables

> GET /api/studio/dubbables — liste les vidéos SOURCES doublables présentes dans le dossier
> out DU COMPTE (montages « <titre>_EN.mp4 » + clips), en EXCLUANT les sorties déjà doublées
> (« _<code>.mp4 »). Sert à peupler le sélecteur « Choisir parmi mes vidéos » de la page Doublage.

### `GET` /api/v1/site/studio/dubbed

> GET /api/studio/dubbed — HISTORIQUE des doublages présents sur disque (out DU COMPTE).
> Regroupe les sorties « <base>_<code>.mp4 » par base → jobs PERSISTANTS (survivent au
> reload de la page ET au redémarrage du serveur). Peuple « Mes doublages » et permet
> de REJOUER chaque vidéo doublée (le viewer lit /api/studio/file?p=<fichier>).

### `POST · GET` /api/v1/site/studio/elements/generate

> POST /api/studio/elements/generate — GÉNÈRE les images d'un ÉLÉMENT (page Créer, fenêtre « Nouvel élément » →
> Générer) EN TÂCHE DE FOND, comme les persos (app/api/characters/generate) : même file (_charJob.ts, type « element »),
> même prix (CREDIT_COST.characterCreate, gratuit quand l'offre inclut les persos), même remboursement si ça échoue,
> même trace en cas de redémarrage. Les propositions ne sont PAS enregistrées : la page garde celle que le client choisit
> (POST /api/studio/elements { job, index, name }).
>
>   POST { id, desc, style, photos?: [dataURL | /api/media/… | https] (≤4), count?: 1-3 } → { id, status, kind }
>        402 → { error, code:"NO_CREDITS", balance, cost }
>   GET  ?id=<id>  → { status, proposals?, error?, creditsRembourses } — sondage (le job de CE compte, type élément)
>   GET  ?cost=1   → { cost } (public : c'est un tarif)

### `GET · POST · PATCH · DELETE` /api/v1/site/studio/elements

> BIBLIOTHÈQUE D'ÉLÉMENTS DU COMPTE (04/10/2026, page Créer d'Amir : « Éléments », « Créer un élément » — un lieu, un
> objet, un animal, un véhicule qu'on retrouve d'une vidéo à l'autre).
>
>   GET    /api/studio/elements                  → { elements: [ { id, name, desc, url, cree } ] }
>   GET    /api/studio/elements?photo=<fichier>  → l'image d'un élément du compte (le seul propriétaire)
>   POST   /api/studio/elements  { name, desc?, photo?: dataURL | /api/media/… | https, job?, index? } → { element }
>            · job + index : la proposition choisie d'une génération d'éléments (POST /api/studio/elements/generate),
>              prise DANS le job du compte — jamais une adresse fournie par la page ;
>            · photo : une photo importée telle quelle (le moteur la redessine dans le style de chaque vidéo).
>   PATCH  /api/studio/elements  { id, name?, desc? } → { element }
>   DELETE /api/studio/elements?id=<id>          → { ok }
>
> Rangement : _elements.ts (racine du compte, elements/index.json + elements/<id>.<ext>).

### `POST` /api/v1/site/studio/export

> POST /api/studio/export — EXPORTE la vidéo de l'éditeur TELLE QU'ELLE EST À L'ÉCRAN.
>
> Jusqu'au 23 sept. 2026, « Enregistrer la vidéo » ne faisait qu'enregistrer le script et proposer le DERNIER
> montage : ni les sous-titres (un simple calque de l'aperçu), ni l'ordre ou les suppressions de plans (« montés à la
> prochaine régénération ») n'étaient dans le fichier téléchargé — « quand t'exportes y a pas les sous-titres ni
> changement ni rien ». Ici, en flux SSE (step / log / done / error — un export dure de 20 s à quelques minutes,
> et le proxy Fly coupe une réponse muette au bout de 60 s) :
>   1. montage:true → la vidéo est REMONTÉE (produce.py RESUME=1 : rien à générer, chaque plan a déjà son clip —
>      vérifié, sinon une reprise générerait des clips sans débit) puis REPUBLIÉE (même carte « Mes vidéos »,
>      published_video_id conservé par /publish) ;
>   2. sub:{preset,scale,x,y} → les sous-titres sont INCRUSTÉS (fichier ASS calé sur montage.json, le vrai
>      chronogramme du montage — clips rognés d'une pub, transitions du 2.5 — écrit par le moteur depuis le 23/09)
>      avec le style, la taille et la position choisis dans l'éditeur, par engine/exporter.py (créneau ffmpeg partagé).
> Le fichier sous-titré est un fichier À PART (« …sous-titres.mp4 ») : la vidéo publiée reste sans sous-titres, et
> /api/studio/last ne le prend jamais pour le montage (il ne finit ni en _EN.mp4 ni en _fr.mp4).
>
> Répliques : les mêmes que l'aperçu de l'éditeur (une pub : sa narration sur les plans « voix off », rien sur les
> autres ; une vidéo : les [Nom]: "…" du video_prompt), calées sur la parole de chaque clip (lib/paroles.ts).
>
> VIDÉO DOUBLÉE (26/09/2026, audit) :
>   • ses sous-titres viennent de la VOIX DOUBLÉE elle-même (mots repérés dans le fichier doublé, dans sa langue) — ils
>     venaient des répliques du script, en anglais, sur la voix française. Repérage impossible : export SANS sous-titres
>     (dit au client), jamais le texte d'une autre langue ;
>   • remontée (ordre ou suppression de plans), elle n'est PLUS republiée : le remontage est la version originale, non
>     doublée, et la carte « Mes vidéos » garde le montage doublé ; l'ancien doublage, qui ne correspond plus aux plans,
>     est retiré de l'éditeur (il était resservi comme « la » vidéo, dans l'ancien ordre).
> Occupation : seulement la vidéo exportée (une génération d'une AUTRE vidéo du compte ne bloque plus rien), et un simple
> téléchargement (ni remontage ni sous-titres) ne vérifie rien du tout. Un ping part toutes les 10 s pendant les longues
> étapes muettes (republication) : le proxy Fly coupait la réponse et la page affichait « Export interrompu ».

### `GET` /api/v1/site/studio/file

> GET /api/studio/file?p=... — sert un fichier de engine/out (sanitize : pas de "..").
> Images en plein, mp4 avec support Range (lecture/seek dans le <video>).
> ?w=320|960 (images) → VERSION LÉGÈRE en JPEG, faite une fois par ffmpeg et gardée à côté du fichier (.thumbs/).
> Chaque réponse porte un ETag : le navigateur revalide (no-cache) et reçoit un 304 sans corps si rien n'a changé.

### `GET` /api/v1/site/studio/idea

> GET /api/studio/idea[?univers=fruit|pixar|animal|clay] — génère UNE idée d'histoire.
> Remplit le champ « ton histoire » ; l'utilisateur garde la main (éditable, relançable).

### `POST` /api/v1/site/studio/improve

> POST /api/studio/improve { brief } — retravaille / enrichit le brief de l'utilisateur.
> Garde son intention, ajoute de la matière (persos nommés, enjeu, twist potentiel).

### `GET` /api/v1/site/studio/languages

> GET /api/studio/languages — langues de doublage dispo (value=anglais pour ElevenLabs, label=FR).

### `GET` /api/v1/site/studio/last

> GET /api/studio/last — état du dernier run pour pré-remplir le studio.
> { brief, characters, script }

### `GET` /api/v1/site/studio/library

> GET /api/studio/library — librairie serveur des persos importés par photo.
> Lit engine/library.json (symlinké sur /data en prod → partagé entre appareils)
> et renvoie chaque entrée au format DefaultCharacter, avec views.front pointant
> vers /api/studio/charimg (servi au runtime).
>
> La librairie était GLOBALE (engine/library.json) : tout le monde voyait — et
> écrasait — les persos importés par les autres. Elle est désormais lue dans
> l'espace du compte, donc la route exige une session.

### `GET` /api/v1/site/studio/presets

> GET /api/studio/presets — la bibliothèque de PRESETS de pub (le front n'a qu'à afficher et renvoyer l'`id`).
>
> Un preset = une créa qui marche, démontée et rendue rejouable avec n'importe quel produit
> (engine/presets/<id>.json ; schéma et méthode : engine/presets/README.md). Le client en choisit un, donne son
> produit (+ ses persos et des détails s'il veut), et /api/studio/produce?preset=<id> fait le reste.
>
> Statique (lecture de fichiers, zéro IA, zéro base) : rapide, gratuit, stable — comme /api/studio/templates.
> Les brouillons (_drafts/) ne sont JAMAIS servis : un preset n'entre dans la bibliothèque qu'après relecture et
> un test sur deux produits différents.
>
> PUBLIC (26/09/2026, audit) : la liste s'affiche avant toute connexion (onglet Publicité de /videos). Ce qui sort est
> une LISTE BLANCHE de champs : jamais le découpage, le corpus, la fiche audio complète ni la source (`source.quoi` =
> le fichier de la créa d'origine) — qui sont le savoir-faire du preset, lus par le moteur seul (engine/brain.js).
> Le middleware la laisse passer sans session (GET, STUDIO_LECTURE_PUBLIQUE de lib/supabase/middleware.ts). La page
> /videos embarque en plus la même liste au build (scripts/build-videos-v2-page.mjs, PRESETS_BUILD) : les cartes sont là
> dès le premier affichage, puis cette route les rafraîchit. Même règle et même durée par défaut (30 s) des deux côtés.

### `GET` /api/v1/site/studio/produce

> GET /api/studio/produce — SSE.
>
> La PRODUCTION tourne en TÂCHE DE FOND (voir ../_produceJob) : elle est DÉCOUPLÉE de la
> connexion SSE. Recharger la page ne tue plus rien — le flux se contente de S'ABONNER
> (replay des logs déjà émis + live). À la fin, la vidéo est AUTO-PUBLIÉE (mode local)
> → elle rejoint « Mes vidéos » même si aucune page n'est ouverte.
>   ?resume=1 → produce.py réutilise frames/clips déjà sur le disque (ne refait que les manquants).
>   ?pick=1   → mode « Choisir mes persos » : les persos choisis gardent leur photo ; ceux que le brief demande en plus sont créés.
>   ?attach=1 → RECONNEXION seule : renvoie l'état du dernier job puis ferme (ne démarre RIEN).
>
> PHASE 0 (casting) : AVANT toute frame, on VERROUILLE le look de CHAQUE perso (une image de
>   référence figée par la recette de l'app + fal Nano Banana Pro). PHASE 1+ : `python produce.py`
>   (frames Nano Banana → vidéos Kling → montage), logs streamés, event:frame, RESULT:: → done.

### `POST` /api/v1/site/studio/product-from-url

> POST /api/studio/product-from-url — LIT une fiche produit publique et en renvoie le nom, la
> description et les PHOTOS, pour remplir la modale « Ajoute ton produit » (onglet Publicité de
> /videos) sans rien retaper.
>
> Ce que cette route N'EST PAS : elle ne dépose rien, n'écrit aucun fichier et ne lance aucune
> génération. Elle rend une fiche EN MÉMOIRE que la page pose dans son formulaire ; c'est ensuite
> POST /api/studio/ad-product — inchangé, déjà utilisé par « Créer manuellement » — qui écrit les
> photos dans l'espace du compte. Les images repartent donc en data URL, exactement la forme que
> /ad-product sait déjà lire (et que la page réduit à 1280 px avant de l'envoyer).
>
> PRUDENCE (l'essentiel est dans ../_lien-public.ts) : l'URL vient d'un visiteur et la requête part
> de la machine de production. Schéma http(s) seul, adresses internes refusées AVANT et APRÈS la
> résolution DNS (le contrôle vit dans le `lookup` du socket, donc un DNS qui change d'avis entre
> deux questions ne gagne rien), chaque redirection recontrôlée, délai / redirections / octets
> bornés. Aucun morceau de la page n'est renvoyé au client : seulement les champs extraits.
>
> EXTRACTION : données structurées JSON-LD (schema.org/Product) puis Open Graph — à eux deux ils
> couvrent Shopify, WooCommerce, PrestaShop, Wix, Squarespace et la grande majorité des boutiques.
> Replis : Twitter Card, microdonnées itemprop, <title> / <meta name="description">,
> <link rel="image_src">. Si rien ne sort, on le DIT (code RIEN_TROUVE) et on invite à créer
> manuellement : jamais de fiche vide et silencieuse, jamais de texte inventé.

### `POST` /api/v1/site/studio/produits/analyse

> POST /api/studio/produits/analyse { photos: [data URL…] } → { name, desc } — l'ANALYSE DU PRODUIT du Marketing Studio
> (03/10/2026, Amir : « l'analyse ne marche pas »). La fenêtre « Créer un produit » de la maquette affichait « Analyse de
> ton produit » pendant 2,4 s puis laissait le nom et la description VIDES : une animation, aucune analyse. Ici Claude
> regarde les photos et rend le nom écrit sur le produit et une description fidèle, que la page pose dans ses champs
> (le client peut les corriger avant de créer le produit). Rien n'est écrit sur le disque : c'est POST /api/studio/produits
> qui enregistre le produit, comme avant.

### `GET · POST · PATCH · DELETE` /api/v1/site/studio/produits

> BIBLIOTHÈQUE DE PRODUITS DU COMPTE (01/10/2026, Marketing Studio d'Amir : « Produits », « Créer un produit », « Lien
> produit »). Avant, les produits ne vivaient que dans le navigateur (localStorage, effacé à la déconnexion).
>
>   GET    /api/studio/produits                 → { produits: [ { id, name, desc, url, photos: [url…], cree } ] }
>   GET    /api/studio/produits?photo=<fichier> → une photo du compte (le seul propriétaire)
>   POST   /api/studio/produits  { name, desc?, url?, photos: [dataURL | /api/media/… | https…] (1 à 4) } → { produit }
>   PATCH  /api/studio/produits  { id, name?, desc? } → { produit }
>   DELETE /api/studio/produits?id=<id>         → { ok }
>
> Rangement : racine du compte, produits/index.json + produits/<id>-p<i>.<ext> (même volume que les autres fichiers du
> compte). Pour une génération, POST /api/studio/ad-product { gid, produitId } copie le produit sous ce gid.

### `POST` /api/v1/site/studio/project/{id}/load

> POST /api/studio/project/[id]/load?part=k — prépare le moteur pour PRODUIRE l'unité k
> d'un projet multi-scripts : écrit le script.json + characters.json + last_brief.txt DU COMPTE
> + un marqueur (.current_part.json). Ensuite le flux produce/publish habituel prend le relais ;
> au publish, l'unité est marquée « produced » et liée à la vidéo (via le marqueur).

### `GET` /api/v1/site/studio/project

> GET /api/studio/project — SSE. Génère TOUS les scripts d'un projet D'UN COUP
> (one-shot=1, parties=N, série=N épisodes), AVEC continuité, et les stocke en base
> (story_projects + story_scripts). La prod vidéo se fait ensuite unité par unité.
>
> Params : brief, style(univers), format(oneshot|parts|series), units(N), season?,
>          ton?, duree?, decor?, nbPersos?, fin?, langage?
> Le cast vient du characters.json DU COMPTE (écrit au préalable par /api/studio/setup),
> comme pour /api/studio/generate.

### `GET` /api/v1/site/studio/projects

> GET /api/studio/projects — projets du user + leurs unités (pour « Mes vidéos »).
> Permet de relancer la prod d'une unité (épisode/partie) restée en attente.

### `POST` /api/v1/site/studio/publish

> POST /api/studio/publish?file=<nom dans engine/out>[&series=<titre>][&episode=<n>]
>
> Publie une vidéo finie dans la COMMUNAUTÉ (page Explorer), AU NOM de l'utilisateur
> connecté (client de session → RLS). Déclenché quand l'user télécharge sa vidéo.
>   1. upload du mp4 + d'une miniature (frame1) sur le Storage public
>   2. insert / maj de la ligne `videos` (idempotent par créateur + titre)
>   3. casting : upload des portraits, find-or-create des `personas`, liens
>      `video_characters`, +1 sur usage_count (RPC) à la 1re publication
>   4. brief original (last_brief.txt) mémorisé → remix / lien viral
>   5. série optionnelle (?series=Titre[&episode=n]) → find-or-create série + n° d'épisode
>
> Métadonnées lues depuis le moteur : engine/script.json + engine/characters.json + engine/last_brief.txt.

### `POST` /api/v1/site/studio/ref-images

> POST /api/studio/ref-images — dépose les IMAGES DE RÉFÉRENCE jointes à une création VIDÉO
> (bouton « + » du composeur, onglet « Create » de /videos) AVANT de lancer la production.
>
> POURQUOI UNE ROUTE À PART : la production vidéo est un GET SSE (/api/studio/produce?…) — on
> ne peut y passer ni une image ni un corps de requête. Les images sont donc ÉCRITES ICI sur le
> disque, dans l'espace du COMPTE, et retrouvées par le GID au démarrage du job
> (app/api/studio/produce/route.ts, refsJointes()). Même modèle que POST /ad-product, qui fait
> exactement ça pour la photo produit d'une pub.
>
> CONTRAT AVEC LE MOTEUR (ce que produce/route.ts ira chercher) :
>   fichiers  engine/u/<compte>/ref-images/<gid>-<i>.<ext>   i = 0,1,2… = ORDRE DU COMPOSEUR
>   manifest  engine/u/<compte>/ref-images/<gid>.json  = { images: [chemins RELATIFS À ENGINE] }
> Les chemins du manifest sont relatifs à engine/ (comme ad-products) : produce/route.ts les
> résout en ABSOLU avant de les donner au moteur — produce.py résout ses chemins relatifs
> contre KARTOON_WORKDIR (= engine/u/<compte>), pas contre engine/, donc un relatif y serait faux.
>
> CLOISONNEMENT : un gid est « g » + un horodatage, donc DEVINABLE. Rien ici n'est rangé sous un
> chemin global : le dossier porte l'identité du compte (espaceUtilisateur), et la lecture au
> démarrage du job ne regarde QUE l'espace du compte qui lance. Deviner le gid d'un autre compte
> ne donne donc accès à rien — au pire on écrase SES PROPRES dépôts.
>
> Body : { gid, images: [dataURL | /api/media/… | https…] }.
> /api/media/<chemin> (26/09/2026, audit) : c'est la forme des portraits de la bibliothèque depuis le bucket privé
> (« Ajouter comme référence ») — lu par la clé serveur, UNIQUEMENT si le fichier est au compte (_images-du-compte.ts,
> mêmes règles que GET /api/media). Une adresse extérieure passe par _lien-public, jamais par un fetch nu.

### `GET · POST · DELETE` /api/v1/site/studio/reference-pub

> RÉFÉRENCE PUB (01/10/2026, Marketing Studio d'Amir : « il met son mp4, ça fait analyser et ça marche »).
>
>   POST   /api/studio/reference-pub?envoi=<hex>&debut=<octet>&taille=<octets>&ext=<mp4|mov|webm|m4v>&nom=<nom>
>            corps = un MORCEAU brut de la vidéo (≤ 32 Mo ; la page envoie 20 Mo) → { ok, recu } ; le dernier morceau
>            → { reference } comme ci-dessous. Vidéo de 500 Mo et 180 s au plus. Un morceau qui ne commence pas là où
>            l'envoi s'est arrêté → 409 { recu } (la page reprend de là) ; un morceau déjà reçu est accepté sans réécrire.
>   POST   /api/studio/reference-pub      multipart : file (180 s et 95 Mo au plus), nom? — l'envoi d'un seul bloc,
>            gardé pour les pages encore en cache.
>            → la vidéo est rangée à la racine du compte (references/<id>.<ext>), puis analysée EN TÂCHE DE FOND par
>              engine/presets/analyser.mjs (coupes réelles, lecture de chaque plan, voix, mini-corpus) : elle devient un
>              preset « ref-… » rejouable avec le produit et les avatars du client (GET /api/studio/produce?preset=ref-…).
>            → { reference: { id, preset, nom, cree, duree_s, statut: "analyse" } }
>   GET    /api/studio/reference-pub      → { references: [ { id, preset, nom, cree, duree_s, statut, titre?, resume?, erreur? } ] }
>   GET    /api/studio/reference-pub?id=<id>&video=1  → la vidéo déposée (le compte seulement)
>   DELETE /api/studio/reference-pub?id=<id>          → retire la référence (vidéo, journal, preset)
>
> statut : « analyse » (en cours), « pret » (preset écrit), « erreur » (l'analyse a échoué : le journal dit pourquoi).
> Le preset vit dans engine/u/_presets-ref (cf. ../_presets.ts) ; la génération vérifie qu'il est bien à ce compte.

### `POST` /api/v1/site/studio/regen-plan

> POST /api/studio/regen-plan — RÉGÉNÈRE UN SEUL PLAN via Opus (repasse par le corpus).
>
> Le user a édité le DIALOGUE et/ou le DÉCOR d'un plan. On demande à Opus de réécrire
> CE plan (frame_prompt + video_prompt + durée + persos + lieu) de façon COHÉRENTE avec
> le nouveau dialogue et le nouveau décor, en suivant TOUTES les lois du corpus. On garde
> cast/voices/titre inchangés (identité figée). Puis on SUPPRIME frame<n>.png + scene<n>.mp4
> pour que /api/studio/produce?resume=1 régénère UNIQUEMENT ce plan (start frame → clip).
>
> ADDITIF : n'écrit NI ne modifie brain.js/produce.py/cerveau.md/corpus.md. Réutilise le
> corpus (cerveau+corpus) comme system, exactement comme brain.js, pour la même fidélité.
>
> 26/09/2026 (audit) : appelée SEULEMENT par la régén serveur (../_regen.ts, jeton du processus) ; écrit la scène par
> FUSION dans le script relu juste avant l'écriture (ce qui a été enregistré pendant les ~75 s d'Opus reste) ; le lieu et
> la lumière ne changent que sur un NOUVEAU lieu ; « répliques retouchées » dit par l'éditeur (`retouchees`).

### `GET · POST` /api/v1/site/studio/regen

> /api/studio/regen — RÉGÉNÉRATION D'UN PLAN PILOTÉE PAR LE SERVEUR (24/09/2026, cf. ../_regen.ts).
>   POST ?k=<vidéo>  corps = celui de /regen-plan ({ n, dialogue, decor, instruction, retouchees } | { insert, after, … } |
>                    narration), + `confirmes` : les plans SANS CLIP que le client accepte de refaire (et de payer) avec
>                    celui-ci → 202 { regen, devis } tout de suite ; le serveur fait TOUT (sauvegarde, réécriture, image,
>                    clip, montage, publication) et remet l'ancien plan à la moindre erreur. 409 PLANS_SANS_CLIP + devis
>                    quand d'autres plans seraient refaits sans accord ; 402 NO_CREDITS quand le solde ne suffit pas.
>   GET  ?k=<vidéo>  → { regens: [...] } : l'état de chaque régén de cette vidéo (la page ne fait que lire ça).

### `POST` /api/v1/site/studio/reopen/{id}

> POST /api/studio/reopen/[id] — REND UNE VIDÉO PUBLIÉE À NOUVEAU ÉDITABLE dans le studio.
>
> Le studio n'a qu'UN slot moteur PAR COMPTE (script.json + characters.json + out/ de son espace).
> Cette route le recharge avec l'état d'une ancienne vidéo pour qu'elle s'ouvre dans l'éditeur
> COMME une neuve :
>   1. script = videos.script (état éditable à jour, écrit à chaque publication ; fallback
>      story_scripts par titre pour les vidéos d'AVANT cette feature) → script.json du compte,
>      avec published_video_id = l'id de CETTE vidéo → une republication MET À JOUR la même ligne.
>   2. cast = video_characters (nom + portrait) → characters.json du compte (refs = URLs, servies
>      telles quelles à l'éditeur ; produce PHASE 0 les localise pour la régén).
>   3. clips = clips/<id>/scene<n>.mp4 (archivés à la publication) → re-téléchargés dans out/ →
>      l'éditeur affiche chaque plan et la régén plan-par-plan remonte à partir d'eux.
> Un dossier par vidéo (23/09) : on ne vide plus out/ — seuls les médias manquants ou changés sont retéléchargés (25/09).

### `POST` /api/v1/site/studio/reset

> POST /api/studio/reset — repart sur une histoire VIERGE.
> Efface l'état de TRAVAIL (script, casting, brief, frames/clips en cours) pour qu'une
> nouvelle histoire ne récupère RIEN de la précédente. GARDE les vidéos FINIES
> (*_EN.mp4, *_fr.mp4) = ta bibliothèque, et la librairie de persos (library.json + refs).

### `GET` /api/v1/site/studio/resume

> GET /api/studio/resume — « Reprends où t'en étais » : créations NON finies, en 3 états.
>   - producing          : une unité est en cours de prod → « Voir l'avancement »
>   - series_in_progress : des unités produites + une suivante en attente → « Faire l'épisode N »
>   - draft              : scripts générés, rien produit → « Reprendre »

### `POST` /api/v1/site/studio/setup

> POST /api/studio/setup — enregistre les persos castés → engine/characters.json.
> Body : { characters: [{ name, desc, ref }] }
>   ref : "/xxx" (chemin /public) → résolu en chemin FS absolu sous <repo>/public
>         "data:..." → octets sauvés dans engine/refs/<safe>.<ext>, ref = chemin absolu
>         "http(s)://..." → laissé tel quel

### `GET` /api/v1/site/studio/style-cover

> /api/studio/style-cover?style=<id> — OUTIL ADMIN (proprio) : rend UNE image de couverture
> représentative pour un style d'univers data-driven (engine/styles.json), via le VRAI pipeline
> fal Nano Banana Pro. Sert à peupler public/assets/uni-<id>.jpg (tuiles du picker d'univers).
> Renvoie directement les octets JPEG → on peut `curl ... > public/assets/uni-<id>.jpg`.

### `GET` /api/v1/site/studio/templates

> GET /api/studio/templates — scénarios-types prêts à l'emploi (base de départ éditable).
> Statique (pas d'IA) : rapide, gratuit, stable.

### `GET` /api/v1/site/studio/thumb

> GET /api/studio/thumb?v=<nom mp4 dans engine/out> — MINIATURE (jpg) de la vidéo.
> Extrait la 1re image via ffmpeg (à 0,5s), mise en cache dans engine/out/.thumbs/.
> Sert le sélecteur « Choisir parmi mes vidéos » de la page Doublage.
>
> 26/09/2026 (relecture) : la miniature n'est servie que si elle vient de la version ACTUELLE de la vidéo — elle porte la
> date exacte de sa source (cf. ../_apercu.ts, signerCache / cacheAJour). « Plus récente que la vidéo » ne suffisait pas :
> un plan renuméroté (scene5.mp4 devenu scene3.mp4) garde sa date, et la miniature de l'ancien scene3 passait pour la
> sienne. Réponse privée, revalidée (ETag) : l'URL est la même pour tous les comptes et pour toutes les versions.

### `GET` /api/v1/site/studio/tips

> GET /api/studio/tips — anecdotes « Le savais-tu ? » pour l'écran d'attente de production.

### `GET · POST · DELETE` /api/v1/site/studio/univers-perso

> UNIVERS DU COMPTE (04/10/2026, page Créer d'Amir, fenêtre « Nouvel univers » : « Décris le style que tu veux ou
> importe une image, une capture ou une vidéo. On en tire l'univers visuel (couleurs, lumière, rendu, ambiance) pour
> l'appliquer à toutes tes prochaines générations »).
>
> Un univers du compte = un univers de BASE du moteur (le plus proche : engine/styles.json et les recettes historiques)
> + une DIRECTION ARTISTIQUE écrite par Claude d'après le texte et/ou l'image du client + cette image. Dans une vidéo
> (public/cs/kartoon-creer.js) : le style de base, la direction dans le brief, l'image en image de référence. Rien de neuf
> dans le moteur : ce sont les chemins de toutes les générations.
>
>   GET    /api/studio/univers-perso                → { univers: [ { id, nom, base, direction, image } ] }
>   GET    /api/studio/univers-perso?img=<fichier>  → l'image d'un univers du compte (le seul propriétaire)
>   POST   /api/studio/univers-perso { nom, texte?, image?: data URL } → { univers }
>   DELETE /api/studio/univers-perso?id=<id>        → { ok }
>
> Rangement : racine du compte, univers/index.json + univers/<id>.<ext> (même volume que les produits et les éléments).

### `GET · POST · DELETE` /api/v1/site/studio/universes

> /api/studio/universes — UNIVERS CUSTOM (admin) : ajouter/éditer un univers avec son propre
> corpus, image, titre, sous-titre, style. Stockage abstrait (lib/universes) :
>   • Supabase configuré → table `custom_universes` (DURABLE, survit aux redeploys)
>   • sinon              → engine/universes.json (mode local)
> L'IMAGE (.webp) va sur Supabase Storage (prod) ou en local (dev), via uploadPublicBytes.
> brain.js lit le corpus de l'univers choisi (le route /project le lui fournit) → il REMPLACE
> cerveau+corpus pour cet univers (fichiers sacrés jamais touchés).
>
> GET    → { universes, isAdmin }  PUBLIC (26/09/2026, audit : un visiteur recevait 401, /creer et /videos perdaient les
>          univers custom) — titre, sous-titre, image, style ; le corpus n'est LU et renvoyé que pour un admin.
> POST   (admin) → crée/édite ; body { key, title?, sub?, style?, corpus?, img?(data:image/webp) }
> DELETE (admin) ?key=…

### `POST` /api/v1/site/studio/upload

> POST /api/studio/upload — enregistre une vidéo TÉLÉVERSÉE dans engine/out afin
> qu'elle devienne une SOURCE doublable réelle (le doublage lit engine/out/<name>).
> multipart/form-data, champ « file ». Renvoie { name, title }.
>
> Le fichier atterrit dans l'espace du compte (engine/u/<compte>/out) : une vidéo
> téléversée n'appartient qu'à celui qui l'a envoyée, et deux comptes qui envoient
> le même nom de fichier ne s'écrasent plus.


<!-- ===== Architecture (https://docs.kartoon.io/#/architecture) ===== -->

# Architecture

Comment Kartoon est construit, de la requête du navigateur jusqu'au MP4 publié. Pour qui veut comprendre, intégrer,
ou reprendre le code.

## 1. Vue d'ensemble

```
                 ┌──────────────── Cloudflare (DNS, TLS, cache des vidéos) ────────────────┐
 navigateur ───► │  kartoon.io  ·  docs.kartoon.io                                        │
 agent / API ──► └───────────────────────────────┬────────────────────────────────────────┘
                                                 ▼
                         ┌──────────── Fly.io · app kartoon-live · Paris ────────────┐
                         │  web ×2   (Next.js : pages, API, routage vers un moteur)  │
                         │      │  relais interne (compte → moteur)                  │
                         │      ▼                                                    │
                         │  moteur A (8 cœurs, 16 Go)   moteur B (4 cœurs, 8 Go)     │
                         │  Next.js + engine/ (Node + Python + ffmpeg) + volume /data│
                         └──────┬───────────────┬───────────────┬───────────────────┘
                                │               │               │
                    Supabase (auth, base,   fal.ai (images,   Anthropic (Claude :
                    stockage des vidéos)    clips vidéo)      scripts, relectures)
                                            ElevenLabs (voix, doublage) · Whop (paiement)
                                            Ayrshare / Meta (Instagram) · Resend (e-mails)
```

- **Un seul code**, une seule image Docker, trois rôles de machine (`KARTOON_ROLE`) : `web` reçoit le public,
  `moteur` (A et B) fabrique les vidéos.
- **Un compte = un moteur** : chaque compte est épinglé sur A ou B. Les machines web relaient vers le bon moteur toute
  requête qui touche aux générations.
- **Le moteur garde l'état chaud** (fichiers de travail, journaux, reprise) sur son volume `/data` ; **Supabase garde
  la vérité durable** (comptes, crédits, vidéos publiées).

## 2. Hébergement (Fly.io)

| Groupe | Machines | Taille | Rôle |
|---|---|---|---|
| `web` | 2, toujours allumées | 2 vCPU partagés, 2 Go | pages, API, authentification, relais vers les moteurs ; contrôle de santé `/api/sante` |
| `app` (moteur A) | 1 | performance 8 cœurs, 16 Go, volume `/data` | 12 générations en parallèle, 3 montages ffmpeg ; moteur principal (WhatsApp, Instagram, références) |
| `app2` (moteur B) | 1 | performance 4 cœurs, 8 Go, volume `/data` | 8 générations en parallèle, 2 montages |

- Région Paris (`cdg`). Aucune mise en veille (`auto_stop_machines = false`).
- **Routage compte → moteur** : table `comptes_etat.moteur` lue par `lib/moteur.ts` (`versMoteur`, cache 60 s).
  Déplacer un compte : `scripts/migrer-compte.mjs` (copie son dossier de travail puis bascule).
- Les machines web ne fabriquent rien : un flux de génération (SSE) qui arrive sur le web est relayé au moteur du
  compte par le réseau privé de Fly.

## 3. Le site

- **Pages** : maquettes HTML servies depuis `public/` (`accueil.html`, `marketing-studio.html`, `creer.html`,
  `ed/editeur.html`, `api.html`, `pricing.html`…), réécrites en adresses propres par `next.config.mjs`
  (`/marketing-studio` → `/marketing-studio.html`). Chaque maquette est **branchée** par un script dédié
  (`public/ms/kartoon-branchement.js`, `public/cs/kartoon-creer.js`, `public/ed/kartoon-editeur.js`…) qui parle aux
  routes `/api/*`. Header commun : `public/ed/kt-header.js` + `kt-header-kartoon.js`.
- **API** : Next.js 15 (App Router), routes dans `app/api/**/route.ts`, exécution Node.
- **Connexion** : Supabase Auth (e-mail + code, Google), fenêtre de connexion en popup ; session lue par `getClaims()`
  (clés ES256, JWKS en cache).
- **Médias privés** : les vidéos et persos d'un compte sont privés (RLS + bucket privé) ; servis par
  `/api/media/...` avec des adresses signées. Copies légères faites à la publication : `lecture1080` (lecture rapide)
  et `vignette360` (8 s muettes pour les grilles).

## 4. Les données (Supabase)

| Table | Contenu |
|---|---|
| `profiles` | compte : e-mail, plan, abonnement Whop, `credits_remaining` |
| `credit_movements` | chaque débit, rabais, surplus, remboursement, par génération (`gid`) |
| `videos` | vidéos publiées : titre, univers, durée, brief, adresses ; `creator_id` |
| `characters`, `video_characters` | persos (fiches, images) et leur présence dans chaque vidéo (par id) |
| `comptes_etat` | état par compte, dont le moteur attribué |
| `cles_api`, `generations_api` | clés API (empreinte SHA-256, autorisations, expiration, rotation) et générations lancées par l'API |
| `instagram_*`, archives Ayrshare | comptes connectés, Reels publiés, relevés de statistiques, messages et commentaires |
| `demandes_dev` | demandes de correctifs venues du bot WhatsApp de l'équipe |

Migrations SQL numérotées dans `supabase/migrations/`. Fonctions de crédits côté base : `spend_credits_job`,
`settle_credits_job` (réglage à la durée réelle), remboursement en cas d'échec.

## 5. Le moteur de génération

Point d'entrée : `GET /api/studio/produce` (flux SSE) → `app/api/studio/_produceJob.ts` met la génération dans la
file du moteur (`KARTOON_MAX_JOBS` en parallèle), la détache du navigateur (elle continue si la page se ferme), et
lance `engine/produce.py` dans un **dossier de travail isolé** par génération (`engine/u/<compte>/videos/<gid>/`).

### Les étapes d'une vidéo

| # | Étape | Outil |
|---|---|---|
| 1 | **Écriture** : script, scènes, persos, dialogues ou voix off, découpage, continuité des lieux | Claude Opus 5.5 (`engine/brain.js` pour les vidéos, `engine/adbrain.js` pour les pubs), puis une **relecture « spectateur »** qui note et corrige |
| 2 | **Casting** : chaque perso reçoit une fiche visuelle verrouillée (visage, tenue) | Nano Banana Pro (fal) |
| 3 | **Images de départ** : la première image de chaque plan (ou de chaque séquence), décor repris d'une scène à l'autre | Nano Banana Pro |
| 4 | **Animation** : chaque plan devient un clip, avec les fiches des persos jointes | Seedance 2.5 (2.5), Kling 3 (2.0), Wan 3.0 Prime (1.5) — via fal |
| 5 | **Voix** : voix off et/ou répliques, puis **doublage** dans la langue demandée | ElevenLabs v3 (voix choisies par un casting IA dans un catalogue) |
| 6 | **Montage** : calage voix/image, resserrement des blancs, sonie normalisée (−14 LUFS), master H.264 | ffmpeg |
| 7 | **Publication** : envoi dans le stockage, ligne `videos`, copies légères, crédits réglés à la durée réelle | Supabase |

### Les trois moteurs

| Moteur | Dossier | Clips | Particularités |
|---|---|---|---|
| **Kartoon 2.5** | `engine/kartoon25/` | Seedance 2.5 en **mode références** | jusqu'à 30 s d'action continue en **une** génération (« séquences »), recoupée en plans ; mise en scène complète ; contrôle qualité de chaque clip |
| **Kartoon 2.0** | `engine/kartoon/` | Kling 3 (image → vidéo) | plans de 3 à 10 s ; 4K native selon l'offre |
| **Kartoon 1.5** | `engine/kartoon25/` (option) | Wan 3.0 Prime | pipeline 2.5, dialogues dans la langue d'origine |

### Les pubs (Marketing Studio)

- `engine/adbrain.js` écrit la pub d'après le brief et les **photos du produit** (lues par Claude) ; le produit est
  **verrouillé sur sa photo** dans chaque image.
- `engine/advoice.js` décide la voix : `narrator` (voix off), `dialogue` (les persos parlent), `mix` (les deux, scène
  par scène, seulement si le client le demande), `none` (aucune parole). Une voix off écrite par le client est dite mot
  pour mot.
- En 2.5, les scènes consécutives sont tournées en **séquences** (une génération Seedance pour plusieurs scènes), puis
  recoupées.
- `engine/kartoon25/pub/` : narration, découpe, doublage, resserrement des blancs, sous-titres.

### Robustesse

- **Reprise** (`KARTOON_REPRISE`) : chaque demande envoyée à fal est notée ; après un redémarrage du moteur, la
  génération reprend où elle en était et récupère les clips déjà payés.
- **Refus de modération** du modèle vidéo : le prompt est nettoyé puis réécrit par un « docteur » IA et relancé.
- **Repli** : un clip Seedance en échec repasse par Kling.
- **Journal** de chaque génération : `/data/journaux/<date>/<gid>.txt` sur le moteur (étapes, durées, décisions, coûts).

## 6. Crédits et paiement

- Abonnements et recharges par **Whop** (webhook `app/api/whop/webhook`) ; offres Starter, Pro, Business
  (`lib/offre.ts` : générations en parallèle 1 / 3 / 10, qualité 1080p / 4K / 4K).
- Tarif : **100 crédits par seconde** de vidéo, **320** en Kartoon 2.5 (`lib/credits.ts`).
- Les crédits sont **réservés au lancement**, **réglés à la durée réelle** livrée, **rendus** en cas d'échec. Un
  moteur qui redémarre ne déclare jamais un échec ni un remboursement d'une génération qui peut reprendre.
- Programme d'affiliation : 30 % sur 12 paiements.

## 7. L'API publique

- `app/api/v1/` : routes dédiées (`videos`, `models`, `account`, `characters`, `products`, `instagram/*`) et le
  **pont** `/api/v1/site/<route>` qui relaie toute route du site au nom du compte (appel interne authentifié par un
  cookie interne, jamais la session du client).
- Clés `kx_live_…` (`lib/cles-api.ts`) : seule l'empreinte SHA-256 est gardée ; autorisations par clé, expiration,
  rotation avec période de grâce ; révocation effective en moins d'une minute.
- Limites par clé : 10 lancements/min, 120 lectures/min. Erreurs `{ error: { code, message } }`.
- Une requête à clé est routée vers le moteur du compte comme une requête du site.

## 8. Instagram, WhatsApp et agents

- **Instagram** : connexion par Ayrshare (ou l'API Meta) ; publication de Reels avec l'étiquette « contenu IA » ;
  relevés automatiques des statistiques à 24 h, 48 h, 7 j, 30 j ; archive complète des messages, commentaires et
  publications.
- **Bot WhatsApp de l'équipe** (`lib/whatsapp.ts`) : reçoit textes, photos et vidéos (devenus produits ou éléments),
  lance des générations et renvoie les vidéos dans le groupe ; un bug signalé part en `demandes_dev`, traité par un
  agent de développement qui corrige et déploie.
- **Agent de croissance** : un agent autonome (Claude, Managed Agents) qui pilote des comptes Instagram par l'API
  Kartoon, réveillé toutes les 2 h.

## 9. Déploiement

- `scripts/deployer.mjs` : vérifie les types, construit **une** image, puis met à jour les moteurs **un par un**
  (chacun n'attend que le travail qui ne sait pas reprendre, 15 min au plus) et enfin les deux machines web, l'une après
  l'autre (le site ne coupe jamais).
- Les générations en cours **reprennent seules** après la mise à jour de leur moteur (reprise fal + garde de 60 s avant
  tout échec) : un déploiement ne coûte rien aux clients.
- Seul le site a changé (pages, scripts) → seules les machines web sont mises à jour.

## 10. Fournisseurs

| Service | Usage |
|---|---|
| **Fly.io** | hébergement (web + moteurs), réseau privé, volumes, certificats |
| **Cloudflare** | DNS, TLS, cache des vidéos et des pages, HTTP/3 |
| **Supabase** | authentification, base Postgres (RLS), stockage des vidéos et images |
| **fal.ai** | Nano Banana Pro (images), Seedance 2.5, Kling 3, Wan 3.0 Prime (vidéo) |
| **Anthropic** | Claude Opus 5.5 : scripts, relectures, décisions de voix, casting des voix, analyse des photos produit |
| **ElevenLabs** | voix off, voix des persos, doublage |
| **Whop** | paiements et abonnements |
| **Ayrshare / Meta** | publication et statistiques Instagram |
| **Resend** | e-mails (codes de connexion) |

## 11. Où regarder dans le code

| Sujet | Fichiers |
|---|---|
| Lancement, file, reprise | `app/api/studio/produce/route.ts`, `app/api/studio/_produceJob.ts` |
| Routage vers les moteurs | `lib/moteur.ts`, `lib/comptes-moteurs.ts` |
| Écriture des vidéos / pubs | `engine/brain.js`, `engine/adbrain.js`, `engine/advoice.js`, `engine/adscene.js` |
| Production | `engine/produce.py`, `engine/kartoon25/*.py`, `engine/kartoon/*.py` |
| Crédits | `lib/credits.ts`, `lib/credits-jobs.ts`, `lib/offre.ts` |
| API publique | `app/api/v1/**`, `lib/cles-api.ts`, `lib/modeles-api.ts` |
| Déploiement | `scripts/deployer.mjs`, `fly.toml`, `Dockerfile` |