Référence API

Créez votre première vidéo en trois appels API : générer → interroger → télécharger.

Sign in and create a key at API Keys. Choose stories:generate and stories:read for generation and polling, then copy the full key immediately — it is shown only once. Keep it in a server environment variable or secret manager. Your account needs enough credits; creating a key does not add credits.

curl https://www.yoh.app/api/v1/credits \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Submitting a generation request authorizes its credit charge; API integrations do not need an interactive price confirmation. To check cost first, POST the same body to /api/v1/stories/estimate. Optionally send X-Max-Generation-Credits with your maximum whole-number credits: exceeding it returns HTTP 409 before charging. Use the canonical host shown here; redirects from yoh.app can drop your Authorization header.

curl -X POST https://www.yoh.app/api/v1/stories/generate \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{ "prompt": "A dragon teaches a young knight how to fly", "contentType": "cinematic_story", "aspectRatio": "16:9", "scope": "full", "renderVideo": true }'

Replace YOUR_UNIQUE_REQUEST_ID with a unique ID for this operation. Reuse that ID and the identical body when retrying a queued generation request after a network failure. A new ID starts a new operation. Direct image/music requests may return a conflict on replay; inspect the asset before retrying. Poll the returned job every 20 seconds until completed or failed. A failed job is terminal; an error on a queued job can describe an automatic retry. For a text-only draft, use scope: "story" and omit renderVideo.

{
  "jobId": "cmnk8wu2q0001q3vpmqv93nmy",
  "status": "queued",
  "pollUrl": "/api/v1/stories/jobs/cmnk8wu2q0001q3vpmqv93nmy"
}

curl https://www.yoh.app/api/v1/stories/jobs/cmnk8wu2q0001q3vpmqv93nmy \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "status": "completed", "progress": 100,
  "storyId": "cmnk8xxnx000004lbd7siief7",
  "videoUrl": "https://cdn.example.com/video/clip.mp4",
  "error": null
}

Toutes les requêtes API doivent inclure votre clé API dans l’en-tête Authorization avec le schéma Bearer.

Authorization: Bearer sk_live_YOUR_API_KEY

Les clés API commencent par sk_live_. Vous pouvez créer et gérer vos clés depuis la API Keys page. /api-keys

Chaque clé API reçoit une ou plusieurs portées qui déterminent les endpoints auxquels elle a accès. La génération du texte d’une Story coûte 55 crédits par tâche ; les portées qui produisent aussi des vidéos de clips ou un rendu final (y compris la portée par défaut, full) les facturent en plus, à l’avance. Les crédits sont remboursés si la tâche échoue après toutes les nouvelles tentatives.

Envoie un prompt et renvoie immédiatement un jobId. La vidéo est générée de manière asynchrone. Interrogez GET /api/v1/stories/jobs/:jobId pour suivre la progression.

Corps de la requête

assets[] optionnel

This array ATTACHES assets to one generation — it is not where an asset is defined. It carries only what is read inline; the full asset shape (character type and role, voice, scene lighting and mood, item material and condition) lives in the series library, which accepts all of it and which the pipeline reads directly. Reference the library by id rather than restating an asset here. Each entry either references an asset in your series library by seriesAssetId (upload it once via POST /api/v1/series/:seriesId/assets and reuse it forever), or defines a one-off asset inline with type + name. The two forms mix freely in one array. Whatever you attach is described to the writer, and its image is reused instead of a new one being generated — so a character keeps their face and a product keeps its packaging.

Characters, scenes and items only enter the story when the prompt names them — attaching a whole series library does not drag its entire cast into every episode. The two pin flags are the exception: a pinned hero product or primary background is guaranteed regardless of whether the script says its name.

globalConfig optionnel

Optional nested object controlling duration, output format, and model selection. Every field has a default; pass only what you want to override. The model fields (videoModel, imageModel, characterImageModel, modelStrategy) may also be passed at the top level as a convenience. Unknown model ids degrade to auto rather than failing the request.

