API-referentie

Maak je eerste video in drie API-aanroepen: genereren → pollen → downloaden.

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
}

Elk API-verzoek moet je API-key bevatten in de Authorization-header, met het Bearer-schema.

Authorization: Bearer sk_live_YOUR_API_KEY

API-keys beginnen met sk_live_. Je kunt keys aanmaken en beheren op de API Keys page. /api-keys

Elke API-key krijgt een of meer scopes die bepalen tot welke endpoints hij toegang heeft. Tekst voor een verhaal genereren kost 55 credits per taak; scopes die ook clipvideo's of een eindrender maken (waaronder de standaardscope, full), rekenen die vooraf extra af. Mislukt de taak na alle nieuwe pogingen, dan krijg je de credits terug.

Dient een prompt in en geeft direct een jobId terug. De video wordt asynchroon gegenereerd. Poll GET /api/v1/stories/jobs/:jobId om de voortgang te volgen.

Request body

assets[] optioneel

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 optioneel

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 optioneel

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.

Andere optionele velden

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"
    }
  }'

Antwoord 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

Poll dit endpoint nadat je POST /api/v1/stories/generate hebt aangeroepen. Een taak duurt meestal 8–15 minuten, afhankelijk van de lengte van het verhaal en of renderVideo aanstaat. We raden aan om elke 15–30 seconden te pollen.

Levenscyclus van taakstatus

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.

Velden in het antwoord

Als een taak klaar is, kun je alle assets die voor het verhaal zijn gegenereerd ophalen met de storyId die de taak teruggeeft. Alle asset-endpoints vereisen de scope assets:read.

Elke clip is een scènesegment met een eigen door AI gegenereerde video, stilstaand beeld en audio. Alle URL-velden zijn absoluut en openbaar toegankelijk.

{
  "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"
  }]
}

Dezelfde bibliotheek waar het assetpaneel in de studio naar schrijft. Upload een personage, achtergrond, item of stijlreferentie, bewaar de id die je terugkrijgt en verwijs er bij het genereren naar door die id als seriesAssetId in de assets-array mee te geven. Je hoeft dus niet per video een nieuwe afbeeldingslink te maken. Afbeeldingen die je meestuurt, worden opnieuw gehost in onze opslag, zodat de id blijft werken nadat je eigen upload-URL is verlopen.

• Stuur één asset, of een "assets"-array om er tot 100 tegelijk te upserten.
• Standaard worden assets samengevoegd bij een exact gelijke naam, dus dezelfde catalogus opnieuw uploaden is idempotent. Behalve bij een personage waarvan de naam al in het verhaal voorkomt: dat geeft 409 SERIES_NAME_EXISTS met het bestaande personage, en er wordt niets opgeslagen. Vraag het de gebruiker en stuur dan seriesDuplicate "new" om een tweede toe te voegen, of geef ?mergeStrategy=exact mee om het bestaande bij te werken. ?mergeStrategy=fuzzy kan tegen hernoemingen; insert maakt altijd een nieuwe asset aan.
• DELETE geeft 409 SERIES_ASSET_IN_USE met de afleveringen die de asset nog gebruiken (stories: id, title, clipCount) en verwijdert niets. Vraag het de gebruiker en stuur dan confirm: true (body of ?confirm=true): afleveringen houden hun eigen kopie en hun clips veranderen niet. Een personage met een lopende inhuring geeft 409 SERIES_ASSET_HIRED (hires) en kan pas worden verwijderd als de inhuring is afgelopen.
• Stel isHeroProduct in op een item (ad_spot) of isPrimaryBackground op een scène (news_analysis / persona_channel) om het vast te pinnen. Bij het genereren wordt de pin automatisch herkend — je hoeft heroItemId nooit handmatig te schrijven.

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 werkt nog steeds en is ongewijzigd, maar ondersteunt alleen personages. Gebruik bij voorkeur dit endpoint.

Uploadt en bewaart een referentieafbeelding van een personage voor een verhaal, zodat de AI een consistent gezicht en een consistente stijl gebruikt in alle verhalen. Deze bewerking is idempotent — het meerdere keren aanroepen met dezelfde personagenaam is veilig.

Stuur een voltooide video rechtstreeks naar een gekoppeld account, zodat een automatisering genereren → renderen → publiceren met één set inloggegevens kan aansturen. Koppel de accounts eerst in de app; dit endpoint publiceert ernaar.

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" }
  }'

