API-Referenz

Erstelle dein erstes Video in drei API-Aufrufen: generieren → abfragen → herunterladen.

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
}

Alle API-Anfragen müssen deinen API-Key im Authorization-Header mit dem Bearer-Schema enthalten.

Authorization: Bearer sk_live_YOUR_API_KEY

API-Keys beginnen mit sk_live_. Du kannst Keys auf der API Keys page erstellen und verwalten. /api-keys

Jedem API-Key sind ein oder mehrere Scopes zugewiesen, die steuern, auf welche Endpunkte er zugreifen kann. Die Textgenerierung für eine Story kostet 55 Credits pro Job; Scopes, die zusätzlich Clips oder ein finales Rendern erzeugen (einschließlich des Standard-Scopes „full“), berechnen diese vorab zusätzlich. Credits werden erstattet, falls der Job nach allen Versuchen fehlschlägt.

Übermittelt einen Prompt und gibt sofort eine jobId zurück. Das Video wird asynchron generiert. Frage GET /api/v1/stories/jobs/:jobId ab, um den Fortschritt zu verfolgen.

Request-Body

assets[] optional

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 optional

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 optional

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 optionale Felder

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

Antwort 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

Frage diesen Endpunkt nach dem Aufruf von POST /api/v1/stories/generate ab. Der Job dauert normalerweise 8–15 Minuten, abhängig von der Länge der Story und davon, ob renderVideo aktiviert ist. Empfohlenes Abfrageintervall: alle 15–30 Sekunden.

Lebenszyklus des Job-Status

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.

Antwortfelder

Nach Abschluss eines Jobs kannst du alle für die Story generierten Assets über die vom Job zurückgegebene storyId abrufen. Alle Asset-Endpunkte erfordern den Scope assets:read.

Jeder Clip ist ein Szenensegment mit eigenem AI-generiertem Video, Standbild und Audio. Alle URL-Felder sind absolut und öffentlich zugänglich.

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

Dieselbe Library, in die auch das Asset-Panel im Studio schreibt. Lade einen Charakter, einen Hintergrund, ein Item oder eine Style-Referenz hoch, behalte die zurückgegebene ID und referenziere sie bei der Generierung, indem du diese ID als seriesAssetId im Assets-Array übergibst – so musst du nicht für jedes Video einen neuen Bild-Link erstellen. Von dir übermittelte Bilder werden auf unserem Speicher neu gehostet, sodass die ID auch nach Ablauf deiner eigenen Upload-URL gültig bleibt.

• Sende ein einzelnes Asset oder ein „assets“-Array, um bis zu 100 gleichzeitig zu aktualisieren oder einzufügen.
• Standardmäßig werden Assets bei exakter Namensübereinstimmung zusammengeführt, sodass das erneute Hochladen desselben Katalogs idempotent ist – außer bei einem Charakter, dessen Namen die Story bereits hat: Das führt zu 409 SERIES_NAME_EXISTS mit dem vorhandenen Charakter, es wird nichts gespeichert. Frage den User, sende dann seriesDuplicate "new", um einen zweiten hinzuzufügen, oder übergib ?mergeStrategy=exact, um den bestehenden zu aktualisieren. ?mergeStrategy=fuzzy ist tolerant gegenüber Umbenennungen; insert erstellt immer ein neues Asset.
• DELETE antwortet mit 409 SERIES_ASSET_IN_USE und den Episoden, die das Asset noch verwenden (Storys: ID, Titel, Clip-Anzahl), und löscht nichts. Frage den User, sende dann confirm: true (Body oder ?confirm=true): Episoden behalten ihre eigene Kopie und ihre Clips ändern sich nicht. Ein Charakter in einem offenen Casting-Vorgang antwortet mit 409 SERIES_ASSET_HIRED (Hires) und kann erst entfernt werden, wenn das Besetzen beendet ist.
• Setze isHeroProduct bei einem Item (ad_spot) oder isPrimaryBackground bei einer Szene (news_analysis / persona_channel), um sie zu pinnen. Bei der Generierung wird der Pin automatisch aufgelöst – du musst die heroItemId nie manuell schreiben.

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 funktioniert weiterhin unverändert, verarbeitet aber nur Charaktere. Nutze bevorzugt diesen Endpunkt.

Lädt ein Charakter-Referenzbild für eine Story hoch und speichert es, damit die AI ein konsistentes Gesicht und einen konsistenten Look über alle Episoden dieser Story hinweg verwendet. Dieser Vorgang ist idempotent – ihn mehrfach mit demselben Charakternamen aufzurufen, ist sicher.

Übertrage ein fertiges Video direkt an einen verknüpften Account, sodass eine Automatisierung generieren → rendern → veröffentlichen mit nur einem Zugang steuern kann. Verknüpfe die Accounts zuerst in der App; dieser Endpunkt veröffentlicht auf ihnen.

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 Plattformen, die viele Kunden bedienen. Anstatt eines Keys und eines Credit-Pools für alle – wo ein aktiver Kunde das Guthaben für den Rest aufbraucht und niemand sagen kann, wer was ausgegeben hat – kannst du pro Kunde ein Konto bereitstellen und jedes aus deinem eigenen Guthaben finanzieren. Deine Kunden melden sich nie hier an oder bezahlen uns; die Geschäftsbeziehung bleibt bei dir.