This is a superset of the studio's own controls, not a mirror of them. resolution is the studio's resolution pills (default 720p; the story keeps the value you send and each clip makes what its model can, e.g. Seedance 2.5 up to 1080p, Kling and MiniMax H3 from 720p). qualityTier, modelStrategy and seed are API-only. Two fields are advisory: they are shown to the writer as context but nothing enforces them, and they are marked below.

contentTypeConfig optionnel

Optional per-contentType creative controls. Fields are validated against the selected content type; omitted fields fall back to sensible defaults. Pass the object matching your contentType. The two pin ids below are usually easier to set as isHeroProduct / isPrimaryBackground on an assets[] entry — an id you write here wins if you send both.

Autres champs optionnels

Fields that aren't part of the selected contentType's schema are silently ignored — cinematic_story takes no per-type fields at all, so pass contentTypeConfig only for ad_spot, news_analysis, or persona_channel.

curl -X POST https://www.yoh.app/api/v1/stories/generate \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 30s spot for a titanium water bottle that keeps ice for 24h",
    "contentType": "ad_spot",
    "scope": "full",
    "renderVideo": true,
    "globalConfig": {
      "durationSec": 30,
      "resolution": "1080p",
      "modelStrategy": "hero_premium"
    },
    "contentTypeConfig": {
      "heroProductName": "Northpeak Flask",
      "heroTagline": "Ice, 24 hours later.",
      "heroKeyBenefit": "Vacuum-sealed titanium keeps ice frozen for a full day"
    }
  }'

Réponse 202 Accepted

{ "jobId": "cmnk8wu2q0001q3vpmqv93nmy", "status": "queued", "pollUrl": "/api/v1/stories/jobs/..." }

# Regenerate clip 3's image, then its video — the rest of the story is untouched
curl -X POST https://www.yoh.app/api/v1/stories/STORY_ID/clips/CLIP_ID/image \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
# Poll GET /api/runs/RUN_ID until completed

curl -X POST https://www.yoh.app/api/v1/stories/STORY_ID/clips/CLIP_ID/video \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videoModel":"bytedance/seedance-2.0"}'
# Poll GET /api/runs/RUN_ID until completed → the clip's videoUrl is replaced

# 1. Rewrite the direction + retime the shot (immediate, free)
curl -X PATCH https://www.yoh.app/api/v1/stories/STORY_ID/clips/CLIP_ID \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "The keeper climbs the stairs as the lamp flickers behind him.",
    "duration": 7
  }'

# 2. Re-shoot it with the new direction
curl -X POST https://www.yoh.app/api/v1/stories/STORY_ID/clips/CLIP_ID/image \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl -X POST https://www.yoh.app/api/v1/stories/STORY_ID/clips/CLIP_ID/video \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

# Step 1: Generate story text (~1-2 min)
curl -X POST https://www.yoh.app/api/v1/stories/generate \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A samurai cat guards a cherry blossom tree","contentType":"cinematic_story","scope":"story"}'
# Poll jobId until completed → get storyId

# Step 2: Generate storyboard images (~3-5 min)
curl -X POST https://www.yoh.app/api/v1/stories/STORY_ID/storyboard \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
# Poll until completed

# Step 3: Generate clip videos (~1-3 min per clip)
curl -X POST https://www.yoh.app/api/v1/stories/STORY_ID/videos \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
# Poll GET /api/runs/RUN_ID until completed

# Step 4: Render final MP4 (~1-2 min)
curl -X POST https://www.yoh.app/api/v1/stories/STORY_ID/render \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
# Poll until completed → videoUrl

Interrogez cet endpoint après avoir appelé POST /api/v1/stories/generate. Une tâche prend en général 8 à 15 minutes selon la longueur de la Story et l’activation de renderVideo. Nous recommandons d’interroger toutes les 15 à 30 secondes.

Cycle de vie du statut de la tâche

