API リファレンス
プログラムで AI 動画を生成します。プロンプトを送信し、完了をポーリングして、直接動画 URL を受け取ります — すべて REST で完結。
ベース URL: https://www.yoh.appサインインするまで、コード例はプレースホルダー sk_live_YOUR_API_KEY を使用します。
クイックスタート
3 回の API 呼び出しで最初の動画を作成:生成 → ポーリング → ダウンロード。
サインインしてAPI キーのページでキーを作成してください。生成とポーリングには stories:generate と stories:read を選び、表示されたらすぐにキー全体をコピーしてください。キーは一度しか表示されません。サーバーの環境変数かシークレット管理サービスに保管してください。アカウントには十分なクレジットが必要です。キーを作成してもクレジットは増えません。
curl https://www.yoh.app/api/v1/credits \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Every request that spends credits needs your consent: send X-Max-Generation-Credits with the most whole-number credits you accept (a price above it returns HTTP 409 with the quote, before charging). Without it the request is refused with HTTP 428 spend_consent_required and nothing is charged. To check cost first, POST the same body to /api/v1/stories/estimate (story create), use the route's own free preview (quoteOnly: true on /videos, with or without fixFirst, and on /clip-check, dryRun: true on /swap-asset), or send X-Max-Generation-Credits: 0: the 409 answer carries the price and nothing is charged. In a video job the creator's /videos quote carries overJobBudget { left, needed, message } when its price is over what's left in the job's AI budget. A /videos start also takes its quote's acceptedQuoteHash instead of the header (on a short balance, affordableQuoteHash with clipIds set to clipIdsAffordable). MCP tools send the price you confirmed for you. 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 "X-Max-Generation-Credits: 500" \
-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
}以上です。videoUrl はダウンロード、ストリーミング、または即座に共有できる公開アクセス URL です。
認証
すべての API リクエストは、Bearer スキームを使用して Authorization ヘッダーに API キーを含める必要があります。
Authorization: Bearer sk_live_YOUR_API_KEYAPI キーは sk_live_ で始まります。API Keys page からキーを作成・管理できます。 /settings/api-keys
API キーは秘密にしてください。クライアント側のコードや公開リポジトリに公開しないでください。キーが漏洩した場合は、すぐに API キーページから取り消してください。
スコープとクレジット
各 API キーには、アクセス可能なエンドポイントを制御する 1 つ以上のスコープが付与されます。ストーリーのテキスト生成はジョブごとに見積もられます(デフォルトのテキストモデルでアイデアから書く場合は約 55 クレジット。完成した脚本どおりに書く場合や別のテキストモデルファミリーではそれ以上。正確な数は /estimate で確認できます)。クリップ動画や最終レンダーを含むスコープ(デフォルトの full を含む)は、その分を前払いで追加請求します。全リトライ後にジョブが失敗した場合、クレジットは返還されます。プロバイダーが開始後に拒否または失敗した場合、プロバイダーが請求した分のクレジットは返金されません。
| スコープ | アクセス権限 |
|---|---|
| stories:generate | POST /api/v1/stories/generate, POST /stories/:id/assets, POST /stories/:id/storyboard, POST /stories/:id/videos, POST /stories/:id/render, POST /stories/:id/clips/:clipId/image, POST /stories/:id/clips/:clipId/video, POST /stories/:id/clips/:clipId/video-edit, POST /stories/:id/characters/:assetId/sheet, POST /stories/:id/soundtrack, POST /stories/:id/assets/:assetId/image, POST /stories/:id/looks/:lookId/image, POST /stories/:id/clips/:clipId/regenerate, POST /stories/:id/continue, POST /stories/:id/clips-all, POST /stories/:id/clips/:clipId/grid-reference, POST /stories/:id/clips/:clipId/lip-sync — and the story-asset edits: PATCH /stories/:id/characters|scenes|items/:assetId. Also implies assets:write and series:write, so keys issued before those scopes existed keep working. |
| stories:read | GET /api/v1/stories, GET /api/v1/stories/:id, GET /api/v1/stories/jobs/:id, GET /api/v1/credits, GET /api/v1/models (the models and visual styles the pickers offer, with durations, resolutions, aspect ratios, reference limits, frame modes, credits per resolution and retired ids; music is the soundtrack model, ElevenLabs Music v2.5, and lipSync the lip-sync model, H3 Max Lip Sync, with whether it is enabled, its resolutions and per-second prices), POST /api/v1/stories/estimate, POST /api/v1/stories/analyze-prompt, and the story reads: GET /stories/:id/removed-clips, GET /stories/:id/archived-storylines, GET /stories/:id/readiness, /attention, /spend, /renders, /versions, /version, /version/lines, /soundtrack, /clip-check, /media, /upload, /clips/:clipId/version, /clips/:clipId/audio-sync. Implies series:read and assets:read. |
| stories:write | The clip edits: POST/PATCH /stories/:id/clips, PATCH/DELETE /stories/:id/clips/:clipId (DELETE moves the clip to Removed clips), POST /stories/:id/clips/:clipId/restore (adds a removed clip back), DELETE /stories/:id/storylines/:storylineId (archives a branch), POST /stories/:id/storylines/:storylineId/restore, POST /stories/:id/clips/:clipId/duplicate, POST /stories/:id/clips/:clipId/lip-sync/apply; a hired character's looks: POST /stories/:id/characters/:assetId/hire-looks; a version's lines: PUT /stories/:id/version/lines; starting an episode from your own video: POST /api/v1/series/:id/uploads, POST /stories/:id/upload (GET with stories:read; so is GET /stories/:id/media, every file of a story); and the MCP server's editing tools (POST /api/mcp): clip content and dialogue, timeline moves/trims/captions, freeform overlays, cast and set edits. Ordinary edits spend no credits. MCP ask_assistant charges its text turn immediately and, like quoted media generation, requires stories:generate. Implied by stories:generate; implies assets:write. |
| assets:read | GET .../characters, .../scenes, .../items, .../clips, .../clips/:clipId, GET .../characters/:assetId/hire-looks, GET /api/v1/series/:id/assets |
| assets:write | POST /api/v1/series/:id/assets, PATCH/DELETE /api/v1/series/:id/assets/:assetId, POST /api/v1/series/:id/assets/:assetId/style-copy, POST /api/v1/uploads, POST /api/v1/uploads/presign (a one-time PUT URL for an audio, video or image file) |
| series:read | GET /api/v1/series, GET /api/v1/series/:id |
| series:write | POST /api/v1/series, PATCH /api/v1/series/:id |
| social:publish | POST /api/v1/social/publish, GET /api/v1/social/publish/:postId |
| accounts:manage | GET/POST /api/v1/accounts, GET/POST /api/v1/accounts/:accountId/credits. For platforms that serve many customers: provision an account per customer and fund it from your own balance. Implied by nothing — an existing key never gains it. |
| hires:read | The MCP hiring reads: hire listings, creators who take video jobs, your hires and deliveries, casting calls and applicants, open video job requests, message threads, your earnings (get_earnings) and how hires pay you (set_payout_method without a method). Changed 2026-10-30 (breaking): get_earnings and set_payout_method used to run on stories:read / stories:write; they now need hires:read (switching the method needs hires:write), so a key with only stories:* scopes loses them. set_payout_method needs hires:read (switching also hires:write); the key picker gives both. Implied by nothing. |
| hires:write | The MCP hiring actions: send, answer and cancel hires and video jobs, deliver and review work, casting calls and open video job requests, your hire listing, messages, switching how hires pay you (set_payout_method with a method). A payment returns a checkoutUrl for a person to open; MCP never charges a saved card. Accepting a delivery or anything that releases money needs a confirmToken. Implied by nothing. |
| ads:read | The MCP Yoh Ads reads: shows, briefs and results. Implied by nothing. |
| ads:write | The MCP Yoh Ads actions: create and edit shows, write and make episodes, pause and resume. Budgets, autopilot and Meta launches need a confirmToken. Implied by nothing. |
| publish:write | The MCP publish tools: publish and unpublish an episode on Yoh (not social posting, which is social:publish). Implied by nothing. |
動画を生成
動画生成ジョブをキューに追加
/api/v1/stories/generatescope: stories:generateプロンプトを送信して即座に jobId を返します。動画は非同期で生成されます。GET /api/v1/stories/jobs/:jobId をポーリングして進捗を追跡してください。
リクエストボディ
| フィールド | 型 | ステータス | 説明 |
|---|---|---|---|
prompt | string | 必須 | ストーリーの説明(最大 20000 文字)。 |
aspectRatio | string | 任意 | 16:9、9:16、1:1 のいずれか。デフォルト:1:1(ad_spot, host, persona_channel, news_analysis, music_video は 9:16)。seriesId を指定するとそのシリーズのエピソードの比率(エピソードがまだないストーリーシリーズは 16:9)。 |
renderVideo | boolean | 任意 | false — 完成動画なし:ジョブの videoUrl は null で、最初のクリップの動画は firstClipVideoUrl にあります。true — Remotion を使用してすべてのクリップを 1 つの合成 MP4(videoUrl)にレンダリングします(約 12–15 分)。 |
scope | string | 任意 | story (text only) or full (text, images and clip videos; default). Use renderVideo: true with full to include the final MP4 and its render fee. Other values return 400 before charging. For assets, storyboard, videos or render on an existing story, use the separate /api/v1/stories/:storyId endpoints below. |
title | string | 任意 | ストーリーの表示名。 |
contentType | string | 任意 | ストーリー形式カテゴリ。cinematic_story、host、news_analysis、persona_channel、ad_spot のいずれか。デフォルト:cinematic_story。host はプロンプトから news_analysis か persona_channel を選びます。 |
locale | string | 任意 | en · zh-TW · ko · ja · th · id · es · pt · nl · sv · he · de · it · pl · fr のいずれか。デフォルト:アプリまたはアカウントの言語、なければ en。 |
seriesId | string | 任意 | 一貫したキャラクタービジュアルのために既存のシリーズに関連付けます。 |
assets | array | 任意 | The cast and props for this story — reference assets already in your series library, or attach one-off assets inline. See the table below. |
continuityMode | string | 任意 | With a seriesId: how much of the previous episodes this one carries. episodic_continuous (default) picks up open threads, finale resolves them, one_off_episode keeps series plot out entirely: it neither takes nor sets the series' colour tone and title look and writes no series continuity bookkeeping (on Auto it takes the series' style like any episode). A quote's style setting reads source: "series" when the series decides the style, with the attention line "This story takes the series' style: <name>". An episode whose continuity has not been planned yet records continuity status not_planned: information, not a warning. |
isFinale | boolean | 任意 | Implied by continuityMode: "finale"; you rarely need both. |
allowMultiStory | boolean | 任意 | Let one request split into several episodes when the prompt clearly carries more than one. Default false — N episodes means N charges, so it is opt-in. |
seriesContinuityContext | object | 任意 | Escape hatch. Supplying it replaces the continuity we assemble from your series (open threads plus the last three episode recaps), so an incomplete object produces a weaker episode than sending nothing. Prefer continuityMode. |
assets[] 任意
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. A library character starts with its portrait; when cast art starts, its library sheet is reused free if the outfit stays, the sheet is in the story's style family, the character is not a hired or licensed face or kept episode-only, and the sheet has no open quality flags and did not fail (a sheet with no recorded style counts as the medium its own sheet request stated, else it is redrawn).
| フィールド | 型 | 説明 |
|---|---|---|
seriesAssetId | string | Reference an existing library asset. Everything else is optional when this is set. |
type | string | character · scene · item · reference. Required for an inline asset. |
name | string | Required for an inline asset. Also how the writer refers to it — name it in your prompt for it to appear. |
description | string | Overrides the library description for this story only. |
imageUrl | string | Image for an inline asset. Re-hosted on our storage. |
itemType | string | Items only: prop · product · logo. A logo is composited flat, never given 3D depth. |
isHeroProduct | boolean | ad_spot: the advertised product — appears in every clip. Fills heroItemId for you. |
isPrimaryBackground | boolean | host / news_analysis / persona_channel: the set reused across every shot. ad_spot: the real place (e.g. your shop) used in the shots that name it. Fills primaryBackgroundAssetId for you. |
useAsReferenceFrame | boolean | Use this image as the first frame / reference for image-to-video on clips featuring the asset. |
gender | string | Characters only: surfaced to the writer. |
age | string | Characters only: surfaced to the writer. |
personalityTraits | string[] | Characters only: surfaced to the writer. |
timeOfDay | string | Scenes only, e.g. dusk. |
weather | string | Scenes only, e.g. rain. |
persist | boolean | Accrue an inline asset into the series library so later stories can reference it by id. Default false. |
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 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, textFamily, 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, Seedance 2.0 Mini up to 720p, Kling from 720p, MiniMax H3 from its 768p tier, which the app still calls 720p (it renders slightly sharper), and up to its 2K tier, which the app calls 1080p (it renders 1440p); GET /api/v1/models gives each model's resolutionLabels, what each resolution renders as). 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.
| フィールド | 型 | 値 | デフォルト |
|---|---|---|---|
storyInputMode | string | auto · develop · follow_script (auto decides whether the prompt is an idea to develop or a finished script to follow verbatim, for every contentType; follow_script on a synopsis or outline is refused free with not_a_script; a cue marked (V.O.) or (O.S.) becomes an offscreen: true line, voiced over the video in that character's own voice) | auto |
durationSec | number | 15–192 (total seconds; about one clip per 5 s, at least 2, each sized to its content — 16 → 3 clips, 20 → 4, 60 → 12; longer content is split into episodes) | 32 (ad_spot 15; music_video 30; host follows its pick: persona_channel 30, news_analysis 45) |
clipCount | number | 2–24 clips sharing durationSec, 4–12 s each (16 with 4 = 4 × 4 s); a count that does not fit is refused 400. Omitted: about one clip per 5 s, or the count the prompt names ("in 4 clips") | — |
fixedRuntime | boolean | true keeps durationSec and clipCount exactly (a funded draft: the deal's runtime and clip count); pacing still varies each clip inside that total. Needs clipCount | false |
lengthDefaulted | boolean | true when durationSec is the create default, not a length the person or the brief asked for. The write fits the story to durationSec: exactly for a sent length or a full job (quoted at that length); a defaulted length whose videos are quoted after the write gets 15 % room and no clip under 5 s. The server sets it when no length is sent | false |
videoQuotedAtLength | boolean | true when the videos were quoted at durationSec before the write (a full job): the story is then fitted to exactly that length. Sending it can only make the fit exact; the 15 % room for a defaulted length is never given on request | false |
aspectRatio | string | 16:9 · 9:16 · 1:1 | 1:1 (9:16 for ad_spot, host, persona_channel, news_analysis, music_video; a series' episode shape when seriesId is given) |
resolution | string | 480p · 720p · 1080p | 720p |
pace | string | slow · normal · fast | normal |
structure | string | auto · 3_act · 4_act · montage | auto |
captionStyle | string | standard · words — how dialogue captions show: each line whole, or word by word (TikTok style: a few words at a time, the spoken word highlighted). Change it later with MCP update_caption_settings style | words for 9:16, else standard |
qualityTier | string | draft · balanced · premium (premium selects the advanced model lane) | balanced |
stylePreset | string | The base style: auto, or a visual style id (list_style_presets kind visual). An unknown id is refused 400; your own touch on it goes in the top-level customStyle | auto |
platformTarget | string | ADVISORY — shown to the writer as context; nothing enforces it. youtube · tiktok · instagram · x | youtube |
safetyMode | string | ADVISORY — shown to the writer as context; not a content filter. standard · strict | standard |
seed | string | any string — shared across clips for continuity (API-only) | — |
videoModel | string | a model id, or auto (Seedance 2.0). bytedance/seedance-2.0-mini is the cheapest Seedance (about half Seedance 2.0; the same references, 4–15 s, 480p/720p; not on the realistic-people list). GET /api/v1/models lists them | auto |
videoEditModel | string | video editing only — bytedance/seedance-2.5-video-edit (Seedance 2.5 Video Edit), or auto. The old ids muapi/sd25-video-edit and muapi/sd2-video-edit are still accepted and mean the same model. Omit to keep the existing editing recipe. | auto |
imageModel | string | clip images (the optional storyboard) + scene/item images — a model id, or auto (GPT Image 2.5) | auto |
characterImageModel | string | character portraits, sheets and appearance variants — auto (GPT Image 2.5), google/nano-banana-2, bytedance/seedream-5-pro or xai/grok-imagine-image-2.0 (list_models: character) | auto |
textFamily | string | the story's text models as one family — auto (Claude), claude (Opus 5.5 · Haiku 5.5), gpt (GPT-6.1 Sol · GPT-6 Luna) or grok (Grok 4.7 · Grok 4.20 Fast). The writing, rewrites, assistant turns, translations and clip prompts run on it and the quote prices it. An unknown value is refused 400. Also accepted top-level and in MCP create_story / estimate_story / update_story | auto |
modelStrategy | string | auto · fixed · cost_optimized · quality_first · hero_premium | auto |
generationMode | string | DEPRECATED — ignored. Each clip's frame mode (omni · start · start_end: the planner's pick or MCP set_clip_frame_mode) decides frame or reference inputs; a model that cannot run it runs the next one down. Two families: start and start_end mix clips into one continuous flow; omni, the reference mode, stands alone and its neighbours do not constrain it. | auto |
locale | string | en · zh-TW · ko · ja · th · id · es · pt · nl · sv · he · de · it · pl · fr (also accepted top-level) | your app / account language, else en |
contentTypeConfig 任意
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.
| contentType | フィールド |
|---|---|
| cinematic_story | (no per-type fields — format craft is built in) |
| host | primaryBackgroundAssetId, primaryBackgroundName (pin the host's set). Nothing else: the prompt picks news_analysis (a topic, event, how-to or explainer) or persona_channel (a personal take, review, vlog or day in the life), and tone, angle and call to action come from the prompt. The estimate names a first pick from the prompt's words; the run's first model step makes the final pick (no extra charge) and the story is saved as it |
| news_analysis | primaryBackgroundAssetId, primaryBackgroundName (pin a studio scene across anchor shots) |
| persona_channel | primaryBackgroundAssetId, primaryBackgroundName (pin the persona's set) |
| music_video | song: { songId (required: from analyze_song, your own song; another id answers 404 song_not_found, none answers 400 song_required), start, end (the part to use, seconds; omitted: the suggested part), noSinging (nobody sings on screen) }. The song's file and title come from the listen. Singers are optional: the prompt says who sings or acts. The writer listens first: one clip per shot of the part (4–15 s, cut on strong beats), each as long as its piece of the song; sung shots show the singer singing on camera, the rest are story shots; no dialogue, the lyrics are captions. A listen still running answers 409 song_listening; a part too short or too long for its shots answers 400 song_part_too_short / song_part_too_long. Nothing is charged on a refusal. |
| ad_spot | heroItemId, heroProductName, heroTagline, heroKeyBenefit, primaryBackgroundAssetId, primaryBackgroundName (the advertised product, and optionally the real place it is sold or used). heroItemId is an item of the seriesId series: its name fills an empty heroProductName (the tagline is never invented from its description) and the item joins the story with its picture. A heroProductName that names another product than that item (your own product in a template's hero slot) makes the story's product yours: it takes the item's place under your name and links to the clips that show it, without the library item's description or picture; give its picture in assets ({ seriesAssetId, imageUrl, isHeroProduct: true }) or draw it with the cast-art step. An id that is not an item of that series answers 400 hero_item_not_found (allowed lists the series items); heroItemId without seriesId answers 400 hero_item_needs_series. With no hero given, the series item flagged isHeroProduct is used, else the series product the prompt names, else the first product. Other series products join the story only when the prompt names them or a shot shows them. |
その他の任意フィールド
| フィールド | 型 | 説明 |
|---|---|---|
storyQualityConfig | object | { characterStyle?: "match_story" | "keep_own", characterStyleOverrides?: { [character name or series asset id]: "match_story" | "keep_own" }, directClipImageGeneration?: boolean, seriesStyleCopies?: { [series asset id]: asset id } }. characterStyle (default match_story, or the series default): a cast member whose own look is another style is redrawn in the story style, or keeps its own look. Hired characters always keep their own look. enableStyleAdaptedCharacters is deprecated (false reads as keep_own). seriesStyleCopies: one series asset = one style; a series asset drawn in another style than the story is replaced, in this story only and under its own name, by the asset given (a copy from POST /api/v1/series/:seriesId/assets/:assetId/style-copy { kind, styleId, storyId?, useAssetId? }, which makes "<Name> (<Style>)" with the identity text and no picture, or reuses the copy the series has; free). The story’s style never changes. An entry counts only while its copy is in the story style's family (a stale one is ignored). The value "make" records intent only: after writing, a copy is made (or the series' copy reused) only for the assets the written story links, and unused "make" entries are dropped. POST /api/v1/stories/generate answers with styleMismatches (each: assetId, kind, name, assetStyleId, storyStyleId, copy, answers: { makeCopy, pickAnother } as { method, path, body } requests, plus makeOnUse { storyQualityConfig: { seriesStyleCopies: { [assetId]: "make" } }, says } when the series has no copy yet) for the series assets in its assets and its draft's linked rows drawn in another style (never a hired or licensed one); the story starts as asked, and the answers apply from the next request. |
castArt | — | Retired: ignored. Writing makes only the script (scope "story"): no cast art starts with it and none is in its price. The writer makes the characters, and one story item for each physical plot prop two or more clips show (a short look from the script, linked to those clips, no picture: each clip picture says that look until the item has one). The 202 answer says castArt: "after_script"; once the cast is right, draw it with POST /assets (its own quote). Every clip video needs it (409 ASSETS_REQUIRED otherwise). scope "full" draws it in its own prepaid assets phase. |
customStyle | string | Your own touch on the base style (the create page's "Add your own touch"), up to 300 characters: colours, era, textures, details, e.g. "mecha, heavy panel lines, metallic highlights" on anime or "1980s VHS look, warm film colours" on realistic. A style is always a base preset (stylePreset) plus these optional words: send both together. The base's own words, category and negatives stay; the touch words are joined to its words (saved as styleTouch beside the story's cinematicStyle and stylePreset), so every picture and video prompt uses them: clip stills and videos say them on their Style line, character sheets, backgrounds and items draw with them; colour, grade and grain words stay; lighting and camera words are left to each scene and shot, as for a preset, even inside a colour phrase ("golden hour amber tones" keeps "amber tones"). A touch clause that only states another medium than the base ("photoreal", "live action", "oil painting style" on anime: the base's medium negatives) is left out; words about the scene stay ("toy soldiers", "oil paintings on the walls"); the answer's style { base, touch, leftOut, note } says so. Sent alone on create (as the create page does): a medium the words clearly state ("anime style, mecha" picks anime) is the base before the writer runs, unless its series already has a look, which comes first; else Auto picks it before the first picture. One style for the story and its pictures (11-03): the create page's Add image → Generate style and its Visual style step are one choice (a picture's style on an Auto story becomes the story's style; Auto's first picture settles the story's style from what is written so far; once set, another style on a picture is that picture only). Through the API make the story first and draw after it: asset pictures with no style of their own are drawn in the story's style (v1 POST /api/v1/stories/:storyId/assets/:assetId/image; MCP generate_all_asset_images, regenerate_asset_image, draw_asset_image); a library picture follows the series look; draw_asset_image generationStyle is that one picture only and never changes the story's style (update_story stylePreset does). Checked by the content gate with the prompt. Longer than 300 characters is refused 400 invalid_custom_style. MCP: create_story / estimate_story / update_story customStyle (update_story stylePreset changes the base and keeps the touch; customStyle alone changes the touch on the story's base (with none, Auto decides before the first picture: the series look, then a stated medium, then the story), with stylePreset "auto" Auto alone plus the new touch, "" takes it away; a later change also updates the story's style guide, so later pictures use it, unless the same call sends its own styleGuide, which wins; nothing is redrawn or charged). New words saved later get the same 300-character cap (400 invalid_custom_style) and the same content check (422 CONTENT_FLAGGED with findings); any style words that are not a preset's text are checked this way (of a base with a touch, all the touch words, kept or left out), at generation and on save, and again when a character, background or item picture, a look picture or a sheet starts (POST /api/v1/stories/:id/assets, /characters/:assetId/sheet, /looks/:lookId/image: 422 CONTENT_FLAGGED, nothing charged; a preset's text, spacing and punctuation aside, or an older text of a preset is never checked), so a draft's words are checked before its first pictures: MCP update_story always; PATCH /api/stories/:id globalParamsPatch or styleGuide once the story has clips (a story with no clips yet is checked when it is generated). An older story saved with its own custom words and no preset (isCustom: true) renders as before until its style is changed. |
style | object | Style-consistency overrides: cinematicStyle, era, colorPalette, lightingStyle, filmGrain, lensCharacter, materialEmphasis, styleCategory, negativeHints, stylePreset. customStyle fills cinematicStyle (the base's words with the touch joined), styleCategory and negativeHints from the base. |
seriesContinuityContext | object | Series continuity context for episodic generation. Used together with seriesId. |
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, host, news_analysis, persona_channel, or music_video.
curl -X POST https://www.yoh.app/api/v1/stories/generate \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "X-Max-Generation-Credits: 500" \
-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"
}
}'レスポンス 202 Accepted
{ "jobId": "cmnk8wu2q0001q3vpmqv93nmy", "status": "queued", "pollUrl": "/api/v1/stories/jobs/..." }/api/v1/stories/estimateWhat the same body would cost on /generate, with the same defaults, checks and quote; nothing is charged and no job is made. Answers { scope, clipCount, totalCredits, renderCredits, castArt?, quote, balance, sufficient, billedToOwner?, note? }: in someone else's series the series owner pays, so balance is null, sufficient says whether the owner can cover it and billedToOwner is true. An editor the owner has not let spend still gets the quote, with sufficient: false, canSpend: false and spendBlocked: { code: "series_credit_permission_required", message, ownerName, grant, askFor }: ask the owner to turn on "Use my credits" in Collaborators (until then /generate answers that code, 403). tryGrok with any scope but "story" is 400 TRY_GROK_STORY_ONLY, as on /generate. Scope "story" prices writing only and answers castArt: "after_script": the cast art is its own step after the write (POST /assets, quoted then). MCP: estimate_story.
/api/v1/stories/analyze-promptShould this prompt be one video or a series? Body { prompt, contentType?, locale? }. Answers { recommendation: "single" | "series", confidence, reason, suggestedEpisodeCount, suggestedSeriesTitle, episodeBreakdown: [{ episodeNumber, title, summary, cliffhangerHook }] }. Only a cinematic_story prompt of 80 characters or more is analysed; anything else answers single at once.
/api/v1/modelsThe models and visual styles the pickers offer: video, image, character, text and videoEdit models, retired ids (and what they run), realisticPeople and visualStyles; music is the soundtrack model (ElevenLabs Music v2.5: music_v2_5, or elevenlabs/music-v2.5 through AI Gateway; per-minute price, 3–600 s; no pick) and lipSync the lip-sync model (H3 Max Lip Sync: enabled, resolutions, usdPerSecond, creditsPer10Seconds, 5–30 s). Video includes Kling 4.0 (kwaivgi/kling-v4-omni-video, on fal: any whole second from 3 to 30 s, 720p or 1080p, up to 9 reference images and 5 reference videos) and Wan 3.0 (alibaba/wan-v3.0-video, AI Gateway first, then fal: 2–30 s, 480p, 720p or 1080p, up to 10 reference images, 5 reference videos and 5 voice samples in omni mode). Each video model has its durations, resolutions, aspect ratios, reference limits, credits per resolution and frameModes { omni, start, startEnd, refsWithStart, reasons } (which clip frame modes it runs, and why not). An image over its model's reference limit is not refused: extra hired photos (the story sheet stays), then items, then the place picture are left out; only when the people in the shot alone are over it does it run on Nano Banana 2, which the quote prices and the image's request record (referenceTrim) names. A run still over the limit fails with errorCategory: "capacity", retryable: false and suggestedModels that have room. Credits are quote ceilings; the quote each step returns is the price. MCP: list_models.
ステップごとのエンドポイント
After generating a story with scope: "story", use these endpoints to make the cast art, an optional storyboard (clip images), clip videos, and the final rendered MP4 as separate steps.
/api/v1/stories/:storyId/assetsGenerate the cast and world: a card for each character (its portrait cut from the card, its views the reference sheet; a hired character keeps the 3×3 sheet), plus scene and item images (on GPT Image and Nano Banana 2 drawn as cards too, the image cut from the card). Required assets must be ready before /storyboard. Skips assets that already have images. Runs as the app's Make cast art: a look the series already has is reused for free, and each asset that could not be drawn is refunded on its own. Answers 202 { jobId, runId, runUrl, pollUrl, estimatedCredits }. Scene looks are always made when clips need them, and clips whose own words dress someone get a look in those clothes in the same run (within the prepaid looks; hired characters too: an outfit that breaks the owner's limits has only that part changed to the closest compliant clothes, recorded as limitedFrom, and the usual look stays only as a last resort, listed as keptUsual with a nextStep in list_looks, where suggested looks show suggested); appearanceVariations is deprecated and ignored.
/api/v1/stories/:storyId/storyboardOptional storyboard review: draw one opening frame for each clip that has neither an image nor a video, the same engine as the app's Generate storyboard. Optional body clipImageMode picks how (also on /videos and /clips-all; the quote answers clipImageModes with both prices, and clipImageModes.grid.sheets lists every picture the grid draws, in order ({ key, kind, clipIds, credits }, kind grid or single for a lone clip drawn alone); omitted, it is always single — the app remembers the story's last choice, but the API never reads it, so send grid each time you want it): single (default, one by one, best quality) draws each clip as its own full-resolution image, in parallel; each scene run (clips in a row in the same place and time of day) draws its first clip first, then the rest of that run with the opener's image as one extra reference for light, colour and set dressing (never its people or framing; no extra charge). grid (quick, cheaper) is the storyboard grid: clips in the same place and look go up to four at a time as ONE 2×2 grid image while all their reference pictures fit the grid model (up to three grids at once; a clip needing more is drawn alone, and auto keeps GPT Image, sending one picture per person (a hired character's sheet without the extra original photo, then no place picture) before it would switch model), drawn at the model's largest size and split into one 1080p frame per clip; a lone last clip is its own image, and a group of two or three leaves its spare panels unused. A grid that comes back in another layout (a strip of frames, the wrong shape) is refunded and its clips are drawn one by one. Each panel is the clip's image prompt (stillPrompt) word for word; a missing one is written first, and a clip whose prompt cannot be written is left out before any charge. Clips a hire covers, and clips that already have an image or a video, are listed in skipped with a reason (hire_blocked, has_image, has_video). An image or video that appears while the run works is kept, never overwritten; a grid that fails (or is still unfinished after ~50 min, then cancelled) is refunded and its clips are drawn one by one only while they fit the approved credits (the quote, or X-Max-Generation-Credits when sent); the rest are left undrawn and uncharged (overApprovedBudget, reason over_approved_budget). Required character sheets, backgrounds and props must be ready first (a selected look with no picture uses the usual look, with a warning, owner 11-17): otherwise 409 ASSETS_REQUIRED (nothing charged) with assetsNeeded (each asset, whether it needs a picture or a look, and the clips waiting on it). Uses the saved image model; an optional imageModel overrides it for this run, and explicit auto keeps automatic selection. Stops after images. Answers 202 { runId, runUrl, clipsToGenerate, imagesToGenerate, skipped, estimatedCredits }; poll GET /api/runs/:runId. To redraw one clip afterwards, use POST /clips/:clipId/image. A Generate All quote's settings also has a clipImageMode row ("Opening pictures (N): quick grid" or "one by one") whenever it draws pictures first. Its runPlans[].willMake pictures are priced as that quote prices them: with the grid, each clip's share of its grid sheet (the sheet's price split over its clips, so they add up to clipImageModes.grid.credits), with grid { key, clipIds, credits } naming the sheet and its whole price.
single — one image price per clip (the clip panel's image quote; the opener reference adds nothing); grid — one image price per 2×2 grid (its model at the drawn size, dearest fallback route; a lone clip is one single-image price). A failed image is refunded | Scope: stories:generate/api/v1/stories/:storyId/videosGenerate video for each clip. Skips clips that already have a video URL. Runs as the app's own Generate All: one clip at a time in story order, each continuing the previous clip's video (parallel: true runs a few at once without that reference), each clip charged, settled and refunded on its own within the batch price. Like Generate All, clipIds narrows it to those clips, and with includeExisting: true they are re-generated even when they have a video. Answers 202 { runId, runUrl, cancelUrl, clipIds, estimatedCredits }: poll GET /api/runs/:runId until it ends (result.results lists each clip); POST /api/v1/runs/:runId/cancel stops it. /clips-all takes the same options. quoteOnly: true answers the price and plan, free, starting and writing nothing ({ storyId, quote: { credits, hash, setupBefore?, … }, plan }; setupBefore lists what the start fills in first for clips that have none: places, staging, cameras and image prompts, each with its clips and a summary, written only once the start is accepted): start it with acceptedQuoteHash set to quote.hash (or X-Max-Generation-Credits); another price or set of clips answers 409 GENERATION_PRICE_CONFIRMATION_REQUIRED with the new quote, nothing charged. On a balance short of all of them the quote also says affordableClips, affordableCredits, clipIdsAffordable and affordableQuoteHash: start just those with clipIds: clipIdsAffordable and acceptedQuoteHash: affordableQuoteHash. With fixFirst: true it first fixes what stops clips (missing character sheets, backgrounds and looks in one cast-art run; the length a clip's lines need, free; videos made before their script changed, unless listed in untick) and then generates, at ONE quote built from each step's own quote: quoteOnly: true answers the plan (fixes, needsYou, readyClipIds, quote { credits, getReady, videos, hash }); start with acceptedQuoteHash; it answers 202 { status: "queued", plan, runId, castArtRunId } (runId is left out when only pictures are fixed: follow castArtRunId, and the videos start inside that run once the pictures land). What needs you is never fixed for you and its clips are skipped; a clip whose fix fails is not started or charged. Send your own Idempotency-Key, one per consent: the same key again (a retry of the same request) joins the batch it started; a new key is a new start with its own charges, so use a new one after a failed batch. MCP: generate_all_videos with fixFirst (a resent confirmToken joins the run it started; a fresh quote is a new consent).
estimatedCredits; GET /api/v1/models lists each model's per-resolution credits) | Scope: stories:generate/api/v1/stories/:storyId/renderStitch all clip videos + music + captions into a final MP4 (on a free plan with the Yoh watermark, as the app's Export; a paid plan's never). A clip with no video and no picture answers 409 clips_missing_video with missingVideoClips (clipId, position, title, hasImage) and charges nothing; a clip with only its picture renders that picture without motion and is listed in the answer's missingVideoClips with missingVideoNote (owner 11-17: a warning, never a refusal). Optional timelineMode (clip or edit); omitted, it is edit when the story has saved freeform layers, Edit-only changes or exported clips, else clip; an explicit mode always wins. Copies of a caption, read or clip picture in the Edit layer whose source changed since they were made never change the default: the answer lists them in staleEditItems with their reason, so ask the user to update them from their source (refresh), keep them as they are (keep) or remove them (delete) with MCP edit_timeline or in the Video editor. An Edit layer with no saved media file answers 400 timeline_media_unsaved, nothing charged. An empty composition in the chosen mode answers 409 empty_timeline, nothing charged: add content or choose the other mode (it never falls back to Clip). Pass expectedRevision (from GET timeline or timeline/preview) to render exactly the cut you reviewed; a changed revision is refused before charging. The answer's emptySeconds is time with no picture (one-frame rounding slivers are not counted; MCP close_gaps closes the gaps), and emptyAtEndSeconds the part of it after the last picture, where a voice, caption or sound runs past it (close_gaps does not close that).
/api/v1/stories/:storyId/soundtrackThe story's background music, the editor's own soundtrack start. POST makes a new track at the episode's exact length: optional body mode (story, the default: scored to the story's genre, mood and synopsis with timed sections from the clips as they play (place and energy), their pacing and sound cues, never the image style; frames: scored to the episode's clip videos; prompt) and prompt (your own music brief; over 4100 characters, the music model's limit, it is cut at its last whole sentence and the answer says so in promptTrimmed; a prompt alone means mode: "prompt"). Every brief opens with the story's world (place and era), its local colour and the style preset as tone, and the storyboard brief lands its peak on the clips' story beats; a prompt is sent as written, with no story world, tone, period or instrument line added. The finished track it replaces stays in the story's audio library (and stays current if the new one fails). Answers 202 { storyId, soundtrack, status: "pending", creditsCharged, runId, pollUrl }; a track still being made answers 409 SOUNDTRACK_PENDING, a locked story 409, nothing charged. GET answers { storyId, soundtrack, status, resolved, playback?, versions } (versions: every background music version the story has had, oldest first, with inUse) (status none, pending, completed or failed; playback is the volume and fades the editor plays): poll it until completed (the runId also polls with GET /api/runs/:runId, MCP get_run: result.status completed with result.audioUrl, or failed). A failed track is refunded. PUT (free) uses an existing file instead: body audioUrl (an https file on Yoh's storage, else 400 unhosted_src) or fromStoryId (copy that story's current soundtrack; a pending, failed or expired one is refused) or versionId (an earlier version from GET versions, free; with fromStoryId, one of that story's versions), optional title and playback; the track it replaces stays in the story's audio library (previousKept), and it answers as GET does. MCP: generate_soundtrack, get_soundtrack, set_soundtrack.
1クリップずつ
The batch endpoints above only fill in what's missing — /storyboard skips clips that already have an image or a video (and clips a hire covers) and /videos skips clips that already have a video. To re-roll a shot you don't like, target it directly. These are the same operations as the editor's per-clip regenerate buttons, and they overwrite whatever that clip already has.
Stories run at the same time. The clip endpoints (image, video, video-edit, regenerate, and the batches /storyboard, /videos, /clips-all) start the app's own run at once, exactly as the clip panel or Generate All would, and follow the app's rule: there is no job queue. Inside a video batch clips run one at a time in story order, each continuing the previous clip's video (/storyboard draws clip images in parallel: one by one by default, each scene's opener first, or with clipImageMode: "grid" its 2×2 grids up to three at once); "parallel": true on /videos or /clips-all trades that continuity for speed (a few clips at once, no previous-clip video; on a single-clip endpoint it is ignored). The same request again (the same Idempotency-Key, or the same body a moment later) answers the run already started instead of charging twice; send one key per consent. Over MCP the confirmToken is that key: the same token again joins the run it started, and a fresh quote is a new start. After a 422 CONTENT_FLAGGED that carries tryGrok (the stills a batch draws first were flagged), /videos, /clips-all and /clips/:clipId/regenerate take "tryGrok": true: the same run with its stills and videos on Grok, as the app's “run it on Grok” choice under a refusal (not with fixFirst). While an API job works on the story (a scope: "full" generate, a render, a continuation) a clip endpoint answers 409 API_JOB_RUNNING (nothing charged, with activeJobId and activeJobScope): retry when that job finishes. The other way round, a story-wide job (render, generate on an existing story) answers 409 STORY_BUSY (nothing charged, Retry-After) while a clip run is working, whether you or the app started it (activeJobScope app_clip_video or app_clip_image, no job to poll; retry later), or another job runs on the story (with pollUrl). A batch of clip videos whose characters have no character sheet yet, or whose background has no picture yet, answers 409 ASSETS_REQUIRED (nothing charged) with missingCharacters, missingScenes and clipIds in the error: make the cast art first (POST /assets). One live video per clip: while a clip's video is still being made (a Generate in the app, another call, a run waiting on a slow provider), a new video or video edit on that clip answers 409 CLIP_VIDEO_IN_PROGRESS (nothing charged, with runId when known): poll that run, then retry. /videos and /clips-all never refuse the whole story for one clip: a clip still being made, or whose cast or look has no picture yet is left out and listed in skipped with its reason (in_progress with runId, references_required, speaker_missing (a line's speaker left the story), motion_framing (a wide or full shot driven by a motion reference video, which motion control refuses: make it a medium or close shot, or take the video out), hire_blocked (a hire covers it), has_video, not_found), not charged; the rest run. A clip whose lines are longer than its new video is warned, never refused (it runs at the same price; the quote lists it in linesWarned with suggestedDurationSeconds). When every named clip is left out the start answers that clip's refusal (for example CLIP_VIDEO_IN_PROGRESS). A clip whose model, frame mode or length changed after the batch was confirmed is not made on that consent, whatever its price: it stops with GENERATION_PRICE_CONFIRMATION_REQUIRED (nothing charged; quote.setupChanged with quoted and now); quote that clip again.
/api/v1/stories/:storyId/clips/:clipId/image(Re)generate the image for ONE clip (one storyboard frame, drawn alone at full resolution from its image prompt). Optional body: prompt (art direction for this shot: it replaces the clip's image prompt for this run), stillNote (a note of up to 2,000 characters ADDED to the clip's own image prompt for this fresh image, as the clip panel's redraw note; ignored when prompt is sent) and imageModel. Runs as the clip panel's own image run: answers 202 { runId, runUrl, estimatedCredits }; poll GET /api/runs/:runId until it ends, then read result.status and result.imageUrl. The same Idempotency-Key answers with the run it already started.
/api/v1/stories/:storyId/clips/:clipIdOne clip as the clip panel shows it: its text, cast, media, resolutionMade, flashbackLook, separation, lineCheck / sourceAudio and delivery (the voice check compares each line with the words heard inside its own window: flagged under 0.8 of the line heard or under 0.6 of the window being the line, in lineCheck.lineFindings; Chinese, Japanese, Korean, Thai, Lao, Khmer and Myanmar by character (Traditional and Simplified folded, Thai vowel and tone marks kept), each line in its own script when a clip mixes languages; a hidden line is never missing; a kept mismatch is asked again once a line's words, speaker or language change; a character name heard another way, e.g. 兩喜 / 梁喜, still counts and is listed in nameVariants; re-voiced reads that say other words are in readsSayOther; readsCheck is the last check_clip_reads verdict (free with source "stored" when the words of the clip's current video were already heard, else a small per-clip price, quoted first), a transcript of the video's own sound, with stale once the clip changed; copied and imported clips are checked too, free), plus frameMode — the same object MCP get_clip returns ({ requested, source, runs, fallback, … }: the mode asked for, where it came from, the mode the clip's model will run, and why it fell back). Setting the frame mode is MCP only (set_clip_frame_mode). MCP: get_clip. lookSuggestion (null when none) is a learned grade, lens look and library light for a clip with no look of its own, as the Grade chip offers it: { grade, lensLook, lightId, line, treatment, dismiss }. A suggestion only: PATCH the clip with { treatment } to use it, or close it with POST …/clip-check/apply fix { type: "dismiss", dismissal: dismiss }. MCP: get_clip.
/api/v1/stories/:storyId/clips/:clipId/video(Re)generate the video for ONE clip. Its quote includes the take's flat sound part (soundSplit { credits, parts: { splitListen, recordings } }, each part ceil(1.10 × its worst-case cost): splitListen, the voice and background split and listen done after it lands, 3 / 4 / 5 / 7 credits for 5 / 8 / 10 / 15 s, plus recordings, every line recorded in its voice and once more if needed, the same 3 / 4 / 5 / 7 (more when the lines run longer than the clip can say: priced for their real characters); 6 / 8 / 10 / 14 a take. No lines: splitListen only; motion control or audio off: recordings only; none for a music-video shot. On own keys splitListen is still charged and recordings only their re-record half), each part refunded on its own when it did not run (a take without sound or a failed split: splitListen; no line recorded: recordings; every read reused from the cache: the first recordings half; no re-record run: the re-record half). A run that delivered no take keeps the cost of the recordings it made. Optional body: videoModel, and the clip panel's pills for this run: durationSeconds (inside the model's range, rounded to a length it makes) and resolution (one the model makes; GET /api/v1/models). Both are saved on the clip, as the pills save them; the aspect ratio is the story's. POST .../regenerate takes the same two. An unknown videoModel is 400; Yoh makes 16:9, 9:16 and 1:1 only, and a model that cannot make the story's shape is refused before any charge, never switched or coerced: 400 aspect_unsupported, duration_unsupported or resolution_unsupported with allowed (what the model makes) and suggestedModels (models that make the whole shape). A story saved on an older shape (21:9, 4:3…) keeps its videos and renders, but generating on it is 400 aspect_retired (allowed.aspectRatio): set one of the three with PATCH /api/stories/:storyId first. Kept and shown as a quote adjustment, not refused: a story-level resolution above the model's top is made at its top (Grok 1080p → 720p); MiniMax H3's 720p / 1080p render as its 768p / 1440p tiers. A malformed field is 400 invalid_video_settings. A clip whose lines need more seconds than the new video would have still runs at the same price (owner 11-17): the quote carries linesWarning (clipId, speechSeconds, videoSeconds, suggestedDurationSeconds, useMoreVideo on a trimmed video), and a bulk quote lists linesWarned: offer that durationSeconds before confirming, or shorten the lines when it is null. Lines the video model speaks must fit the seconds it generates (playback speed and trim do not count); lines the voice track carries (re-voiced reads, narrator or voice-over lines) must fit what the clip plays on screen, its trim at its playback speed, and then videoSeconds is those on-screen seconds. A line counts its measured read while its words are unchanged or nearly so. The MCP speechOverflowSeconds warning uses the same rule. Each clip has a frame mode: omni (the cast, place, items and, where the model takes audio, the recordings of the lines as voice input go in as named references), start (the clip image is the first frame) or start_end (the clip image first, the next clip's image last) — the story planner's pick, or one saved with MCP set_clip_frame_mode. A model that cannot run the mode runs the next one down (start_end → start → omni; GET /api/v1/models frameModes says what each model runs). Ready movement footage or a hire-filmed clip runs omni; start_end with no next-clip image runs start. A frame clip with no clip image gets one drawn first, priced in the quote. A start / start_end take carries no voice input (Kling V3 Omni keeps its image references with a start image but takes no audio in any mode): the recordings of its lines are placed after it lands; re-voice it to change the voices. generationMode is deprecated and ignored. Optional for this run, as the clip panel's switches: startFromPrevious (true: start this take on the previous clip's last kept frame, where it was trimmed — the panel's "Continue from the previous cut"; needs the previous clip's video; a start-image take), continuity and audioRefEnabled. A clip with no cast, no pictured place or item and no clip image makes a text-only video from its prompt at the same price, as in the app (no picture is drawn unasked). Pictures the video needs that nobody made yet (a character picture, the background, an item picture) are made first, inside the same quote (makeMissingFirst, default true): the 409 price answer lists them in quote.preSteps.castArt { credits, assets: [{ kind, id, name, credits }] } next to videoCredits, and its credits is the total. Each picture charges on its own and is refunded if it fails; the video then starts with them as references, or is not started (nothing charged for it) when one did not land. "makeMissingFirst": false runs without them and the quote's advice says so (owner 11-17). The same quote lists every picture the video sends in quote.referencePictures [{ key, kind, name, stale, changed, because?, drawnFrom?, redraw: { credits } | null, picked }], out-of-date ones first (changed: what changed since it was made; a clip picture's because: the characters, places and items it was drawn from that changed since, each with its picture, look, description or details; drawnFrom: "clipImage": an asset picture a start-frame take's start frame was drawn from, which the video does not send itself; a start / start_end take starts on the clip picture, so redrawing one of these also redraws clipImage from it, priced in the total and named in autoAddedRedraws, unless "-clipImage" is in the list). "redrawFirst": [keys] redraws the picked ones before the video (each key exactly as listed: an asset key is its kind and its whole id, colons included, such as character:<storyId>:character:source:<seriesAssetId> for a character linked from the series; a string that is no key, a key past the 24th, or a key with no priced picture in the list is ignored at 0 credits and named in ignoredRedraws, the same at the quote and the run) (an asset by the asset editor's Generate, the old picture kept in History; then the clip picture, the end frame (the next clip's picture, by that clip's own image run) and the sketch), each at its own price inside the total (quote.preSteps.redraw); an asset two videos both picked is redrawn once. Without it the video uses the pictures as they are; a redraw that fails or is still being drawn stops the video with nothing charged for it (REDRAW_FIRST_MISSING, naming them in failed and stillDrawing; redrawn lists the ones already redrawn, charged). Runs as the clip panel's own Generate: answers 202 { runId, runUrl, estimatedCredits, durationSeconds, resolution, aspectRatio, videoModel, requested, adjustments? } (what the run makes, and what was asked); poll GET /api/runs/:runId until it ends, then read result.status. The same Idempotency-Key answers with the run it already started; while an API job works on the clip or story it answers 409 API_JOB_RUNNING. A clip changed after pricing so that it would now send a reference video its price left out (switched to Reference, continuity or its Mannequin turned on) is refused: a start re-prices it and answers 409 generation_budget_exceeded over the accepted credits (nothing charged), and a run already started stops before anything is made with result.status failed and code VIDEO_REFERENCE_VIDEO_QUOTE, refunded in full; quote it again.
What the quote says about its price (MCP generate_clip_video; display only, the price is the same): videoQuote.tier (with_reference_video, without_reference_video or no_reference_video_tier) with a plain tierLine when it is not the usual one; breakdown { video, allowance, sound, motionReference, picturesMadeFirst }, whose parts always sum to the credits (subsidized: a run that charges nothing, every part 0; ownKeys: your own provider keys run the video, so video and allowance are 0); referenceToggles.sent, what this take really sends beside the continuity switch (no continuity video for a clip in another place or with no finished previous video; a last frame instead; a frame take sends none); startImage { usable, reason } (none, sketch, pre_casting or frame_from_own_video: whether the clip picture is one a Start take starts on); and videoQuote.chain, only the routes that can run this clip in run order, with chainSkipped (each route left out and why). A confirm whose clip changed after the quote in what the take sends or is priced from, or whose previous clip got a video since, runs nothing and answers a fresh quote with quoteChanged { reason: "clip_changed", clipIds?, nothingCharged: true }; on-screen text, a caption move or a recorded read change nothing. GET /api/v1/models gives each video model's creditsByMode: the whole 8 s quote per frame mode and resolution (clip is the video part alone).
estimatedCredits) | Scope: stories:generate/api/v1/stories/:storyId/clips/:clipId/regenerateRebuild ONE clip end to end — a fresh clip image, then a fresh video from it — as a single run: the app's Generate All over this clip with its still drawn first, so the video never starts against the old image, and a still that does not land leaves the video unstarted (nothing charged for it). The right call after changing a clip's description or cast. Optional body: prompt (art direction for the new image), imageModel, videoModel, and the clip panel's durationSeconds / resolution pills (saved on the clip), and for this run only (never saved, as in the clip panel) continuity, audioRefEnabled and startFromPrevious (true: the new video starts on the previous clip's last kept frame, where it was trimmed, instead of the fresh still, which is still drawn; priced that way; needs the previous clip's video). Answers 202 { runId, runUrl, estimatedCredits, breakdown, durationSeconds, resolution, aspectRatio, videoModel, requested } (what the clip's video makes, and what was asked); poll GET /api/runs/:runId: result.results[0] is the clip, its image the still.
breakdown | Scope: stories:generate/api/v1/stories/:storyId/clips/:clipId/grid-referenceClip authoring supports description for scene and image context, and optional motionDescription for video movement and timed beats. Video generation uses both. When motion is empty, video generation automatically creates and saves timed motion first: one physical action that lands on a person, an object or the place, continuing from the previous clip without replaying it, and never ending reset to the opening positions or on a hold longer than 1 s. Send null to prepare new motion on the next video run. Draw a multi-panel continuity reference sheet for one clip. The panels are the clip's timed beats, one per beat in time order, always 2 or more (an untimed or one-beat motion is re-timed into panels; short beats never merge into one) unless the clip is a still (camera locked off and every beat a hold: one frame); the answer carries panels, panelSeconds and still. A clip with no motion yet has its timed motion written and saved first, free (motionFirst: true, the quote's motionFirst at 0 credits; panels is null until then). Every sketch stays on the clip; the newest is the one the video sends until another is picked (the clip panel's Sketch view "Use this one", MCP select_clip_sketch; MCP get_clip sketches lists them). The sheet is drawn on the canvas (2:3, 3:2 or square) whose panels come closest to the frame shape of the clip (a 2×2 sketch of a 9:16 story is 2:3). Starts a run and answers 202 with runId and runUrl; poll GET /api/runs/:runId until status is terminal, then read result.status: completed with the grid URL in result.imageUrl (also saved on the clip), or failed with result.error (refunded). The balance is checked before the run starts: too few credits answers 402 insufficient_credits, and a start the platform refuses answers 503 workflow_start_failed with nothing charged.
Changed 2026-10-19 (breaking): this endpoint used to answer 200 { gridImageUrl, gridData, creditsCharged } with the finished grid. It now answers 202 { runId, runUrl, status: "queued", creditsQuoted, panels, imageModel } at once. A finished clip run names the route that made it: result.route { provider, routeId, model, failover: [{ provider, routeId, category, error }], note } (a batch: on each result.results[] entry; routes when a clip picture was drawn first too), and failoverNote says in one sentence, once the run has ended, which routes did not run it and why in Yoh's words (refused, input not supported, timed out, unavailable, failed), e.g. "AI Gateway did not run it (unavailable); it ran on Replicate." (absent while the run is still going; a route's error never quotes the provider). A failed run's error names the most telling route: a refusal first, else the last route that ran. While a delivered clip's price is still settling, its result (a batch: the clip's result.results[] entry and the top level) carries priceSettling: true: the output is ready and the run reads completed, but refundedCredits can still rise; read the run again later for the final figure. Poll GET /api/runs/:runId (MCP: get_run) every 15–30 s until status is completed, failed, canceled or needs_attention; the grid is result.imageUrl. The same Idempotency-Key answers with the run it already started (deduped: true).
/api/v1/stories/:storyId/assets/:assetId/image/api/v1/stories/:storyId/characters/:assetId/sheetDraw (or redraw) ONE character, scene or item from its description, or re-derive a character's reference sheet and portrait from its current portrait. Characters are sheet-first: one generation draws the character's card, the portrait is cut from its top-left and its views without the text are the reference sheet. The card itself (cardUrl on the character, scene and item lists) is for people; generators never receive it. The picture is drawn in the story's style; a story still on Auto settles its style once, before this first picture (the same decision cast art makes: the series look, else the story's own words, else chosen from its text), and keeps it./image is the app's asset editor Generate then Save (the same price, checks and History): body { description?, imageModel?, characterImageModel?, save? }; with save (the default) the result becomes the asset's picture, and save: false keeps it as a History preview (applied: false, versionId, preview). A logo item is refused (upload it). A long /image run answers 202 { "status": "queued", "operationId", "runId", "runUrl" } and is saved when it ends. The answer is the new URLs when the run finishes within the request. A long /sheet run answers 202 { "status": "queued", "runId", "runUrl", "creditsCharged" }: poll GET /api/runs/:runId (runUrl) until status is completed or failed; on completion result.status is the HTTP status the request would have answered and result.body the same JSON (the asset, or { error } with the charge already refunded). The charge is made before the run starts and is settled or refunded by the run either way.
/api/v1/stories/:storyId/looks/:lookId/imageDraw (or redraw) the picture of one look (an outfit or variation of a character, background or item) with the app's own look recipe: drawn from the asset's picture, face and layout kept. Body { "imageModel"? } (a character look takes the character list). Answers the look when the run finishes within the request, else 202 { "status": "queued", "runId", "runUrl" } to poll. A failed run is refunded.
/api/v1/stories/:storyId/characters/:assetId/hire-looks/api/v1/stories/:storyId/characters/:assetId/hire-looksThe looks a hired character brings from its creator: { bookingId, owner, pictures, canChoose, looks: [{ id, kind: "main" | "style" | "look", label, styleId, styleLabel, imageUrl, characterSheetUrl, chosen, imported, clipAssetId }] }. The main sheet always comes, and a hire brings every listed look (all in the character's one style: a series character is one style, "Mia (3D)" is a separate character) unless it picked fewer; chosen looks are in the episode as ready looks (imported) that never apply on their own: a clip uses one when it is picked for that clip. Names only until the hire is paid (pictures: false), pictures after. POST { lookIds } sets the extra looks to bring (ids from GET; the ones left out are removed) and answers { bookingId, roleId, lookIds, imported, removed, staleClipIds, looks }: clips that used a removed extra look go back to the usual look and are marked out of date. Selection controls only extra imports; outfits already in the episode can reuse matching creator artwork for free and stay when an extra look is removed. Episode write locks apply, including 409 VIDEO_JOB_OPEN while a creator is working. Free (the looks are included in the character fee); the same as Add (free) / Remove on the hire page. A character that is not hired answers 404 not_hired; an unpaid hire or one without the face 409 LOOKS_NOT_AVAILABLE. MCP: list_hire_looks, choose_hire_looks.
/api/v1/stories/:storyId/clips-allGenerate every missing clip video, drawing first the still of each clip that has nothing else to reference (no cast, no pictured place or item), as ONE run: the app's Generate All, each such still drawn (as the clip panel's image run) just before its own clip's video. Running /storyboard and /videos separately lets the video pass start while images are still missing. It only fills gaps, so re-running after a partial failure is safe; a still that does not land leaves its clip's video unstarted (nothing charged for it). Answers 202 { runId, runUrl, cancelUrl, imagesToGenerate, videosToGenerate, breakdown }; poll GET /api/runs/:runId. While it runs, result is null and progress (0–99) with batch: { total, finished, completed, pending, failed, running, queued, currentClipIds, clips: [{ clipId, state, step, error }] } says how far it is; once it ends, result.results lists each clip.
breakdown | Scope: stories:generate/api/v1/stories/:storyId/continueWrite a NEW storyline branching off an existing clip — an alternative continuation the story keeps alongside the original, which is untouched. Required body: branchFromClipId. Optional prompt (where the story goes) and clipCount (4–24). The new clips and their images are made within the price; video is not, so animating them is a separate, separately-priced step. The price is for the clipCount clips it writes: a writer answer short of them is asked again once at no extra cost, and one still short fails with nothing written and the whole charge refunded. Runs as the editor's own continuation (a story run): answers 202 { jobId, runId, runUrl, pollUrl }; poll the job (or GET /api/runs/:runId) until it ends. A paid-value price above X-Max-Generation-Credits answers 409 with the quote and starts nothing.
/api/v1/stories/preview-scriptReview a finished script before it is written, free: what a follow_script write (or an episode draft) keeps of it. Body { screenplay, seriesId?, storyId? } (a storyId alone reviews that draft's stored screenplay). Answers { scenes: [{ heading, clips: [{ number, seconds, lines: [{ speaker, text }], cast }] }], linesKept, linesTotal, clipCount, totalSeconds, newCast, flags }; flags: voice_only_speakers, lines_too_long, lines_missing, too_long, not_a_script, no_lines, several_speakers (3 or more on-screen speakers in a clip: a note only, kept as written). A clip's cast is who is on screen as the written clips will cast it: its on-screen speakers and everyone its action shows, never one put out of frame, only talked about, or a voice-only speaker. Fixes are made in the script; the AI's wording of each shot is not previewed. MCP: preview_script.
/api/v1/generation-previewWhat will be sent, free: the exact prompt and references a paid generation would send its model, composed by the same code that sends it (no provider call, nothing saved). A model id /models does not have answers unknown_model. Body { kind, storyId, clipId?, clipIds?, assetId?, lookId?, lineId?, layerId?, model?, models?, modes?, withFallbacks?, request? }; kind is clip_image, clip_video, grid, sketch, sheet, look, place, item, panorama, edit_image, edit_video, restyle, enhance, switch, layer_image, layer_video, soundtrack, tts or revoice. Answers { model, route, fallbacks, prompt: { text, final, lengthFit, hash }, references: [{ slot, tag, kind, role, name, url, filledAtRunTime? }], skipped, params, warnings, checks, score, docsUrl, compare?, modes? }. A reference the run makes when it starts (a voice sample recorded then, the previous clip's last frame cut then) has url null and filledAtRunTime true. prompt.lengthFit names what runs first (model, and route its provider), as get_clip's promptFit names what ran; when the prompt was fitted for another route, fittedFor names that route and fittedFamily its model family. For tts (lineId) and revoice, prompt.text is the exact text the voice provider gets and params holds the voice, language and the body's other settings (never a key). A clip video whose camera is locked off (a static move) says the camera does not move (no push, pull or drift), and on Seedance 1.5 Pro its params.cameraFixed is true (the model's fixed-camera switch). prompt is null with unavailable where the builder cannot run dry. models composes the same generation for other models (each with its own tags, fit and checks against its prompting guide); modes composes a clip video's frame modes (blocked ones say what to make first). A clip video whose character sheets or backgrounds are not made yet is still composed, with an assets_required warning naming them and no error (unless they are made first, the video runs without them at the quoted price; a character with a portrait is sent by its portrait). Every generation quote also carries a compact preview (prompt, references with their kind, skipped and params): the app shows it in the confirm dialog every paid generation opens before anything is sent, so show it to your user with the price before you confirm; and a run whose prompt differs from its confirmed preview records it in deliveryMismatch. MCP: preview_generation; get_run and get_clip add sentRequest (what was actually sent, story owner only).
/api/v1/stories/:storyId/readinessWhat a paid step still needs before it can run, from the same rules that step refuses with. ?target=clip_video|storyboard|cast_art|render (default clip_video), optional clipIds (comma-separated; default: the clips the step would run), videoModel, durationSeconds, storylineId, timelineMode. Answers { target, ready, items: [{ kind, subject, reason, clipIds, fix: { action, mcpTool, args, credits, lines?, names?, count? } }] } in the order to fix them. fix.args is always one call of fix.mcpTool exactly as written (only keys it takes). fix.lines, when present, lists each line the fix covers with its own call's fields (one call per entry, in order). fix.names, when present, is who the fix's button names, never an argument. fix.count, when present, is how many pictures a make_cast_art run draws, never an argument. A missing_video item whose clip's last take failed has status: "failed", details.code: "video_failed" and the plain reason, not "no video yet". An item with severity: "warn" is a warning, never a blocker: clip_location, the clip's own Setting text names another place than the location it is linked to (details.place, details.scene); fix its sceneId or stillPrompt with the clip PATCH (MCP update_clip, free) or leave it; screen_direction, a character switches sides (left ↔ right) from the clip before in the same place with no move written (details.name, previousSide, side): fix keep_side sends fix.args.staging with the clip PATCH (free), altFix open_staging sets the sides yourself; clothes never checked for each scene are not here (the attention endpoint's look_check); generation is not changed; a refused start (assets_required, dialogue_longer_than_video, clip_audio_review, clips_missing_video) carries the same list as error.readiness. A look on a place or item with no picture can't be drawn: its fix is use_usual_look (set_clip_look { storyId, assetId, clipIds, lookId: null }, free). A clip whose voice check heard its lines as written is never held for its fitted dialogue (clip_audio_review): it plays its own sound. A clip with narrator or voice-over lines still is: those lines are only in the mix. Two warnings never block: empty_line (a line with no words; fix remove_empty_line, free: remove_dialogue_line once per fix.lines entry in order, { lineIndex } (0-based, highest first) for an older line whose id is null, then { lineId }; fix.args is the first of those calls) and sound_stale (the clip's sound was made for other lines or another take, or with details.reason read_trimmed a lip-synced or hand-placed read starts before the clip's trim and is cut, whose free prepare starts it at the trim; fix update_sound: fix_audio_sync prepare when free, else revoice_clip at its quoted credits; a suggestion only: the reads keep playing as they were until the user approves, and altFix keep_sound (keep_clip_as_is with only: "sound", free) keeps the sound as it is and clears the warning until a line changes again), speaker_label (a line that starts with its speaker's name, e.g. "陳兩喜:…": never read aloud or shown in captions; fix remove_speaker_label, free, takes it out of the text) and dialogue_speaker with details.dangling (a line whose character was deleted; fix repoint_speaker, free, gives it to the cast member its name means). Story copies never carry a deleted character's id. MCP: check_readiness.
/api/v1/stories/:storyId/attentionEverything on the episode that failed or waits on you, failures first: { count, locale, items: [{ kind, code, text, subject, reason, status, clipIds, href, fix: { action, mcpTool, args, credits, lines?, names?, count? } }] }. fix.args is always one call of fix.mcpTool exactly as written (only keys it takes). fix.lines, when present, lists each line the fix covers with its own call's fields (one call per entry, in order). fix.names, when present, is who the fix's button names, never an argument. fix.count, when present, is how many pictures a make_cast_art run draws, never an argument. text is the app's sentence in the reader's language (?locale=zh-TW, else your app language) and code its stable id (e.g. line.speechLanguage); reason stays English. Kinds: cast_art · look · look_stuck · clip_video · narration_missing · version_step · upload_lines · clip_speech · sound_stale · empty_line · hired_picture · look_check · clip_check: what a run left failed or wrong, and hired_picture, a character with no picture of its own whose role another episode cast with a hired face (details.episode, details.choices: hire for this episode, add a picture, or let Yoh draw one; ask before a cast-art run, which would still draw a new face; closable), look_check, a character hired or a picture swapped after cast art whose sheet's clothes were never checked for each scene (details.names; only here, never in readiness): worth doing, its fix make_cast_art is one cast-art run (it starts even with every picture made; fix.credits is the most it charges, unneeded looks are refunded). The readiness check's empty_line and sound_stale warnings are listed here too, with the same fix (clip_video includes a clip video refused before it started, e.g. for a look with no picture), plus one clip_check line when Check clips' free rules find something in clips without a video, or its after-take check found something in a finished clip video (details.takes) (fix check_clips). Otherwise what a step still needs before it runs (and the location warning) is the readiness check's, never both. clip_speech is the voice check of a clip video: it says words the script does not have (fix remove_extra_words, quoted: free only while the take's paid split part is unused, while its sound can still be separated, else new_take; altFix keep_speech) or misses a line (fix revoice); narration_missing: the clip's narration is not in its sound. Each fix names the existing tool; try_grok runs the same step on Grok, try_model retries a failed clip video on the model in fix.args.videoModel, and a priced fix (credits: null) quotes before it charges. Read it after any run. MCP: get_story_attention. The voice check judges the sound the user hears: a clip whose voice is replaced by re-voiced reads is not flagged (lineCheck.clearedBy: "voice_replaced"); captions can follow what is said (source-audio actions keepWithCaptions, captionFromSpeech, scriptCaptions; the script is unchanged). A delivered clip video always matches its quote; the clip GET's delivery.deliveryMismatch, when present, lists what differs (a bug signal, settled to the real cost).
/api/v1/stories/:storyId/spendCredits an episode used: { charged, refunded, used, charges, settling, steps: [{ step, charged, refunded, used }] }, steps being write · art · videos · audio · render · other. Every charge holds its maximum and settles down to the real cost, so used = charged − refunded; settling counts charges whose final can still go down. The whole story: GET /api/v1/series/:seriesId/spend, which adds episodes (most used first; each has kind: episode, version — with versionOf and locale — or archived) and storyWide (its characters and places). Credits only; owner and editors. MCP: get_story_spend.
/api/v1/stories/:storyId/clip-checkCheck clips before generating (a clip cut from the episode with hide_clip_video is left out of the checks, the story-logic pass and the counts unless named in clipIds): the free rules over each clip's information (too many actions for its seconds, the place the text names vs the linked place, clips with no place at all no_place (free fix name_places: places named the way the writer does; a place two or more clips share gets a background from the priced cast-art step; clips already made are listed too, unticked when only they lack a place, as placing them marks their takes out of date), an episode that ends where it started story_shape (fix review_story: the AI review, quoted first), a clip whose movement ends on more than 1 s of stillness dead_tail (free fix rewrite_motion: the movement is cleared and the next video writes it again), an action-series episode with a blow whose action is under a quarter of its seconds action_share (advice, no fix; it counts a whole intense or explosive clip, its spoken beats half, and only the blows, takedowns and chases of other clips), an intense clip with a blow and a spoken line in it, in a series whose lines go between the action (action, thriller, horror, music video) line_in_exchange (free fix split_clip: the blow alone, the line in the clip after; also a chase, sport, stunt, montage or hero_moment clip the writer tagged, with a line spoken on screen, in any genre: params.sceneType), “slowly” or “slow motion” in an intense clip's action calm_words_on_intense (free fix edit_text, or keep as is), three or more calm clips in a row in an action, comedy, suspense or music series (never drama or a factual series), or, in any series, a cliffhanger with nothing tense in the two clips before it episode_rhythm (params.reason calm_run or cliffhanger_flat; a suggestion with the free fix set_energy: one clip raised to tense as the user's energy, with before and beforeSource; apply skips a clip whose energy a person set (USER_SET) or whose energy or source changed since (TEXT_CHANGED); whole episode only), a clip that cuts between shots but will play as one take or has a shot problem cut_sequence (params.reason spoken_lines, too_many_shots, short_shot, too_long, length_mismatch or calm_energy | scene_type (writer shots on a scene type that never cuts: scare, suspense, reveal, product_hero, demo, drama_hit, cliffhanger, hero_moment); a suggestion, no fix), a clip longer than its lines and action need slow_clip (a suggestion, unticked and closable: before the video, free fix set_duration to the sized length; after it, free fix trim_clip, which plays only what is needed and never makes a new take), clothes vs the character's look, clothes a scene clearly doesn't suit (a fight or a swim in street clothes; a look the character already has with fitting clothes, such as a hired character's own fight gear, is the free fix), a look switching in the middle of a scene, speakers, crowds set up as one character, time of day, a peak-moment first picture, off-frame people, continuity, lines longer than the clip, an empty line empty_line and sound out of date sound_stale, said as readiness says them; a hidden line the clip's video still says, heard with no caption, hidden_line_spoken, no fix), a caption not heard in its window (caption_not_spoken, free fix caption_speech from_speech: the caption shows what is said), speech with no caption over it (speech_without_caption, free fix caption_speech add_caption) and kind method (the best way to make the clip, or a setting that does not fit), and kind framing: the staging rules (framing that will not read, such as a fight framed tighter than knees-up or a back-to-camera close-up, and bad cuts from the clip before: a jump cut (the clip before taken where its camera move ends, so a push-in from MS to MCU cuts out of the MCU; on the same two-shot it names both people, params.who people, and its fix goes over the listener's shoulder onto the speaker), eyelines that don't meet; a name in the action who is not cast is flagged, never a voice heard only off screen or a name inside a picture; params.rule names the rule, fix set_staging, free), and the writer checks on the clip as it is now (light_vs_scene, no_light_treatment, move_without_reason, same_framing_as_previous, writer_skipped_shot_contract, slow_motion_over_beats with params.count, opening_vs_subjects with params.name: low, no fix; the light is update_clip treatment.lightId, the camera set_staging). Kind fact_conflict: a text that says a fact unlike its owner field (params { fact, owner, conflictingField, said, set }; fact staging (a note, no fix: a staging id the timed beats replace), speech (motion that has a voice speak beside a speech cue with no words; only a sentence that is nothing but the voice, its verb and an optional speakers phrase has a free fix that removes it; anything else, the clip's only action, or a beat label alone on the line above it, is a note with no fix, listed in the app too), ots_facing, posture, light or move), with one free fix: the text rewritten to match (edit_text), or a typed over-the-shoulder facing turned back (set_staging). Optional clipIds (comma-separated). Answers { clipIds, issues: [{ id, clipId, clipIds, kind, severity, message, fix: { type, … }, selected, suggestion?, info?, madeVideo?, advice? }], count, uncounted, userScript }: count is the findings to act on; info notes, advice and madeVideo suggestions are listed but not counted, and uncounted { info, advice, madeVideo } says how many of each (count + uncounted = the issues listed). MCP: check_clips. Optional videoModel (query or body, a list_models id): the model the run will use when not the story's; each clip's frame mode, peak-moment first picture and voice-sample notes are judged on that clip's model (movement footage runs on motion control). Send the same videoModel to apply_clip_check_fixes (or …/apply) so the issue ids match. A clip whose video was set by hand (set_clip_video, Upload) or came with a copy of the episode already says its lines: it gets no lines_too_long and no voice-sample or Re-voice note while that video is current. A look offered for clothes a clip writes wears nothing the text does not write. A name the action only mentions ("After Ku leaves", "holds Lin's phone") is not an uncast person, and a character taken out of a clip's cast is not put back from its old picture text.
/api/v1/stories/:storyId/clip-checkThe same check with the AI review: body { clipIds?, ai: true, quoteOnly?: true, takes?: false, language?, videoModel? }. quoteOnly answers ai: { status: "quote", credits, clips, batches, storyPass, takes, breakdown: { review, takes } } (free, about 1-3 credits a clip, plus about 5-11 credits per finished clip video for the after-take check); without it the review runs held to X-Max-Generation-Credits (send the quoted credits) and answers ai: { status: "done", quotedCredits, chargedCredits } — the charge settles to the real cost of its calls. Two or more clips add a story-logic pass over the whole episode (kind story_logic; on a user's own script these are suggestions, selected: false). The after-take check (on unless takes: false) reads each checked clip that has a finished video: a frame at each line and one or two for the cast, with the cast's pictures, for who is on screen and who is talking (identity only, never clothes; narrator and voice-over lines are exempt). Its kinds take_wrong_speaker, take_speaker_unseen, take_cast_missing and take_cast_extra come with fix: regenerate_video (generate_clip_video, quoted first) and altFix: keep_take (free), and stay listed on later free checks and in the attention clip_check line while that video is the clip's, for everyone who can edit the episode. Every on-screen line gets a frame, up to 10 a clip (linesSkipped in the quote and the run counts the rest, said as a take_lines_skipped note); an answer the model could not tell is a take_unsure note (info: true, no fix, never counted). MCP: check_clips with ai: true.
/api/v1/stories/:storyId/clip-check/applyApply the fixes the user picked: { issueIds } or { fixes: [{ issueId?, fix }] }. Text, place, length, voice-only and method changes go through the editor's own edits (locks, hires and collaborators respected); a fix whose text changed since the check is skipped. A new look's picture is a priced next step (next.mcpTool generate_all_asset_images). regenerate_video comes back suggestion_only with next.mcpTool generate_clip_video, and regenerate_image (a peak-moment first picture, or an opening posed otherwise than the still) with next.mcpTool regenerate_clip_image and its note as the prompt; send an issue's altFix (keep_take) as its fix to keep the video. Answers { applied, outcomes: [{ issueId, fixType, status, reason?, next? }], recheck }. MCP: apply_clip_check_fixes.
/api/v1/stories/:storyId/voice-only-speakersA line whose speaker is a name nobody in the cast has (readiness kind dialogue_speaker, e.g. "announcer") gets a voice-only cast member with its own voice, and its lines are credited to it — what new stories get when they are written. Optional body clipIds. Answers { members: [{ id, name, created }], creditsCharged: 0 }. MCP: cast_voice_only_speakers.
/api/v1/stories/:storyId/template-adaptMake it yours on your template copy (a claim_template episode): the Adapt price and what was adapted. Answers { quote: { storyId, clipCount, credits, costModel, exact: true }, adaptedClipIds, lastIdea, lastCredits, prompt }. The price is fixed and exact: a base plus a per-clip charge (17 clips = 41 credits). A story that is not your template copy answers 409 not_a_template_copy.
/api/v1/stories/:storyId/template-adaptAdapt to my idea: body { idea, quoteOnly?: true, maxCredits?, operationKey?, sourceSeriesId?, roleMap? } (sourceSeriesId + roleMap: Remix with one of your stories, see template-remix). quoteOnly answers { quote } (free). Otherwise send the quoted credits as X-Max-Generation-Credits (or maxCredits); below the quote it answers 409 price_confirmation_required with the quote and charges nothing. One text run rewrites the clips' words (description, movement, narration and line text) for the idea and writes them straight into the clips: every shot, its order and length, each line's speaker and the storylines stay; titles are never changed. The charge is exactly the quote, with no settlement; a failed run charges nothing. Answers { status: "applied", storyId, operationKey, credits, chargedCredits, changedClipIds, clips, voiceNote? }. A retry with the same operationKey or Idempotency-Key answers the first run (replayed: true) and is charged once; a key reused with another idea answers 409 key_reused. No budget at all (no header, no maxCredits) answers 428 spend_consent_required, and a header that is not a whole number 400 bad_request; nothing is charged. Refusals: not_a_template_copy · no_clips · idea_required · idea_too_long · price_changed · key_reused · adapt_running · no_changes · dialogue_too_long · adapt_failed · insufficient_credits · operation_conflict, all before any charge; adapt_not_saved means it was charged but the words could not be saved, and the credits are refunded in full. A copy a production pays for is checked first, at the quote and before the run: its refusal keeps the production's own status and code (e.g. 409 contributions) and nothing runs or is charged. MCP: adapt_template_copy.
/api/v1/stories/:storyId/template-remixRemix with one of your stories: the stories you can remix this template copy with, { stories: [{ seriesId, title, coverUrl, episodeCount, coEditor }] }: the ones you own or co-edit as an editor, newest first, without this copy's own world or archived stories; at most 100, with no paging (?q= filters by title to find an older one). seriesId is the whole story's id (the same as /api/v1/series), never an episode id. MCP: propose_template_remix.
/api/v1/stories/:storyId/template-remixBody { sourceSeriesId }. One small text read of that story (its logline, characters and every episode's plot) proposes who plays each part of the template and an idea: { source, characters: [{ id, name, role, imageUrl }], parts: [{ roleId, name, role, kind, characterId }], idea, free: true } (characterId null keeps the original's; for an empty role, story:<characterId> casts a character already in the copy instead, filled with the rest on confirm, never before; a hired actor fills its role from the hire, never in a remix). Nothing is written or charged. Hired actors of that story are never listed. Then POST template-adapt with { idea, sourceSeriesId, roleMap: { roleId: characterId | null } }: the same fixed Adapt price and one charge; the picked characters are copied into the copy and play those parts, then the words are rewritten; the picked story is never written, and if the Adapt does not apply the cast is put back (castRestored) and the character copies the run made leave the copy's library (one in use by then stays). Refusals: not_a_template_copy · source_is_copy · role_not_found · character_not_available · character_twice · proposal_failed; a story that is not yours answers 404.
/api/v1/stories/:storyId/template-adapt/restoreBack to original: body { clipIds? } (default: every clip an Adapt changed). Each clip gets the words it had just before that Adapt: only what Adapt wrote, and only while the clip still says it (a beat changed since is kept); lines go back by line id; the title is never touched. Answers { storyId, restoredClipIds, skipped: [{ clipId, reason: "EDITED_SINCE" | "LINES_CHANGED", message }], voiceNote? }. 409 adapt_running while an Adapt runs, restore_running while another restore runs. MCP: restore_template_original.
/api/v1/stories/:storyId/rendersThe story's finished videos, newest first, with latestSuccessful called out so a failed render is never mistaken for the current cut. A story keeps every render. Optional ?limit (max 50). Each render has width, height and duration (seconds; API renders), aspectRatio, the story's locale and its fileName (API renders are named <title>_<aspect>_<language>.mp4, e.g. glow-cola_9x16_zh-TW.mp4) and timelineMode (clip or edit: the composition it rendered, recorded for API renders and the app's Export alike; null = an older cut whose mode was never recorded). API renders run in their own pool (2 at once per account, 3 across accounts) and never take the app's export slots; a render past the pool waits its turn (the job reads queued, phase waiting_for_render_slot).
/api/v1/stories/:storyId/clips/:clipId/video-editRewrite a clip's existing video — video-to-video, so subject, composition and motion carry over. Send one of: prompt (an instruction: "make it night and rainy", "push the camera in slowly"); restyleStyleId (redraw the footage in a style preset, keeping its length); or switchAsset ({ target: { kind: "character" | "scene" | "item", id }, subject: { assetId } | { description }, updateCast? }: put the story's character, place or item named by target into the footage by its picture, in place of subject — an asset of the same kind, or a description of what to replace). restyleStyleId and switchAsset cannot be combined; with either one prompt is optional. Optional resolution (480p, 720p, 1080p — the edit dialog's pill; default the clip's, then the story's, then 720p, as in the editor). The edit keeps the source clip's length (durationSeconds is accepted for old callers and does not change it). The clip must already have a video, and the result becomes a new selectable version rather than replacing the old one. A restyle includes a frame review in its price. Runs as the clip panel's own video edit: answers 202 { runId, runUrl, estimatedCredits, durationSeconds, resolution }; poll GET /api/runs/:runId until it ends, then read result.status. A switch with updateCast (default true) points the clip's cast and speakers at the target when the edit lands.
estimatedCredits is the accepted price | Scope: stories:generate/api/v1/stories/:storyId/clips/:clipId/versionGET lists the clip's versions as its Versions list shows them: video takes only, newest first (a picture-only generation is an earlier picture of the clip picture, MCP get_clip imageVersions), each with kind (generate, regenerate, edit, restyle, switch, version, delivery, upload, hire_review), imageUrl / videoUrl, durationSeconds, active, selectable and recipe (what the take was made from: model, length, resolution, characters, place, items, looks, and referenceToggles: continuity, audioRefEnabled and voiceSamples, which remake_like_take runs with again unless continuity / audioRefEnabled override them, listed in its quote's restoresRunSettings; null for takes made before recipes), plus activeTake { generationId, recipe, changedSinceTake } — each step changed since the shown take was made (MCP restore_take_setup puts a take's setup back, free; ★ remake_like_take makes another like it). POST { "generationId" } makes the clip show that version: its media, its delivered length (the old trim is cleared) and a timeline span to match — the clip panel's own switch. Refused with 409 and nothing changed: HIRE_REVIEW_NOT_LIVE, CASTING_STALE, VERSION_HAS_NO_MEDIA, VERSION_NOT_READY, approved_clip_locked or PICTURE_VERSION (a picture-only id: use names the MCP select_clip_image_version args; the clip keeps its video). Series editors and a video job's creator may switch, as in the app. MCP: select_clip_version; the clip image's own versions: select_clip_image_version.
/api/v1/stories/:storyId/swap-assetPut one story asset in place of another — a character, an item or a background — in one clip (scope: "clip", clipId) or in every clip that uses it (scope: "story"), keeping the script and other clips (refused with character_permission before any quote while a hired character in the story has no active permission); a character's spoken lines are re-voiced in the new character's voice inside the same video step, and its price includes that part (voice: lines, credits; refunded alone when the voice cannot be recorded, and the run answers voice.status: "not_recorded"). Body: { scope, clipId?, assetType: "character" | "item" | "scene", from, to, redo: "image" | "video" | "image_video", wardrobe?, light?, resolution?, steps?, dryRun? }. resolution (480p · 720p · 1080p) sets the video steps; omitted, each clip takes its own default, as the clip panel's edit dialog opens at (the clip's resolution, then the story's, then 720p). Per clip it is the clip panel's Switch asset (.../clips/:clipId/image or .../video-edit with switchAsset), and when each lands the clip's cast and dialogue speakers name the new asset. dryRun: true answers the plan and total without charging; otherwise each clip step is charged its own quoted price as it starts (X-Max-Generation-Credits caps the whole swap) and the answer lists each step's runId (each step is the app's own run: poll GET /api/runs/:runId; an image and a video step of one clip run side by side). Its status is started, partial or failed (409): steps that did not start are in retry.steps (nothing charged for them); resend with the same Idempotency-Key, or a new request with steps: retry.steps, and only those run. A clip where a switch to that asset is already running, in the app or from an earlier call, is listed in skipped (with its runId). Clip image and video-edit also take switchAsset / restyleStyleId directly for one clip. MCP: swap_asset.
/api/v1/stories/:storyId/versionsMake a new version of your story in another language, aspectRatio (16:9, 9:16 or 1:1) and/or stylePreset. Every clip keeps its media; clips are cropped or fitted to the new frame and text layers re-laid out. A language change finds where each line is spoken and translates the script by itself. A format or style version is free and made at once (201). A language version first answers a quote (200, status: "quote"): translationCredits (the copy dialog's price, charged when the version is made), laterSteps (what the paid steps after it will ask), separation (confirming it separates voice and background on each clip with dialogue, free, so the new voices play over each clip's own sound) and a confirmToken; send the same body plus confirmToken to make it, once per token. Over X-Max-Generation-Credits is 409 generation_budget_exceeded, a short wallet 402 insufficient_credits; nothing is made or charged then. Every version lives in a story; placement chooses where: "version" keeps it under its episode, unnumbered and out of the episode list and AI continuity (default for a language or format change); "episode" adds it as the next episode (default for a style change or a plain copy); "own_story" starts a new story with it as episode 1, named seriesTitle (else after the episode), its characters, backgrounds and items copied into that story's library; "other_story" adds it as the next episode of another of your stories (targetSeriesId), its cast joining that story's library (what it already has is reused) and its custom voices coming along. To move an episode, copy it there and archive the original. A target story you can't add episodes to, or an archived one, is refused (target_story_forbidden, nothing made); your custom voices come along only into a story you own. Without the right to add episodes to this story, "version" and "episode" become "own_story" and placementNote says why. A copy never fails on media that can't be copied into Yoh's storage (a deleted file, a host that does not answer): it is made without that item. Without its music the answer carries soundtrackRemoved: true and soundtrackNote; without any other item, mediaLeftOff and mediaNote. "series" and "standalone" still work (= episode, own_story). The answer names its placement, seriesId and episodeNumber (null for a version). Optional clipFormat ({ clipId: "crop" | "fit_blur" | "rerender" }). Stories with hired or licensed characters can't be copied (409, error code hired_episode or licensed_cast); one that uses another creator's character is 409 external_asset. Only the story's owner makes a version: another user's story answers 404 (MCP: 403 story_version_owner). MCP: create_story_version.
/api/v1/stories/:storyId/versionsEvery story made from this one, and from those (versions of versions, up to 3 levels), newest first: language, format and style versions and template recasts. Each has depth (1 = made from this story), parentStoryId, versionOf, kind (language, format, style, copy, template, template_claim), language, aspectRatio, stylePreset, a version status (done, running, attention, ready) and links. MCP: list_story_versions. GET /api/v1/stories/:storyId and the story list carry the same provenance object.
/api/v1/stories/:storyId/versionGET lists what is left in a version, in order — prepare (automatic, free), visual (restyle / AI re-render), voice (re-voice in the new language; it includes separating voice and background on each clip, free, and its price says so in separation), framing — each with its status and any failed clips. POST { "step": "visual" | "voice" } returns the price and a hash; POST it again with quoteHash to run it. Clips that fail are refunded one by one; POST again to retry only those. "step": "all" runs everything left with one price. A clip the step can't price or run (an unreadable length, or a re-render on a shape Yoh no longer makes) is listed in skipped with its code and is not charged. POST { "step": "prepare" } starts a failed prepare step (measure + translate) again for free (202). Refusals are 409 with busy, blocked (wait for the translation), quote_changed or nothing. A charge over X-Max-Generation-Credits is 409 generation_budget_exceeded with nothing charged; the charge counts toward the key's spend.
GET /api/v1/stories/:storyId/version/lines lists every spoken line next to its original, with the seconds it takes to say and the seconds it has; PUT it with { "edits": [{ "clipId", "index", "text" }], "keep": [...], "retake": [...] } to fix lines (retake records a line again with the same words) — a voiced clip re-voices only those lines.
# 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" \
-H "X-Max-Generation-Credits: 500"
# 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 "X-Max-Generation-Credits: 500" \
-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ストーリーを編集する
Direct the story instead of only re-rolling it: rewrite a shot, retime it, add a beat, reorder, or cut one. These are immediate (no job to poll) and cost no credits. A clip's description provides scene and image context; optional motionDescription provides video choreography. Video uses both — edit the appropriate field, then call that clip's /image or /video to re-shoot it with the new direction. Access follows the editor: anyone with edit access to the story (its owner, a series collaborator with edit rights, a job's creator) may edit it with their own key; others get 404.
Line timing in GET .../clips and GET .../clips/:clipId (and MCP get_clip / get_story): a line whose stored window is only its estimate (often 0–0.8 s on older narrator lines) reads startTime/endTime null with timingIsEstimate: true; measuredDuration is how long the line is actually spoken (its voice read, or the speech measured in the video), when known. Size trims and fits from measuredDuration, never from an estimate. Both fields are read-only and dropped on write. The editor, get_clip_timeline and the render place such a line's caption like an untimed line (by its voice read, else an even share of the clip), not in the estimate window.
characterIds in GET .../clips and GET .../clips/:clipId (and MCP get_clip / get_story, one reader for all four) is the clip's on-screen cast, read from the whole clip: its stored ids, less a voice-only narrator not put on screen and anyone its words or lines put off screen. The clip panel shows the same cast.
/api/v1/stories/:storyId/clips/:clipIdEdit a clip. Send only what you want to change: title, description, motionDescription, stillPrompt (the prompt the clip image is drawn from; null clears it; at most 4000 characters), duration, generationDuration, resolution, transitionStyle, sceneId, characterIds, itemIds, dialogue, audioFx, onScreenText (title cards, taglines and lower thirds shown over the video: [{ text, role: title|tagline|label|other, start, end, position: top|center|bottom|lower_third }]; [] clears it; a \n in text is kept as a line break (up to three lines), otherwise a title breaks after punctuation or a separator, never inside a number word such as 一九七〇年代; the same words twice at once show once, and words a caption says at that moment are left to the caption; a top entry stays at the top, moving aside off a face, never down the frame; a label such as a location super is one line unless it is too long for the width), staging (the camera and where each of the clip's characters stands: { camera: { size, angle, lens, move }, subjects: [{ characterId, side: left|center|right, depth?: front|middle|back, facing?: camera|left|right|away, endSide? }] }; camera values are writer-menu ids such as size.two_shot; saved as yours, so the writer never overwrites it; null clears it; the image and video prompts keep each side, and a camera move set here wins over any other move the motion names). flashbackLook (auto|faded|black_and_white|sepia|off): the colour grade the timeline and the render lay over a flashback, memory or dream clip, free, no new video; auto goes back to the automatic pick (the writer's mark, or the clip's words naming a flashback, a dream or a memory; colour words alone never do). The clip GET and this answer carry { flashbackLook: { look, source, automatic } }. cutSequence ({ shots: [{ seconds, size, angle, move, action? }] }, true or null): cut between 2–4 timed shots in one generation, each with its own size, angle and move (true cuts the clip's own action into default shots, null makes it one take again and puts back the length and the motion and sound it had before, keeping a motion or cue edited while the cuts were on); free, no new video. The clip becomes the sum of its shots (6–10 s, a length the model makes) and its motion is written from them. Seedance gets timed shot lines and Kling 3.0 also multi_prompt. Shots you send play at any energy; default shots only in an intense or explosive clip; any other model, a motion reference video or a sketch plays as one take framed like shot 1. Turning cuts on is refused while a line is spoken on screen (cut_sequence_spoken_lines, 409) or when the server switch CUT_SEQUENCES=0 is set (cut_sequences_off, 409). A later duration or generationDuration change rescales the shots inside 6–10 s and is refused outside it (cut_sequence_length, 400). The clip GET and this answer carry { cutSequence: { shots: [{ start, end, seconds, size, angle, move }], seconds } | null }. Its sound cues follow the shots (a whole-clip bed spans the new length, a beat's cue moves with the beat, a cue that ran to the end still ends with the clip), and a fight shot's camera always moves unless you send move.static (in a clip tagged with another scene type a writer's static shot takes that type's camera or stays still, never the fight's impact handheld).sceneType (one of the scene types, or null) sets the kind of scene as the writer tags it, kept as yours through later edits; motion typed as "Cut to:" timed windows plays as that many shots wherever a cut sequence would play (no line spoken on screen, no motion reference video or sketch, a model that cuts), else one take (on Seedance without the later windows' framing leads).
Media columns (imageUrl, videoUrl, generation history) are deliberately not writable — those belong to the pipelines. Use the clip's /image and /video endpoints to change them.
It is the editor's own save: new dialogue never changes the clip's length: when the lines outgrow it the answer carries lengthSuggestion (lineNumber, speechSeconds (the need: the read plus the 0.8 s safety margin a new video needs; neededSeconds the same), readSeconds (the read alone), clipSeconds, suggestedSeconds, fits, why), answered with { "lengthSuggestion": "apply" } (that length, free, the motion re-timed and its quotes in step) or "keep" (409 NO_SUGGESTION when none is waiting); otherwise the motion's quotes are kept in step; a changed duration is pinned and held to the story's video model (past its maximum: 400 duration_exceeds_lane with allowed: { min, max, tiers }; within range snapped up to whole seconds, with generationDuration and the timed motion beats moved with it, as the clip panel's duration pill does); the answer, and GET on a clip or the clip list, carries resolutionMade: { target, value, adjusted, reason? } (the asked resolution against what the story's model makes); a visual edit on a clip that has an image or video answers scriptEdit (that media is out of date until you regenerate). Refusals, each 409 with nothing written: CLIP_IN_HIRE (the clip is in an unfinished hire and keeps its hired character; bookingId, characterId), approved_clip_locked (an approved collaboration version), DELIVERY_EDIT_CONFLICT (a delivered take's history), CASTING_STALE (made before the casting changed), story_locked (a job or template run holds the story).
/api/v1/stories/:storyId/clipsInsert a clip. title and description required; place it with afterClipId or beforeClipId (omit both to append). Optional: the PATCH fields (including stillPrompt, treatment, sceneType and cutSequence, checked and stored the same way as the PATCH and MCP add_clip; every refusal, a cut the new clip's own spoken line refuses included, comes before the clip is made, so a retry never makes two), plus storylineId (a branch of this story). Following clips shift down automatically and looks keep starting at their clip. The new clip has no image or video yet. 409 CLIP_WORKSPACE: a clip-hire workspace holds only its hired clip.
/api/v1/stories/:storyId/clips/:clipIdRemove a clip, as the editor's delete button and MCP delete_clip: it moves to Removed clips. Nothing is lost: its media, takes, sound, lines, storyline and Edit-mode items stay saved (its Edit items, also one moved under another clip, leave the Edit timeline and render with it and come back with it), and it leaves the clip list, timeline, preview, render, readiness, estimates and copies until it is added back. The clips after it move up. → { id, deleted: true, removed: true, storyId }. A story keeps at least one clip (LAST_CLIP); a clip a storyline branches from stays (BRANCH_POINT); a clip in an unfinished hire stays (CLIP_IN_HIRE); a clip with a run still working on it (its video, picture, re-voice, lip sync or voice and background separation) stays until that run is done (CLIP_VIDEO_IN_PROGRESS, with runKind: video, image, revoice, lip_sync or separation). A removed clip is not generated or edited (409 CLIP_REMOVED) until it is added back; deleting it again answers 409 CLIP_REMOVED too, and a clip on an archived branch 409 BRANCH_ARCHIVED. Deleting a whole branch archives it with its clips (see DELETE .../storylines/:storylineId below). To take a clip off the render while it stays in the list, hide it instead.
/api/v1/stories/:storyId/removed-clipsThe story's Removed clips (the timeline header's "Removed clips"; MCP list_removed_clips), most recently removed first: { storyId, count, clips: [{ id, title, description, imageUrl, videoUrl, duration, storylineId, removedAt, previousOrder, afterClipId }] }. GET .../clips/:clipId and MCP get_clip still read a removed clip by id, marked archived: true with its removedAt.
/api/v1/stories/:storyId/clips/:clipId/restoreAdd a removed clip back (Removed clips → Add back; MCP restore_clip): it returns to its old place, right after the clip that came before it when that clip is still in the story, else at its old position, with its media, takes, sound, lines and Edit-mode items. The clips after it move down. → { id, restored: true, order, storyId }; 400 when the clip is not removed.
/api/v1/stories/:storyId/storylines/:storylineIdDelete a branch, as the editor's branch delete and MCP delete_storyline: it is archived, never deleted. It and the branches forked from its clips leave the story (branch list, timelines, preview, render, estimates, generate-all, readiness, copies, counts, GET /stories/:id); every clip in it stays exactly as it is, and its Clip-mode layers are kept with it. A clip on an archived branch is not generated or edited (409 BRANCH_ARCHIVED). → { id, archived: true, storylines, clips, layers, storyId }. The main line cannot be archived (MAIN_STORYLINE); a branch with a clip in an unfinished hire stays (CLIP_IN_HIRE), and one with a run still working on one of its clips stays until that run is done (CLIP_VIDEO_IN_PROGRESS, with clipId and runKind). No clip is added to an archived branch, and a removed clip of one is not added back (409 BRANCH_ARCHIVED); a clip route given a removed clip or one on an archived branch answers 409 CLIP_REMOVED / BRANCH_ARCHIVED, not 404.
/api/v1/stories/:storyId/archived-storylinesThe story's archived branches (the editor's "Archived branches"; MCP list_archived_storylines), newest first: { storyId, count, storylines: [{ id, label, archivedAt, clipCount, branches, branchFromClipId }] }; branches counts the branch and the sub-branches archived with it.
/api/v1/stories/:storyId/storylines/:storylineId/restoreRestore an archived branch (Archived branches → Restore; MCP restore_storyline): it comes back with its clips, the sub-branches archived with it, anchors and layers; clips removed inside it stay in Removed clips. When the clip it started from was removed since, it starts from the nearest clip before that one (movedBranchPoint). Body (optional): { branchFromClipId }, the clip it should start from when the old one is gone. Refusals: BRANCH_POINT_REMOVED (add that clip back first), BRANCH_POINT_GONE (pass branchFromClipId), BRANCH_POINT_ARCHIVED (restore that branch first), ARCHIVED_WITH_BRANCH (restore the branch it was archived with). → { id, restored: true, storylines, layers, branchFromClipId, movedBranchPoint?, storyId }.
/api/v1/stories/:storyId/clips/:clipId/duplicateThe clip panel's Copy clip: a copy with its text, still prompt, cast, items, scene, storyline, dialogue, sound cues, on-screen text and its made image/video with their versions. Nothing is generated. Body (optional): { afterClipId } puts it right after that clip, { position: "end" } after the last clip of its storyline, { position: "start" } first in the episode (placedBeforeClipId names the clip it now precedes); nothing sent = right after the clip it copies. A copy put after another clip joins that clip's storyline; a clip in an unfinished hire is refused (409 CLIP_IN_HIRE); placedAfterClipId names that clip. Later clips move right; shiftedClipIds lists every clip that moved. MCP: duplicate_clip.
/api/v1/stories/:storyId/clips/:clipId/shot-from-descriptionThe clip panel's "Write the shot from this": the description is the source. Proposes what the opening picture shows (the app's word for the clip image; stillPrompt, written first, from the description), then the timed movement (motionDescription, opening on that first frame, every spoken word kept; the app's Movement) and the camera (the app's Camera; shot; staging with only writer/default camera fields filled, stagingKept = fields the person typed, kept). Nothing is saved: PATCH the clip with what the user accepts, sending the proposal's shot as writerShot so the camera is saved with the text it was written for (its image and video are then marked out of date). The proposal may also answer stillBrain (an opaque record, signed for that clip): send it back unchanged with the stillPrompt and the save records it; edited words ignore it. The first frame's Shot line is said from the proposal's camera, as the story writer says it. Every still keeps what each character wears; only an item the clip's action puts on is left out of the first frame (not worn yet). Body (optional): { "durationSeconds"?, "videoModel"? }. No proposal: ok: false with step and reason. MCP: write_shot_from_description.
A save of new description words (adding a clip, PATCH clip, MCP add_clip / update_clip(s), the clip panel) with no stillPrompt or motionDescription in the same request runs this writer itself a few seconds later: the clip's place when it has none, the characters and items its words name (links are only added), the first frame, the movement (one 0–3s: beat per range, spoken lines inside their beat) and the camera in all four fields (size, angle, lens, move) with the image prompt's Shot line said from it and, over Yoh's own image prompt, the director's reasons (staging.directed.why, one per field present). Free. The save's answer (POST clip, PATCH clip, MCP) carries shotWriting { for, at, failed? } and shotWritingNote; GET clip shows shotWriting while it runs (failed: call this endpoint). The latest description wins; an image prompt or movement written meanwhile is kept. Each part goes by who wrote it: Yoh's own or empty text is rewritten and saved; text a person typed (a save of stillPrompt / motionDescription without writerShot) is never replaced: its new version waits on the clip as shotProposal ({ stillPrompt?, motionDescription?, staging?, shot?, replaces, saved? }), holding only the typed parts. Use it by saving exactly the fields it holds with writerShot: shot; discard it with { "shotProposal": null } in PATCH clip.
/api/v1/stories/:storyId/clips/:clipId/still-promptThe clip panel's image-prompt writer, the same proposal as MCP write_still_prompt: proposes the clip's stillPrompt from its scene, cast and place, with lint (the planned video model's budget and anything still over it). Nothing is saved: PATCH the clip with { stillPrompt, stillBrain: brain } if the user wants it (stillBrain only when brain was answered; send it back unchanged). No proposal: stillPrompt: null with a reason.
/api/v1/stories/:storyId/clips/:clipId/stagingThe clip's framing as the image and video prompts get it (the app's Staging screen): the resolved framing with a source per field (typed, copied, media, brain, directed, writer or default; brain is Yoh's pick from its own measured takes: describe it as Yoh's), notes, the staging rule warnings with one fix each (issues[].fix.framing, to send to PATCH), the suggestion and why, the library ids (framing.libraryIds) and the shot treatment, and the same for every clip of its scene (scene[]). MCP: get_staging.
/api/v1/stories/:storyId/clips/:clipId/stagingChange the clip's framing. Body: { "framing"?, "staging"?, "restore"?, "treatment"? }. framing in plain values (size, elevation, lens, move, moveId, relationship, foregroundId, povOfId, subjectId, onlyThese, light, people): only the fields sent change, each written as yours; null puts one back to "not set". staging with restore: true puts an undo entry back exactly; beforeTreatment sent back as treatment with restore: true puts the treatment back with who set each field. treatment as the clip PATCH takes it. A typo is a 400. Answers { clip, before, beforeTreatment }. MCP: set_staging.
/api/v1/stories/:storyId/clips/:clipId/staging/stage-scene"Let AI stage it" (rule-based, no model call): frames this clip, or with { "scene": true } every clip of its scene. Fields a person typed or copied, the camera read from the clip's own video, and Yoh's measured and director's picks stay; only fields the writer or Yoh's default set are restaged. Answers { credits: 0, clips, undo }; PATCH .../staging each undo entry with restore: true to undo. MCP: stage_scene.
/api/v1/stories/:storyId/clips/:clipId/audio-syncA talking clip's audio sync, the clip panel's own read and actions. Every take is handled after it lands, per take (owner 11-13), from what it records (hasSound, voicesSent, its lines), never from the model name: no sound places each line's read, not lip-synced, with a warning; sound and no lines has its speech heard by speech-to-text and taken out, only its background playing (no_lines_speech), or, nothing heard, keeps its sound as the background; sound and lines is decided by what the delivering route received (batch 3b H, owner 11-14): a take whose route got our line recordings as audio input (voicesSent, a reference take on a model that takes voice input) keeps the model's split character voice as the voice layer and the rest as the background, with nothing fitted, re-recorded or replaced (each line is checked against the split speech); any other take (no audio input, or a fallback that dropped it) uses the characters' own recordings as the voice layer: the take is split, the model's speech is discarded and only listened to for where each line starts and ends, its pauses and speed, and each recording is placed phrase by phrase at the heard times, its speed fitted (a recording much faster or slower than the video's line is recorded again at the heard speed; a line not heard goes at its planned time; while this runs separation reads in_progress with preparing: true and the video's own sound plays); narration (never sent to the model) is always our recording, placed over the clip with its background apart, lowered under the narrator (under_narrator), and read over the split voice on an audio-input take. An upload or a hire delivery keeps its own sound; a video edit and a music-video shot are never split on their own. The sound is paid by the user inside the clip video's quote (soundSplit { credits, parts: { splitListen, recordings } }, flat per take: 6 / 8 / 10 / 14 credits for 5 / 8 / 10 / 15 s), and each part alone is refunded when it did not run (splitListen when the take comes back without sound or its split fails, recordings when no line was recorded); an audio-input take uses no re-record, at the same price; there is no separate Analyze step. Nothing is asked and no note is shown; Restore original is original below. The cut is labelled voice_restored on the clip's sound state; extra_words_removed and speech_replaced only label takes cut before plan v3. A line the video clearly did not say (not said, said differently, another language) or whose recording failed after one retry, a line added after the video (it has no voice until it is re-voiced), a line whose words were edited while its read, still playing, says the old ones (words_changed; its takes stay in one list, or keep the take) and the on-screen lines of a take made without sound each get one warning in separation.lineWarnings [{ index, lineId?, lineNumber, why, heard?, revoice }], fixed with a quoted re-voice of that line; uncertain timing gets none. Every spoken line is recorded first in its speaker's voice inside the take's flat sound part (batch 3b, owner 11-14, replacing the 11-06 voice-sample rule); a reference take on a model that takes voice input sends each on-screen character's recorded lines, named in the prompt as "<name>'s recorded lines for this shot", as the mouth guide (a character with no TTS voice, or whose recording still fails after one retry, keeps its voice sample), and the same recordings are placed as the voice layer after it lands; narrator and voice-over lines are recorded too (never sent to the model); a narrator read that fails after one retry stops nothing else (its line gets the warning). GET answers separation (state: original, separated, in_progress or no_sound; neededFor; nextStep when original; in_progress also while a clip with no dialogue has its new take's sound checked and its background kept, seconds after the take lands), audioFinishing (status: queued, running, ready, needs_review or original; stage, error, errorCode, retryable, warnings, runId), revoice and, for needs_review, a candidate. POST { "action": "prepare" | "retry" | "accept" | "cancel" | "original" | "mix" | "restore" | "background", "runId"?, "volume"? } (the clip panel's and fix_audio_sync's actions): prepare separates voice and background and fits the dialogue (the user's choice, quoted: free only while the take's paid split part is unused: without the price confirmed it answers 409 GENERATION_PRICE_CONFIRMATION_REQUIRED with the quote, send it again with X-Max-Generation-Credits; refunded when it fails; on a clip whose lines were all removed it keeps the separated background alone, and answers NO_SPOKEN_LINES when there is none), retry resumes a failed sync, accept uses the fitted dialogue a needs_review sync prepared, cancel stops a running sync and plays the video's own audio, original plays the video's own audio with every mix off at once (Original sound; reversible, nothing deleted), mix turns Your mix back on (answers NO_MIX when there is none), restore goes back to the fitted dialogue and background, background sets the separated background's volume (0–1). 409 with a code when the state does not allow it (story locked, result changed, nothing to retry, re-voice running). MCP: get_audio_sync, fix_audio_sync. A clip that keeps its video's own voice (or its split speech and background, uploads included) is levelled to the re-voiced takes automatically, in the preview and the render (turned up at most +6 dB, never on silence); the clip's own volume multiplies on top.
/api/v1/stories/:storyId/clips/:clipId/source-audioA clip's own sound and its voice check, the clip panel's sound section (MCP get_source_audio / clip_source_audio, the same service). GET answers { sourceAudio, separationAvailable, separation, lineCheck } (each waveform 64 points with peakStats; ?fullPeaks=1 for the full arrays). POST { "action": "check" } runs one action: prepare, separate (Split voice from background — the user's choice, quoted: free only while the take's paid split part is unused: answered 409 GENERATION_PRICE_CONFIRMATION_REQUIRED with the quote until sent with X-Max-Generation-Credits, ask first), retry, cancel, original | extracted | separated, volume (with track, volume, fadeIn, fadeOut), captions, applyCaptions, and the voice check's: check (hear it again), keep (keep the video as it is), keepWithCaptions, captionFromSpeech and scriptCaptions. sourceVideoUrl / revision default to the clip's current ones; pass them to be refused with 409 video_changed when the video changed meanwhile.
/api/v1/stories/:storyId/voice-levelsEach character's voice level for the whole story, Cut & sound's level on a character's voice row (MCP set_voice_mix target "character", the same service). GET answers { voiceLevels: { [speakerId]: 0-1 }, speakers: [{ speakerId, name, level }] } ("narrator" for the narrator; a speaker not set plays at 1). PUT { speakerId, volume } (0-1) sets that character's level in every clip of the story: its reads, its narrator lines and its pieces of a split take's voice; 1 clears it.
/api/v1/stories/:storyId/clips/:clipId/split-audioPaid Split again / Split audio, including speech captions, kept for API callers (a new take with sound already arrives split, paid inside its video quote as soundSplit) (MCP split_clip_audio). GET quotes credits and the current split state; ?again=1 quotes Split again. POST { credits, again?, sourceVideoUrl?, revision? } starts using the accepted price. Pass the quoted take and revision to reject stale edits; preserve Idempotency-Key on retries. Poll get_source_audio or the returned run. Failed or cancelled split runs are refunded in full; successful runs settle to actual usage.
/api/v1/stories/:storyId/clips/:clipId/revoicePOST re-voices the clip's lines (paid), the clip panel's own request and MCP revoice_clip's price and start: { lines?: [{ index, lineId?, delivery?, styleInstructions?, variationId? }], quoteOnly?, separateFirst?, splitCredits?, autoLipSyncCredits?, revision? }. quoteOnly: true answers { reads, cached, credits, autoLipSync?, split?, totalCredits }, nothing charged (credits: each read priced by its line's length, ceil(1.10 × the ElevenLabs cost of its characters), about 1-2 credits a line; cached reads free); the start charges at most X-Max-Generation-Credits under Idempotency-Key and answers 202 { jobId, runId, status, creditsCharged, statusUrl }; GET ?jobId= (stories:read) is the job's state, as MCP get_revoice; without it, the job running on the clip now. A clip whose voice is not split yet answers 409 needs_separation with the split's price. Scope stories:generate. DELETE: undo one read, as the clip panel's Undo and MCP undo_revoice: ?lineId= (or ?index=) steps that line back to its earlier read of this video; omitted, the clip's latest read steps back. The read it leaves is kept (MCP select_revoice_take brings it back, free). ?all=1 is "Delete all new reads": every read of the clip's current video is deleted and its own sound plays — { clipId, removed, restored, revision, note }; making them again costs credits. A refusal is 400 with reason in error.details.
/api/v1/stories/:storyId/clips/:clipId/lip-syncLip-sync a clip's dialogue with H3 Max Lip Sync (fal), the clip panel's Lip sync and MCP lip_sync_clip: the clip's re-voiced reads, mixed where they play, are spoken by a still of the character, so the mouth moves with the new voice. Narrator and voice-over lines are left out. Optional body: resolution (480P|768P|1080P|2K; default: the clip's own resolution, else the story's, on these tiers; anything else is a 400), imageSource (clip, the default: the clip's still; or character, the first speaker's picture, or characterId's; a picture without the story's shape is 400 aspect_mismatch, uncharged), characterId, applyToClip (true: the result becomes the clip's video as a new version when it lands), quoteOnly (the price, nothing charged) and requestId. The track is the clip's length, 5–30 s, priced per second (GET /api/v1/models lipSync). A start needs X-Max-Generation-Credits (428 otherwise; 409 generation_budget_exceeded under the price). 400 no_voice_reads when the clip has no re-voiced read; 404 lip_sync_disabled where lip sync is off. Answers 202 { runId, runUrl, libraryRunId, credits, applyToClip }; poll GET /api/runs/:runId.
/api/v1/stories/:storyId/clips/:clipId/lip-sync/applyPut a finished lip sync on its clip, MCP apply_lip_sync. Body { libraryRunId } (the start answered it). The clip gets a new silent version named "Lip sync", selected now, and its re-voiced reads keep playing over it; earlier takes stay (POST …/clips/:clipId/version switches back). Answers { storyId, clipId, generationId, version, videoUrl, durationSeconds }. 409 not_ready while the run works.
/api/v1/stories/:storyId/separate-audioSeparate voice and background — priced: free only while the take's paid split part is unused or when the video already has its split (switched on at 0 credits); otherwise the take split's flat price. Without credits ≥ the quote it answers 409 GENERATION_PRICE_CONFIRMATION_REQUIRED (details.quote). For a clip without a split (an older take, an upload; a new take with sound arrives split, above) — the user's choice; ask first. Re-voicing a clip and changing the music under its voices need it: a re-voice of an unseparated clip is quoted with the split as its own line (split, the same split and price as Cut & sound's Split voice from background, reused by every feature and never charged twice, and totalCredits); confirming it runs the split and answers 202 status: "separating", a start without that confirmation answers 409 needs_separation, and a split the take's paid part covers (split credits 0) starts with separateFirst: true. Re-voicing some lines replaces only those: the other lines keep the clip's own voice from its separated speech track, where the video says them, on a generated clip as on an upload. Body { "clipId"? }: that clip, or without it every clip with video not yet separated (separated, separating and soundless clips are skipped; a clip whose earlier reads still play over its video separates too, its reads kept over the new background). Answers started, skipped and results ([{ clipId, status: "started" | "skipped", reason? }]; a clip with no lines whose voice check heard no speech is skipped with reason no_speech at once, nothing started, and reads separation.noSpeech: true); each clip's separation.state (audio-sync GET) turns separated when its run ends. "Back to original sound" is audio-sync original. GET /api/v1/stories/:storyId/clips/:clipId answers the same separation and, for your own video, sourceAudio.result: whether its lines match, which line is missing, the narrator lines read (inside a new upload's price), and its actions in order (keep, separate, revoice_missing, play_original). For every other clip video it answers lineCheck, the voice check of its own speech against its lines: status match · needs_review · needs_voice, reason missing_lines · extra_speech · wrong_speaker_unknown · wrong_language (language { heard, expected, probability }) · wrong_speaker (speakerMismatches: a line said in another character's voice) · unsure (heard too unclearly to judge; unsureLines), extraSpeech (the words), missingLines, kept; a mismatch the user kept reads status kept, with keptStatus the status it had. Captions keep the script's words (or the line's caption override, when captions follow what the video says) and follow the voice: a re-voiced read from its first spoken word to its last, else the video's measured words or the speech heard in it (at least 0.9 s on screen, script dashes not shown). A caption moved by hand on a voiced line keeps its offset from that voice, so a new take or a moved read carries it along. MCP: clip_source_audio (action separate), separate_story_audio.
/api/v1/stories/:storyId/clipsReorder. Body: { "clips": [{ "id": "...", "order": 0 }, …] } — send every clip with a contiguous 0-based order. Looks (a running injury, a change of outfit) keep starting at the clip they started at.
/api/v1/stories/:storyId/clips/:clipIdCut a clip; the remaining orders close up. A story keeps at least one clip (400 LAST_CLIP); a clip a storyline branches from stays (409 BRANCH_POINT, with its storylineId); a clip in an unfinished hire stays (409 CLIP_IN_HIRE).
# 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" \
-H "X-Max-Generation-Credits: 500"
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 "X-Max-Generation-Credits: 500"# 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 "X-Max-Generation-Credits: 500" \
-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 (optional): Review a storyboard — one frame per clip, one by one (default)
# or {"clipImageMode":"grid"} for a quick, cheaper 2×2 grid
curl -X POST https://www.yoh.app/api/v1/stories/STORY_ID/storyboard \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Max-Generation-Credits: 500" \
-d '{"clipImageMode":"single"}'
# 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" \
-H "X-Max-Generation-Credits: 500"
# 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" \
-H "X-Max-Generation-Credits: 500"
# Poll until completed → videoUrlジョブのポーリング
ジョブのステータスを取得
/api/v1/stories/jobs/:jobIdscope: stories:readPOST /api/v1/stories/generate を呼び出した後にこのエンドポイントをポーリングします。ストーリーの長さや renderVideo が有効かどうかによって、ジョブには通常 8–15 分かかります。15–30 秒 ごとのポーリングを推奨します。
ジョブステータスのライフサイクル
queuedgenerating_storygenerating_assetsgenerating_videosrendering_videocompletedまたはfailedWhich 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.
Refunds when the provider billed a failure (changed 2026-10-26). A failure is refunded, except: if the provider refuses or fails after it starts, the credits for what it billed are not refunded (never more than the quote). Every quote says so in refundRule. A failed result then carries providerBilledKept and refundNote ("The provider charged for this attempt, so N credits were kept. Refunded: M."): in a job's credits, per clip in a run's result, and on the refund row of the credit history (providerBilledKept, reason: "provider_billed_failure"). A failure the provider did not bill (refused before it started, or never sent) is refunded in full.
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 full story job that failed or expired while its final render was running waits for that render (changed 2026-11-18): while it renders, the job answers videoUrl: null with waitingFor: "render", render.progress and a message (wait, never start a new job for it); one that finishes is saved, the job answers its videoUrl beside the job's error and its render fee is kept; one that fails is refunded, and the job answers videoUrl: null with its first clip only as firstClipVideoUrl. A job making several clip videos (a clips or full scope, or a series' auto render) lists refusedClips [{ clipId, code, error }]: clips its pricing refused for their own reason (lines longer than the video, missing references, a shape the model cannot make), not charged and not made; fix the reason, then make them. Every 402 insufficient_credits carries required, available (also as balance) and topUpUrl, which opens the story's page (or Settings → Credits when there is no story) with the buy sheet ready for what is needed; after paying it comes back to the same step, ready to press again. A Generate All that runs out of credits midway stops at that clip: its result has stoppedForCredits { clipId, required, available, notStarted, topUpUrl } and the clips after it are not started (nothing charged).
Waits and failures (changed 2026-11-18). A story job still writing its script reads the message "Writing the script." and its execution.heartbeatAt keeps moving: it is alive, keep polling. A run or clip still pending answers error null; the wait is in status and phase. A job waiting on a character, background or item picture still being made on a backup route reads waitingFor "provider" with that in its message; past an hour that picture stops and is refunded. A run whose price had to be confirmed again fails with category price_changed, never insufficient_credits: nothing was charged, quote again. A v1 asset picture (POST /api/v1/stories/:storyId/assets/:assetId/image) that failed at its provider (5xx) answers generation_failed; asset_image_refused is only a refusal of the request itself. The asset editor's picture call (/api/ai/generate) that failed at its provider answers code "GENERATION_FAILED" with refundedCredits (what was given back) and a message in Yoh's words.
レスポンスフィールド
| フィールド | 型 | 説明 |
|---|---|---|
jobId | string | 一意のジョブ識別子。 |
status | string | 現在のステータス。上記のライフサイクルを参照。 |
progress | number | 完了率を示す 0–100 の整数。 |
storyId | string|null | ストーリー生成完了後に設定。アセットの取得に使用。 |
renderVideo | boolean | 合成最終 MP4 が要求されたかどうか。 |
videoUrl | string|null | 完了時の完成動画の絶対 URL:レンダー、または renderVideo: true の合成 MP4。それ以外は null — 何もレンダーしていないストーリージョブは最初のクリップの動画を firstClipVideoUrl で返します。 |
error | string|null | 人間が読めるエラーメッセージ。失敗時に設定されるほか、リトライ中(ステータスが queued に戻る)にも設定されます。成功時は常に null。 |
waitingFor / message | string (optional) | ジョブが待機中で、問題がないときに返されます(error は null)。message に待っている内容が入ります。ポーリングを続けてください。"provider":プロバイダーの結果をまだ待っています。"render":最終動画のレンダリングに通常より時間がかかっています。status は rendering_video のままで、render に進捗が表示され、動画が保存されるとジョブは自動的に完了します(新たな料金は発生しません)。 |
execution | object (optional) | このジョブを実行している Workflow ラン:{ version, runId, phase, heartbeatAt, status }。GET /api/runs/:runId(またはその /stream)で追えます。古いジョブにはありません。 |
createdAt / startedAt / completedAt | string (ISO) | タイムスタンプ。 |
runId / runUrl | string (202 only) | 各ジョブ開始時の 202 応答に含まれます(このポーリングには含まれません):ジョブのために開始したランとそのステータス URL。使わなくても構いません。このエンドポイントのポーリングで十分です。 |
ストーリー
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.
ストーリーの一覧
/api/v1/storiesscope: stories:readストーリーのページネーションリストを返します。
クエリパラメータ
| パラメータ | デフォルト | 説明 |
|---|---|---|
page | 1 | ページ番号(≥ 1)。 |
limit | 20 | 1 ページあたりの結果数(1–100)。 Capped at 100. |
status | — | ストーリーステータスでフィルタリング。 |
This is the only endpoint that returns a pagination envelope alongside data:
{
"data": [ { "id": "cmnk9cibl0004q3vpijkqfwl4", "title": "...", "status": "completed" } ],
"pagination": { "page": 1, "limit": 20, "total": 137 }
}ストーリーを取得
/api/v1/stories/:storyIdscope: stories:readキャラクター、シーン、アイテム、クリップの数を含む単一ストーリーの完全なメタデータを返します。
{
"id": "cmnk9cibl0004q3vpijkqfwl4",
"title": "A robot chef cooks in a futuristic kitchen",
"status": "completed", "aspectRatio": "9:16", "locale": "en",
"counts": { "characters": 3, "scenes": 4, "items": 6, "clips": 6 },
"createdAt": "2026-04-04T11:37:04.662Z"
}/api/v1/stories/:storyIdEdit the story's settings, the same service as the editor's settings and MCP update_story (body: its fields, e.g. { title?, description?, locale?, styleGuide?, colorTone?, stylePreset?, customStyle?, resolution?, videoModel?, imageModel?, characterImageModel?, videoEditModel?, textFamily?, characterStyle?, characterStyleOverrides?, thumbnailUrl?, autoLipSync? }). Future generations only; nothing is redrawn or charged. Answers { storyId, updated }; refusals keep the tool's codes (for example color_tone_only_names, CONTENT_FLAGGED).
/api/v1/stories/:storyId/captionsThe story's captions, as the editor's caption panel and MCP update_caption_settings: { captionsOn?, style?: "standard" | "words", verticalPosition? (0–100), boxWidthFraction? (0–1), boxHeightFraction? (0–1), fontSizeScale? (0.5–3) }. Preview, export and render follow it. GET /api/v1/stories/:storyId answers textLookSuggestion (null when none): the caption / on-screen text look stories like this use, as the caption panel suggests it ({ value: no_text | captions | title_cards | null, subtitleBand, held, total, apply, dismiss }), only while it would change the captions. Send its apply here to use it; close it with POST …/clip-check/apply fix { type: "dismiss", dismissal: dismiss }. MCP: get_story.
/api/v1/stories/:storyId/publishPOST publishes the episode, as the app's Publish sheet and MCP publish_story: { videoUrl?, visibility?, tier?, price?, seriesId?, template?, templateOwnershipConfirmed? } (see publish_story for each field). Ask the user first: it makes the video public. Safe to retry. DELETE takes it off Yoh (back to draft), as Unpublish and unpublish_story; the video and the story stay. Refusals keep the app's codes (PUBLICATION_BLOCKED, MEDIA_CHANGED, VIDEO_REQUIRED, TEMPLATE_OWNERSHIP_REQUIRED…).
アセット概要
ジョブが完了したら、ジョブが返した storyId を使用してストーリー用に生成されたすべてのアセットを取得できます。すべてのアセットエンドポイントには assets:read スコープが必要です。
GET /api/v1/stories/:id/charactersキャラクター — 名前、説明、役割、imageUrl、音声情報
GET /api/v1/stories/:id/scenesシーン — 説明、時間帯、天気、照明、imageUrl
GET /api/v1/stories/:id/items小道具 / アイテム — 説明、重要性、imageUrl
GET /api/v1/stories/:id/clipsクリップ — ナレーション、時間、videoUrl、imageUrl、audioUrl
キャラクター
キャラクターの一覧
/api/v1/stories/:storyId/charactersscope: assets:read{
"data": [{
"id": "char_abc123", "name": "Chef Axon", "role": "protagonist",
"description": "A robot chef with a warm personality",
"imageUrl": "https://cdn.example.com/characters/chef-axon.jpg",
"voiceName": "Neutral-EN", "order": 0
}]
}クリップと動画
クリップの一覧
/api/v1/stories/:storyId/clipsscope: assets:read各クリップは、AI 生成の動画、静止画像、音声を持つシーンセグメントです。すべての URL フィールドは絶対パスで公開アクセス可能です。
{
"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"
}]
}renderVideo が false の場合、ジョブに完成動画はありません:videoUrl は null で、最初のクリップの動画は firstClipVideoUrl にあります。このエンドポイントを使用して各クリップの動画 URL を取得してください。
シリーズアセットライブラリ
一度アップロードすれば、ずっと再利用できます
/api/v1/series/:seriesId/assetsscope: assets:writeスタジオのアセットパネルが書き込むのと同じライブラリです。キャラクター・背景・小道具・スタイル参照をアップロードし、返却された id を保存しておけば、生成時に assets 配列の seriesAssetId としてその id を渡すだけで参照できます。動画ごとに画像リンクを作り直す必要はありません。渡された画像は当社ストレージに再ホストされるため、元のアップロード URL が失効しても id は使い続けられます。
| フィールド | 型 | 説明 |
|---|---|---|
type | string | character、scene、item、reference のいずれか。 |
name | string | 表示名。以降の生成で照合に使われるキーでもあります。 |
imageUrl | string | 画像の公開 URL。代わりに imageBase64 も指定できます。 |
itemType | string | 小道具のみ:prop、product、logo。logo は平面として合成され、立体的な奥行きは付きません。 |
isHeroProduct | boolean | 小道具のみ:この広告の主役となる商品。全クリップに登場します。 |
isPrimaryBackground | boolean | シーンのみ:すべてのアンカーショットで使い回すスタジオ/セット。 |
seriesDuplicate | string | キャラクターのみ。ユーザーに確認したうえで "new" を送ると、シリーズにある名前で 2 人目のキャラクターを追加します。 |
Asset cards: a generated asset or look drawn as an information card also answers cardUrl with sheetLayout: "card-1" (GET /series/:seriesId/assets and the story asset reads). The card is for people only; the asset's imageUrl is the picture cut from its top-left and is what to pass wherever a picture is taken. A card url (of any story) sent as a picture or a reference is refused with 400 card_reference_refused (urls lists it), nothing saved or charged: send the asset's imageUrl instead.
- アセットを 1 件送るか、"assets" 配列で最大 100 件をまとめて登録できます。
- 既定では名前が完全一致するアセットは統合されるため、同じカタログを再アップロードしても重複しません。ただし、シリーズにすでに同じ名前のキャラクターがいる場合は 409 SERIES_NAME_EXISTS(既存のキャラクター付き)を返し、何も保存しません。ユーザーに確認してから、2 人目を追加するなら seriesDuplicate "new" を、既存を更新するなら ?mergeStrategy=exact を送ってください。?mergeStrategy=fuzzy は名前の変更に寛容、insert は常に新しいアセットを作ります。
- DELETE は、まだアセットを使っているエピソード(stories: id, title, clipCount)を付けて 409 SERIES_ASSET_IN_USE を返し、何も削除しません。ユーザーに確認してから confirm: true(body または ?confirm=true)を送ってください。エピソードは自分のコピーを持ち続け、クリップも変わりません。進行中の依頼に含まれるキャラクターは 409 SERIES_ASSET_HIRED(hires)を返し、依頼が終わるまで削除できません。
- 小道具に isHeroProduct(ad_spot)、シーンに isPrimaryBackground(news_analysis / persona_channel)を設定すると固定できます。生成時に自動で解決されるため、heroItemId を手書きする必要はありません。
| メソッド | エンドポイント |
|---|---|
GET | /api/v1/series |
POST | /api/v1/series |
GET | /api/v1/series/:seriesId |
PATCH | /api/v1/series/:seriesId |
GET | /api/v1/series/:seriesId/assets?type=character |
POST | /api/v1/series/:seriesId/assets |
PATCH | /api/v1/series/:seriesId/assets/:assetId |
DELETE | /api/v1/series/:seriesId/assets/:assetId |
DELETE | /api/v1/series/:seriesId/assets/:assetId/looks/:lookId |
POST | /api/v1/series/:seriesId/assets/:assetId/looks/:lookId |
POST | /api/v1/series/:seriesId/assets/:assetId/style-copy |
POST | /api/v1/uploads |
PATCH | /api/v1/stories/:storyId/characters/:assetId |
PATCH | /api/v1/stories/:storyId/scenes/:assetId |
PATCH | /api/v1/stories/:storyId/items/:assetId |
POST | /api/v1/stories/estimate |
GET | /api/v1/credits |
GET | /api/v1/models |
POST | /api/v1/stories/:storyId/swap-asset |
POST | /api/v1/series/:seriesId/uploads |
POST | /api/v1/stories/:storyId/upload |
GET | /api/v1/stories/:storyId/upload |
POST | /api/v1/uploads/presign |
GET | /api/v1/stories/:storyId/media |
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 "X-Max-Generation-Credits: 500" \
-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.
シリーズアセット
シリーズのキャラクター画像を登録
/api/v1/series-assets/ensure-character-imagescope: assets:writePOST /api/v1/series-assets/ensure-character-image は引き続き利用でき動作も変わりませんが、キャラクターのみ対応です。こちらのエンドポイントを推奨します。
シリーズのキャラクター参照画像をアップロードして保存し、AI がそのシリーズのすべてのストーリーで一貫した外見を使用できるようにします。この操作は idempotent です — 同じキャラクター名で複数回呼び出しても安全です。
| フィールド | 型 | 説明 |
|---|---|---|
seriesId | string | キャラクターを関連付けるシリーズの ID。 |
characterName | string | キャラクターの名前(シリーズ内の一意キーとして使用)。 |
imageUrl | string | キャラクター参照画像の公開アクセス可能な URL。 |
マネージドアカウント
多数の顧客を抱えるプラットフォーム向けです。全員でひとつのキーとひとつのクレジットプールを共有すると、使用量の多い顧客が残高を使い切り、誰がいくら使ったかも分かりません。代わりに顧客ごとにアカウントを発行し、あなた自身の残高から資金を移してください。顧客がここで登録したり当社に支払ったりすることはなく、商取引の関係はあなたのものに留まります。
アカウントを発行する
/api/v1/accountsscope: accounts:manageexternalId は顧客に対するあなた自身の ID です。同じ ID で二度呼び出しても、新しく作らず既存のアカウントを返すので、リトライは安全です。API キーが返るのは初回作成時の一度だけです。当社はハッシュのみを保存し再表示できないため、受け取った時点で保管してください。新しいアカウントの残高はゼロから始まります。
| フィールド | 型 | 説明 |
|---|---|---|
externalId | string | 必須。この顧客に対するあなたの ID(テナント ID など)。プラットフォーム内で一意である必要があります。 |
name | string | 任意のラベル。あなた自身のレポート用です。 |
管理対象アカウントのキーを交換する
/api/v1/accounts/:accountId/api-keysscope: accounts:manage最初のキーを紛失した場合は、所有元プラットフォームのキーを使用し、リクエスト本文なしでこのエンドポイントを呼び出してください。アカウント ID または externalId を指定できます。以前のキーをすべて無効化し、新しい apiKey を一度だけ返します(201)。この処理は単一のトランザクションで行われます。キーは安全に保管してください。再度呼び出すと再びキーが交換されます。通常のアカウント作成の再試行では、既存のキーは交換されません。
アカウントへ入金する
/api/v1/accounts/:accountId/creditsscope: accounts:manageクレジットを「あなたの」残高からそのアカウントへ移します。付与ではなく振替なので、実際に購入した分しか配れません。自分の残高で賄えない場合は 402 を返します。:accountId には当社のアカウント ID か、あなたの externalId のどちらでも指定できます。
| フィールド | 型 | 説明 |
|---|---|---|
amount | integer | 必須。移動するクレジット数。正の値である必要があります。 |
idempotencyKey | string | 請求書 ID や購読期間 ID を渡してください。リトライや再配信された呼び出しは、二重に入金する代わりに元の振替を返します。 同じキー、送金先、金額で再試行してください。プラットフォーム残高がなくなっていても、再試行で二重送金されることはありません。送金先や金額を変更すると 409 が返ります。長すぎるキーは切り詰めずに拒否されます。 |
description | string | 任意のメモ。クレジット履歴の振替の両側に表示されます。 |
GET /api/v1/accounts は各アカウントの残高と累計利用額を一覧します。GET /api/v1/accounts/:accountId/credits は単一のアカウントを読み取ります。マネージドアカウント自身のキーは生成系のスコープのみを持ち、アカウントの発行や入金は決してできません。
Claude Code と Codex(MCP)
Yoh は MCP サーバーを提供しており、AI エージェント(Claude Code、Codex、Claude Desktop、その他の MCP クライアント)があなたのアカウントでストーリーを作成・編集できます。アイデアから新しいストーリーを書き、キャストを決めて動画を生成したり、クリップの内容とセリフ、タイムラインの移動やトリム、フリーフォームのオーバーレイを変更したりできます。クレジットを使う操作は、毎回あなたの明示的な承認を待ちます。ブラウザ版エディターと同じルールで動作するため、ターミナルからの編集はドラッグした場合とまったく同じ位置に着地します。
Claude · Codex · MCP · REST API · Skill · /install
3つの使い方
エージェントが使えるツールに合わせて選んでください。下の yoh スキルは3つすべてに対応しています。
- MCP + ブラウザ(Codex、Claude Code、Claude アプリでおすすめ) エージェントはこの MCP ツールで作業しながら、ブラウザのタブも自分で操作します(Claude in Chrome、Codex のブラウザ)。各ステップのあと、返ってきたリンク(新しいストーリーなら台本テーブル、クリップ動画ならクリップパネル、実行中は Generate All の一覧、タイムラインやテキストレイヤーは動画エディター、レンダリング後は MP4)を開き、実際のページで結果を確かめます。そのブラウザで、API キーと同じアカウントに一度ログインしてください。MCP とページは同じデータを使います。エピソードページは MCP での変更から数秒で自動更新され、タイムラインを変えたあとはエージェントが動画エディターを再読み込みします。支払いは1つの経路だけ:MCP の見積もりか、アプリの料金ダイアログのどちらかです。
- ブラウザだけ(API キーなし) ブラウザーで Yoh のページを操作します。生成料金はアプリの確認画面で確認してください。アシスタントとのテキストのやり取りは即時課金される場合があるため、使用前に料金への同意を得てください。支払い情報やログインコードは入力しないでください。
- MCP だけ(ブラウザなし) スクリプト、CI、制作会社向け:★ のツールは見積もり → confirmToken の順で実行します。get_job / get_run で進捗を確認し、cancel_generation で停止し、完成した動画をダウンロードします。ask_assistant はテキストのやり取りに即時課金します。定期生成と外部決済には別の同意ルールがあります。MCP 呼び出しにブラウザーは不要です。
どの使い方でも例は同じ:英語と日本語の16秒・9:16の広告を、商品と一緒にストーリーの中で書き、動画を作り、日本語版を作って2本レンダリングします。
接続
おすすめ:Yohでサインイン(APIキー不要)。このアドレスをそのまま使ってください(wwwなしのyoh.appはリダイレクトされ、サインインはアドレスを照合します)。Claude Codeでは:
claude mcp add --transport http --scope user yoh https://www.yoh.app/api/mcp次に /mcp と入力し、yoh を選んで Authenticate を選択。開いたブラウザで使いたいアカウントでYohにサインインし、承認します。
Codex(CLI、IDE拡張、ChatGPTデスクトップアプリ)では、サーバーを追加してサインインし、~/.codex/config.toml の [mcp_servers.yoh] に tool_timeout_sec = 300 を設定してCodexを再起動します:
codex mcp add yoh --url https://www.yoh.app/api/mcp
codex mcp login yoh- Claudeデスクトップアプリまたはclaude.ai:Customize → Connectors → + Add → Add custom connector で名前をYohにしてアドレスを貼り付け、Connect してサインイン。各チャットで + → Connectors からオンにします。TeamやEnterpriseプランでは、先にオーナーが追加します。
- Cursor:このアドレスでyohを ~/.cursor/mcp.json に追加し、Cursorに求められたらサインインします。
- ChatGPT:Plugins → + → Add custom MCP server で名前をYohにしてアドレスを貼り付け、サインインします。プランによっては管理者がカスタムサーバーを許可する必要があります。
確認:エージェントに get_credits を実行してもらい、Yohの残高が表示されればOKです。接続中のアプリは 設定 → APIキー → 接続済みアプリ で確認・解除できます。
エージェントが変更したページを見られるように:Claude Codeは claude --chrome(Claude in Chrome拡張)、Claudeデスクトップアプリは Claude in Chrome コネクタ、CodexはChatGPTデスクトップアプリのブラウザを使います。いつ確認するかはスキルがエージェントに伝えます。
またはAPIキーを使う(スクリプト、CI、サインインできないアプリ)
/settings/api-keys で API キーを作成します。新しいストーリーを作って動画を生成するなら stories:generate を含めてください。クレジットを使わず編集するだけなら stories:read と stories:write で十分です。次に Claude Code で:
claude mcp add --transport http yoh https://www.yoh.app/api/mcp \
--header "Authorization: Bearer sk_live_YOUR_API_KEY"あるいはプロジェクト設定をコミットすれば、チーム全員がリポジトリを開いた時点で接続を得られます。キーは各自が環境変数で渡します:
{
"mcpServers": {
"yoh": {
"type": "http",
"url": "https://www.yoh.app/api/mcp",
"headers": { "Authorization": "Bearer ${YOH_API_KEY}" },
"timeout": 900000
}
}
}Codex では、サーバーを ~/.codex/config.toml に追加し、シェルで YOH_API_KEY を設定します:
# 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 = 300Yoh スキルをインストール
このスキルは、Yoh のストーリーをうまく作り、編集する方法をエージェントに教えます。まずシリーズに入れる、使う前に見積もる、判断する前にクリップを見る。小さなフォルダー(SKILL.md と参照ファイル)で、サーバーと一緒に常に最新です。使っているエージェントの行を実行するか、 スキルをダウンロード(.tar.gz)
# Claude Code
mkdir -p ~/.claude/skills/yoh && curl -fsSL https://www.yoh.app/skills/yoh.tar.gz | tar -xz -C ~/.claude/skills/yoh
# Codex
mkdir -p ~/.agents/skills/yoh && curl -fsSL https://www.yoh.app/skills/yoh.tar.gz | tar -xz -C ~/.agents/skills/yohあとは頼むだけです:「幽霊の声が聞こえる夜勤看護師の 60 秒のストーリーを作って」、または「第3話のテンポを締めて——間延びを削り、字幕を拍に合わせて、再レンダリングして」。Claude Code または Codex で /mcp を実行すると接続を確認できます。
These task guides explain which tool calls to make. They do not turn ordinary reads or edits into background jobs. Start with your task below. The connected MCP tool list provides each tool's exact arguments; use returned IDs and links. A missing scope requires a key with that permission. After a write, read the result back; a started job is not a completed video.
Turn a script or PDF into a series
Use plan_series with text, an uploaded pdfUrl, or an idea. Poll get_series_plan, review episode boundaries and cast, then create_series_from_plan. It saves draft episodes without generation. Read each draft with get_story before quoting its generation steps. bulk_create_episodes is for writing new episodes, not filling those drafts.
Write an episode from a finished script
Call preview_script first (free) and show the user linesKept of linesTotal, clipCount, totalSeconds and its flags; fixes are made in the script. Then quote create_story with storyInputMode follow_script and the script's locale (or storyDraftId for a saved draft: its stored screenplay is written word for word, the prompt is only direction beside it and never overwrites it); the quote prices the script's own clips and length. follow_script on text that is not a script (a synopsis or outline: no spoken lines, scene headings or shots) is refused free with not_a_script: send it as develop. Hires stay on the story they were made for: a quote with hiredDrafts means the series has an unwritten draft with hired characters, so write that draft (storyDraftId) instead of a new story. A followed script starts no cast art: quote generate_all_asset_images next. Its clips read as story text: each description is the shot's action lines (the heading, cues, spoken lines and ON-SCREEN TEXT lines live in the script, the dialogue and onScreenText), places are named without their time or shot note ("Las Vegas Strip", not "Las Vegas Strip - Night (Establishing)"), a cast description leaves outfits that change by scene to looks, and a script that asks for no trademarks keeps every place generic and unbranded. Each clip is sized to its action by Check clips' own budget: too much action for its seconds makes it longer, then splits it into consecutive clips, every word kept; a role cued by its job (ANNOUNCER) keeps its lines as its own voice-only member with a voice no one else in the cast uses.
Is a clip ready, blocked or busy?
get_clip (and GET /api/v1/stories/:id/clips/:clipId) answers videoStatus: null when no hire, permission or live run stops the clip's video; else state busy, elsewhere or blocked with a reason: running (a take is being made; follow runId with get_run; a second start answers CLIP_VIDEO_IN_PROGRESS), creator_makes or owner_films (a hired creator or the character's owner makes it; bookingId is the hire), not_allowed (code says why, e.g. funding or character_face_licence). Then check_readiness (a step first) and the generate_clip_video quote (insufficient_credits, a shape refusal, omni_refs_over_capacity) decide the rest. A clip is ready only when all three agree, the same rule as the clip panel's status headline.
Fix what blocks generation, then generate
check_readiness (free; target clip_video, storyboard, cast_art or render) lists each missing thing with its fix tool, arguments and price; fix them in order and check again. Or quote generate_all_videos with fixFirst: true for one price that fixes and generates; plan.needsYou lists what only the user can fix, and untick leaves a fix out. A clip waiting on a character's missing picture is priced as drawn after the pictures fix (its frame image too, on the model and route the run takes once the picture exists); a quote refused for a clip's references answers clip_references_required (details.missingCharacters), never internal_error. After any run, read get_story_attention (free) and tell the user each failure and its fix; a try_grok fix re-runs the step on Grok after a content flag, and a try_model fix retries a failed clip video on the named model (args.videoModel), with the user's OK; only a model that runs the clip as configured (its frame mode, its reference videos and audios) is named. On a balance short of the whole Generate All, its quote says affordableClips, affordableCredits and clipIdsAffordable: start just those clips with clipIds set to clipIdsAffordable (a start for all answers 402 with the same fields). They never end on a start + end clip whose last frame is the next clip's image still to be drawn: that clip waits for the rest, so it keeps its end frame. Over MCP a refusal's extra fields (readiness, tryGrok, suggestedDurationSeconds) sit on the error itself. A tryGrok offer is taken by quoting the same tool again with tryGrok: true (create_story, generate_all_asset_images, generate_storyboard, generate_all_clips, generate_all_videos, regenerate_clip, generate_clip_video) and confirming that new quote. The fixFirst confirm answers runId and castArtRunId; with only picture fixes there is no runId, so poll castArtRunId. Generate All leaves out a clip for its own reason (skipped: in_progress, references_required, speaker_missing, motion_framing, hire_blocked, has_video, not_found) and runs the rest.
Retries, replays and refusals over MCP
The confirmToken is the idempotency key: sending the same token again joins the run it started and is never charged twice; a new quote is a new start, so quote again after a failed batch. While the first confirm is still starting, a resend answers confirmation_in_progress with retryAfterSeconds: send the same token again. confirmation_needs_review means that confirm started work and then failed: read get_job or get_run, then quote again. confirmation_inputs_changed and confirmation_stale need a fresh quote. A refusal that started nothing (a busy story, a rate limit, credits) frees the token for a retry. v1 refusals reach MCP with their own codes: GENERATION_PRICE_CONFIRMATION_REQUIRED (quote again), WORKFLOW_START_FAILED (nothing charged; retry), INSUFFICIENT_CREDITS (required and available), GENERATION_IN_PROGRESS (poll its runId). A clip with a Motion reference video takes the footage's length (footage_sets_length): pick a longer range with set_clip_motion_reference instead of set_clip_duration. set_clip_duration re-plans the clip's timed beats for the new length (free); when the clip then holds more action than the length fits, its answer carries actionOverflow: split it with check_clips' action_budget split_clip fix (free) or cut action, nothing is split on its own. A clip that cuts between shots never gets actionOverflow (each action has its own shot; check_clips' cut_sequence checks the shots). write_time_beats and write_still_prompt answer with lint: the planned video model's per-field character budgets and anything still over_budget after the free tidy; split_for_lines (fix split_clip) means the spoken lines are more than that model voices in one clip, so split it; lines are never shortened. The beats open on the previous clip's ending and end on the description's last stated action; write_time_beats' lint.ending (code end_action_missing, with the action: the last clause of the description's last sentence; English stories only) says the final beat still misses it after one re-ask. Each quote's speaker is named once (Sir Whiskerton says: "…" or Sir Whiskerton: "…"); a doubled "…and says, Sir Whiskerton: "…"" is folded. The still writers (write_still_prompt, write_shot_from_description) write the still's Shot, Subjects and Setting lines (a Light line is optional, since light comes from the place; the writers add none), pose everyone in frame and use only the place's furniture; lint.checks (write_still_prompt) or lint.still.checks (write_shot_from_description) lists subject_without_pose and furniture_not_in_place (lint only: the writer is not asked again), and write_shot_from_description fits both lints to the videoModel it is given. write_still_prompt may add brain (cardIds and takeIds): an opaque record to send back unchanged as stillBrain. Show nothing of it on screen. Timed beats never state the shot size, orientation, lens or camera height (that is the clip's framing, set_clip_framing); a camera move is named in the beat where it happens. update_clip refuses a stillPrompt with nothing to draw (only a Shot line, "same as before", a lone name) with invalid_field, rule still_prompt_content, saying what to add. The full table with each next step is in the guide resource yoh://guide/timeline and the skill.
Edit existing pictures, motion or audio
Read get_clip, list_asset_image_versions, list_looks and get_source_audio first. Use set_clip_image or use_asset_image_version to reuse an existing image; edit_asset_image edits a picture and draw_asset_image draws a new one, both quoted first. A result on an asset with no picture yet becomes its picture by itself (a character with only a sheet counts as having one: its sheet is kept); an asset that has a picture never changes on its own: the result waits for use_asset_image_version. Only a first sheet run lands its matching portrait and sheet together, never over a portrait the user chose. apply: false always stays a preview. generate_look_image draws an existing look's picture with the app's look recipe (quoted first). An asset edit returns a preview; use_asset_image_version applies it. A save that replaces a picture answers previousVersionId (use_asset_image_version with it undoes the change) and clipsStillShowingOldPicture: the made clips that wear the asset's usual look and still show the old picture (v1 asset image with save: true answers the same). draw_asset_image applies by default (preview:true requests review first). Text and look suggestions must be saved separately after approval. Before re-voicing or changing the music under voices, check get_clip separation: when it is original, offer to separate voice and background (quoted: free only while the take’s paid split part is unused; clip_source_audio separate, or separate_story_audio for every clip), then re-voice or adjust. Each new read of a character line lands where the video was heard saying that line: it starts on the line's first heard word and is cut at the heard pauses, each piece placed on its heard phrase at 0.8–1.2× (a pause in the mouth is a pause in the voice); when the whole line would need below 0.8× or above 1.35× it is recorded at the heard pace (still one read, priced in the quote). Heard words outside what the clip plays (before its head trim or after its end) do not count, and a read longer than what is visible starts on the first visible heard word and runs on, never cut. A line whose words were edited since is fitted across its heard window. With no heard words, it lands in the span audio finishing measured (for a reused or uploaded video with no finishing, the speech runs of its separated speech track, in line order), fitted into it at 0.8–1.2×. Narrator lines are placed, never lip-synced; a read moved by hand (pin_dialogue_read) keeps its spot; a negative offset places a read by its first word, skipping at most the silence before it (speech never starts before the clip). Each new read's register is measured: a read far off its voice's usual pitch (1.5× or more against at least two other reads of that voice in the story; never a whispered read, which has too little voiced pitch and never sets the usual) is flagged with the warning read_off_register and get_revoice lines[].offRegister { hz, usualHz, message }, as the clip panel shows it: it may sound like a different person, so ask the user to listen and offer a re-voice with less intensity or another take. On a Mandarin line a new read heard in another language (Cantonese, Hokkien …) or saying other words is read once more without direction, at no charge, and the better read is kept: get_revoice lines[].wrongDialect { heard, probability, message }, lines[].wrongWords { heard, expected, message } and lines[].retried { reasons, kept } say so; offer a re-voice or plainer wording. revoice_clip's quote lists direction for each line whose voice ignores some or all of the asked direction (applies partial or none, ignored, message; a Qwen voice reads the words only), as the clip panel's confirm says "Direction applies partially": tell the user before they approve. A line's delivery (get_clip, get_revoice and the quote's lines) is the app's chips: an older free-text note (e.g. "激動・絕望") is read into them in every app language, kept as the note, with suggested: true. Offer Separate only when get_source_audio separationAvailable is true (a clip with no sound is no_sound; a clip with no lines whose voice check heard no speech reads separation.noSpeech, and Separate answers no_speech at once). get_source_audio and clip_source_audio answer each track's waveform as 64 points with peakStats (points, max, mean, silentShare); fullPeaks: true returns the full arrays. Movement footage for one clip: set_clip_motion_reference (3–12 s range), set_clip_motion_source, remove_clip_motion_reference. The clip panel's Reference ticks, in its main view (Start frame, sketch, Motion reference video): get_clip referenceRows reads them, set_clip_references (v1 PATCH clip references) sets them; a tick is kept in every frame mode, only what the mode sends is made and charged, a scene-changed reference is a flag (sent as it is while ticked, Remake optional), and a ticked one that does not exist at all is made first inside the video's quote (never a Motion reference video: the app films that when it is ticked). The sketch is one pencil sheet with one panel per timed beat of the clip's motion (2–9 panels in time order, each the clip's own frame shape), drawn from its camera and staging (the shot's light treatment as pencil shading when it fits the place, a dutch angle or POV drawn, the exact camera move such as a whip pan, crane, dolly zoom or rack focus as its own red-arrow mark); the video reads it as one continuous shot with no cuts. How a clip's video starts: set_clip_frame_mode omni, start (on the clip image) or start_end (ending on the next clip's image); a start-image take carries no voice input: the recordings of its lines are placed after it lands; re-voice it to change the voices. set_voice_mix controls source speech/background tracks; set_soundtrack_playback controls music volume. Text edits do not update generated media. The app’s Edit with AI asks first whether the result is saved as a new look (add_look with the edit’s versionId, free; the default for an outfit or age change) or replaces the picture (use_asset_image_version).
Hire a creator or offer your work
Two kinds, both paid at send and refunded in full if declined or unanswered. Use a character: search_hire_listings, inspect quote_hire, then send_hire_request after terms approval (per-episode price; a posting package or bundle adds the owner posting your video). The posting brief: each standard post has its own posts[] entry (date inside the package's window, what it is for, caption, hashtags); custom packages share postingInstructions and requiredHashtags, which are sent only when a custom package is chosen, also beside standard posts. The app pre-fills each added post from the one before, date left empty. A hired character always keeps its own look: when the episode is in another style, quote_hire answers styleNote (characterStyle, storyStyle), to tell the user before sending. Unlisted stories are link-only: their characters come back from search_hire_listings only with seriesId, and a private story's character answers LISTING_UNAVAILABLE. send_job_video with no render answers NO_RENDER; accepting a video job needs deliveryDays (DELIVERY_TIME_REQUIRED, DELIVERY_DAYS_INVALID). Several unpaid character requests in one episode pay together: quote_hire with storyId (and optional hireIds) answers a group quote with each part, the total and a quoteHash; pay_hire with storyId, hireIds and quoteHash gives one checkout link (HIRES_UNAVAILABLE: quote again without the named hires; QUOTE_CHANGED: quote again); each hire keeps its own page, refund and messages. pay_hire hands checkout to the user; a character fee is paid to the owner when the buyer's refund window closes (at first use, or 7 days after the face is added if that comes first), and get_earnings shows it as licenceHeldUntil, or onHold while the bank reviews the payment; get_hire tracks payment and delivery (payment.outsideRefundedCents is the total refunded on the charge, Yoh's item refunds included). Video job: a creator makes the whole episode (never a subset of scenes): search_video_job_creators then hire_creator_clips, or post_clip_call and pick_clip_offer (a whole new video can be the next episode of one of your series with production.seriesId, the same choice the app's form offers); get_clip_call compares offers by price, delivery days, note and maker.trust: videoJobsDone, replyMinutes, a sample story and accounts, with no star ratings). The hirer reads the script's summary only (get_hire outline.latest has no scenes; the full script stays with the creator until the video is ready) and may add_job_budget at any time while the job is open. list_call_applicants shows each applicant's accounts for that character. Every video job works in its own new episode: a job on your existing episode starts in a full copy of it, filed as a version of that episode (get_hire jobVersion); your original is never changed and stays editable, and you watch the job's version read-only. The creator works there with the normal tools and sends it with send_job_video; review_delivery acceptance can release payment. After accepting, use_job_version puts the job's version in the original's place (restore puts it back) and decides per changed shared character, place or item: series or this episode only. A refunded or cancelled job archives its version and changes nothing else. Until the creator delivers a video, the hirer reads the job's episode with its script as a summary only, everywhere (editor, get_story, the job page): clips keep their pictures, videos, order and branches, but their script fields are empty with scriptHidden: true, and jobScriptSummary carries the summary the creator sent (a read-only Script summary panel in the editor); after a delivery it reads in full. The job page can accept an earlier delivered version instead of the latest. A hired face never wipes your own character: a role picture never used in a clip (any episode of the series) and not your upload is replaced and kept hidden; a used one makes attach_hired_character answer HIRE_ROLE_CHOICE_NEEDED, and you choose use_hired (replace; the old picture comes back on refund) or keep_mine (the face is added as a new character beside it, in no scenes; attach_hired_character useInScenes: true, or Use in these scenes on the hire page, moves the role's scenes and lines to it, and ending the hire moves them back). A waiting choice sends a bell notice and shows a line at the top of the hire page. A role still holding a refunded hired face counts as unused only if nothing was made with it. A creator's own story on a whole-new-video job lands in the job's new episode, adapted to the brief: the brief's length, language, format, product and photos win (offer_on_clip_call check:true and the pick list where they differ). A story in another language is translated into the brief's by the writer in the script step, in the same run, at no extra charge. The 20% story share is paid only when the hirer OKs the adapted script; a cancel before that means the story isn't used and everything is refunded. open_clip_workspace and send_clip_take are legacy (clip hires sent before 2026-10-17). set_character_listing creates a first listing (one with no character sheet is refused at the quote with needs_sheet); an uploaded photo alone does not establish likeness rights. After acceptance, anything not delivered yet can be refunded: the hirer calls cancel_hire_work ask_refund (paid parts with nothing delivered), the person hired answers cancel_hire_work answer_refund refund or keep, and with no answer in 3 days it is refunded automatically; delivered work is accepted or sent back instead (get_hire booking.refundRequest shows the open request and its deadline). While the buyer's bank reviews the payment (a dispute or card-fraud warning), nothing on the hire can change: answers, step backs and refund asks are refused with PAYMENT_DISPUTED. Hire rules: every paid hire is at least $5 (character use, bundles, posting services, the per-minute clip rate, an offer, and a job priced from a rate); free stays free, and a lower paid price is refused with MINIMUM_PAYMENT (a price saved before this rule keeps working until it is changed). No counter-offers: the price comes from the listing, the creator's rate or the creator's offer. respond_hire, pick_clip_offer, send_hire_request and hire_creator_clips refuse an argument they don't take (for example a priceCents sent as a counter) with invalid_arguments (rule known_arguments) instead of dropping it; for another price, send a new request, or the creator makes a new offer. When accepting, any version the creator sent can be picked (review_delivery with that version's deliveryId), not only the latest. A delivered clip or video can be sent back twice in total; the 3rd delivery can only be accepted, or it is accepted after 7 days (asking again answers SEND_BACKS_USED; get_hire assignments[].sendBacksLeft). Stolen-card protection: a seller's first 3 cash payouts for hires go out 7 days after the buyer's charge (get_hire payment.newSellerPayoutAt while one waits; the seller's earned notice names the date, in UTC). An ended hire says "This hire has ended. No fee is held." and does not repeat the first-use or new-seller wait. A new Stripe refund sets metadata refund_reason to talent_declined, withdrawn, expired, unanswered or cancel_licence. The idempotency key and replacementSettlementId stay as they were. Replaying a used key omits refund_reason and sends that key's original body, so Stripe returns the original refund. A card-fraud warning from the buyer's bank freezes the hire; with no open or lost dispute 30 days later it continues, both sides are told, and a request not answered yet gets a fresh 7-day answer window. A won dispute does the same: the hire goes back to where it was before the freeze. A won dispute on a hire already refunded goes back to that refund state, and both sides hear the refund stands. With more than one dispute on the payment, the hire stays frozen until the last one closes. If a bank decision never reaches Yoh, the hire cron asks Stripe once a freeze is 7 days old and applies it, so no hire stays frozen for good. A bank inquiry closed with no chargeback is not a win: a warning's freeze still waits for its 30 days, unless another dispute on the payment was won. A warning on a hire already frozen is kept and starts its own 30 days. Cash a seller earned but can't receive because payouts aren't set up gets a reminder at 7, 30 and 60 days after the work was accepted, then every 30 days; that money stays the seller's and never goes back to the hirer, choosing credits pays it at once, and cash goes out on the next payout run after payouts are set up. A tax form, where one is needed, is asked for only before the first cash payout. The face owner can stop new hires anytime on the whole listing (withdraw_listing_consent), and withdraw consent on one hire (cancel_hire_work withdraw_consent) only until the hirer first uses the face, at most 7 days after it was added: the hirer gets the licence and unused parts back and the face leaves. After that the episode keeps the face (CONSENT_WINDOW_CLOSED). Hires agreed before 2026-11-06: new uses stop at once, unused parts are refunded, used parts are not, and an episode already published with the face must be changed within 30 days or it is taken down. preview_generation on such an episode leads its warnings with character_permission: the real run is refused (only when the run would refuse that kind: in a production story, voice and prompt work still runs). Paying again after leaving Stripe Checkout is safe: only a second completed payment for the same hire (a true duplicate), or one that arrives after the hire closed, is refunded in full, and the hirer gets one notice with the amount. Fair hire rules (hires agreed from 2026-11-06, terms.rulesVersion): a script with no answer is approved after 5 days; a first version sent on time releases 30% of its video money at once (a video_first_version part); after a send-back the creator has max(3 days, a third of the delivery days); unfinished work can be cancelled as late 24 hours after the due date; an unanswered ask_job_budget pauses the due date (deliveryProgress.duePausedSince, DELIVERY_PAUSED) and add_job_budget moves it by the wait; AI credits the creator used are not refunded. Ask Yoh to decide: while a video waits for review either side calls review_delivery decision ask_yoh (no money moves); the money stays held and auto-accept pauses, both sides have 14 days to agree (the creator can offer a partial refund on the hire page), then Yoh decides 0–100% of the held video money back with a reason (get_hire booking.decision, read-only). A full refund takes the creator's takes out of the hirer's Versions. Character hires under these rules (get_hire booking.rules): the face licence is held until first use (the first paid picture or video with the face, or the first publish) or day 7, whichever comes first; until then cancel_hire_work cancel_licence refunds it in full and the face leaves the episode (booking.licenceCancel; LICENCE_FINAL after). A paid picture or video counts once it is made: while one is being made the cancel is refused (FACE_USE_PENDING); one that fails, never starts (2 hours) or is stuck for 24 hours is refunded and does not count. A withdrawal inside its window refunds the licence in full and the face leaves (booking.faceConsent.window says until when). There is no Start now box: every buyer gets the same windows, and a paid licence whose face is never added is refunded 30 days after payment. A chargeback the hirer wins takes the face out. Story access (2026-11-07): the owner of a hired character may read the episode it plays in. As the owner, get_hire gives booking.storyId, booking.canReadEpisode and booking.ownerEpisodeAccess (active, done or consent_withdrawn: readable; refunded, cancelled or removed: closed; posts_only: no access). get_story then reads it; writes, generations and model runs (write_time_beats, suggest_clip_duration included) need edit access. Reading stays after Done and after consent is withdrawn, and ends on refund or cancel. A video job's creator gets one step per phase, the same on the Hires row and the hire page: no script yet opens the writer, a started script, making or changes open the editor, and the hirer's review phases open the episode read only.
Public lists leave out test content
Explore, public profiles' lists, the landing feeds, search and discovery (search_hire_listings, search_video_job_creators, list_casting_calls, list_clip_calls) leave out QA and test content: titles that start with a test tag such as [QA-…], [Stripe QA …], [E2E] or [TEST], and the stories, characters and calls of test accounts. Your own calls still show to you, and direct links still open. In the app "Open calls" now reads "Calls" and "People" reads "Creators"; URLs are unchanged.
Build a Yoh Ads show
Create with create_brand_show, read get_brand_show and review its brief and season, then accept_brand_show. Quote write_show_episode for a planned slot. Poll get_brand_show, then quote make_show_episode for videos and again for the render. get_show_plan previews run_show_autopilot; review credit costs, posting and Meta money actions together. Follow get_show_activity. Connect Meta accounts in the app.
Review inputs and finished exports
check_clips storyReview: "viewer" reviews what the audience can understand instead of the continuity pass, at the same quoted price. Still images check identity; speech and lip-sync need playback. Unknown or partial checks are not passes. generate_all_clips and generate_all_videos productionReview: true opt into saved-input approval: finish setup and pictures, review the quote, then confirm. This mode excludes parallel and fixFirst. Changed inputs hold affected clips before charge. A newly generated continuity reference also needs a new review, so a dependent chain may pause between shots; quote the remaining explicit clipIds to continue. The ordinary generation path remains available. get_render_review reads one exact export. review_render records its fingerprint, revision and the user's explicit decision; accepted also requires watchedFullVideo: true. It does not publish or teach anything. Technical metadata is not visual, audio or caption QA. REST uses GET / POST /api/v1/stories/:storyId/renders/:renderId/review with stories:read / stories:write respectively.
Publish a finished video
Inspect list_renders · get_render_review · review_render and get_publish_options. Confirm the selected video, audience and any template rights before publish_story. For social posting, list_social_accounts, approve account/video/caption, call social_publish, then poll get_social_post. Publishing is a separate decision from rendering.
Check spending and manage access
Use get_credits for balance, get_credit_history for charges (each with its receipt: charged, refunded, final, and providerBilledKept when the provider charged for a failed attempt), get_story_spend for what a story used, get_earnings for creator income (cash and credit payouts kept apart; expected payouts total dollars and credits separately, as expectedPayouts.cash.totalNet and expectedPayouts.credits.credits, and a failed payout-method read puts hire items in expectedPayouts.unknownMethod.usdCents, outside both; an approved cash item waiting under the new-seller rule carries payoutAt, the date it goes out, and is not stuck; the seller's earned notice names that date too, also while payout setup or the tax form is still missing (the payout then goes on that date or once that is done, whichever is later); payoutTotals counts every credit payout while creditPayouts.items lists the latest 200, cancelled ones included (each with cancelReason, in no total)) and list_notifications for activity. set_payout_method reads or changes how hires pay you: cash to your bank through Stripe, or credits with no setup (75 credits per $1, spendable 7 days after they're paid to you, never turned into cash). It is confirm-gated: the first call shows what changes (owed money paid as credits now and the hires affected) and a confirmToken; the second call with that token commits. Until a method is chosen, paid work (accepting a paid hire, a paid listing or rate, instant hire, a paid offer) is refused with payout_method_required and nextStep set_payout_method. list_api_keys shows metadata; revoke_api_key removes access. Check get_auto_generate before changing a schedule; enabling set_auto_generate needs explicit recurring-spend consent and stories:generate as well as series:write.
Colour tone
A story has one colour tone: its palette and grade in plain English colour words (get_story / GET /api/v1/stories/:id colorTone). The writer picks it from the idea or the pasted script and the style; an episode takes its series' tone, the first story of a new series gives the series its tone, and a tone you send wins (create_story colorTone, the same field as style.colorPalette on POST /api/v1/stories/generate; a tone of only names is refused there too); a tone a person set is never replaced by a later writer run. update_story colorTone (or the Edit story dialog; an older caller's styleGuide.colorPalette on update_story or PATCH /api/stories/:id is the same edit by the same rule) changes it, up to 70 characters; "" clears it, nothing is redrawn, and a tone of only brand or film names is refused (color_tone_only_names; 422 COLOR_TONE_ONLY_NAMES on the app's PATCH). The Edit story dialog, PATCH /api/stories/:id and update_story save it through the same rule, the tone last under a lock. A black-and-white style or shot says it as black and white. Every clip picture and video carries it in the Style line, background plates and location pictures are drawn in it, character sheets are not, and a scene's own light still sets that moment's light. A classified shot look that is the tone's real opposite (muted vs vibrant, pastel vs saturated, colour vs black and white) is left out and noted by check_clips (fact_conflict, fact look); a typed look, black and white and flashback, dream or memory clips keep theirs. search_stock_media with storyId puts photos in the tone's main colour first, then the plain search when none match.
Reading episodes
list_stories / GET /api/v1/stories leave archived stories out (an original replaced by its copy is not an episode); includeArchived: true lists them with archived: true and no episodeNumber, as get_story says too. get_story gives each clip its staging, treatment and frameMode { requested, source, runs, reason?, fallback? } (fallback no_next_image: a start_end clip whose next clip has no picture yet runs start); compact: true answers a smaller story (versions become versionCount, resolvedAssets keep the look ids). A format version says its new shape in each clip's words; older copies get the free Check clips finding aspect_wording (fix edit_text, applied on the user's tap).
Title look
A story's title cards, taglines and hook lines share one look composed from parts (get_story / GET /api/v1/stories/:id titleLook: { palette { id, text, accent, glow }, typeMood, motion, source, summary }; null on older stories, which keep the plain white look). The palette is read from the colour tone (ember, golden, sepia, neon, cold, pastel, crimson, verdant, mono; an unknown tone stays neutral), the type mood from the style, era, genre and format (classic_serif, bold_sans, rounded, condensed, elegant_thin, handwritten; Chinese, Japanese and Korean titles get the mood's Noto Serif or Sans TC, SC, JP or KR face) and the motion from the genre (calm, punchy, thriller). Each card's glow follows its shot's light (fire and lamps warm, neon magenta, moonlight cold blue, daylight none) and a dark outer shadow always stays. An episode takes its series' look. MCP set_on_screen_text_look storyTitleLook { palette?, typeMood?, motion?, reset? } changes it (free): unstyled entries take it at once, entries someone already styled keep the look they show. Labels and the CTA keep their own look.
One owner per fact
A sound cue that names a voice (announcer, commentator, loudspeaker) with no written line is sent as plain sound, with no voice for it, because a model otherwise invents the words: if the words should be heard, add them as a dialogue line. A clip with any written line keeps the cue as it is, since only the quoted words are spoken; a rung or struck sound ("announcement chime") is plain sound. Written action wins: over timed beats a staging id's stock sentence is left out of the video prompt when the beats own that action (stage.face_off when people act in the beats, stage.impact_recoil when the beats name the target's reaction, each noted by check_clips; otherwise it stays; the opening picture keeps its pose). Timed beats written in another script (Chinese, Thai and others) get no staging sentence in the video prompt, since those checks read English only. A typed end anchor also binds when the ending is the clip's own last beat (end.hold_frame, end.on_face, end.on_object and end.motion_carry alike). end.hold_frame stays the protected ending ("Ends holding on…") and is never dropped; the others go on their own line that never counts toward the prompt's target length or motion share and never shortens another line, and under a model's hard limit it is shortened or dropped after the sound line and the rules but before every other line: end.motion_carry says the action is still under way so the next clip continues it (before a scene change only that nothing settles; the story's last visible clip says it is still going as the video ends), a last beat that brings its people to rest (or ends on "Hold.") drops the carry, and a stock staging phrase that stops the person goes beside a carry (stage.reaction_hold over a last beat where nobody in frame moves their body is the ending and the carry goes; while someone else still moves, the carry stays and the phrase loses "then holds"; a phrase about one named person says "Ku's", never a guessed pronoun); end.on_face names whose face (the typed one, the one person in frame, or the face the last beat ends on; otherwise it is not said) and end.on_object says the object with its article; a last beat that fades out or cuts to a title card ends on none of them. A part of a split clip keeps only the carry. A speed ramp's timeAt is the second its peak slows, clamped inside the clip: normal speed until then. Every clip fact has one owner field, and the picture, video, edit and sketch prompts read it from there only; free text (Shot, Subjects, Setting, description, beats) describes but never sets the camera, sides, facing, light, move, speed or time of day (a clip's time is its place row's, its recorded shotData.place.timeOfDay or a picked look; against a series background's time, check_clips time_of_day notes an explicit phrase such as "late that night" in the description at low severity with no picked fix, never "night-market" or "the night he lost"). Who is in frame: the clip cast and the staging people, plus an unnamed counterpart the clip's present action puts with a lone person ("his opponent"; English words only). A typed profile or from-behind angle on a group is said in the camera line and turns everyone nobody placed. Side and depth: staging people. Facing at the first frame: staging facing (an over-the-shoulder foreground person faces away unless you set their azimuth). Gaze during the clip: the motion beats. Pose at the first frame: the opening, beat 1 of the motion (a start picture follows it). Shot size, height and lens: staging camera. Camera move: the staging move, in the library move's own words with the clip's seconds (an unset move gives way to one other move the beats name with the word camera). Composition: the treatment composition, else the Shot line's non-camera clauses. Light: the Staging Light chip, else the place's lighting, said once (the image prompt's own Light line is not used). Atmosphere and speed: the treatment. Props: the clip items. Place: the scene. Spoken words: the dialogue lines (the speech rule is never trimmed). Style: the story style guide, the same in every clip. Change the owner, not a prose line.
Read the video prompt before paying
A failed run with errorCategory internal is a fault on Yoh's side before any provider ran: try it again later; it names no other model because none would help. The quote of generate_clip_video carries videoPrompt { model, prompt, final, filledAtRunTime, note, lengthFit } (lengthFit.summary, e.g. Prompt fits Kling (1,840 / 2,500), says how the prompt fits the model and trimmed lists what was shortened; does_not_fit also answers error PROMPT_TOO_LONG with the reason; get_clip promptFit is the same for the current video); get_clip also returns writerLint, checks on the clip as it is now (light_vs_scene for a light id against its place (reason interior, exterior, night, day or window), no_light_treatment, same_framing_as_previous for a jump cut from the clip before, move_without_reason, slow_motion_over_beats when slow motion covers more than one action beat (the model may hold still), opening_vs_subjects when the written opening poses someone otherwise than the still's Subjects line or a posture its Shot line gives them (the start picture keeps both), writer_skipped_shot_contract, gone once the user sets the staging, treatment or motion; check_clips says them too), fixed with update_clip or set_staging, never a block and the quote of generate_all_videos carries videoPrompts, one per planned clip (the first 30; videoPromptsOmitted lists the rest): the text the clip panel's prompt card shows, built without generating or charging anything. final: true is the text sent word for word; otherwise filledAtRunTime names what only the run makes: motion (no written motion yet, so the run writes timed motion first, inside the price), clipImage or sketch (a picture drawn first), continuity (the previous clip's video made earlier in the same batch), condensed (too long for the model: the run shortens its own reference text first, such as picture labels, restated outfits and staging lines, before any of the motion, and never a quoted line), translation (the clip's text is not in English: the run translates its written text and motion to English first, inside the price; the motion is the clip's own) or runStep (another run-time step changes some words). Only motion means the clip has no written motion. When even that cannot fit, videoPrompt.error.code is PROMPT_TOO_LONG: the run would refuse it before any video, so shorten the motion or dialogue, or drop references, before confirming. Both quotes carry warnings [{ code: "model_refuses_realistic_people", message, suggestedModels }] when the picked model refuses realistic people (list_models acceptsRealisticPeople false) and the story has them: a warning, not a block. A failed clip video's run result has errorCategory, failureReason (likeness_rejected for a refused real face), nextStep and, when another model fits, suggestedModels.
Add a note to a clip image redraw
A prompt on regenerate_clip_image is added to the clip's still as a note: the shot, cast, place, light and style still come from the clip. Send replace: true to make your prompt the frame's subject and action: the clip's framing, place and medium still wrap it, and framing words you write (close-up, wide shot, low angle) win. A plain redraw or a note sends the start_end partner's picture (else the same-place neighbour's) as a layout reference; replace: true sends none, as the clip panel's own prompt redraw.
A new still keeps the video
A new clip image on a clip with a finished video (regenerate_clip_image, edit_clip_image, enhance_clip_image, or the app's image tools) keeps that video selected: the image is saved as a new image version and becomes the clip's picture (its opening picture), so the next video run starts from it (the quote says keepsVideo with an attention line). The video is then older than its opening picture: get_clip activeTake.changedSinceTake lists step openingPicture { from, to } (a take that started from the clip image; not a continued cut), the clip panel shows it as out of date, and get_story_attention lists the clip as opening_picture_changed. Ask the user whether to make a new video: fix new_take (generate_clip_video; fix.credits is that clip's price in the batch quote, about) or altFix keep_take (keep_clip_as_is, free: the video stays with the new picture and the item stops showing). To use the image instead of the video, pick its version with select_clip_version. After Keep as is (keep_clip_as_is or the clip panel), changedSinceTake lists only what changed since the take was kept, on get_clip as in the clip panel and get_story_attention. The same picture under another link (a signed or moved copy) is no change.
Every suggestion can be closed
Nothing changes on its own: a suggestion says what to change and why, and the user decides. Check clips findings, readiness warnings and the Needs attention lines that are suggestions carry dismiss { clipId, key, print }. POST /api/v1/stories/{id}/clip-check/apply (MCP apply_clip_check_fixes) with fixes: [{ fix: { type: "dismiss", dismissal } }] closes one as it is, free; it stays out of /clip-check, /readiness and /attention and their counts until what it was read from changes. hidden counts closed ones and includeDismissed=true lists them as dismissed. Blockers a paid step refuses and failures cannot be closed. keep_clip_as_is also closes the clip's "written from an older description" and its opening-picture notice until the clip changes.
An edited line keeps its read
Nothing changes a clip's sound until the user approves. When a re-voiced line's words, speaker or voice change (in the script, the clip panel or a caption on the timeline), its read keeps playing exactly as before, in the preview and the render: get_revoice marks it stale (and the clip stale), and readiness, get_story_attention, get_clip soundStale and Check clips say the sound is out of date. A line added with no read has none yet while the other reads play on; a deleted line's read stops. The sound changes only through the fix (update_sound: revoice_clip of the changed lines, quoted first), the clip's Original sound switch (set_revoice_enabled false; true switches out-of-date reads back on), or the user's Keep as is: altFix keep_sound, keep_clip_as_is with only: "sound" (free), which clears the suggestion until a line, the cast or the take changes again (get_revoice staleKept). A re-voice made for another take of the clip is a different case and is left alone.
See what each clip really runs
Every video quote also says what each clip really runs: runPlan (generate_clip_video) or runPlans (generate_all_videos, generate_all_clips, regenerate_clip; frameModes counts them) { clipId, clipNumber, pickedModel, model, modelName, frameMode, requestedFrameMode, warnings: [{ code, message }] }, also shown as the frameMode setting. frameMode is refs_only, start, start_end or motion_control (set_clip_frame_mode calls refs_only "omni" and takes either). A clip with movement footage runs on Kling V3 Motion Control whatever model was picked (motion_control_takeover). A frame mode the model can't run is lowered the way the run lowers it: start_end on a model with no end frame (Grok) starts from the clip image and drops the end frame (end_frame_dropped); start on a model that can't start from an image runs on references only (start_frame_unsupported); a start_end clip whose next clip has no image when it starts drops the end frame (no_next_image). A start_end the user picked whose next clip's picture cannot be its last frame (another cast, look, framing, sides or state) keeps the pick and starts on the clip image only: the run plan warns end_frame_refused (details { reason, why }: reason is the frameMode reason code, e.g. end_cast_change), never no_next_image (frameMode fallback end_refused, with that reason, in get_clip and set_clip_frame_mode too, also for a clip whose image the run draws first; plan_changed when the story planner picked it and the clips changed since); a clip cut from the episode never ends on another clip's picture. A start_end clip whose start and end pictures differ clearly (shot sizes two or more steps apart, or drawn by different image models) warns end_frame_mismatch (with details { startSize, endSize, startImageModel, endImageModel }): such a take tends to cross-dissolve mid-clip and lose the action, so offer to redraw the next clip's image from this one (edit_clip_image on the next clip with this clip's image in referenceImageUrls) or set_clip_frame_mode start; it is a warning, never a block. The two pictures of a start_end pair are one take: drawing either one (regenerate_clip_image) sends the other, when it exists, as a layout reference (same room the same way round, its own moment and framing; the first reference to leave a full model, so the price never changes), and the picture records it (imageHistory.details[url].pairedFrom). Any other clip picture drawn on its own (no pair, no scene opener) gets its same-place neighbour's picture (the clip before, else the clip after) the same way, for the room's layout only. A pair whose pictures were drawn apart, neither from the other, warns end_frame_drawn_apart (details { redrawClipId }; fix regenerate_clip_image on that clip): look at both, and when the sides, props or cast differ, redraw the next clip's image before the video; a warning, never a block. A start or start_end clip whose image was drawn by another image model than the story's still model warns still_model_off_story (details { startImageModel, storyImageModel }): a start take copies the faces in its picture (Kling V3 Omni start_end only when it falls back to Replicate), so offer regenerate_clip_image on the story's model before the video; also a warning only. Kling V3 Omni start_end carries up to 3 characters: its first route (fal O3) sends both frames plus the 3 most prominent on-screen characters (most lines first) as references, then falls back to Replicate with the two frames only (no references beside an end frame is Replicate's limit); more than 3 on screen warns cast_over_elements (details { sent, leftOut }), lines_language_unsupported (a line in a language the model does not voice, e.g. Thai on Seedance 2.0; suggestedModels names one that does; never a block). A take that fell back while it had characters to send says so: charactersNotice { code kling_frames_only, characters, message } on its run result (get_run) and a clip_frames_only line in get_story_attention (made without character references; faces copied from the pictures only). The quote's videoPrompt and preview and preview_generation show the prompt word for word as the lead route sends it (on fal O3 with its "Cast references: @Element1 is …" line); its references list tags each character's pictures with its @ElementN and the two frames Start frame and End frame, and videoQuote.chain lists fal O3 first and Replicate second (fal O3 is never listed for a clip that does not run start_end). Each warning is also an attention line: say it with the price.
See how each clip starts (frame modes)
The story planner picks each clip's frame mode from its shot (opening, ending, beats) and framing (size, the camera move's start and end size, who stands where, who is in frame at the first instant): start_end when the clip flows straight on into the next one: the next clip is written as continuous (never a match-action cut) and opens exactly where this one ends (the same place, people, looks and posture, this clip's end size (where a push ends) within one size step of the next opening size, everyone on the same side and angle, no orbit, crane or tilt, at most 10 s), and both clips can open on a picture; start for the clip right after a start_end clip (after_start_end: it opens on the shared image); omni for everything else. In start and start_end the clip image is frame 1, so it must show the clip's opening moment, at the move's start size. get_clip frameMode.reason says why: the clip's own cause (footage; enters_later: someone walks in after it starts; voice_refs; scene_change; new_character; new_look), else why it does not end on the next clip (end_framing_mismatch, end_sides_mismatch, end_state_break, end_cast_change, end_look_change, end_move_changes_frame, end_too_long, or next_from_references: the next clip has to be made from references), else not_continuous. These are suggestions: a person's pick (set_clip_frame_mode) always wins. get_clip frameMode and set_clip_frame_mode also answer willMake (clip_image, next_clip_image or sketch made first, with credits; all are priced in the video quote, a sketch at the price of generate_clip_grid_reference for the clip's real reference count, plus the clip image when the run makes it first: Auto may widen to a model that takes more pictures, at that model's price; the quote lists it as referenceSketch { model, credits }, the app shows "Sketch · +N cr", and the run adopts that charge, so it is paid once), revoiceNeeded { lines, credits } (a talking clip's take that carries no voice input, a start or start_end take or a reference take on Kling V3 Omni or Grok, which take none in any mode: offer revoice_clip after it, at about that price, not in the video quote; runPlan.revoiceNeeded says the same on a quote, and runPlan.voiceInput says whether the take carries voice input (the recordings of the cast's lines as @audio), so the quote's Audio reference row reads off, and why, when it carries none), startImageStale (the clip image is a storyboard grid crop, shows another moment or framing, or reason character_redrawn: a character in it got a new sheet or portrait since it was drawn, so a start take would copy the old face; a sheet drawn later around the same portrait, or the same file moved to storage, is no new face: offer regenerate_clip_image before the video, at its credits; runPlan warning start_image_stale names who) and omniReferences (an omni clip needs more references than the model takes; runPlan warning omni_refs_over_capacity). set_clip_frame_mode preferVoiceRefs (story-wide, default off) makes the planner pick omni for close dialogue clips on models whose omni takes voice input, so they lip-sync to the recordings without Re-voice.
★ means a credit quote followed by confirmToken. Other costs need their own review: ask_assistant charges its text turn immediately and needs stories:generate, set_auto_generate enables future credit spending, and hiring or Meta ads can involve external money. No ★ does not mean free. Review those costs with the user before calling.
エージェントにできること
| ツール | 範囲 | 例 |
|---|---|---|
| 読み取り | stories:read | get_guide · list_stories · get_story · list_story_versions · get_timeline · get_clip_timeline · get_edit_timeline · list_timeline_versions · get_clip · get_job · get_run · get_credits · list_models · get_soundtrack · list_overlays · get_revoice · get_audio_sync · list_style_presets · list_voices · list_renders · list_audio_assets · check_readiness · get_story_attention · preview_script · analyze_prompt · preview_generation · estimate_storyget_clip はクリップ画像(ある場合)を添付し、withFrames を付けると生成済み動画からサンプリングした実際のフレームも返します。エージェントがクリップの実際の見た目を確認できる唯一の手段です。get_asset_images はキャスト・セット・小道具について同じことを行います。生成されたキャラクター・場所・アイテム(および場所やアイテムのルック)には情報カードもあります(get_asset_images、list_asset_image_versions、list_looks の cardUrl)。左上はコードで切り出したポートレート、メイン画像または背景プレートです。カードは人が見るためのもので、生成モデルには渡されません。 |
| Export review | stories:read / stories:write | get_render_review · review_renderRead an exact export and record its human playback decision. Free; separate from publishing. |
| Template versions | stories:write / stories:read / assets:read | create_template_version · get_template_version · list_template_destinations · list_template_assets · update_template_version · analyze_template_version · get_template_analysis · accept_template_adaptation · quote_template_version · commit_template_version · cancel_template_version · fork_template_versionMap existing or newly created series assets, review wording and language, then create a free draft. REST families: /api/v1/template-version-sessions/:sessionId and /api/v1/template-version-runs/:runId. Template REST OpenAPI schemas and endpoints · Full v1 OpenAPI (/api/v1/openapi.json) |
| Template generation ★ | stories:generate | generate_template_versionQuote the run first, show the maximum credits, then confirm. Poll get_template_version for persisted progress and recovery. |
| 作成 ★ | stories:generate | create_storyプロンプトから新しいストーリーを書き起こします。estimate_story は無料で、計画全体をあらかじめ見積もれます(個別の見積もりではできません)。まずは scope="story"(テキストのみ)から始めてください。"full" はすぐに動画分を課金します。 |
| Analyse a saved timeline | stories:read | get_timeline_analysis · GET /api/v1/stories/:storyId/timeline/analysisRead-only download manifest for the selected Edit/Clip branch: deduplicated Yoh-stored HTTPS media URLs, timeline item IDs, trim/speed mappings, sample timestamps and labelled script/caption/read evidence. Filter by itemIds, range or includeHidden; these and revision use JSON query values. Download and inspect relevant files locally, then re-read the revision before editing and verify the composed preview. No media analysis, rendering or credit spend occurs when collecting the package. |
| Timeline commands | stories:read / stories:write | get_timeline_capabilities · preview_timeline · undo_timeline_edit · GET /api/v1/timeline/capabilities · GET /api/v1/stories/:storyId/timeline/preview · POST /api/v1/stories/:storyId/timeline/undo · GET /api/v1/stories/:storyId/timeline/versionsFree. get_timeline_capabilities lists the edit_timeline ops and limits. preview_timeline checks the saved composition with the render builder and answers a read-only player link with its revision, size and duration (the REST route answers the render snapshot itself); nothing is rendered or saved. To try an edit without saving it, send edit_timeline (or PATCH timeline) with dryRun: true. undo_timeline_edit undoes one saved command by its commandId against a freshly read revision; unrelated later edits stay, and a conflicting undo is refused. GET timeline/versions lists the saved versions add_timeline_version can insert. |
| Clip-mode timeline actions over REST | stories:write | trim_clip · move_caption · pin_dialogue_read · hide_clip_video · hide_dialogue_line · export_clip_to_freeform · export_caption_to_freeform · export_clip_audio_to_freeform · POST /api/v1/stories/:storyId/clips/:clipId/trim · POST /api/v1/stories/:storyId/clips/:clipId/caption-timing · POST /api/v1/stories/:storyId/clips/:clipId/read-offset · POST /api/v1/stories/:storyId/clips/:clipId/hide · POST /api/v1/stories/:storyId/clips/:clipId/hide-line · POST /api/v1/stories/:storyId/clips/:clipId/freeform-export · POST /api/v1/stories/:storyId/clips/:clipId/freeform-export/caption · POST /api/v1/stories/:storyId/clips/:clipId/freeform-export/audioFree. Each route runs the same service as its MCP tool, with the tool's body fields (storyId and clipId come from the path) and refusals: trim { start, end }, caption-timing { lineId, start?, end? }, read-offset { lineIndex, startOffset, lineId? }, hide { hidden }, hide-line { lineId, hidden }, freeform-export/caption { lineId }, freeform-export/audio { part, lineId?, lineIndex?, track? }. These change Clip mode; the clip's Edit items not changed in Edit follow, and an item changed in Edit keeps its own (stale when its source changed). A clip's place in time is Edit arrangement: move_clip is refused (position_in_edit_mode), so move its video item with PATCH /api/v1/stories/:storyId/timeline (op move); split, speed and volume are PATCH /timeline ops too. The exports are legacy: they hide the source in Edit only. |
| Clip-mode looks and mix over REST | stories:write | set_caption_style · set_on_screen_text_look · set_voice_mix · POST /api/v1/stories/:storyId/clips/:clipId/caption-style · POST /api/v1/stories/:storyId/on-screen-text-look · POST /api/v1/stories/:storyId/voice-mixFree. Each route runs the same service as its MCP tool, with the tool's body fields (storyId, and clipId for caption-style, come from the path) and refusals: caption-style { lineId, presetId?, styles?, fontSizeScale?, clear? }, on-screen-text-look { clipId?, textId?, box?, styles?, fontSizeScale?, reset?, storyTitleLook? } (an entry, the story's title look, or both), voice-mix { target, clipId?, lineIndex?, lineId?, track?, speakerId?, volume?, fadeIn?, fadeOut?, detached?, background? }. These change Clip mode; in Edit the clip's items not changed there follow at once, and an item changed in Edit keeps its own (it reads stale). An Edit item's level is PATCH /api/v1/stories/:storyId/timeline (op update styles.volume on that item). |
| Production plan and export issues | stories:read / stories:write | get_production_plan · save_production_plan · record_production_observation · get_render_issues · record_render_issue · repair_render_issue · GET / POST / PUT /api/v1/stories/:storyId/production-plan · GET / POST /api/v1/stories/:storyId/renders/:renderId/issues · POST /api/v1/stories/:storyId/renders/:renderId/repairsFree and optional. The plan is versioned (scene and beat IDs, goals, opening and ending state, transitions, reference roles); a save needs the revision and source hash you read. The issue ledger belongs to one exact export; a repair applies a chosen free fix to a confirmed issue once per requestId and changes the source, not the exported file, so export again and review. Paid fixes keep their own quote and confirmToken. |
| Start from a video ★ | stories:write / stories:generate / stories:read / assets:write | upload_video · finish_video_upload · get_video_upload · upload_file · list_story_mediaUploading is free; cutting and reading are one price, set by the video's length and quoted before the cut. Cutting is what lets the video be sold as a template: buyers get its template shell (clip order, timing, camera plan and script, with empty roles), never the creator's pictures, video, voices or face; the creator sets the price and gets about 90% of each sale after Stripe's fee and any tax. upload_video makes a draft episode in a series and answers one curl command that sends the local file straight to storage; finish_video_upload verifies it, fills the details from the video, picks a cover and quotes cutting and reading it (the clips, each clip's description, motion, captions and text, and the characters and places) from its length, before the cut: show the price and call it again with confirmToken (stories:generate) once the user agrees; exactly that price is charged, refunded in full if the cut fails, or if it is stopped before any clip is read. get_video_upload reports the cut (cut.phase: awaiting_confirm while the quote waits (the upload status says confirm_read), then finding_clips while the scenes are read, minutes at 0%, then reading_clips) until it is ready; get_job on the cut answers the same real status (cutting, awaiting_confirm, confirming_read), never the stored queued between passes. Open links.upload to watch it; the page shows the same price in its confirm dialog. The cut reads the video with Yoh's scene decoder (rea) first, inside the same charge: its scene cuts are on (the plain ffmpeg cut is the fallback); its camera size and move are not trusted yet. Text in the video is sorted per clip into captions, on-screen text (burned in, so hidden on the timeline) and text in the picture. An upload's reading only fills that episode's own clips and is never learned from. Each cut reads its footage into the clip: timed beats, the visible people (p1, p2… as seen, never named), framing, light and period fill its staging and motion; get_clip shows it as uploadReading. A line's speaker is set only when one known character is seen speaking it; otherwise the line stays unassigned with a speakerHint for the user to pick. upload_file hosts a song, logo or extra footage the same way (for an overlay src or an asset picture); list_story_media lists every file of a story to download and check. |
| Story versions ★ | stories:generate / stories:write / stories:read | create_story_version · create_story_versions · get_story_version · get_version_translation · edit_version_translation · list_story_versionsA language, format or style version keeps every clip's media. A format or style version is free; a language version's translation is charged when it is created, so it answers a quote first and is made with confirmToken (the copy dialog's price). create_story_versions makes many at once the cheap way: each new style or aspect once, then its languages from it after its visual step. create_story_version(s) need stories:generate, edit_version_translation stories:write; the reads need stories:read. The paid steps run with run_story_version_step (stories:generate); its free 'prepare' step restarts a failed translation. |
| シリーズ | series:read / series:write assets:read / assets:write | list_series · get_series · create_series · update_series · list_series_assets · add_series_asset · update_series_asset · delete_series_asset · remove_series_look · use_series_look_as_main · make_style_copyひとつのストーリーの上位レイヤー。エピソードをまたいで共有されるキャラクター・背景・スタイルです。create_story の seriesId で新しいストーリーを紐づければ引き継げます。 新しいエピソードでは、脚本が別の服を求めない限り、各キャラクターの定着した衣装(前のエピソードのルック、なければメインのシート)がそのまま使われます。 |
| クリップとセリフ | stories:write | update_clip · update_clips · set_all_clips · reorder_clips · add_clip · delete_clip · list_removed_clips · restore_clip · delete_storyline · list_archived_storylines · restore_storyline · duplicate_clip · reorder_clip · set_clip_duration · select_clip_version · select_clip_image_version · select_clip_sketch · restore_take_setup · add_dialogue_line · update_dialogue_line · cast_voice_only_speakers · remove_dialogue_line · hide_dialogue_line · add_audio_fx · update_audio_fx · remove_audio_fx · update_story · update_caption_settingsクリップに収まりきらないセリフは、クリップの長さを自動的に延ばします。テキストの編集が生成済みのメディアを変えることはありません。update_clips は複数のクリップをそれぞれ別の値でまとめて編集します。set_all_clips はひとつの値を全クリップに適用し、テキストは受け付けません(同じ説明を全編に書くと物語が平板になるためです)。どちらも一件でも不正があればバッチ全体を拒否します。 reorder_clips は並び順をまとめて一度に設定します。 |
| Yoh アシスタント | stories:write stories:generate | ask_assistant · apply_assistant · undo_assistant脚本ページの「yohに聞く」やエディターの AI エージェントと同じ、Yoh 自身のアシスタントに依頼を渡します。ask_assistant は提案だけを返します。編集は変更案として、有料の手順は見積もりとして戻ります。apply_assistant は残すと決めた変更を実行します。有料の変更には、ユーザーが同意した後にその見積もりの confirmToken も必要です。undo_assistant は適用済みの実行で変わった内容を元に戻します。 ask_assistant は 1 回ごとに数クレジットかかります。実際の AI 費用で、1 回あたりの見積もりが上限です。上限はストーリーの長さで決まり、長いストーリーほど高くなります。 |
| タイムライン | stories:write | edit_timeline · add_timeline_version · resize_clip · trim_clip · reset_clip_timing · close_gaps · set_clip_framing · set_clip_canvas_layout · move_caption · hide_clip_video · pin_dialogue_read · export_clip_to_freeform · export_caption_to_freeform · remove_soundtrackClipモードは元の構造と配置を表示し、Editモードは独立した変更を保存します。音声や音楽などのレイヤー種別は共通ですが、配置やレンダリング結果は異なる場合があります。get_edit_timelineの後にedit_timelineを使います。編集にエクスポートやWorkflowは不要です。レンダリング時はClipかEditを選び、render_storyにtimelineModeを明示してください。 クリップモードで追加したレイヤーは自由に置け(クリップと一緒に動きません)、両方のモードに表示され、「クリップモードにリセット」しても残ります。A saved video version added with add_timeline_version is one video item of (clip, version) playing that take's video and own sound; get_edit_timeline names it in pieceVersion, and its captions, voice and background are added as their own items. Clips sit in story order in Clip mode (move_clip is refused with position_in_edit_mode; move the video item in Edit). Caption and audio exports hide their source in Edit only; exporting the same caption, read or track again is refused with already_exported. restore_clip_audio undoes an audio export and removes the one free copy that export made (a read named by lineId or lineIndex). Deleting an exported copy in Edit (edit_timeline delete, delete_overlay or delete_freeform_row) releases its hide, so the clip's own item plays again. A clip video changed in Edit that plays another video than the clip's current one is stale (video_changed): refresh moves it to the current video, keep keeps it.Reset to clip mode: edit_timeline { op: "reset_to_clip" } (alone in its batch, with the current revision) puts the branch's Edit timeline back to exactly what Clip shows: edited clip items come back and added items (text, stickers, saved-version copies, added media) are removed; other branches stay. { op: "reset_to_clip", itemIds: ["overlay:<id>"] } does it for single edited clip items (all their pieces go; an added item answers not_resettable). get_edit_timeline clipDifference { changedItems, addedItems, addedByType, matchesClip } gives the numbers. It discards the user's Edit work: tell them the numbers and ask first. The Video editor offers the same as Reset on the Edit toolbar and Reset to clip on an edited item's menu, with Undo.Clip or Edit (owner 11-11): Clip mode holds the clip's source (its lines, timing, voice and background). In Edit a clip's video, captions, on-screen text, reads and background are separate items, each moved, trimmed, split, sped, restyled, leveled, deleted or reworded on its own with edit_timeline; at the end of a generation Edit is identical to Clip, items not changed in Edit follow Clip, and an item changed in Edit keeps its own and reads stale when its source changes. A clip video's Mute / volume in Edit is that video's own sound only. edit_timeline mode clip answers source_edit_required naming the tool to use. set_voice_mix detached true answers use_export_tool (use export_clip_audio_to_freeform) and set_playback_speed with clipId answers speed_in_edit_mode (use edit_timeline op speed); clipId with speed 1 clears an older Clip-mode speed instead. |
| Split a clip, reopen a suggestion, speech check | stories:write | split_clip · restore_clip_suggestion · check_clip_speechFree. split_clip makes a clip with no video two clips in one call (two parts, each with its description, length and line ids), as the clip panel's Split clip. restore_clip_suggestion undoes a Keep as is. check_clip_speech starts the voice check of one clip's video (quoted: free only while the take's paid split part is unused, else quoted); read the result in get_clip lineCheck. |
| Branches, songs, history, motion versions | stories:read / stories:write | rename_storyline · list_songs · delete_assistant_history · delete_clip_motion_reference_versionFree. Rename a branch; list the songs already listened to (reused free by songId); delete your own assistant runs on a story; delete a saved motion reference version that is not in use. |
| Render anyway, ready for owner, series visibility | stories:write / publish:write | render_anyway · mark_ready_for_owner · set_series_visibilityFree. render_anyway reads the render check and records the owner's choice to render clips that still show media made before a character was hired. mark_ready_for_owner is a series editor handing a saved cut to the owner. set_series_visibility sets private, unlisted or public and the custom link, as the Publish panel does. |
| Video job writing and posting services | hires:write | start_job_writing · save_posting_servicestart_job_writing answers where a video job's script is written and sets an older job's empty episode up from the brief once. save_posting_service adds, changes or pauses a posting service in the shared Selling library; its price is real money a hirer pays. |
| Ads tab actions and workspace clients | ads:read / ads:write | sync_series_ads · link_series_ad_videos · disconnect_series_ads · list_ads_clients · save_ads_client · archive_ads_clientNo Yoh credits. Sync now (at most once an hour), link or unlink ads Yoh could not match to an episode, disconnect a series from Meta (two steps with confirmToken; the ads keep running on Meta), and the Agency plan's clients. |
| Yoh Brain team: templates and series | stories:write / series:write | use_team_template · move_series_teamFree. The team's full copy of a team template, and moving a series into or out of the team. |
| Kept for older callers | stories:write | move_clipAlways refused with position_in_edit_mode: Clip mode keeps clips in story order (change it with reorder_clips or reorder_clip); to place a clip at a time, move its piece in Edit with edit_timeline op move. |
| オーバーレイ | stories:write | add_overlay · update_overlay · move_overlay · resize_overlay · split_overlay · duplicate_overlay · delete_overlay · delete_freeform_row数値 ID で扱うこれらのオーバーレイツールは従来のルールのままです。同じ行に 2 つのオーバーレイは置けず(衝突は拒否され、空いている行が示されます)、時間は 0.1 秒単位にそろえられます。重ねたい場合やフレーム単位で正確に編集したい場合は get_edit_timeline + edit_timeline を使ってください。メディアには Yoh のストレージ上の https ソースが必要です。先にアップロードしてください(他サイトのリンクは拒否されます)。 |
| オーバーレイ | assets:write | upload_media数値 ID で扱うこれらのオーバーレイツールは従来のルールのままです。同じ行に 2 つのオーバーレイは置けず(衝突は拒否され、空いている行が示されます)、時間は 0.1 秒単位にそろえられます。重ねたい場合やフレーム単位で正確に編集したい場合は get_edit_timeline + edit_timeline を使ってください。メディアには Yoh のストレージ上の https ソースが必要です。先にアップロードしてください(他サイトのリンクは拒否されます)。 |
| スタイル | stories:write | apply_overlay_preset · set_caption_styleエディター自身のテキストプリセット、字幕テンプレート、約32種の登場・退場アニメーション——エージェントが CSS を自作せず、製品が備えるスタイルを適用するためのものです。字幕のスタイルはセリフ1行ごとに設定されます。 |
| キャラクターとセット | stories:write | add_character · update_character · delete_character · add_scene · update_scene · delete_scene · add_item · update_item · delete_item · keep_character_sheetキャラクターを削除すると、すべてのクリップから外れます。そのセリフは話者なしのまま残り、誰が話すかを選ぶまで(update_dialogue_line)そのままです。ライセンスされた顔を持つ役や、契約待ちの役は削除できません。 |
| 音声のキャスティング | stories:write | set_character_voiceストーリーの言語で絞り込まれたストック音声と、アカウントで利用可能なクローン音声です。キャスティングは無料で、すでに収録済みのセリフは生成時の音声を保ちます。 中国語(zh-TW)のストーリーでは、各ストック音声を台湾華語の声優が読み上げます。 |
| 再収録 | stories:write | set_revoice_enabled · select_revoice_take · undo_revoice · fix_audio_sync · apply_lip_sync新しい読みと元の音声の切り替えは無料で、いつでも戻せます。「元に戻す」はこの動画の読みを一つ前に戻し、その読みは保持されます。「新しい読みをすべて削除」は読みを破棄し、作り直すには再びクレジットがかかります。Each new read follows the clip's scene (place, light, beat, sound bed, mood): a roaring stadium raises the voice, a quiet room keeps it close; the words never change, and an audition plays exactly the read the paid take sends.undo_revoice steps back ONE read of the clip's current video (lineId or lineIndex; omitted, the latest read): the line goes back to its earlier read, or from its only read to the video's own voice, and the read it leaves is kept (select_revoice_take redoes it, free); answers { clipId, stepped, index, lineId, fromTakeId, toTakeId, refusal?, note }. all: true is the clip panel's "Delete all new reads" (in its sound Details): every read of the current video is discarded (other videos' reads stay), not free to redo; answers { clipId, removed, restored, revision, note }. The app's session route does the same: DELETE /api/stories/:storyId/clips/:clipId/revoice steps back one read (?lineId= or ?index= for one line), ?all=1 deletes every read of the current video. get_revoice marks a read made in a voice its speaker no longer has stale: true, staleReason: "recast" (it plays in the old voice until that line is re-voiced) and names each read's voice actor (voice, in the line's language); a re-voice quote's voiceSwaps messages name the voice actors by display name, never a voice id.Take 1 from the video: on a split take every spoken character line has a take cut from the split's speech track where the video says it (matched by the split's own words, else by the lines' order and the diarized voice). get_revoice lists it first in a line's takes with source: "video" and in videoTakes (clip seconds, where the Voice lane plays it); reading it stores nothing, and it is free and never billed. select_revoice_take with takeId: "video" puts a re-voiced line back on it (the read stays a take), and undo_revoice of a line's first read steps back to it.Dialogue and Cut & sound (owner 11-07): A line's Emotion is eight chips (neutral, happy, sad, angry, afraid, tender, surprised, sarcastic) plus More (the other seven), Strength Low / Mid / High (intensity 1 / 2 / 3; Mid stores nothing) and a short "how they say it" note; pace, sounds and intention sit under More direction. The stored delivery values are unchanged. A note of 6 words or fewer (48 characters; 12 in Chinese, Japanese, Korean or Thai) also reaches the video model with the line; a longer one guides the voice only. A line that has a delivery no longer falls back to its old free-text emotion in the video prompt. update_dialogue_line delivery is checked strictly: an unknown key is refused with the field named, and every older valid payload still works. get_clip and the v1 clip GET give each dialogue line directionChanged (its playing take was made with other words, another voice or another direction), playingTake (1 = from the video) and changedReason ("words", "voice" or "direction"); a line with no take (hidden, or a narrator line not read yet) has none of them, and writes ignore them. Re-voice the changed lines with one ★ revoice_clip quote: the app's "Revoice this line · price" (Dialogue, shown only after a change on a line that already has a voice) and "Revoice N changed lines · price" (Cut & sound's footer) show that quote's total (reads, plus the split and the lip sync when they run), the same total the confirm charges. A Qwen voice reads the words only (no emotion, no pace); on ElevenLabs v3/v4, High on a pitch-raising emotion (sad, crying, excited, afraid, surprised, angry) plays at Mid. In the app, Cut & sound edits each item in place (owner 11-07 refine), free and one Undo per change, through the tools' own functions: a tap selects an item and its bar opens Dialogue on that line or the clip's edit view (Back returns); a caption drags to move and its edges change its length (move_caption: inside its clip, never across a sibling caption); a read, or a voice piece whose line plays a read, drags to move (pin_dialogue_read); the Voice and Background rows drag to move and their edges set where they are heard (clip_source_audio offset and range); ✂ on the Video's edges trims any take, generated ones too (trim_clip, source seconds: the clip's length follows and later clips ripple; uploads no longer make a new version for it). Drags snap to the other items' edges and the playhead; on a phone the bar nudges ±0.1 s. Level, mute and Original | Analyzed sit on each row's header; Lip sync and Sounds moved from Dialogue to Cut & sound.apply_lip_sync puts a finished lip_sync_clip (its libraryRunId) on the clip as a new silent version named "Lip sync", selected, with the re-voiced reads still playing over it; earlier takes stay. Free. |
| 生成 ★ | stories:generate | regenerate_clip · regenerate_clip_image · edit_clip_image · enhance_clip_image · generate_clip_video · remake_like_take · edit_clip_video · swap_asset · revoice_clip · lip_sync_clip · regenerate_character_sheet · regenerate_asset_image · generate_look_image · generate_all_asset_images · generate_soundtrack · generate_storyboard · generate_all_videos · generate_all_clips · generate_clip_grid_reference · continue_story_from_clip · run_story_version_step · render_story各組は「編集」対「描き直し」です。edit_clip_image は指示に従って現在のフレームを書き換え、regenerate_clip_image は新たに描き起こします。edit_clip_video は動画から動画への変換で被写体・構図・動きを保ち、generate_clip_video はクリップの参照(キャストシート、背景、小道具、画像があればその画像)から作り直します。enhance_clip_image はキャストシートを基に顔を似せ直します。regenerate_clip は画像→動画をひとつのジョブとして実行し、クリップの説明やキャストを変更した後に適した選択肢です。generate_clip_grid_reference は、固定の一般的な場面ではなくクリップ自身のタイムビートから起こしたコマで連続性シートを描きます。 |
| Stop | stories:write | cancel_generationThe app's Stop for a jobId or a batch runId: nothing further starts, work in flight finishes and is kept, the rest is refunded. Free. |
| Hired character looks | assets:read stories:write | list_hire_looks · choose_hire_looksThe creator's looks a hired character brings (main sheet, earlier style sheets, the creator's looks) and which are in the episode; choose_hire_looks adds or removes them, the same as the hire page. Names only until the hire is paid. Free. |
| Plan scripts and create episodes | stories:write | plan_series · create_series_from_plan · split_series_arc · cancel_bulk_jobPlan a script or PDF, poll get_series_plan, review the plan, then store draft episodes. bulk_create_episodes writes NEW episodes and cast art; it does not make videos. Poll get_bulk_job; cancel_bulk_job stops after the current episode. |
| Plan scripts and create episodes | stories:read | get_series_plan · get_bulk_jobPlan a script or PDF, poll get_series_plan, review the plan, then store draft episodes. bulk_create_episodes writes NEW episodes and cast art; it does not make videos. Poll get_bulk_job; cancel_bulk_job stops after the current episode. |
| Plan scripts and create episodes ★ | stories:generate | bulk_create_episodesPlan a script or PDF, poll get_series_plan, review the plan, then store draft episodes. bulk_create_episodes writes NEW episodes and cast art; it does not make videos. Poll get_bulk_job; cancel_bulk_job stops after the current episode. |
| Find and install templates | stories:read | list_templates · preview_template · get_uploaded_assetsA claimed template brings its script and shot plan, never pictures, video or voices: a copy with its descriptions, prompts, motion, dialogue and camera, characters by name with no pictures, hired people as empty roles, free and instant, and it is listed only once its creator has confirmed the rights statement. A template with no statement is not listed or sold at all until its creator confirms they own the rights (one tap on the Access ask lists it again at once); while it isn't selling it can't be bought (watching is never sold), and buyers whose purchase carried the template before keep it. A statement under an earlier wording counts until the date in the creator's one template.reconfirm notification; after it the template is not listed until they confirm again, and buyers who paid keep theirs. Preview a template before claiming it. Review detected upload assets before accepting them into the cast. get_uploaded_assets answers next and, for a failed scan, retryable: one with retryable: false (its source, series or clips changed, its answer can't be read, or its video has too many references or a section too large to analyse) is never retried. |
| Make it yours ★ | stories:generate / stories:write | adapt_template_copy · restore_template_original · propose_template_remixThe template copy's setup page over MCP: Remix with one of my stories (propose_template_remix, free: your stories, then a proposed cast and idea from one; adapt_template_copy with sourceSeriesId + roleMap casts and rewrites for the same fixed price, one charge, the picked story untouched). Adapt to my idea quotes one fixed, exact price (a base plus a per-clip charge; the charge equals the quote), then with confirmToken writes the new words straight into the clips (timing, speakers and storylines stay; the shot camera is kept; per-beat shots are redone if the motion changes). restore_template_original (free) gives those clips, or all adapted ones, the words they had just before the Adapt: only what Adapt wrote, only while unchanged since (a beat edited since is kept and listed in skipped), lines by line id, never the title. v1: GET|POST /api/v1/stories/:id/template-adapt (quoteOnly, then X-Max-Generation-Credits; a retry with the same Idempotency-Key is charged once) and POST …/template-adapt/restore. |
| Find and install templates | stories:write | claim_template · fill_template_role · start_uploaded_assets · review_uploaded_assetfill_template_role marks a clip of the filled role that already has a picture or video out of date (Keep as is / Remake); nothing is redrawn. Only templates are sold: a template has its own price (whole-story purchases made before 2026-11-08 keep theirs); a subscription is watch only, so claim_template answers TEMPLATE_NOT_BOUGHT with priceCents and unlockUrl (the user buys in the app). A free-to-watch episode's template is free or has its own price. Buyers keep it after the creator turns it off, and templates are never refunded. In the app every template has one button, "Use this template": the same claim (a second press opens the existing copy, never a second one), landing on the copy's "Make it yours" setup page (look, characters, Adapt to my idea; skippable, reopened from the Script page's mode menu). Old /generate?templateSource= and templateSession= links redirect to the claim, then the copy. fill_template_role (free) puts a character of the copy into an empty role: on every clip, the role label in the copied text becomes its name, and no second character is left. Preview a template before claiming it. An uploaded video can be a template once it's cut into clips; until then it answers TEMPLATE_UNAVAILABLE with reason uploaded. Review detected upload assets before accepting them into the cast. get_uploaded_assets answers next and, for a failed scan, retryable: one with retryable: false (its source, series or clips changed, its answer can't be read, or its video has too many references or a section too large to analyse) is never retried. |
| Manage a series and its team | series:write | reorder_episodes · archive_series · set_auto_generate · invite_collaborator · update_collaborator_role · remove_collaborator · set_series_coverRead the saved schedule and collaborators first. Enabling set_auto_generate also needs stories:generate and consent:true: future episodes spend owner credits without another approval. Disable with enabled:false. |
| Manage a series and its team | stories:write | archive_storyRead the saved schedule and collaborators first. Enabling set_auto_generate also needs stories:generate and consent:true: future episodes spend owner credits without another approval. Disable with enabled:false. |
| Manage a series and its team | series:read | get_auto_generate · list_collaboratorsRead the saved schedule and collaborators first. Enabling set_auto_generate also needs stories:generate and consent:true: future episodes spend owner credits without another approval. Disable with enabled:false. |
| Motion references and clip audio | stories:write | upload_clip_video · set_clip_motion_reference · remove_clip_motion_reference · select_clip_motion_reference · set_clip_references · set_clip_motion_source · set_clip_frame_mode · set_clip_video · set_clip_image · clip_source_audio · separate_story_audio · set_voice_mixA Motion reference video tick is intent only: nothing is made or charged when ticked; the next Scene composition video that needs one makes it first at one flat motion_reference_make price (the same as one sketch make) inside its quote — a stock pick (set_clip_motion_source makeWith "stock") or the 3D video the app films. A stock video set with set_clip_motion_reference is quoted first (confirmToken, needs stories:generate); your own footage stays free. A new file set as a clip's take with set_clip_video is a real person's recording: its voice and background are split and what was said is listened to by themselves, paid inside the upload's price (quoted first with confirmToken, needs stories:generate; a trim or re-save of the same file is free; refunded only when the split did not run). Its range {start, end} picks 3–12 s of the video, the same bounds as the app's trimmer, checked on the server. Every motion reference a clip has had stays a version (get_clip motionReferenceVersions, newest first, the one in use chosen); select_clip_motion_reference picks one by version or versionId, free, and remove_clip_motion_reference keeps it as a version. Read get_source_audio or get_revoice before choosing tracks and volumes. set_voice_mix target video sets a take's own sound level (0-1, the Video row), free and saved on that take, for any take (generated, upload or gallery); set_voice_mix target character (speakerId, volume 0-1, no clipId; v1 GET/PUT /voice-levels) sets one character's voice level for the whole episode, free, as Cut & sound's level on that character's voice row; set_voice_mix target background with background "drop" (or "keep") silences (or brings back) a re-voiced clip's background under its reads, as the clip panel does; "keep" needs a separated background (a split clip's own is attached), and without one it is refused with reason no_separated_background, since the video's own track would play the old voice under the new reads. Mix existing audio for free; check_clip_reads is free for a clip whose current video's words were already heard (source "stored"), else quoted first; generate_clip_panorama and split_clip_audio quote credits first. split_clip_audio includes speech captions; again requests Split again. Motion control needs at least 3 s of clear movement in the footage: set_clip_motion_reference warns on a pick under 4 s, and a refused video fails as motion_reference_rejected without trying other providers. It also needs one person seen from head to waist in the clip image and the footage: the quote says so, and a video refused for that fails as motion_upper_body without trying other providers. Motion control keeps the clip image's facing and framing (the person turns as the picture shows; the camera follows the picture) when the footage is up to 10 s and the movement is simple; footage over 10 s, or a clip whose text names complex movement (spins, flips, dance, fighting), keeps the footage's own facing instead, and then the fal route also sends the clip's lead character (most lines) as a face reference. The footage's own sound is never kept. |
| Motion references and clip audio | stories:read | get_source_audioRead get_source_audio or get_revoice before choosing tracks and volumes. set_voice_mix target background with background "drop" (or "keep") silences (or brings back) a re-voiced clip's background under its reads, as the clip panel does; "keep" needs a separated background (a split clip's own is attached), and without one it is refused with reason no_separated_background, since the video's own track would play the old voice under the new reads. Mix existing audio for free; check_clip_reads is free for a clip whose current video's words were already heard (source "stored"), else quoted first; generate_clip_panorama and split_clip_audio quote credits first. split_clip_audio includes speech captions; again requests Split again. |
| Staging | stories:read stories:write | get_staging · set_staging · stage_sceneThe camera and who stands where, free. get_staging answers the clip's resolved framing (size, elevation, lens, move, shot relationship, light — the key-light direction, onlyThese, inFrame.unnamed (an unnamed opponent or attacker the clip's words put with a lone person, or a counted group such as "seven anonymous competitors", read from the clip's present action in English only (never the description, nobody past, remembered, absent or on a screen), said with them and in the headcount, never "no other people"), relationship.pairIds (the pair a typed two-shot of three or more frames, the two its words name most; the in-frame line then says the headcount), foregroundId, povOfId, each person's side, depth, azimuth, contact and extra, each with its source: typed, writer or default), the staging rule warnings with fixes, the suggestion and the scene's clips. set_staging changes only the fields sent, as the user's own; restore puts a staging back (undo). stage_scene is Let AI stage it for a clip or its scene (rule-based, free; answers undo). Every change rewrites the image prompt's Shot / Subjects lines when the prompt is Yoh's own (framingRewrite on the clip says so); an image prompt the user typed is never rewritten: the new lines wait as framingProposal, answered with a clip PATCH framingProposal apply or keep. The shot treatment is the prompt library ids beside the camera: lightId (light.*, the library light; never light, the key-light direction), atmosphere (atmo.*), look, staging (stage.*), time (time.*, the speed) with timeAt, composition (comp.*) intent (what the image is for, up to 100 characters) and energy (calm, tense, intense or explosive; null = Auto, from the series genre and the beats and answered as energyAuto; an intense or explosive clip plays in real time with timed beats, ends on the action unless its last beat leaves people at rest, and gets a handheld that follows the blows in place of a derived locked camera; calm clips are as before; what a person typed wins. A start-frame prompt leaves light and style to the picture only when Yoh drew the clip image from its image prompt as it is now: no Light line, unless the light moves, and a Style line with only the era and a character drawn in another medium; an uploaded, stale or previous-take picture keeps both; one Location line with the time of day. energyAuto is read with the series genre, so it is the energy the prompt renders; a strong line in an intense or explosive clip is said at full voice; sceneType, read only, is the kind of scene the writer tagged that plays under the clip's energy (chase, sport, dance, stunt, comedy_gag, scare, suspense, reveal, montage, celebration, product_hero, demo, drama_hit, entrance, argument, cliffhanger, flashback, hero_moment, transformation, fight or a talk type; null = none): it sets Auto's energy, the clip's camera (chase, sport, dance and stunt over the writer's staged move too; other types replace only a locked, breathing or derived camera, never a rack focus or another staged move; a person's typed camera or one read from their footage always wins; a type with no camera of its own, such as comedy_gag or drama_hit, keeps the writer's camera, never the fight's impact handheld or the running handheld), the ending, the speed line (only hero_moment may slow down) and one feel line, one short sound added after the clip's own cues in its Sound line on a model that makes sound (no type's sound names music or a voice; talk types, fight and a redraw that follows its source video add none), and whether the writer's shots may cut; no type renders as before; a person's typed energy wins over the type (its ending, speed, delivery, timed beats and camera stop applying, and a typed calm on an action type turns the type off and sceneType reads null; a cutting type cuts only at intense or explosive under a typed energy; a montage plays its feel line and whoosh only where cuts may play); a person's own edit of the description or motion drops the type, Yoh's edits (the shot writer, Check clips and length fixes, cut writes, accepted proposals, clearing the motion) keep it). get_staging and get_clip answer treatment (with names — each id's name as the app's Staging chips show it, e.g. Warm lamps — and the fields the user set); set_staging treatment, update_clip / update_clips treatment and v1 PATCH clip treatment set them (null clears one; written as the user's own, so a new motion keeps them; a wrong id is refused with the allowed ids). A take made before a treatment change lists it in activeTake.changedSinceTake as step camera. An uploaded clip's reading fills lightId and atmosphere from what the footage clearly shows; the user's own value stays. A light or atmosphere id reaches the prompts only when it fits the place, sharing one Light line with the place's light; a lightId you set is always said, and replaces the place's light words where the place's time would not take it; a place an episode uses by day and at night gets a row per time, with the writer's light and sound bed for each; look, composition and speed reach the video prompt; a grid cell is drawn from the same text as that clip's opening picture; the clip's audioFx are said, timed, for models that make sound; editing motionDescription or dialogue drops the writer's draft beats that no longer match. The camera's library ids are framing.libraryIds; set_staging framing.moveId sets the exact library move (move.whip_pan, move.dolly_zoom …). Non-human and giant characters (11-02): a robot, a monster or a creature that acts is a character, never an item; its pilots are separate characters. A giant is a typed fact only: characterType mech (also mecha, giant_robot, giant robot, 機甲, 巨大ロボット, 거대 로봇) or kaiju (also giant_creature, giant creature, giant monster, 怪獸, 怪獣, 괴수); the description never makes one (60 m tall, giant, colossal, a yacht or a storey count on a typed adult leave it a person), and a typed giant's own height phrase (60 m tall, 60m, 全高18m, 身長60メートル, 高達60米) only fills "about N m" in its Scale line. Everything giant-specific is gated on a typed giant in the clip's cast, on every path (story writing, continuation, Time beats, Write the shot, write_time_beats, write_shot_from_description, Check clips, camera coverage, the director, the duration budgets): its height class in every still, video and sheet prompt (a size cue from a medium shot out; a close-up says the class alone), action pacing and giant strike words for its clips, the writers' GIANT FIGHTERS rule, no low_wide staging note, and a sheet likeness check by design instead of a face (a person-sized robot and an ordinary animal keep the face check). A cockpit clip whose cast has no giant gets none of it; a story with no typed giant composes byte for byte as before, and a brief's words never change the genre: set the series genre. |
| Check clips ★ | stories:generate | check_clipsFree rules without ai; ai:true adds the AI review of the clips and the story, and the after-take check of finished clip videos (who is on screen, who is talking), quoted first (confirmToken). Show the findings, then apply the ones the user keeps. |
| Check clips | stories:write | apply_clip_check_fixesFree. Applies the picked fixes through the editor's own edits; a new look's picture is a priced next step. |
| Music video songs ★ | stories:generate | analyze_songListens to a song put on hosted storage with upload_file (mp3, wav, m4a or ogg, 8 s to 10 min): beats and strong beats, parts, mood, genre and lyrics timed word by word. About 12 credits a minute; quote first, then confirmToken. A failed listen is refunded in full; a finished one settles to real usage. songId reuses an earlier song free; storyId attaches the song to a story. |
| Music video songs | stories:read | get_song_analysisThe listen's state and analysis, a plain summary line, the suggested part (the chorus or hook, about 30–60 s) and, for any part, the shots it is cut into (4–15 s on strong beats, each performance or story). |
| Music video shots | stories:write | set_song_shotFree. Switches one music-video shot between singing (the singer sings its line on camera) and story; a shot with no sung words stays story. get_story shows the song plan as musicVideo and each clip's songShot (time in the song, part, lyric, energy, strong beats). Shot lengths follow the song. |
| Music video lyric captions | stories:write | set_lyric_captionFree. Edits one lyric caption of a shot (songShot.lyricCaptions: index, text, start, end, hidden; seconds from the shot's start): text (null = the sung words), hidden, or start/end inside the shot. v1: POST /api/v1/stories/:storyId/clips/:clipId/lyric-caption (and POST /api/v1/stories/:storyId/clips/:clipId/song-shot { kind } for set_song_shot). Sung shots are made on Seedance 2.0 / 2.5 with the shot's part of the song as a reference video (priced as input video); a switch marks the shot's picture and video out of date; on the timeline the clips are muted and the song plays on Music. |
| Motion references and clip audio ★ | stories:generate | check_clip_reads · generate_clip_panorama · split_clip_audio · set_clip_motion_reference · set_clip_video · clip_source_audio · separate_story_audio · check_clip_speech · fix_audio_syncRead get_source_audio or get_revoice before choosing tracks and volumes. set_voice_mix target background with background "drop" (or "keep") silences (or brings back) a re-voiced clip's background under its reads, as the clip panel does; "keep" needs a separated background (a split clip's own is attached), and without one it is refused with reason no_separated_background, since the video's own track would play the old voice under the new reads. Mix existing audio for free; check_clip_reads is free for a clip whose current video's words were already heard (source "stored"), else quoted first; generate_clip_panorama and split_clip_audio quote credits first. split_clip_audio includes speech captions; again requests Split again. set_clip_video with a new uploaded file quotes its sound step (split + listen) first, priced from the stored file's measured length (unmeasurable: as 10 minutes; over 10 minutes: not split or charged), and needs stories:generate for that part. |
| Asset pictures and looks | assets:read | get_asset_imagesEvery picture of the story's characters, places and items, to look at before choosing or editing one. |
| Asset pictures and looks | stories:read | list_asset_image_versions · get_asset_image_job · list_looksList versions and looks before choosing one. Edit an existing picture or draw a new one; both quote credits first. Poll get_asset_image_job for returned jobs. |
| Asset pictures and looks | stories:write | use_asset_image_version · add_look · update_look · delete_look · set_clip_look · import_lookList versions and looks before choosing one. Edit an existing picture or draw a new one; both quote credits first. Poll get_asset_image_job for returned jobs. A look needs its picture: add_look with only words refuses look_needs_picture, whose details.options are three choices to ask the user about — upload their own picture, draw it with AI (quoted first) or pick a stock photo (search_stock_media, then add_look with imageSource "stock"). A clip made with add_clip wears the looks picked with set_clip_look for the clip before it (the clip after, when it goes first). A look is worn from a clip's first frame: a change the clip itself shows happening (a drink thrown in a face) belongs on the clip after it, where Yoh's detected looks start; set_clip_look on the clip where it happens puts it on from frame 1. |
| Asset pictures and looks ★ | stories:generate | edit_asset_image · draw_asset_image · generate_missing_series_pictures · polish_asset_description · suggest_looksList versions and looks before choosing one. Edit an existing picture or draw a new one; both quote credits first. Without generationStyle a picture is drawn in the story's style (a library asset: its series look); generationStyle is that one picture only and never changes the story's style. A character's sheet (sheet: true) with sheetStyle: for an episode character, a style id from list_style_presets, and the sheet is redrawn in that style (the quote's Style line says so); for a library character, style words. Poll get_asset_image_job for returned jobs. Pictures and suggested looks of a hired character follow the limits its owner set. |
| Custom voices | stories:write | create_custom_voice · delete_custom_voiceCreate or remove a custom voice using authorized reference audio; this does not regenerate existing dialogue. create_custom_voice answers a quote first (credits 0 today, the same number as the app's “Create voice · free” button; quote = charge) and clones only when called again with its confirmToken. characterId names the clone after that character and its voice description. A custom voice is its owner's in every series: list_voices lists the account's own voices from any of its series (one made for another series carries madeFor) and set_character_voice casts it for a character or the narrator without cloning it again. Anyone who can view a series hears every custom voice its episodes already use, whoever owns it (its name and sample in list_voices narrator.series and get_story narrator), and an episode the voice's owner owns may take as its narrator a voice another episode of the same series narrates with; only the voice's owner deletes it or casts it anywhere new. Only episodes you can read count. A copy into another series keeps stock voices and your own cloned voices; someone else's goes back to Auto (a request draft too, when it is published into a series other than its own; a buyer's paid delivery keeps every voice). Only the owner reads why their voice failed. |
| Reuse library assets | assets:write | promote_asset_to_series · use_series_picture · copy_series_assetsRead episode assets, promote them to the series library, or copy library or episode-only assets to another series (hired or licensed ones are skipped; characters of a commission, hire or clip-hire workspace episode stay in it, and so do a claimed template's own characters). An episode asset added with seriesDuplicate "link" starts as the library asset's copy (picture, sheet, voice and text); a description sent with it stays in the episode. Episodes are copies: a new library picture or sheet reaches an episode only through use_series_picture (the editor's "Use library image here", free; it takes the library's sheet in the episode's style when there is one, else answers styleNote; the voice never changes; previousVersionId undoes it, null when History holds no copy of the old picture; changed is the picture alone, textFilled when only empty text was filled); get_story marks each linked row libraryPicture same, differs or not_usable (a row the tool refuses). |
| Reuse library assets | series:read | list_episode_assetsRead episode assets, promote them to the series library, or copy library assets to another series. |
| Editor playback | stories:write | set_soundtrack · set_soundtrack_playback · set_on_screen_text_look · set_playback_speed · export_clip_audio_to_freeform · restore_clip_audioUse an existing file or another story's track as the music (free), set music playback, text appearance, speed and detached audio. |
| Publishing | publish:write | get_publish_options · publish_story · unpublish_storyInspect get_publish_options, review the video and audience, then publish. |
| Social posting | social:publish | list_social_accounts · social_publish · get_social_postNeeds account and caption approval; poll get_social_post for the result. |
| Generate an overlay asset ★ | stories:generate | generate_layer_assetQuote generate_layer_asset first; inspect its result with get_layer_asset before using the asset on the timeline. A video layer can name clipId, the clip it sits over: the prompt goes first, framed by the story's medium, world and that clip's place and light. |
| Generate an overlay asset | stories:read | get_layer_assetQuote generate_layer_asset first; inspect its result with get_layer_asset before using the asset on the timeline. |
| Creator hiring, jobs and messages | hires:read | search_hire_listings · quote_hire · search_video_job_creators · list_hires · get_hire · get_video_job · list_casting_calls · list_call_applicants · list_application_characters · list_my_applications · list_clip_calls · get_clip_call · get_my_hire_offers · get_clip_service · list_threads · read_threadExternal money and commitments: review quote_hire before send_hire_request. pay_hire returns Stripe checkout for the user to pay. A video job (hire_creator_clips, post_clip_call) is always the whole episode; clipIds from older calls is ignored. open_clip_workspace and send_clip_take are legacy. Review deliveries before accepting payouts. A first character listing needs explicit rights and any real-person likeness authorization. send_hire_message takes an optional about { kind, itemId? } (a post, delivery, licence or script of that hire), returned on each get_hire message. |
| Creator hiring, jobs and messages | hires:write | send_hire_request · hire_creator_clips · pay_hire · attach_hired_character · respond_hire · deliver_clip · open_clip_workspace · send_clip_take · review_delivery · use_job_version · hire_post_action · cancel_hire_work · withdraw_listing_consent · send_hire_message · submit_outline · review_outline · send_job_script · send_job_video · ask_job_budget · add_job_budget · create_casting_call · update_casting_call · close_casting_call · apply_to_casting_call · update_application · post_clip_call · offer_on_clip_call · withdraw_clip_offer · pick_clip_offer · close_clip_call · set_hire_offer · set_character_listing · set_clip_service · mark_thread_read · mark_hire_read · check_hire_payment · dismiss_casting_call · start_thread · send_messageExternal money and commitments: review quote_hire before send_hire_request. pay_hire returns Stripe checkout for the user to pay. A video job (hire_creator_clips, post_clip_call) is always the whole episode; clipIds from older calls is ignored. open_clip_workspace and send_clip_take are legacy. Review deliveries before accepting payouts. A first character listing needs explicit rights and any real-person likeness authorization. send_hire_message takes an optional about { kind, itemId? } (a post, delivery, licence or script of that hire), returned on each get_hire message. |
| Yoh Ads shows and campaigns | ads:read | list_brand_shows · get_brand_show · get_show_episode · get_show_results · get_show_activity · get_show_plan · get_series_ads · list_series_ad_pages · list_meta_ad_accountsCreate and review a show, then accept it. Paid writing, video and autopilot also need ads:write. get_show_plan previews autopilot; inspect posting and Meta budgets as well as credits. A zero-credit confirmation can still authorize external ad spending. |
| Yoh Ads shows and campaigns | ads:write | create_brand_show · reread_brand_show · accept_brand_show · update_brand_show · update_show_action · create_show_episode_version · set_series_ad_status · set_up_series_ads · add_episode_to_adsCreate and review a show, then accept it. Paid writing, video and autopilot also need ads:write. get_show_plan previews autopilot; inspect posting and Meta budgets as well as credits. A zero-credit confirmation can still authorize external ad spending. |
| Yoh Ads shows and campaigns ★ | stories:generate | write_show_episode · make_show_episode · run_show_autopilotCreate and review a show, then accept it. Paid writing, video and autopilot also need ads:write. get_show_plan previews autopilot; inspect posting and Meta budgets as well as credits. A zero-credit confirmation can still authorize external ad spending. |
| Yoh Brain team | stories:read / stories:write | list_rising_topics · list_team_members · set_topic_status · invite_team_member · remove_team_memberAn Enterprise team's /brain over MCP. Everyone on the team reads its rising topics and its people, viewers too. Team owners, admins and editors dismiss, use or restore a topic. The team owner manages everyone; a team admin adds, changes and removes editors and viewers (admin seats are the owner's alone). Without a team whose owner has a current Enterprise plan, every call answers enterprise_required. |
| Yoh Brain team ★ | stories:generate | look_again_topicsLook again for rising topics now, charged to the team owner's credits. The first call saves the exact price and answers it with a confirmToken (nothing charged); call again with its quoteId and confirmToken after the user agrees. Owners, admins and editors only; a viewer is refused. A newer, expired or someone else's price answers quote_changed. |
| Script helpers, account and activity | stories:read | get_script_marks · list_assistant_history · get_credit_history · get_story_spend · list_notifications · list_api_keys · get_profile · list_episode_commentsRead script marks before targeted text edits. Inspect earnings, credit history, notifications and profile. API key listings do not reveal secrets; revoking the current key disconnects the client. |
| Script helpers, account and activity | stories:write | keep_clip_as_is · write_still_prompt · write_time_beats · write_shot_from_description · suggest_clip_duration · mark_notifications_read · revoke_api_key · update_profile · remove_episode_commentRead script marks before targeted text edits. Inspect earnings, credit history, notifications and profile. API key listings do not reveal secrets; revoking the current key disconnects the client. |
| Script helpers, account and activity | assets:read | search_stock_mediaRead script marks before targeted text edits. Inspect earnings, credit history, notifications and profile. API key listings do not reveal secrets; revoking the current key disconnects the client. |
| Script helpers, account and activity | hires:read | get_earnings · set_payout_methodEarnings and how hires pay you (cash or credits) are hire money: they need the consent-only hires scopes, like the hiring tools. set_payout_method reads the method on hires:read; switching it needs hires:write and is confirm-gated (switching to credits pays money you are owed now as credits, final). |
消費は二重に保護されています ★ のツールは、課金前にクレジットの見積もりと署名付き confirmToken を返します。見積もりを提示し、明示的な同意を得てから実行してください。これらのツールには stories:generate が必要です。ただし、他のツールが無料とは限りません。ask_assistant はテキストのやり取りに即時課金し、stories:generate が必要です(stories:write のみのキーでは実行できません)。定期生成、クリエイターへの支払い、Meta 広告には、それぞれ別の同意と費用のルールがあります。
安全性と正確性の保ち方
- サーバーはエディターのルール(スライド移動、トリム境界、字幕レーン、オーバーレイ行)を強制し、違反時には黙って値を丸めるのではなく許容範囲を返します。
- エージェントは yoh://guide/timeline リソースから完全なルールを読み取り、/mcp__yoh__edit-story プロンプトが安全な手順を与えます。
- 生成は非同期です。ほとんどのツールは runId を返し、エージェントは get_run でポーリングします。一部(create_story、render_story、キャストアート)は get_job 用の jobId を返します。REST API と同じです。
- .mcp.json で長めの timeout(例:900000)を設定し、レンダリングがクライアント側でタイムアウトしないようにしてください。
接続を検証する
エージェントに get_credits ツールを呼び出すよう頼んでください。無料で、何も変更しません。クレジット残高が返ってくれば、サーバーとキーは正常に動作しています。エラーの場合は直すべき点が示されます(401:キーが間違っているか、無効化されています)。
yoh の get_credits ツールを呼び出して、私のクレジット残高を教えてください。API キー管理
API キー管理エンドポイントは API キーではなく session authentication(ログイン済みユーザーの Cookie)を使用します。ブラウザベースのワークフローには API Keys page を使用するか、有効なセッションでバックエンドからプログラムでこれらのエンドポイントを呼び出してください。 /settings/api-keys
API キーの一覧
/api/v1/api-keysscope: session{
"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"
}]
}API キーを作成
/api/v1/api-keysscope: session// 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"]
}API キーを取り消し
/api/v1/api-keys/:idscope: session{ "id": "key_abc123", "revoked": true }エラー
HTTP 428 with error.code = spend_consent_required means a paid request came without X-Max-Generation-Credits (or, where taken, an acceptedQuoteHash);error.message says how to see the price first, and nothing was charged. HTTP 409 with error.code = generation_budget_exceeded means your 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 (for an editor the error names the owner and what to ask for: ownerName, missingGrants, askFor, the "Create new episodes" setting in Collaborators), 403 series_credit_permission_required on /generate when an editor may add episodes but the owner has not turned on "Use my credits" (ownerName, askFor; /estimate still answers the quote, with spendBlocked). Nothing is charged.
An unknown model id is 400 naming the id sent, the closest allowed one ("Did you mean …") and the allowed list; it never runs as Auto. A clip's video, regenerate, image and /videos body that names its model as model (instead of videoModel / imageModel) is 400 too. Over MCP a ★ tool refuses an argument name it does not take: invalid_arguments with rule known_arguments and allowed[].didYouMean (e.g. model → videoModel). Nothing is quoted or charged. offer_on_clip_call refuses the same way, so a price sent as totalCents names priceCents instead of being dropped.
Rate limits are per key: 5 generation calls, 60 reads, 60 writes and 10 social publishes 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.
多くのエンドポイントは、機械可読の code を含む error オブジェクトを返します。一部の専用エンドポイントは文字列のエラーやトップレベルのコードを返すため、必ず HTTP ステータスを確認してください。
{ "error": { "code": "insufficient_credits", "message": "...", "status": 402, "required": 120, "available": 30, "balance": 30, "shortfall": 90, "topUpUrl": "https://yoh.app/studio/episodes/…?credits_sheet=1&credits_need=120" } }| HTTP | コード | 意味 |
|---|---|---|
| 401 | unauthorized | API キーがないか無効です。 |
| 403 | forbidden | API キーに必要なスコープがありません。 |
| 404 | not_found | 要求されたリソースが存在しません。 |
| 400 | bad_request | 無効なリクエストボディまたはパラメータ。 |
| 402 | insufficient_credits | この操作を実行するためのクレジットが不足しています。 |
| 429 | rate_limited | リクエストが多すぎます。Retry-After ヘッダーを確認してください。 |
| 500 | internal_error | 予期しないサーバーエラー。 |
| 503 | JOB_SCRIPT_CHECK_UNAVAILABLE | ストーリーの読み込みで動画の案件の台本チェックを完了できませんでした。何も表示・変更されていません。Retry-After の後にもう一度読み込んでください。 |
レート制限: API キーごとに、生成エンドポイントは 1 分あたり 5 リクエストまで。読み取りとクレジットを消費しないクリップ編集は 60 リクエストまでです。制限に達した場合、レスポンスには待機する秒数を含む Retry-After ヘッダーが含まれます。失敗したジョブ(全リトライ後)は差し引かれたクレジットを自動的に返還します。プロバイダーが開始後に拒否または失敗した場合、プロバイダーが請求した分のクレジットは返金されません。
SNSへの投稿
完成した動画を接続済みアカウントへ直接送れます。ひとつの認証情報で「生成 → レンダリング → 投稿」までを自動化できます。まずアプリ内でアカウントを接続してください。このエンドポイントはそこへ投稿します。
動画を投稿する
/api/v1/social/publishscope: social:publish202 と { postId, status: "publishing" } を返し、アップロードはバックグラウンドで進みます。下のステータスエンドポイントをポーリングしてください。代わりにアップロード完了まで待たせたい場合は wait: true を渡します(数分かかることがあります)。 動画 URL は、このストーリーの正常に完了したレンダリング結果または元のアップロード動画と一致する必要があります。YouTube のストリームは公開アドレスのみを許可し、既存の 512 MB 制限が適用されます。
socialAccountIdstringstoryIdstringvideoUrlstringplatformstringcaptionstringyoutubeobjectfacebookPageIdstringdurationSecnumberaspectRatiostringfileSizeBytesnumberwaitboolean投稿ステータスを確認する
/api/v1/social/publish/:postIdscope: social:publishライフサイクル:
publishing→published|failed.