Aller au contenu

Hooks et musique

GET /hooks chercher les hooks qui ont marché
GET /hooks/forms les meilleures formes de hook pour une vidéo, avec exemples
GET /hooks/families l’effet mesuré de chaque famille
GET /music choisir des morceaux
GET /music/pillars à quoi sert chaque pilier
GET /music/{slug} un morceau

Le hook est la première phrase d’une vidéo. La bibliothèque contient de vrais hooks avec leurs vues rapportées à la base de leur compte (normViews : ×5 veut dire cinq fois les vues habituelles du compte) et les étiquettes des études. Rien de ce qui en sort ne nomme un créateur.

La bibliothèque est mesurée par UseNadia : environ 25 800 premières phrases de vidéos de 61 comptes, chacune avec ses vues normalisées (ses vues rapportées à la médiane des vidéos publiées autour d’elle sur le même compte). C’est la même pour tous les comptes : chercher, demander des formes ou lire les familles marche dès la première clé API. UseNadia la tient à jour à chaque nouvelle mesure des études ; l’API ne fait que la lire, personne n’y importe de hooks.

Les hooks rendus par GET /hooks et GET /hooks/forms sont comptés par organisation et par jour (UTC), selon l’offre :

Offre Hooks par appel Hooks par jour (UTC)
Solo, Starter ultime 10 300
Équipe 30 1 000
Agence 50 3 000
Pendant l’essai de 7 jours, quelle que soit l’offre 5 50

Au-delà du plafond par appel, la demande est rognée, pas refusée : limit descend au plafond ; pour les formes, examples d’abord, puis forms. Une fois le plafond du jour atteint, ces deux routes répondent 429 avec le message dans msg (le quota, l’offre, le renouvellement à 00:00 UTC, l’offre du dessus) et un en-tête Retry-After en secondes. GET /hooks/families ne rend aucun hook : il n’est ni compté ni refusé.

Chaque réponse des trois routes porte ces en-têtes :

En-tête Valeur
X-Hooks-Quota-Limit Hooks par jour de l’offre, unlimited sans plafond journalier
X-Hooks-Quota-Remaining Ce qui reste aujourd’hui après cette réponse, unlimited sans plafond journalier
X-Hooks-Per-Call Hooks au plus par appel
GET /hooks?q=malte+impôts&nature=tuto_methode&limit=20
Requête Type Description
q string ≤ 200 Mots cherchés dans le hook, son ouverture et le sujet ; les hooks qui contiennent le plus de mots passent en premier, puis les meilleurs normViews
family string Seulement cette famille de hooks
nature string Ce que la vidéo apporte : tuto_methode, ressource_outil…
language fr | en | all fr par défaut
minNorm number ≥ 0 Seulement les hooks à ce normViews ou au-dessus
limit 1–100

Réponse 200 : { "total", "hooks": [ … ] }, total étant la taille de toute la bibliothèque. Chaque hook porte hook, opening (les quelque 40 premiers mots), views, normViews, family, nature, subject, language et matchedWords.

GET /hooks/forms?nature=tuto_methode&q=malte&forms=5&examples=3
Requête Type Description
nature string La nature de la vidéo en préparation
q string ≤ 200 Son sujet : un exemple sur ce sujet passe en premier quand il en existe un
language fr | en | all
forms 1–15 Nombre de familles
examples 1–5 Vrais hooks par famille, tirés au hasard (deux appels ne donnent jamais les mêmes)

Réponse 200 : un tableau de familles classées (grossièrement) par leur effet mesuré sur cette nature : family, label, ratio, ps, bangers, accountsFor, accountsAgainst, verdict et examples. Les vues suivent la taille du sujet : elles ne classent pas les exemples.

GET /hooks/families?nature=all

L’effet mesuré de chaque famille sur le corpus : ratio (vues comparées au reste à base égale, ×1,10 = +10 %), ps (probabilité de supériorité, 0,50 = aucun effet), bangers (part des vidéos à au moins 2× la base), accountsFor / accountsAgainst, et un verdict. Seule une famille PROUVÉ fait règle.

Un catalogue global de morceaux du domaine public et sous licence CC-BY, préparés pour qu’une seule recette règle le niveau sous n’importe quelle voix : dynamique aplatie, volume sonore normalisé. Le même catalogue pour toutes les organisations.

Depuis le 18 novembre 2026, le catalogue n’est plus un outil MCP : la musique relève du montage, pas de la publication. Ces routes de lecture restent pour la chaîne de montage qui s’en sert.

GET /music?pillar=piano&minDuration=60&limit=5
Requête Type Description
pillar piano | news | synthwave | epique Récit et pédagogie ; tension et actualité ; tech ; cinématique
minDuration number ≥ 0 En secondes
q string ≤ 100 Texte dans le titre ou l’artiste
includeLimite boolean Inclure aussi les morceaux limite (utilisables, un peu rapides ou avec un coup tôt)
limit 1–100

Réponse 200 : { "total", "howTo", "tracks": [ … ] }. howTo est la recette, la même pour chaque morceau : niveau sous la voix, mixage, ligne de crédit. Les morceaux ok passent en premier, dans un ordre aléatoire. Chaque morceau porte slug, title, artist, pillar, durationS, bpm, intro, verdict, license, attributionRequired, creditLine (la ligne exacte à coller en bas de la description, null quand rien n’est dû), url (le MP3 préparé) et storedLufs.

GET /music/pillars → [ { pillar, use, ok, limite } ]
GET /music/{slug} → un morceau, 404 s’il est inconnu

Les hooks n’ont aucune route d’écriture dans l’API publique : la bibliothèque est alimentée par UseNadia, hors de l’API. Le catalogue de musique a deux routes d’écriture, par lesquelles il est alimenté :

POST /music/import insérer ou mettre à jour les métadonnées des morceaux
PUT /music/{slug}/file téléverser un MP3 préparé

Elles répondent 403 sauf si la clé appartient à un super admin : le catalogue est global, ce n’est pas à vous de l’écrire. Aucune des deux n’est exposée à l’agent MCP non plus.