API-referens

Skapa din första video med tre API-anrop: generera → kontrollera → ladda ner.

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
}

Alla API-anrop måste inkludera din API-nyckel i headern Authorization med schemat Bearer.

Authorization: Bearer sk_live_YOUR_API_KEY

API-nycklar börjar med sk_live_. Du kan skapa och hantera nycklar från API Keys page. /api-keys

Varje API-nyckel tilldelas ett eller flera omfång som styr vilka slutpunkter den har åtkomst till. Textgenerering för en berättelse kostar 55 credits per jobb; omfång som även skapar klippvideor eller en slutlig rendering (inklusive standardomfånget full) debiteras för dessa i förskott utöver det. Credits återbetalas om jobbet misslyckas efter alla försök.

Skickar in en prompt och returnerar ett jobId omedelbart. Videon genereras asynkront. Kontrollera GET /api/v1/stories/jobs/:jobId för att följa förloppet.

Anropskropp

assets[] valfri

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 valfri

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 valfri

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.

Andra valfria fält

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

Svar 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

Kontrollera den här slutpunkten efter att du har anropat POST /api/v1/stories/generate. Jobbet tar vanligtvis 8–15 minuter beroende på berättelsens längd och om renderVideo är aktiverat. Vi rekommenderar att du kontrollerar var 15–30 sekunder.

Livscykel för jobbstatus

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.

Svarsfält

När ett jobb är klart kan du hämta alla resurser som genererats för berättelsen med det storyId som jobbet returnerade. Alla resursslutpunkter kräver omfånget assets:read.

Varje klipp är ett scensegment med egen AI-genererad video, stillbild och ljud. Alla URL-fält är absoluta och offentligt tillgängliga.

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

Samma bibliotek som Studions resurspanel skriver till. Ladda upp en karaktär, bakgrund, ett föremål eller en stilreferens, spara det returnerade id:t och referera till det vid generering genom att skicka id:t som seriesAssetId i assets-matrisen – du behöver inte skapa en ny bildlänk per video. Bilder du skickar lagras om hos oss, så id:t fortsätter att fungera även efter att din egen uppladdnings-URL har gått ut.

• Skicka en resurs, eller en ”assets”-matris för att uppdatera upp till 100 samtidigt.
• Som standard slås resurser ihop vid exakt namnmatchning, så att ladda upp samma katalog igen är idempotent – utom för en karaktär vars namn redan finns i berättelsen: då svarar systemet 409 SERIES_NAME_EXISTS med den befintliga karaktären och inget sparas. Fråga användaren och skicka sedan seriesDuplicate ”new” för att lägga till en till, eller skicka ?mergeStrategy=exact för att uppdatera den befintliga. ?mergeStrategy=fuzzy tål namnbyten; insert skapar alltid en ny resurs.
• DELETE svarar 409 SERIES_ASSET_IN_USE med de avsnitt som fortfarande använder resursen (stories: id, title, clipCount) och tar inte bort något. Fråga användaren och skicka sedan confirm: true (i body eller ?confirm=true): avsnitten behåller sin egen kopia och deras klipp ändras inte. En karaktär i ett pågående anlitande svarar 409 SERIES_ASSET_HIRED (hires) och kan inte tas bort förrän anlitandet upphör.
• Ange isHeroProduct på ett föremål (ad_spot) eller isPrimaryBackground på en scen (news_analysis / persona_channel) för att fästa det. Vid generering löses det fästa automatiskt – du behöver aldrig skriva heroItemId för hand.

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 fungerar fortfarande och är oförändrad, men den hanterar bara karaktärer. Använd hellre denna slutpunkt.

Laddar upp och sparar en referensbild för en karaktär i en berättelse så att AI:n använder samma ansikte och stil i alla avsnitt i berättelsen. Åtgärden är idempotent – det är säkert att anropa den flera gånger med samma karaktärsnamn.

Skicka en färdig video direkt till ett anslutet konto, så att en automatisering kan styra generera → rendera → publicera med en inloggning. Anslut kontona i appen först; denna slutpunkt publicerar till dem.

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

