API リファレンス

3 回の API 呼び出しで最初の動画を作成：生成 → ポーリング → ダウンロード。

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

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

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

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

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

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

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

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

すべての API リクエストは、Bearer スキームを使用して Authorization ヘッダーに API キーを含める必要があります。

Authorization: Bearer sk_live_YOUR_API_KEY

API キーは sk_live_ で始まります。API Keys page からキーを作成・管理できます。 /api-keys

各 API キーには、アクセス可能なエンドポイントを制御する 1 つ以上のスコープが付与されます。ストーリーのテキスト生成はジョブあたり 55 クレジットです。クリップ動画や最終レンダーを含むスコープ（デフォルトの full を含む）は、その分を前払いで追加請求します。全リトライ後にジョブが失敗した場合、クレジットは返還されます。

プロンプトを送信して即座に jobId を返します。動画は非同期で生成されます。GET /api/v1/stories/jobs/:jobId をポーリングして進捗を追跡してください。

リクエストボディ

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.

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, 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, qualityTier, modelStrategy and seed are API-only — the studio expresses the same choices through its quality picker. Two fields are advisory: they are shown to the writer as context but nothing enforces them, and they are marked below.

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.

Other optional fields

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

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

レスポンス 202 Accepted

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

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

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

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

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

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

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

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

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

POST /api/v1/stories/generate を呼び出した後にこのエンドポイントをポーリングします。ストーリーの長さや renderVideo が有効かどうかによって、ジョブには通常 8–15 分かかります。15–30 秒 ごとのポーリングを推奨します。

ジョブステータスのライフサイクル

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

レスポンスフィールド

ジョブが完了したら、ジョブが返した storyId を使用してストーリー用に生成されたすべてのアセットを取得できます。すべてのアセットエンドポイントには 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"
  }]
}

スタジオのアセットパネルが書き込むのと同じライブラリです。キャラクター・背景・小道具・スタイル参照をアップロードし、返却された id を保存しておけば、生成時に assets 配列の seriesAssetId としてその id を渡すだけで参照できます。動画ごとに画像リンクを作り直す必要はありません。渡された画像は当社ストレージに再ホストされるため、元のアップロード URL が失効しても id は使い続けられます。

• アセットを 1 件送るか、"assets" 配列で最大 100 件をまとめて登録できます。
• 既定では名前の完全一致でマージするため、同じカタログを再アップロードしても冪等です。?mergeStrategy=fuzzy で改名に強い照合、insert で常に新規作成になります。
• 小道具に isHeroProduct（ad_spot）、シーンに isPrimaryBackground（news_analysis / persona_channel）を設定すると固定できます。生成時に自動で解決されるため、heroItemId を手書きする必要はありません。

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

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

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

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

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

POST /api/v1/series-assets/ensure-character-image は引き続き利用でき動作も変わりませんが、キャラクターのみ対応です。こちらのエンドポイントを推奨します。

シリーズのキャラクター参照画像をアップロードして保存し、AI がそのシリーズのすべてのストーリーで一貫した外見を使用できるようにします。この操作は idempotent です — 同じキャラクター名で複数回呼び出しても安全です。

完成した動画を接続済みアカウントへ直接送れます。ひとつの認証情報で「生成 → レンダリング → 投稿」までを自動化できます。まずアプリ内でアカウントを接続してください。このエンドポイントはそこへ投稿します。

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

多数の顧客を抱えるプラットフォーム向けです。全員でひとつのキーとひとつのクレジットプールを共有すると、使用量の多い顧客が残高を使い切り、誰がいくら使ったかも分かりません。代わりに顧客ごとにアカウントを発行し、あなた自身の残高から資金を移してください。顧客がここで登録したり当社に支払ったりすることはなく、商取引の関係はあなたのものに留まります。

externalId は顧客に対するあなた自身の ID です。同じ ID で二度呼び出しても、新しく作らず既存のアカウントを返すので、リトライは安全です。API キーが返るのは初回作成時の一度だけです。当社はハッシュのみを保存し再表示できないため、受け取った時点で保管してください。新しいアカウントの残高はゼロから始まります。

最初のキーを紛失した場合は、所有元プラットフォームのキーを使用し、リクエスト本文なしでこのエンドポイントを呼び出してください。アカウント ID または externalId を指定できます。以前のキーをすべて無効化し、新しい apiKey を一度だけ返します（201）。この処理は単一のトランザクションで行われます。キーは安全に保管してください。再度呼び出すと再びキーが交換されます。通常のアカウント作成の再試行では、既存のキーは交換されません。

クレジットを「あなたの」残高からそのアカウントへ移します。付与ではなく振替なので、実際に購入した分しか配れません。自分の残高で賄えない場合は 402 を返します。:accountId には当社のアカウント ID か、あなたの externalId のどちらでも指定できます。

GET /api/v1/accounts は各アカウントの残高と累計利用額を一覧します。GET /api/v1/accounts/:accountId/credits は単一のアカウントを読み取ります。マネージドアカウント自身のキーは生成系のスコープのみを持ち、アカウントの発行や入金は決してできません。

Yoh は MCP サーバーを提供しており、AI コーディングエージェント（Claude Code、Claude Desktop、その他の MCP クライアント）がストーリーを直接開いて編集できます。クリップの内容とセリフ、タイムラインの移動やトリム、フリーフォームのオーバーレイ、そして毎回あなたが明示的に承認した場合のみ再生成とレンダリングを行います。ブラウザ版エディターと同じルールで動作するため、ターミナルからの編集はドラッグした場合とまったく同じ位置に着地します。

接続

/api-keys で API キーを作成し（点数を消費せず編集するだけなら stories:read と stories:write の範囲で十分です）、次を実行します：

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

あとは Claude Code に話しかけるだけです：「第3話のテンポを締めて——間延びを削り、字幕を拍に合わせて、再レンダリングして」。Claude Code 内で /mcp を実行すると接続を確認できます。

エージェントにできること

安全性と正確性の保ち方

• サーバーはエディターのルール（スライド移動、トリム境界、字幕レーン、オーバーレイ行）を強制し、違反時には黙って値を丸めるのではなく許容範囲を返します。
• エージェントは yoh://guide/timeline リソースから完全なルールを読み取り、/mcp__yoh__edit-story プロンプトが安全な手順を与えます。
• 生成は非同期です。ツールは jobId を返し、エージェントは REST API と同じく get_job でポーリングします。
• .mcp.json で長めの timeout（例：900000）を設定し、レンダリングがクライアント側でタイムアウトしないようにしてください。

接続を検証する

リポジトリにはスモークテストが付属します。実際のプロトコルで通信し、各ルールを検証し、消費ゲートが機能することを確認します。点数は一切消費せず、唯一の書き込みも元に戻されます：

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

API キー管理エンドポイントは API キーではなく session authentication（ログイン済みユーザーの Cookie）を使用します。ブラウザベースのワークフローには API Keys page を使用するか、有効なセッションでバックエンドからプログラムでこれらのエンドポイントを呼び出してください。 /api-keys

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

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

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

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

多くのエンドポイントは、機械可読の code を含む error オブジェクトを返します。一部の専用エンドポイントは文字列のエラーやトップレベルのコードを返すため、必ず HTTP ステータスを確認してください。

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