Which statuses you see depends on the scope you requested — a story job goes straight from generating_story to completed. A transient failure sends the job back to queued with error set to a retry message; that is not terminal, so treat only completed and failed as final states.

Stop. POST /api/v1/stories/jobs/:jobId/cancel (scope stories:write) stops a job the way the app's Stop does: no further paid step starts, work already sent to the provider finishes and is kept, and everything not delivered is refunded once. It answers { outcome: "cancelled" | "stopping" | "already_finished", status }; stopping means a clip is still in flight, so poll until the job reads cancelled (a final state too). POST /api/v1/runs/:runId/cancel stops a batch run (Generate All, started in the app or by /videos, /clips-all or /regenerate; a clip-images batch such as /storyboard) with the app's own Stop: no more clips start; clips never started are never charged. A single clip run's runId (a clip video, video edit or image) cannot be stopped: it answers 409 not_cancellable, and the run finishes and settles itself (a failure is refunded). MCP: cancel_generation.

Reading a job (changed 2026-10-20). A story job that rendered nothing (no render scope, no renderVideo) answers videoUrl: null; its first clip's video is firstClipVideoUrl, never the finished film. A failed clip image job answers failure { category, reason, message } like a clip video. A failed or cancelled job whose refund has not been settled yet says settlement: "pending". A 402 insufficient_credits carries required, balance and topUpUrl.

Champs de la réponse

Une fois la tâche terminée, vous pouvez récupérer tous les éléments générés pour la Story grâce au storyId renvoyé par la tâche. Tous les endpoints d’éléments exigent la portée assets:read.

Chaque clip est un segment de scène avec sa propre vidéo générée par IA, son image fixe et son audio. Toutes les URL sont absolues et publiques.

{
  "data": [{
    "id": "clip_001", "order": 0, "narration": "In the year 2157...",
    "duration": 8,
    "videoUrl": "https://cdn.example.com/generated/video/clip1.mp4",
    "imageUrl": "https://cdn.example.com/generated/image/clip1.jpg",
    "audioUrl": null, "status": "completed"
  }]
}

Il s’agit de la même bibliothèque que celle utilisée par le panneau des éléments du Studio. Importez un personnage, un arrière-plan, un objet ou une référence de style, conservez l’ID renvoyé et référencez-le lors de la génération en passant cet ID comme seriesAssetId dans le tableau des éléments — plus besoin de générer un nouveau lien d’image par vidéo. Les images que vous transmettez sont ré-hébergées sur notre stockage, ainsi l’ID reste fonctionnel même après l’expiration de votre propre URL d’importation.

• Envoyez un seul élément, ou un tableau « assets » pour en mettre à jour jusqu’à 100 à la fois.
• Par défaut, les éléments fusionnent si le nom correspond exactement, l’importation répétée du même catalogue est donc idempotente — sauf pour un personnage dont le nom existe déjà dans la Story : cela renvoie une erreur 409 SERIES_NAME_EXISTS avec le personnage existant, rien n’est sauvegardé. Demandez à l’utilisateur, puis envoyez seriesDuplicate "new" pour en ajouter un second, ou passez ?mergeStrategy=exact pour mettre à jour l’existant. ?mergeStrategy=fuzzy tolère les renommages ; insert crée toujours un nouvel élément.
• DELETE renvoie une erreur 409 SERIES_ASSET_IN_USE avec les épisodes qui utilisent encore l’élément (stories : id, titre, clipCount) et ne supprime rien. Demandez à l’utilisateur, puis envoyez confirm: true (corps ou ?confirm=true) : les épisodes conservent leur propre copie et leurs clips ne changent pas. Un personnage faisant l’objet d’un recrutement en cours renvoie 409 SERIES_ASSET_HIRED (hires) et ne peut pas être supprimé tant que le recrutement n’est pas terminé.
• Définissez isHeroProduct sur un objet (ad_spot) ou isPrimaryBackground sur une scène (news_analysis / persona_channel) pour l’épingler. Lors de la génération, l’épingle est résolue automatiquement — vous n’avez jamais besoin d’écrire heroItemId manuellement.