För plattformar som betjänar många kunder. I stället för en nyckel och en gemensam pott med credits för alla – där en aktiv kund tömmer saldot för de andra och ingen kan se vem som har spenderat vad – skapar du ett konto per kund och finansierar vart och ett från ditt eget saldo. Dina kunder registrerar sig aldrig här och betalar inte oss; affärsrelationen förblir din.

externalId är ditt eget ID för kunden. Om du anropar två gånger med samma ID returneras det befintliga kontot i stället för att ett nytt skapas, så ett upprepat anrop är säkert. API-nyckeln returneras en gång, vid första skapandet — vi sparar en hash och kan inte visa den igen, så spara den när du får den. Ett nytt konto startar med noll i saldo.

Om den ursprungliga nyckeln har gått förlorad anropar du den här slutpunkten med den ägande plattformsnyckeln och utan anropskropp. Använd kontots ID eller externalId. Anropet återkallar atomärt kontots tidigare nycklar och returnerar en ny apiKey en gång (201). Förvara den säkert. Om du upprepar anropet roteras nyckeln igen; vanliga omförsök att skapa konton ersätter aldrig en fungerande nyckel.

Flyttar credits från ditt eget saldo till kontots – en överföring, inte en gåva, så du kan bara dela ut det du faktiskt har köpt. Returnerar 402 när ditt eget saldo inte räcker. :accountId accepterar antingen vårt konto-ID eller ditt externalId.

GET /api/v1/accounts listar dina konton med respektive saldo och totala förbrukning; GET /api/v1/accounts/:accountId/credits läser ett konto. Ett hanterat kontos egen nyckel har bara genereringsomfång – den kan aldrig själv skapa eller finansiera konton.

Yoh har en MCP-server så att AI-agenter (Claude Code, Codex, Claude Desktop eller valfri MCP-klient) kan skapa och redigera berättelser i ditt konto: skriva en ny berättelse utifrån en idé, lägga till dess karaktärer och generera videon, eller ändra klippinnehåll och dialog, flytta och trimma i tidslinjen samt fria överlägg. Allt som kostar credits väntar på ditt uttryckliga godkännande varje gång. Servern följer samma regler som redigeraren i webbläsaren, så en ändring från terminalen hamnar exakt där en dragning skulle hamna.

Tre sätt att använda det

Välj det som passar de verktyg din agent har. Yoh-skillen nedan lär ut alla tre.

• MCP + webbläsare (rekommenderas i Codex, Claude Code och Claude-apparna) Agenten gör arbetet med dessa MCP-verktyg och styr en webbläsarflik bredvid (Claude in Chrome, Codex webbläsare): efter varje steg öppnar den länken som svaret innehåller (Manustabellen efter en ny berättelse, klippanelen efter en klippvideo, Generera alla-listan medan en körning pågår, den avancerade redigeraren för tidslinje och textlager, renderingens MP4) och kontrollerar resultatet på den riktiga sidan. Logga in en gång i den webbläsaren med samma konto som API-nyckeln. MCP och sidan delar samma data: avsnittssidan uppdateras av sig själv inom några sekunder efter en MCP-ändring, och agenten laddar om den avancerade redigeraren efter en ändring i tidslinjen. Varje kostnad går bara en väg: MCP-offerten eller appens prisdialog.
• Endast webbläsare (ingen API-nyckel) Agenten använder yoh.app-sidorna i din webbläsare, precis som du skulle göra: Skapa → Berättelse, Manustabellen och klippanelen, karaktärsredigeraren och dess modellväljare, Generera alla, den avancerade redigeraren, versioner och export. Varje kostnad går genom appens egen prisdialog, och agenten skriver aldrig in betalningsuppgifter eller din inloggningskod.
• Endast MCP (headless) För skript, CI och byråer som gör många varianter: quote → confirmToken för varje kostnad, kontrollera med get_job / get_run, stoppa med cancel_generation, skapa varianter med create_story_versions och generate_all_clips, och ladda ner videoUrl för varje färdig rendering. Ingen webbläsare behövs.

Exempel i varje läge: en 16 sekunder lång 9:16-annons på engelska och japanska, skriven i en berättelse med sin produkt, genererad, versionerad till japanska och renderad två gånger.

Anslut

Rekommenderat: logga in med Yoh, ingen API-nyckel behövs. Använd exakt den här adressen (yoh.app utan www omdirigerar, och inloggningen kontrollerar adressen). I Claude Code:

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

