เอกสารอ้างอิง API

สร้างวิดีโอแรกของคุณด้วยการเรียก API เพียง 3 ครั้ง: สร้าง → ตรวจสอบสถานะ → ดาวน์โหลด

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

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
}

คำขอ API ทั้งหมดต้องแนบ API key ของคุณในส่วนหัว Authorization โดยใช้รูปแบบ Bearer

Authorization: Bearer sk_live_YOUR_API_KEY

API key จะขึ้นต้นด้วย sk_live_ คุณสามารถสร้างและจัดการ key ได้จากAPI Keys page /api-keys

API key แต่ละอันจะได้รับสิทธิ์หนึ่งขอบเขตขึ้นไปที่ควบคุมว่า endpoint ใดที่เข้าถึงได้ การสร้างข้อความเรื่องราวมีค่าใช้จ่าย 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, 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 $BASE/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 $BASE/api/v1/stories/STORY_ID/clips/CLIP_ID/image \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
# Poll jobId until completed

curl -X POST $BASE/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 $BASE/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 $BASE/api/v1/stories/STORY_ID/clips/CLIP_ID/image \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl -X POST $BASE/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 $BASE/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 $BASE/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 $BASE/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 $BASE/api/v1/stories/STORY_ID/render \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
# Poll until completed → videoUrl

ตรวจสอบ endpoint นี้หลังจากเรียก 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 ที่ได้จากงานนั้น endpoint แอสเซ็ตทั้งหมดต้องใช้ขอบเขตสิทธิ์ assets:read

แต่ละคลิปคือส่วนของฉากที่มีวิดีโอสร้างโดย AI ภาพนิ่ง และเสียงเป็นของตัวเอง ฟิลด์ URL ทั้งหมดเป็น 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 นั้นเป็น seriesAssetId ในอาร์เรย์ assets โดยไม่ต้องสร้างลิงก์รูปใหม่ทุกครั้ง รูปที่คุณส่งมาจะถูกนำไปโฮสต์บนพื้นที่จัดเก็บของเรา ดังนั้น id จะยังใช้งานได้แม้ URL ต้นทางของคุณจะหมดอายุ

• ส่งแอสเซ็ตเดียว หรือใช้อาร์เรย์ "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://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://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://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 — เรียกซ้ำหลายครั้งด้วยชื่อตัวละครเดียวกันได้อย่างปลอดภัย

Push a finished video straight to a connected account, so an automation can drive generate → render → publish with one credential. Connect the accounts in the app first; this endpoint publishes to them.

curl -X POST $BASE/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" }
  }'

endpoint การจัดการ API key ใช้ session authentication (คุกกี้ของผู้ใช้ที่ล็อกอินอยู่) ไม่ใช่ API key ใช้ API Keys page สำหรับขั้นตอนการทำงานผ่านเบราว์เซอร์ หรือเรียก endpoint เหล่านี้ผ่านโปรแกรมจากแบ็กเอนด์ของคุณด้วยเซสชันที่ถูกต้อง /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 }

ข้อผิดพลาดทั้งหมดจะคืนค่าในรูปแบบ JSON ที่สอดคล้องกัน โดยมีอ็อบเจ็กต์ error ที่มี code ที่เครื่องอ่านได้

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