Start from your own video (MP4, MOV or WebM, up to 1 GB and 10 minutes; free): POST /api/v1/series/:seriesId/uploads makes a draft episode and answers a one-time upload.url that takes one PUT of the file, straight to storage (upload.command is the curl line). Then POST /api/v1/stories/:storyId/upload verifies it, fills an empty title and description from the video, sets its style, picks a cover and cuts it into editable clips; it answers verifying until the check is done, so call it again. GET /api/v1/stories/:storyId/upload reports cutting (with progress) until ready, and links.upload is the page that shows it.

curl -X POST https://www.yoh.app/api/v1/series/series_abc/uploads \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"trip.mp4"}'
# → { "storyId": "story_123", "upload": { "url": "https://…", "command": "curl --fail-with-body -sS -X PUT -T <path-to-video> '…'" }, "links": { … } }

curl --fail-with-body -sS -X PUT -T ./trip.mp4 "<upload.url>"

curl -X POST https://www.yoh.app/api/v1/stories/story_123/upload \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
# → { "status": "cutting", "title": "…", "cut": { "progress": 10, … }, "links": { "upload": "…", "workspace": "…" } }

End to end — put a brand's logo in an ad, and keep the id for every ad after it:

curl -X POST https://www.yoh.app/api/v1/series \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Acme brand films","styleGuide":{"cinematicStyle":"clean product cinematography"}}'
# → { "series": { "id": "series_abc", ... } }

curl -X POST https://www.yoh.app/api/v1/series/series_abc/assets \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "item",
        "name": "Acme Logo",
        "itemType": "logo",
        "description": "Wordmark, orange on white",
        "imageUrl": "https://your-admin.example.com/tmp/logo.png"
      }'
# → { "asset": { "id": "series-item-...", "imageUrl": "https://...blob..." } }
# That imageUrl is ours now — your temporary link can expire.

curl -X POST https://www.yoh.app/api/v1/stories/generate \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "A 30-second spot for the Acme cordless drill",
        "contentType": "ad_spot",
        "seriesId": "series_abc",
        "assets": [
          { "seriesAssetId": "series-item-...", "isHeroProduct": true }
        ]
      }'
# → { "jobId": "...", "pollUrl": "/api/v1/stories/jobs/..." }

Step 2 happens once per asset, not once per video. Step 3 repeats forever with the same id — and because the asset is pinned, the logo is guaranteed in every clip even if the script never says its name. To check the cost before committing, POST the same body to /api/v1/stories/estimate.

POST /api/v1/series-assets/ensure-character-image fonctionne toujours et reste inchangé, mais il ne gère que les personnages. Préférez ce point de terminaison.

Importe et conserve une image de référence de personnage pour une série, afin que l’IA garde le même visage et le même style dans toutes les Stories de cette série. Cette opération est idempotent : l’appeler plusieurs fois avec le même nom de personnage ne pose aucun problème.

Envoyez une vidéo terminée directement vers un compte connecté, afin qu’une automatisation puisse piloter générer → rendu → publier avec un seul identifiant. Connectez d’abord les comptes dans l’app ; ce point de terminaison publie vers ceux-ci.

curl -X POST https://www.yoh.app/api/v1/social/publish \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "socialAccountId": "acct_123",
    "storyId": "STORY_ID",
    "videoUrl": "https://cdn.example.com/video/final.mp4",
    "platform": "youtube",
    "caption": "Episode 1 is live",
    "youtube": { "title": "The Lighthouse — Ep 1", "privacyStatus": "public" }
  }'

Pour les plateformes qui servent de nombreux clients. Au lieu d’une seule clé et d’une seule réserve de crédits pour tout le monde (où un client très actif épuise le solde des autres et où personne ne sait qui a dépensé quoi), créez un compte par client et alimentez chacun depuis votre propre solde. Vos clients ne s’inscrivent jamais ici et ne nous paient pas : la relation commerciale reste la vôtre.