externalId ist deine eigene ID für den Kunden. Ein zweifacher Aufruf mit derselben ID gibt das bestehende Konto zurück, anstatt ein zweites zu erstellen, sodass ein wiederholter Request sicher ist. Der API-Key wird einmalig bei der ersten Erstellung zurückgegeben – wir speichern einen Hash und können ihn nicht erneut anzeigen, also speichere ihn dauerhaft, wenn du ihn erhältst. Ein neues Konto beginnt mit einem Guthaben von Null.

Wenn der ursprüngliche Key verloren ging, rufe diesen Endpunkt mit dem Plattform-Key des Eigentümers und ohne Request-Body auf. Verwende die Account-ID oder externalId. Er widerruft atomar die vorherigen Keys des Kontos und gibt einmalig einen neuen apiKey zurück (201). Speichere ihn sicher. Ein wiederholter Aufruf rotiert den Key erneut; normale Wiederholungsversuche bei der Kontobereitstellung ersetzen niemals einen funktionierenden Key.

Überträgt Credits von deinem eigenen Guthaben auf das des Kontos – ein Transfer, keine Gewährung, du kannst also nur das weitergeben, was du tatsächlich gekauft hast. Gibt 402 zurück, wenn dein eigenes Guthaben dies nicht deckt. :accountId akzeptiert entweder unsere Account-ID oder deine externalId.

GET /api/v1/accounts listet deine Konten mit dem jeweiligen Guthaben und den Gesamtausgaben auf; GET /api/v1/accounts/:accountId/credits liest eines aus. Der eigene Key eines verwalteten Kontos verfügt nur über Berechtigungen zum Generieren – er kann niemals selbst Konten bereitstellen oder finanzieren.

Yoh liefert einen MCP-Server aus, damit AI-Agenten (Claude Code, Codex, Claude Desktop oder jeder MCP-Client) Storys in deinem Account erstellen und bearbeiten können: schreibe eine neue Story aus einer Idee, füge ihre Charaktere hinzu und generiere das Video, oder ändere Clip-Inhalte und Dialoge, Timeline-Verschiebungen und Kürzungen sowie freiform-Overlays. Alles, was Credits kostet, wartet jedes Mal auf deine ausdrückliche Zustimmung. Es gelten dieselben Regeln wie im Browser-Editor, sodass eine Bearbeitung aus dem Terminal genau dort landet, wo auch ein Drag landen würde.

Drei Arten der Nutzung

Wähle den Modus, der zu den Tools deines Agents passt. Der Yoh-Skill unten deckt alle drei ab.

• MCP + Browser (empfohlen in Codex, Claude Code und den Claude-Apps) Der Agent arbeitet über diese MCP-Tools und steuert daneben einen Browser-Tab (Claude in Chrome, Codex-Browser): Nach jedem Schritt öffnet er den enthaltenen Link (die Skript-Tabelle nach einer neuen Story, das Clip-Panel nach einem Clip-Video, die „Alle generieren“-Liste während eines Durchlaufs, den erweiterten Editor für Timeline und Textebenen, die MP4 des Renders) und prüft das Ergebnis auf der echten Seite. Melde dich in diesem Browser einmal mit demselben Account wie für den API-Key an. MCP und die Seite teilen sich dieselben Daten: Die Episoden-Seite aktualisiert sich innerhalb von Sekunden nach einer MCP-Änderung, und der Agent lädt den erweiterten Editor nach einer Timeline-Änderung neu. Jede Ausgabe erfolgt nur über einen Pfad: das MCP-Angebot oder den Preisdialog der App.
• Nur Browser (kein API-Key) Der Agent bedient die yoh.app-Seiten in deinem Browser so, wie du es tun würdest: Erstellen → Story, die Skript-Tabelle und das Clip-Panel, der Charakter-Editor und dessen Modellauswahl, Alle generieren, der erweiterte Editor, Versionen und Export. Jede Ausgabe erfolgt über den app-eigenen Preisdialog, und der Agent gibt niemals Zahlungsdaten oder deinen Anmeldecode ein.
• Nur MCP (Headless) Für Skripte, CI und Agenturen, die viele Varianten erstellen: quote → confirmToken für jede Ausgabe, Abfrage von get_job / get_run, Stoppen mit cancel_generation, Erstellen von Varianten mit create_story_versions und generate_all_clips sowie Download der videoUrl jedes fertigen Renders. Kein Browser erforderlich.

Beispiel in jedem Modus: Eine 16-sekündige 9:16-Anzeige auf Englisch und Japanisch, geschrieben als Story mit ihrem Produkt, generiert, als japanische Version angelegt und zweimal gerendert.

Verbinden