Voor platforms met veel klanten. In plaats van één key en één gedeelde creditpot voor iedereen, waarbij één drukke klant het saldo voor de rest opmaakt en niemand kan zien wie wat heeft uitgegeven, maak je per klant een account aan en vul je dat aan vanuit je eigen saldo. Je klanten registreren zich hier nooit en betalen ons niet; de commerciële relatie blijft van jou.

externalId is je eigen id voor de klant. Twee keer aanroepen met dezelfde id geeft het bestaande account terug in plaats van een tweede aan te maken, dus een herhaald verzoek is veilig. De API-key krijg je één keer, bij het aanmaken, terug: we bewaren alleen een hash en kunnen hem niet opnieuw tonen, dus sla hem meteen op. Een nieuw account begint met een saldo van nul.

Is de oorspronkelijke key kwijt, roep dit endpoint dan aan met de key van het platform dat eigenaar is, zonder request body. Gebruik de account-ID of externalId. Dit trekt de vorige keys van het account in één keer in en geeft eenmalig een nieuwe apiKey terug (201). Bewaar die veilig. Herhaal je deze aanroep, dan wordt de key opnieuw vervangen; gewone nieuwe pogingen om een account aan te maken vervangen nooit een werkende key.

Zet credits over van je eigen saldo naar dat van het account. Het is een overboeking, geen gift, dus je kunt alleen weggeven wat je echt hebt gekocht. Geeft 402 als je eigen saldo niet toereikend is. :accountId accepteert zowel onze account-id als je externalId.

GET /api/v1/accounts toont je accounts met het saldo en de totale uitgaven van elk; GET /api/v1/accounts/:accountId/credits leest er één. De eigen key van een beheerd account heeft alleen generatiescopes: daarmee kun je nooit zelf accounts aanmaken of opwaarderen.

Yoh heeft een MCP-server, zodat AI-agents (Claude Code, Codex, Claude Desktop of elke andere MCP-client) verhalen in je account kunnen maken en bewerken: een nieuw verhaal schrijven vanuit een idee, de personages toevoegen en de video genereren, of de inhoud en dialoog van clips, verplaatsingen en inkortingen op de tijdlijn en vrije overlays wijzigen. Alles wat credits kost, wacht elke keer op je uitdrukkelijke goedkeuring. Het volgt dezelfde regels als de editor in de browser, dus een bewerking vanuit de terminal komt precies terecht waar een sleepactie terecht zou komen.

Drie manieren om het te gebruiken

Kies de manier die past bij de tools van je agent. De yoh-skill hieronder leert ze alle drie.

• MCP + browser (aanbevolen in Codex, Claude Code en de Claude-apps) De agent doet het werk via deze MCP-tools en bestuurt daarnaast een browsertabblad (Claude in Chrome, de browser van Codex): na elke stap opent hij de link uit het antwoord (de scripttabel na een nieuw verhaal, het clippaneel na een clipvideo, de lijst bij Alles genereren terwijl een run loopt, de geavanceerde editor voor de tijdlijn en tekstlagen, de MP4 van de render) en controleert hij het resultaat op de echte pagina. Log in die browser één keer in met hetzelfde account als de API-key. MCP en de pagina delen dezelfde gegevens: de afleveringspagina ververst zichzelf binnen enkele seconden na een MCP-wijziging, en de agent herlaadt de geavanceerde editor na een wijziging op de tijdlijn. Elke uitgave loopt via één weg: de MCP-prijsopgave of het prijsvenster van de app.
• Alleen browser (geen API-key) De agent werkt in je browser op de pagina's van yoh.app, zoals jij dat zou doen: Maken → Verhaal, de scripttabel en het clippaneel, de personage-editor en de modelkiezer, Alles genereren, de geavanceerde editor, versies en export. Elke uitgave loopt via het eigen prijsvenster van de app, en de agent typt nooit betaalgegevens of je inlogcode in.
• Alleen MCP (headless) Voor scripts, CI en bureaus die veel varianten maken: quote → confirmToken voor elke uitgave, poll get_job / get_run, stop met cancel_generation, maak varianten met create_story_versions en generate_all_clips, en download de videoUrl van elke voltooide render. Geen browser nodig.

Voorbeeld in elke modus: een advertentie van 16 seconden in 9:16, in het Engels en Japans, geschreven in een verhaal met het product, gegenereerd, als Japanse versie gemaakt en twee keer gerenderd.

Verbinden