externalId est votre propre identifiant pour le client. Deux appels avec le même identifiant renvoient le compte existant au lieu d’en créer un second : une requête relancée ne pose donc aucun problème. La clé API est renvoyée une seule fois, à la création : nous n’en stockons qu’un hachage et ne pouvons pas la réafficher, alors enregistrez-la dès réception. Un nouveau compte démarre avec un solde nul.

Si la clé initiale a été perdue, appelez cet endpoint avec la clé de la plateforme propriétaire et sans corps de requête. Utilisez l’ID du compte ou l’externalId. L’appel révoque de façon atomique les clés précédentes du compte et renvoie une seule fois une nouvelle apiKey (201). Conservez-la en lieu sûr. Répéter cet appel fait de nouveau tourner la clé ; les nouvelles tentatives normales de création de compte ne remplacent jamais une clé qui fonctionne.

Transfère des crédits de votre propre solde vers celui du compte : il s’agit d’un transfert, pas d’un don, vous ne pouvez donc distribuer que ce que vous avez réellement acheté. Renvoie 402 si votre solde ne suffit pas. :accountId accepte notre ID de compte ou votre externalId.

GET /api/v1/accounts liste vos comptes avec le solde et les dépenses cumulées de chacun ; GET /api/v1/accounts/:accountId/credits en lit un seul. La clé propre d’un compte géré n’a que des portées de génération : elle ne peut jamais créer ni alimenter de comptes elle-même.

Yoh propose un serveur MCP pour que les agents IA (Claude Code, Codex, Claude Desktop ou tout client MCP) puissent créer et modifier des Stories sur votre compte : écrire une nouvelle Story à partir d’une idée, ajouter ses Personnages et générer la vidéo, ou modifier le contenu d’un Clip et les Dialogues, déplacer ou couper des séquences sur la Timeline, et ajouter des superpositions libres. Toute action consommant des Crédits attend votre approbation explicite à chaque fois. Les règles sont les mêmes que dans l’Éditeur web : une modification effectuée depuis le terminal produit exactement le même résultat qu’un glisser-déposer.

Trois façons de l’utiliser

Choisissez celle qui correspond aux outils de votre agent. La skill Yoh ci-dessous enseigne les trois.

• MCP + navigateur (recommandé dans Codex, Claude Code et les applications Claude) L’agent effectue le travail via ces outils MCP et pilote un onglet de navigateur à côté (Claude dans Chrome, le navigateur de Codex) : après chaque étape, il ouvre le lien contenu dans la réponse (le tableau du Script après une nouvelle Story, le panneau du Clip après une vidéo de clip, la liste Tout générer pendant qu’une exécution est en cours, l’Éditeur avancé pour la Timeline et les calques de texte, le MP4 du Rendu) et vérifie le résultat sur la page réelle. Connectez-vous une fois dans ce navigateur avec le même compte que la clé API. MCP et la page partagent les mêmes données : la page de l’Épisode s’actualise quelques secondes après une modification MCP, et l’agent recharge l’Éditeur avancé après un changement de Timeline. Chaque dépense passe par un seul chemin : le devis MCP ou la boîte de dialogue de prix de l’app.
• Navigateur uniquement (pas de clé API) L’agent travaille sur les pages yoh.app dans votre navigateur, comme vous le feriez : Créer → Story, le tableau du Script et le panneau du Clip, l’éditeur de Personnage et son sélecteur de modèle, Tout générer, l’Éditeur avancé, les Versions et l’exportation. Chaque dépense passe par la boîte de dialogue de prix de l’app, et l’agent ne saisit jamais vos coordonnées de paiement ou votre code de connexion.
• MCP uniquement (headless) Pour les scripts, le CI et les agences créant de nombreuses variantes : quote → confirmToken pour chaque dépense, poll get_job / get_run, arrêt avec cancel_generation, création de variantes avec create_story_versions et generate_all_clips, et téléchargement du videoUrl de chaque Rendu terminé. Aucun navigateur n’est requis.

