Yoh

API 參考文件

以程式方式生成 AI 影片。提交提示詞、輪詢完成狀態，並取得直接影片連結 — 全部透過 REST 完成。

基礎 URL: https://yoh.app

Story Category Showcase

登入前，程式碼範例將使用佔位符。

快速開始

透過三個 API 呼叫建立您的第一部影片：生成 → 輪詢 → 下載。

1. 生成影片

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

回應 — 工作已排入佇列

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

2. 輪詢直到完成

curl https://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 請求都必須在標頭中使用方案包含您的 API 金鑰。

Authorization: Bearer sk_live_YOUR_API_KEY

API 金鑰以開頭。您可以從建立和管理金鑰。

請妥善保管您的 API 金鑰。不要在客戶端程式碼或公開儲存庫中暴露它們。如果金鑰外洩，請立即從 API 金鑰頁面撤銷它。

範圍與點數

每個 API 金鑰被授予一個或多個控制其可存取端點的範圍。故事生成每個工作消耗點數。如果工作在所有重試後失敗，點數將被退還。

範圍	授予存取權限
stories:generate	POST /api/v1/stories/generate, POST /api/v1/series-assets/ensure-character-image
stories:read	GET /api/v1/stories, GET /api/v1/stories/:id, GET /api/v1/stories/jobs/:id
assets:read	GET .../characters, .../scenes, .../items, .../clips

生成影片

排入影片生成工作

POST/api/v1/stories/generatescope: stories:generate

立即提交提示詞並返回。影片以非同步方式生成。輪詢以追蹤進度。

請求本體

欄位	型別	狀態	說明
`prompt`	`string`	必填	故事描述，最多 5000 個字元。
`aspectRatio`	`string`	選填	、、、之一。預設：。
`renderVideo`	`boolean`	選填	— 返回第一個 AI 片段（快速，約 10 分鐘）。 — 透過 Remotion 將所有片段渲染成一個合成 MP4（約 12–15 分鐘）。
`title`	`string`	選填	故事的顯示名稱。
`contentType`	`string`	選填	故事格式分類。可選 cinematic_story、news_analysis、music_video、persona_channel、youtube_clone、ad_spot。預設：cinematic_story。
`locale`	`string`	選填	語言代碼，例如、。預設：。
`seriesId`	`string`	選填	附加到現有系列以保持一致的角色視覺效果。

回應 202 Accepted

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

輪詢工作狀態

取得工作狀態

GET/api/v1/stories/jobs/:jobIdscope: stories:read

呼叫後輪詢此端點。工作通常需要 8–15 分鐘，取決於故事長度以及是否啟用了。建議每輪詢一次。

工作狀態生命週期

queuedgenerating_storygenerating_videosrendering_videocompleted或failed

回應欄位

欄位	型別	說明
`jobId`	`string`	唯一工作識別碼。
`status`	`string`	目前狀態。參見上方的生命週期。
`progress`	`number`	0–100 整數，表示完成百分比。
`storyId`	`string\|null`	故事生成完成後設定。用於取得資產。
`renderVideo`	`boolean`	是否請求合成最終 MP4。
`videoUrl`	`string\|null`	狀態完成時的絕對影片 URL。可以是合成 MP4（renderVideo: true）或第一個片段的 AI 影片（renderVideo: false）。
`error`	`string\|null`	失敗時的人類可讀錯誤訊息。成功時始終為 null。
`createdAt / startedAt / completedAt`	`string (ISO)`	時間戳記。

故事

列出故事

GET/api/v1/storiesscope: stories:read

返回您的故事分頁列表。

查詢參數

參數	預設值	說明
`page`	1	頁碼（≥ 1）。
`limit`	20	每頁結果數（1–100）。
`status`	—	按故事狀態過濾。

取得故事

GET/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"
}

資產概覽

工作完成後，您可以使用工作返回的取得為故事生成的所有資產。所有資產端點都需要範圍。

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

角色

列出角色

GET/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
  }]
}

片段與影片

列出片段

GET/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"
  }]
}

當為 false 時，工作的指向第一個片段的影片。使用此端點取得每個單獨片段的影片 URL。

系列資產

為系列註冊角色圖片

POST/api/v1/series-assets/ensure-character-imagescope: stories:generate

為系列上傳並保存角色參考圖片，使 AI 在該系列所有故事中使用一致的面孔/外觀。此操作是的 — 使用相同角色名稱多次呼叫是安全的。

欄位	型別	說明
`seriesId`	`string`	要附加角色的系列 ID。
`characterName`	`string`	角色名稱（在系列中用作唯一鍵）。
`imageUrl`	`string`	角色參考圖片的可公開存取 URL。

管理 API 金鑰

API 金鑰管理端點使用（已登入用戶的 Cookie），而非 API 金鑰。使用進行瀏覽器工作流程，或從後端以有效 Session 以程式方式呼叫這些端點。

列出 API 金鑰

GET/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 金鑰

POST/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 金鑰

DELETE/api/v1/api-keys/:idscope: session

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

錯誤代碼

所有錯誤都返回一致的 JSON 結構，其中包含帶有機器可讀的物件。

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

HTTP	代碼	含義
401	`unauthorized`	缺少或無效的 API 金鑰。
403	`forbidden`	API 金鑰沒有所需的範圍。
404	`not_found`	請求的資源不存在。
400	`bad_request`	無效的請求本體或參數。
402	`insufficient_credits`	點數不足，無法執行此操作。
429	`rate_limited`	請求過多。請查看 Retry-After 標頭。
500	`internal_error`	意外的伺服器錯誤。

速率限制： 生成端點的速率限制比讀取端點更嚴格。達到限制時，回應包含標頭，其中包含等待的秒數。失敗的工作（所有重試後）自動退還已扣除的 25 點數。