Skriv sedan /mcp, välj yoh och sedan Authenticate, logga in på Yoh i webbläsaren som öppnas med kontot du vill använda, och godkänn.

I Codex (CLI, IDE-tillägget eller ChatGPT-skrivbordsappen) lägger du till servern och loggar in, sätter sedan tool_timeout_sec = 300 under [mcp_servers.yoh] i ~/.codex/config.toml och startar om Codex:

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

• Claude-skrivbordsappen eller claude.ai: Customize → Connectors → + Add → Add custom connector, döp den till Yoh, klistra in adressen, sedan Connect och logga in. Slå på den i varje chatt via + → Connectors. På Team- eller Enterprise-planer lägger en ägare till den först.
• Cursor: lägg till yoh med den här adressen i ~/.cursor/mcp.json och logga in när Cursor ber om det.
• ChatGPT: Plugins → + → Add custom MCP server, döp den till Yoh, klistra in adressen och logga in. Vissa planer kräver att en admin tillåter egna servrar.

Kontrollera: be din agent köra get_credits; den ska visa ditt Yoh-saldo. Anslutna appar ser och kopplar du bort under Inställningar → API-nycklar → Anslutna appar.

Så att din agent ser sidorna den ändrar: Claude Code med claude --chrome (tillägget Claude in Chrome), Claude-skrivbordsappen med kopplingen Claude in Chrome, eller Codex i ChatGPT-skrivbordsappen med dess webbläsare. Skillen talar om för agenten när den ska titta.

Eller använd en API-nyckel (skript, CI, appar utan inloggning)

Skapa en API-nyckel på /api-keys. För att skapa nya berättelser och generera video, inkludera stories:generate; för att redigera utan kostnad räcker stories:read och stories:write. Sedan i Claude Code:

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

Eller checka in en projektkonfiguration så att ett helt team får anslutningen när de öppnar repot, där varje medlem anger sin egen nyckel via env:

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

I Codex lägger du till servern i ~/.codex/config.toml och anger YOH_API_KEY i ditt skal:

# 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

Installera Yoh-skillen

Skillen lär din agent att skapa och redigera en Yoh-berättelse på ett bra sätt: börja i en berättelse, ta fram ett pris innan du spenderar och titta på klippen innan du bedömer dem. Det är en enda fil som hålls uppdaterad med servern. Kör raden för din agent, eller ladda ner 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

Sedan är det bara att be: ”skapa en 60 sekunder lång berättelse om en nattsjuksköterska som kan höra spöken” eller ”strama åt tempot i avsnitt 3: trimma bort dödtid, flytta undertexterna till taktslagen och rendera om”. Kör /mcp i Claude Code eller Codex för att kontrollera anslutningen.

Vad agenten kan göra

Hur det förblir säkert och korrekt

• Servern upprätthåller redigerarens regler (förflyttningar, trimningsgränser, undertextspår, överläggsrader) och svarar vid en överträdelse med det tillåtna intervallet i stället för att tyst justera värdet.
• Agenten läser hela regelverket från resursen yoh://guide/timeline, och prompten /mcp__yoh__edit-story ger den ett säkert arbetsflöde.
• Generering sker asynkront – de flesta verktyg returnerar ett runId som agenten kontrollerar med get_run; ett fåtal (create_story, render_story, karaktärsbilder) returnerar ett jobId för get_job, precis som REST-API:et.
• Ställ in en lång timeout i .mcp.json (till exempel 900000) så att en rendering inte gör timeout på klientsidan.

Verifiera din anslutning

Ett röktest följer med i repot. Det använder det riktiga protokollet, prövar reglerna och visar att kostnadsspärren håller – det spenderar aldrig credits, och dess enda skrivning återställs:

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

Slutpunkter för hantering av API-nycklar använder session authentication (inloggad användares cookie), inte en API-nyckel. Använd API Keys page för ett webbläsarbaserat flöde, eller anropa dessa slutpunkter programmatiskt från din backend med en giltig session. /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 flesta slutpunkter returnerar ett error-objekt med en maskinläsbar code. Specialiserade slutpunkter kan returnera ett fel som en sträng eller en kod på toppnivå; kontrollera alltid HTTP-status.

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