Exemple dans chaque mode : une publicité de 16 secondes au format 9:16 en anglais et en japonais, écrite dans une Story avec son produit, générée, déclinée en version japonaise et rendue deux fois.

Connexion

Recommandé : connectez-vous avec Yoh, sans clé API. Utilisez exactement cette adresse (yoh.app sans www redirige, et la connexion vérifie l’adresse). Dans Claude Code :

claude mcp add --transport http --scope user yoh https://www.yoh.app/api/mcp

Tapez ensuite /mcp, choisissez yoh, puis Authenticate, connectez-vous à Yoh dans le navigateur qui s’ouvre avec le compte voulu, et approuvez.

Dans Codex (CLI, extension IDE ou app de bureau ChatGPT), ajoutez le serveur et connectez-vous, puis mettez tool_timeout_sec = 300 sous [mcp_servers.yoh] dans ~/.codex/config.toml et redémarrez Codex :

codex mcp add yoh --url https://www.yoh.app/api/mcp
codex mcp login yoh

• App de bureau Claude ou claude.ai : Customize → Connectors → + Add → Add custom connector, nommez-le Yoh, collez l’adresse, puis Connect et connectez-vous. Activez-le dans chaque discussion via + → Connectors. Sur les forfaits Team ou Enterprise, un propriétaire l’ajoute d’abord.
• Cursor : ajoutez yoh avec cette adresse dans ~/.cursor/mcp.json, puis connectez-vous quand Cursor le demande.
• ChatGPT : Plugins → + → Add custom MCP server, nommez-le Yoh, collez l’adresse et connectez-vous. Certains forfaits exigent qu’un administrateur autorise les serveurs personnalisés.

Vérifiez : demandez à votre agent d’exécuter get_credits ; il doit afficher votre solde Yoh. Vous pouvez voir et déconnecter les apps connectées dans Paramètres → Clés API → Apps connectées.

Pour que votre agent voie les pages qu’il modifie : Claude Code avec claude --chrome (l’extension Claude in Chrome), l’app de bureau Claude avec le connecteur Claude in Chrome, ou Codex dans l’app de bureau ChatGPT avec son navigateur. Le skill indique à l’agent quand regarder.

Ou utilisez une clé API (scripts, CI, apps sans connexion)

Créez une clé API dans /api-keys. Pour créer de nouvelles Stories et générer de la vidéo, incluez stories:generate ; pour éditer sans dépenser de Crédits, stories:read et stories:write suffisent. Ensuite, dans Claude Code :

claude mcp add --transport http yoh https://www.yoh.app/api/mcp \
  --header "Authorization: Bearer sk_live_YOUR_API_KEY"

Ou validez une configuration de projet pour que toute l’équipe bénéficie de la connexion à l’ouverture du repo, chaque membre fournissant sa propre clé via env :

{
  "mcpServers": {
    "yoh": {
      "type": "http",
      "url": "https://www.yoh.app/api/mcp",
      "headers": { "Authorization": "Bearer ${YOH_API_KEY}" },
      "timeout": 900000
    }
  }
}

Dans Codex, ajoutez le serveur à ~/.codex/config.toml et définissez YOH_API_KEY dans votre shell :

# export YOH_API_KEY=sk_live_YOUR_API_KEY
[mcp_servers.yoh]
url = "https://www.yoh.app/api/mcp"
bearer_token_env_var = "YOH_API_KEY"
tool_timeout_sec = 300

Installer la skill Yoh

La skill enseigne à votre agent comment bien créer et éditer une Story Yoh : commencer dans une série, estimer le prix avant de dépenser, et regarder les Clips avant de les juger. C’est un fichier unique, maintenu à jour avec le serveur. Exécutez la ligne pour votre agent, ou télécharger SKILL.md

# Claude Code
mkdir -p ~/.claude/skills/yoh && curl -fsSL https://www.yoh.app/skills/yoh/SKILL.md -o ~/.claude/skills/yoh/SKILL.md