Aanbevolen: log in met Yoh, geen API-sleutel nodig. Gebruik precies dit adres (yoh.app zonder www stuurt door, en het inloggen controleert het adres). In Claude Code:

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

Typ daarna /mcp, kies yoh en dan Authenticate, log in bij Yoh in de browser die opent met het account dat je wilt gebruiken, en keur goed.

In Codex (CLI, IDE-extensie of de ChatGPT-desktopapp) voeg je de server toe en log je in; zet daarna tool_timeout_sec = 300 onder [mcp_servers.yoh] in ~/.codex/config.toml en herstart Codex:

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

• Claude-desktopapp of claude.ai: Customize → Connectors → + Add → Add custom connector, noem hem Yoh, plak het adres, dan Connect en inloggen. Zet hem per chat aan via + → Connectors. Bij Team- of Enterprise-abonnementen voegt een eigenaar hem eerst toe.
• Cursor: voeg yoh met dit adres toe aan ~/.cursor/mcp.json en log in als Cursor erom vraagt.
• ChatGPT: Plugins → + → Add custom MCP server, noem hem Yoh, plak het adres en log in. Bij sommige abonnementen moet een beheerder eigen servers eerst toestaan.

Controleer het: vraag je agent get_credits uit te voeren; die hoort je Yoh-saldo te tonen. Gekoppelde apps zie en ontkoppel je via Instellingen → API-sleutels → Gekoppelde apps.

Zodat je agent de pagina’s ziet die hij wijzigt: Claude Code met claude --chrome (de extensie Claude in Chrome), de Claude-desktopapp met de connector Claude in Chrome, of Codex in de ChatGPT-desktopapp met zijn browser. De skill vertelt de agent wanneer hij moet kijken.

Of gebruik een API-sleutel (scripts, CI, apps zonder inloggen)

Maak een API-key aan op /api-keys. Wil je nieuwe verhalen maken en video genereren, voeg dan stories:generate toe; om te bewerken zonder credits uit te geven, zijn stories:read en stories:write genoeg. Daarna in Claude Code:

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

Of commit een projectconfiguratie, zodat een heel team de verbinding krijgt bij het openen van de repo; ieder lid levert zijn eigen key via env:

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

Voeg in Codex de server toe aan ~/.codex/config.toml en stel YOH_API_KEY in je shell in:

# 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

Installeer de Yoh-skill

De skill leert je agent hoe hij een Yoh-verhaal goed maakt en bewerkt: begin in een verhaal, bepaal de prijs voordat je uitgeeft en bekijk de clips voordat je ze beoordeelt. Het is één bestand dat gelijk blijft met de server. Voer de regel voor je agent uit, of download 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

Vraag dan gewoon: “maak een verhaal van 60 seconden over een nachtverpleegkundige die geesten kan horen” of “maak het tempo van aflevering 3 strakker: haal de stiltes eruit, zet de ondertitels op de beats en render opnieuw”. Voer /mcp uit in Claude Code of Codex om de verbinding te controleren.

Wat de agent kan doen

Hoe het veilig en correct blijft

• De server handhaaft de regels van de editor (verschuivingen, grenzen voor inkorten, ondertitelsporen, overlay-rijen) en beantwoordt een overtreding met het toegestane bereik in plaats van het stilletjes te corrigeren.
• De agent leest alle regels uit de bron yoh://guide/timeline, en de prompt /mcp__yoh__edit-story geeft hem een veilige werkwijze.
• Genereren is asynchroon: de meeste tools geven een runId terug die de agent met get_run pollt; een paar (create_story, render_story, personageafbeeldingen) geven een jobId voor get_job terug, net als de REST API.
• Stel in .mcp.json een lange timeout in (bijvoorbeeld 900000), zodat een render aan de clientkant niet verloopt.

Controleer je verbinding

De repo bevat een smoketest. Die spreekt het echte protocol, test de regels en bewijst dat de uitgavebeveiliging werkt. Hij geeft nooit credits uit en zijn enige schrijfactie wordt teruggedraaid:

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

Endpoints voor het beheer van API-keys gebruiken session authentication (cookie van de ingelogde gebruiker), geen API-key. Gebruik de API Keys page voor een workflow via de browser, of roep deze endpoints programmatisch aan vanuit je backend met een geldige sessie. /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.

De meeste endpoints retourneren een error-object met een machineleesbare code. Gespecialiseerde endpoints kunnen een foutmelding als tekst of een code op het hoogste niveau retourneren; controleer altijd de HTTP-status.

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