API 參考文件

透過三個 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 請求都必須在 Authorization 標頭中使用 Bearer 方案包含你的 API 金鑰。

Authorization: Bearer sk_live_YOUR_API_KEY

API 金鑰以 sk_live_ 開頭。你可以從 API Keys page 建立和管理金鑰。 /api-keys

每個 API 金鑰被授予一個或多個控制其可存取端點的範圍。故事文字生成每個工作消耗 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 後輪詢此端點。工作通常需要 8–15 分鐘，取決於故事長度以及是否啟用了 renderVideo。建議每 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，之後生成時把該 id 當作 assets 陣列中的 seriesAssetId 引用即可，不需要每次重新產生圖片連結。你提供的圖片會重新託管在我們的儲存空間，因此即使你自己的上傳網址過期，該 id 仍然有效。

• 可傳入單一素材，或用 "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 是你自己給客戶的識別碼。用同一個 externalId 呼叫第二次，會回傳既有的帳號而不是再開一個，所以重試是安全的。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，代理再以 get_job 輪詢，與 REST API 相同。
• 在 .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 金鑰管理端點使用 session authentication（已登入用戶的 Cookie），而非 API 金鑰。使用 API Keys page 進行瀏覽器工作流程，或從後端以有效 Session 以程式方式呼叫這些端點。 /api-keys

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

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

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

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

多數端點會傳回含有機器可讀取 code 的 error 物件。部分專用端點可能傳回字串錯誤或頂層代碼；請一律檢查 HTTP 狀態。

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