Yoh

API リファレンス

プログラムで AI 動画を生成します。プロンプトを送信し、完了をポーリングして、直接動画 URL を受け取ります — すべて REST で完結。

ベース URL: https://yoh.app

Story Category Showcase

サインインするまで、コード例はプレースホルダーを使用します。

クイックスタート

3 回の 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 キーには、アクセス可能なエンドポイントを制御する 1 つ以上のスコープが付与されます。ストーリー生成はジョブあたりクレジットを消費します。全リトライ後にジョブが失敗した場合、クレジットは返還されます。

スコープ	アクセス権限
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 を使用してすべてのクリップを 1 つの合成 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`	ステータスが completed の場合の絶対動画 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 ページあたりの結果数（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 キー管理エンドポイントは API キーではなく（ログイン済みユーザーの Cookie）を使用します。ブラウザベースのワークフローにはを使用するか、有効なセッションでバックエンドからプログラムでこれらのエンドポイントを呼び出してください。

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 クレジットを自動的に返還します。