Empfohlen: Mit Yoh anmelden, kein API-Schlüssel nötig. Verwende genau diese Adresse (yoh.app ohne www leitet weiter, und die Anmeldung prüft die Adresse). In Claude Code:

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

Gib dann /mcp ein, wähle yoh, dann Authenticate, melde dich im geöffneten Browser mit dem gewünschten Konto bei Yoh an und bestätige.

In Codex (CLI, IDE-Erweiterung oder ChatGPT-Desktop-App) den Server hinzufügen und anmelden, dann unter [mcp_servers.yoh] in ~/.codex/config.toml tool_timeout_sec = 300 setzen und Codex neu starten:

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

• Claude-Desktop-App oder claude.ai: Customize → Connectors → + Add → Add custom connector, Name Yoh, Adresse einfügen, dann Connect und anmelden. In jedem Chat über + → Connectors einschalten. Bei Team- oder Enterprise-Plänen fügt ihn zuerst ein Owner hinzu.
• Cursor: yoh mit dieser Adresse in ~/.cursor/mcp.json eintragen und anmelden, wenn Cursor fragt.
• ChatGPT: Plugins → + → Add custom MCP server, Name Yoh, Adresse einfügen und anmelden. Bei manchen Plänen muss ein Admin eigene Server erst erlauben.

Prüfen: Lass deinen Agenten get_credits ausführen; er sollte dein Yoh-Guthaben zeigen. Verbundene Apps siehst und trennst du unter Einstellungen → API-Schlüssel → Verbundene Apps.

Damit dein Agent die Seiten sieht, die er ändert: Claude Code mit claude --chrome (Erweiterung Claude in Chrome), die Claude-Desktop-App mit dem Connector Claude in Chrome oder Codex in der ChatGPT-Desktop-App mit ihrem Browser. Der Skill sagt dem Agenten, wann er nachsehen soll.

Oder mit API-Schlüssel (Skripte, CI, Apps ohne Anmeldung)

Erstelle einen API-Key unter /api-keys. Um neue Storys zu erstellen und Videos zu generieren, schließe stories:generate ein; zum Bearbeiten ohne Kosten reichen stories:read und stories:write aus. Dann in Claude Code:

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

Oder hinterlege eine Projekt-Konfiguration, damit ein ganzes Team die Verbindung erhält, wenn es das Repo öffnet, wobei jedes Mitglied seinen eigenen Key via env bereitstellt:

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

Füge in Codex den Server zu ~/.codex/config.toml hinzu und setze YOH_API_KEY in deiner 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

Installiere den Yoh-Skill

Der Skill bringt deinem Agent bei, wie man eine Yoh-Story gut erstellt und bearbeitet: in einer Serie starten, Preise vor dem Ausgeben prüfen und die Clips ansehen, bevor man sie bewertet. Es ist eine einzelne Datei, die mit dem Server aktuell gehalten wird. Führe die Zeile für deinen Agent aus, oder SKILL.md herunterladen

# 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

Frage dann einfach: „Erstelle eine 60-sekündige Story über eine Nachtschwester, die Geister hören kann“ oder „Straffe das Pacing von Episode 3: kürze die Pausen, verschiebe die Untertitel auf die Beats und rendere neu“. Führe /mcp in Claude Code oder Codex aus, um die Verbindung zu prüfen.

Was der Agent tun kann

Wie es sicher und korrekt bleibt

• Der Server erzwingt die Regeln des Editors (Verschieben von Slides, Trim-Grenzen, Untertitel-Spuren, Overlay-Zeilen) und beantwortet einen Verstoß mit dem erlaubten Bereich, anstatt ihn stillschweigend zu kappen.
• Der Agent liest das vollständige Regelwerk aus der Ressource yoh://guide/timeline, und der Prompt /mcp__yoh__edit-story gibt ihm einen sicheren Workflow vor.
• Die Generierung erfolgt asynchron – die meisten Tools geben eine runId zurück, die der Agent mit get_run abfragt; einige wenige (create_story, render_story, Charakter-Grafik) geben eine jobId für get_job zurück, genau wie die REST-API.
• Setze einen hohen Timeout in der .mcp.json (zum Beispiel 900000), damit ein Rendern auf Client-Seite nicht abbricht.

Verbindung verifizieren

Ein Smoke-Test wird mit dem Repo ausgeliefert. Er nutzt das echte Protokoll, prüft die Regeln und beweist, dass die Ausgabensperre hält – er verbraucht niemals Credits, und sein einziger Schreibvorgang wird rückgängig gemacht:

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

Endpunkte für die API-Key-Verwaltung verwenden session authentication (Cookie des angemeldeten Nutzers), keinen API-Key. Nutze das API Keys page für einen browserbasierten Workflow oder rufe diese Endpunkte programmatisch von deinem Backend mit einer gültigen Session auf. /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.

Die meisten Endpunkte geben ein error-Objekt mit einem maschinenlesbaren code zurück. Spezialisierte Endpunkte können einen Fehler als String oder einen Top-Level-Code zurückgeben; prüfe immer den HTTP-Status.

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