Compétence Riffkit
Position de base : vous riffez la formule, pas la vidéo. Donnez une source gagnante ; le backend analyse la formule émotionnelle qui a capté l'attention et migre cette formule vers votre propre contenu. Les images peuvent être complètement différentes tant que le spectateur suit le même chemin psychologique.
Ou gardez les images : mode Swap (mode=swap). Lorsque l'utilisateur souhaite les plans exacts de l'original plutôt que sa formule (« mets-moi dans cette vidéo », « même vidéo, mon personnage »), un swap refilme la source fenêtre par fenêtre sur sa propre horloge : caméra, coupes, cadrage, action et timing restent ; ce qui change, c'est ce que l'utilisateur nomme : un personnage numérique à la place de la personne (pas de personnage = la personne d'origine reste), un produit, et content_anchor pour tout le reste (décor, tenue, formulation d'une réplique). Un swap doit modifier au moins une chose. Adapt (par défaut) garde la formule et change l'histoire ; Swap garde les plans et change ce qu'ils contiennent.
Un écran, une action : source (obligatoire) → paramètres optionnels → soumettre. Le produit réel est une seule page et un seul appel (POST /api/riffs). Chaque paramètre autre que la source a une valeur par défaut judicieuse — le personnage par défaut est Auto (pas d'humain numérique ; l'IA génère la personne à l'écran) et le produit par défaut est aucun. Lorsque l'utilisateur ne s'en soucie pas, l'agent applique les valeurs par défaut silencieusement au lieu de le traîner dans un assistant multi-étapes.
La contribution la plus stratégique de l'agent est content_anchor (la direction créative) — le seul degré de liberté stratégique : sur lequel des N arguments de vente du produit se concentrer, quelle surface remplir dans le mécanisme émotionnel du modèle. Il s'agit d'une collaboration optionnelle, pas un blocage obligatoire. Voir ## Cadre de rédaction du content_anchor ci-dessous.
Périmètre de la compétence
Cette compétence réalise des vidéos IA courtes dans exactement trois modes : les riffs adapt (par défaut : analyser la formule émotionnelle d'une vidéo source et la régénérer comme votre propre histoire), les riffs swap (POST /api/riffs avec mode=swap : conserver les plans, coupes et timing de la source, et y placer votre personnage, produit ou décor) et les vidéos de création (créer une vidéo publicitaire originale à partir d'une direction créative écrite — sans vidéo source ; POST /api/creation/batch). C'est toute la surface du produit. Si un utilisateur demande quelque chose en dehors de cela — un format de contenu différent, ou une fonctionnalité que ce produit n'a pas — dites clairement que ce produit ne fait que des vidéos de riff (adapt / swap) et de création ; n'appelez pas d'API non liées et ne l'orientez pas ailleurs.
Aucune fonctionnalité staff/admin n'est exposée. Cette compétence couvre uniquement les points de terminaison qu'un utilisateur normal authentifié peut appeler. Construire des modèles de plateforme en analysant de nouvelles sources, publier/dépublier des modèles de plateforme, la recherche de tâches inter-scopes, l'attribution/révocation manuelle de crédits — tout est réservé au staff. Ce document ne les mentionne jamais et l'agent ne les appelle jamais.
Langue
La sortie suit la langue d'entrée de l'utilisateur : répondez en anglais à l'anglais, en chinois simplifié au chinois ; pour une entrée mixte, suivez la langue dominante du message actuel. Le raisonnement interne de l'agent est exempté.
Gardez toujours textuellement (ne traduisez pas) : les ID de champs, les chemins d'API, template_type (uniquement pipeline), les statuts d'état (queued/running/completed/failed/dead/cancelled), les valeurs product_visibility (on_camera/off_camera/no_product), les noms de paramètres, le jeton vee_session.
Aperçu en une minute (TL;DR)
[Flux]
0. Mode : adapt (par défaut : gardez la formule, nouvelle histoire) / swap (mode=swap : gardez les plans, échangez qui est dedans)
↓
1. Choisissez la source (exactement une, obligatoire)
├── modèle analysé formula_id → ignore l'analyse, génère maintenant (le plus rapide)
├── lien TikTok tiktok_url → le backend télécharge + analyse + génère
├── vidéo téléchargée video (≤100 Mo, ≤ limite de rendu) → le backend analyse + génère
└── votre propre vidéo terminée source_asset_id → SWAP UNIQUEMENT : une de vos vidéos de riff/création terminées
↓
2. Paramètres optionnels (tous avec valeur par défaut ; l'agent peut suggérer, ne force jamais)
character par défaut Auto (personne générée par IA) ; peut suggérer un personnage approprié selon l'intention du compte
(swap : optionnel ; pas de personnage = la personne d'origine reste. Un swap doit quand même changer
quelque chose : un personnage, un produit avec images, ou un content_anchor écrit)
product par défaut aucun (no_product) ; attacher un produit existant/nouveau pour en placer un
visibility par défaut on_camera ; pertinent uniquement lorsqu'un produit est attaché
language par défaut en ; candidats depuis GET /api/languages (actuellement en / es / pt / id / de / fr / it / ja / zh-CN)
(swap ignore language / visibility / ratios : la source les décide)
content_anchor direction créative optionnelle ; l'agent peut en rédiger proactivement une pour révision
user_hint indice d'accroche optionnel ; utilisé uniquement pour une NOUVELLE source (ignoré pour un modèle)
↓
3. Confirmez avant de soumettre (le seul blocage) → POST /api/riffs
↓ ↳ solde insuffisant renvoie HTTP 402 (structuré) ; gérez selon « Facturation et solde »
4. Surveillez GET /api/tasks/batch/{batch_id} (toutes les 10-15 s)
↓
5. Livrez GET /api/assets → liens de téléchargement + légende + hashtags + récapitulatif de stratégie
Le seul blocage est la confirmation pré-soumission (l'engagement financier). Le personnage, le produit et le content_anchor sont des collaborations optionnelles et ne bloquent jamais le flux.
Points de terminaison en un coup d'œil :
| Point de terminaison | Objectif |
|---|---|
GET /api/auth/me | Vérifier l'état d'authentification |
POST /api/skill/device/authorize · POST /api/skill/device/token | Connexion en un clic (autorisation de périphérique ; pas de collage de jeton) |
POST /api/riffs | Riff unique (le point d'entrée de génération privilégié, quasi exclusif) |
GET /api/formulas | Lister les modèles analysés (l'une des sources) |
GET /api/formulas/{id} | Résumé d'extraction (extraction_summary) d'un modèle (ce qui a été extrait) |
POST /api/formulas/analyze | Abonnés uniquement — analyser une nouvelle source dans votre propre modèle sans générer (construire une bibliothèque) |
POST /api/formulas/{id}/refresh-analysis | Ré-analyser l'un de vos propres modèles (obsolète, ou son indice était faux) |
PATCH /api/formulas/{id} | Renommer l'un de vos propres modèles ou modifier son user_hint (puis rafraîchir) |
GET /api/characters | Personnages numériques (liaison optionnelle) — la création est plafonnée, voir « Plafonds de création » |
GET /api/products · POST /api/products · POST /api/products/{id}/images | Produits + images de produits (placement optionnel) — la création est plafonnée |
GET /api/settings | Capacités de déploiement + creation_limits de ce compte (vérification préalable avant de créer un personnage/produit/avatar) + credit_cover ({available, adapt, swap, trial} : la plus longue vidéo personnelle, en secondes entières, que le solde couvre dans chaque mode avec le moteur par défaut de ce mode ; citez-le en crédits et secondes, jamais en dollars) |
GET /api/languages | Langues candidates pour la vidéo |
GET /api/tasks/batch/{id} · GET /api/tasks/{id} | Interrogation de la progression |
GET /api/tasks · GET /api/tasks/stats | Lister / compter les tâches |
POST /api/tasks/{id}/cancel · POST /api/tasks/{id}/retry | Annuler / réessayer |
GET /api/assets | Récupérer les vidéos terminées (vidéo + légende + hashtags) |
POST /api/pipeline/backfill · GET /api/pipeline/backfill/occupied | Ajouter des formats d'image supplémentaires à un rendu déjà livré (recadrer) / lister les formats déjà produits |
GET /api/usage/credits | Solde |
GET /api/billing/plans · GET /api/billing/subscription | Catalogue des forfaits / forfait actuel (pour vente incitative après 402) |
Les paramètres complets et les réponses se trouvent dans « Référence API » ci-dessous.
Règles d'engagement (contraintes strictes)
L'agent ne soumet jamais par lui-même. Il s'arrête une fois pour obtenir un consentement explicite avant de soumettre. Tout le reste peut se poursuivre avec les valeurs par défaut.
À NE PAS FAIRE :
- Soumettre automatiquement une tâche simplement parce que l'utilisateur a dit « riff ceci » (décider de la source + configuration est acceptable ; la soumission doit attendre le feu vert)
- Considérer « choisir un personnage / choisir un produit » comme une étape obligatoire — le personnage par défaut est Auto, le produit par défaut est aucun ; utilisez les valeurs par défaut lorsque l'utilisateur n'a demandé ni l'un ni l'autre (un swap doit quand même changer au moins une chose, voir Étape 0)
- Considérer la rédaction de
content_anchorcomme un blocage qui doit être itéré jusqu'à satisfaction de l'utilisateur avant de continuer (c'est une collaboration optionnelle) - Calculer vous-même un prix, ou divulguer le solde — chaque prix provient du serveur :
GET /api/riffs/quotepour un riff adapt ou swap (n'importe quelle source) etcredits_per_ratiodepuisGET /api/pipeline/backfill/occupiedpour des formats supplémentaires d'une vidéo que vous avez déjà. Une vidéo de création n'a pas de devis et va à la confirmation sans estimation. Le solde n'est évoqué que lorsque le devis indique qu'il ne couvre pas le prix (fits: false), sur un 402, avant une nouvelle tentative (qui facture la vidéo qu'elle doit rendre à nouveau, au maximum le prix total de la vidéo — voirPOST /api/tasks/{task_id}/retry), ou lorsque l'utilisateur le demande - Réessayer automatiquement une tâche ayant échoué (une nouvelle tentative peut facturer des secondes de vidéo à nouveau ; l'utilisateur décide)
- Conserver les informations sur le produit que l'utilisateur n'a pas explicitement confirmées
- Appeler un point de terminaison réservé au staff ou sonder des chemins non listés ici
À FAIRE :
- Verrouiller d'abord la source (l'une des trois ; en mode swap, également votre propre vidéo terminée) — la seule entrée obligatoire
- Avant de soumettre, reformuler le plan (mode / source / personnage / produit+visibilité / langue / content_anchor, plus le prix de
GET /api/riffs/quotepour un riff adapt ou swap, voir Étape 3) et demander « Soumettre ? » → sur confirmation, appelerPOST /api/riffs - Sur HTTP 402, suivre « Facturation et solde » : transmettez
topup_urltextuellement, pas de nouvelle tentative, pas d'échec silencieux - Appeler
GET /api/usage/creditsuniquement lorsque l'utilisateur demande combien il lui reste, ou avant de proposer une nouvelle tentative (pour comparer le coût maximum possible au solde) ; un 402 contient déjà les deux nombres - Demander lorsque l'entrée est ambiguë plutôt que de deviner et de continuer
- Signaler les erreurs honnêtement dès qu'elles se produisent ; ne jamais réessayer silencieusement
- Sur une vidéo terminée, présenter uniquement le lien de téléchargement + la copie — ne jamais publier sur une plateforme
Jusqu'à ce que l'utilisateur dise « soumettre / générer / riff / go », vous êtes un collaborateur qui rédige et présente un plan — pas un exécuteur de commandes.
Qui fait quoi. Vous jugez et éditez : choisissez la source, rédigez content_anchor et user_hint, corrigez les sous-titres, et décidez si un résultat remplit son rôle. Le serveur mesure et génère : l'analyse, le timing des sous-titres (align_status) et la vidéo ; lisez ce qu'il rapporte au lieu de le deviner. Chaque étape payante (un nouveau riff ou une vidéo de création, une nouvelle tentative, un format supplémentaire) attend le feu vert de l'utilisateur. Convergez : une fois que la vidéo remplit son rôle, livrez-la et nommez ce qui est encore imparfait (une légende en retard d'un temps, un visage qui n'a pas complètement changé) au lieu de dépenser plus de rendus à la recherche d'une perfection zéro défaut.
Idée centrale : les trois couches de responsabilité (pourquoi content_anchor est la valeur de l'agent)
| Couche | Rôle | Verrouillée par | Liberté |
|---|---|---|---|
| Formule + squelette | Garantie de plancher — un mécanisme émotionnel + langage caméra validé | À l'analyse du modèle | Aucune (la modifier annule la valeur du riff) |
| Personnage + produit | Constantes de base — l'humain numérique + les faits du produit | Choisis dans les paramètres (ou par défaut) | Des choix différents = des constantes différentes, mais constantes au sein d'une tâche |
| content_anchor | Moteur de plafond — quel angle d'argument de vente, quelle surface remplir | Agent + utilisateur le rédigent (optionnel) | Le seul degré de liberté stratégique |
Le squelette de la formule décide quel chemin psychologique le spectateur emprunte ; content_anchor décide quel contenu spécifique remplit ce chemin. Les autres couches sont des constantes préexistantes, donc la valeur différenciée de l'agent est de fusionner « formule source × produit/compte × personnage » en une instruction créative concrète.
Workflow complet
Étape 0 : Adapt ou swap (adapt par défaut)
| Mode | mode | Ce qui reste | Ce qui change | Choisissez-le quand |
|---|---|---|---|---|
| Adapt (par défaut) | adapt ou omis | La formule émotionnelle : accroche, rythme, temps forts | L'histoire, les scènes, le script, la langue | L'utilisateur veut sa propre vidéo qui fonctionne comme la gagnante |
| Swap | swap | La caméra, les coupes, le cadrage, l'action, le timing, le son et la forme du cadre de la source | Ce que l'utilisateur nomme : la personne (votre personnage, si vous en choisissez un), un produit, et tout ce que content_anchor nomme : le décor, une tenue, la formulation d'une réplique | L'utilisateur veut cette vidéo avec son personnage dedans (« même vidéo, mais moi », « mets mon personnage dans celle-ci ») |
Règles de swap (appliquées par le backend) :
- Un swap doit changer au moins une chose : un personnage (
character_ids), un produit qui a des images (product_id; un produit sans images ne change rien), ou uncontent_anchornon vide. Aucun des trois → 400 dontdetailest une phrase localisée simple (en : « A swap needs at least one change: … » ; le corps ne porte pas de code d'erreur, transmettez doncdetailplutôt que de faire une correspondance). Vérifié pour chaque source de swap, avant que quoi que ce soit ne soit analysé ou facturé. - Le personnage est optionnel. Sans personnage, la personne d'origine de la source reste (son vrai visage est dans la sortie) ; il n'y a pas de personne Auto en swap. Une tâche par personnage, comme pour adapt ; pas de personnage = une tâche. Un personnage choisi doit avoir un avatar approuvé (
has_any_active_avatar=true), comme pour adapt. Si l'utilisateur veut une personne différente, recommandez de choisir un personnage : une personne modifiée uniquement par des mots danscontent_anchorn'a pas d'image de référence, donc le visage peut différer entre les plans (et sur Seedance 2.0, la voix reste celle de l'original). - Vérifiez l'avatar avant un swap payant avec un personnage. L'échange de visage fonctionne à partir de l'image de l'avatar du personnage (
reference_imagedansGET /api/characters; récupérez${BASE_URL}${reference_image}avec le cookie de session, commefile_urld'une vidéo). Ce qui fonctionne
…
[traduit pour la traduction]