# Codex
mkdir -p ~/.agents/skills/yoh && curl -fsSL https://www.yoh.app/skills/yoh/SKILL.md -o ~/.agents/skills/yoh/SKILL.md

Ensuite, demandez simplement : « crée une Story de 60 secondes sur une infirmière de nuit qui entend des fantômes », ou « dynamise le rythme de l’Épisode 3 : supprime les blancs, cale les sous-titres sur le tempo et relance le Rendu ». Lancez /mcp dans Claude Code ou Codex pour vérifier la connexion.

Ce que l’agent peut faire

Comment la sécurité et l’exactitude sont garanties

• Le serveur applique les règles de l’Éditeur (déplacement de diapositives, limites de découpe, pistes de sous-titres, lignes de superposition) et répond à une violation en indiquant la plage autorisée au lieu de brider silencieusement.
• L’agent lit l’ensemble des règles depuis la ressource yoh://guide/timeline, et le prompt /mcp__yoh__edit-story lui donne un flux de travail sécurisé.
• La génération est asynchrone — la plupart des outils renvoient un runId que l’agent interroge avec get_run ; quelques-uns (create_story, render_story, illustration de personnage) renvoient un jobId pour get_job, comme pour l’API REST.
• Définissez un délai d’expiration long dans .mcp.json (par exemple 900000) pour qu’un Rendu n’expire pas côté client.

Vérifiez votre connexion

Un test de fumée est fourni avec le repo. Il utilise le protocole réel, teste les règles et prouve que la barrière de dépense fonctionne — il ne dépense jamais de Crédits, et son unique écriture est annulée :

node scripts/mcp-smoke.mjs --url https://www.yoh.app/api/mcp --key sk_live_YOUR_API_KEY
# read-only variant:
node scripts/mcp-smoke.mjs --url https://www.yoh.app/api/mcp --key sk_live_YOUR_API_KEY --skip-write

Les endpoints de gestion des clés API utilisent l’session authentication (cookie de l’utilisateur connecté), pas une clé API. Utilisez l’API Keys page dans le navigateur, ou appelez ces endpoints depuis votre backend avec une session valide. /api-keys

{
  "data": [{
    "id": "key_abc123", "name": "Production",
    "keyPrefix": "sk_live_7WH3",
    "scopes": ["stories:generate", "stories:read", "assets:read"],
    "revokedAt": null, "createdAt": "2026-04-03T10:00:00.000Z"
  }]
}

// Response — full key shown once
{
  "id": "key_abc123",
  "key": "sk_live_...",
  "name": "My integration",
  "keyPrefix": "sk_live_7WH3",
  "scopes": ["stories:generate", "stories:read", "assets:read"]
}

{ "id": "key_abc123", "revoked": true }

HTTP 409 with error.code = generation_budget_exceeded means your optional X-Max-Generation-Credits cap was exceeded. The response includes quote.credits; nothing was charged. Change the request or explicitly raise your budget to retry. A malformed cap returns 400. Other 409 conflicts can mean an idempotency key was reused with different input or work is already running. Template-version generation uses its own persisted quoteId contract; see its OpenAPI reference.

Story create (POST /api/v1/stories/generate and /estimate, MCP create_story / estimate_story) checks the series before pricing: 404 series_not_found when the key's user cannot open that seriesId, 403 series_forbidden when they can open it but may not add episodes to it. Nothing is charged.

Rate limits are per key: 5 generation calls, 60 reads and 60 writes a minute. Each call counts once: an MCP tool call is one call even when it runs several v1 steps, and POST /stories/:id/swap-asset is one generation call for every clip it switches.

La plupart des endpoints renvoient un objet error avec un code lisible par une machine. Certains endpoints spécialisés peuvent renvoyer une erreur sous forme de chaîne ou un code au premier niveau ; vérifiez toujours le statut HTTP.

{ "error": { "code": "insufficient_credits", "message": "...", "status": 402 } }