เอกสารอ้างอิง 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, 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 $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 — เรียกซ้ำหลายครั้งด้วยชื่อตัวละครเดียวกันได้อย่างปลอดภัย

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

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

สำหรับแพลตฟอร์มที่ให้บริการลูกค้าจำนวนมาก แทนที่จะใช้คีย์เดียวและกองเครดิตเดียวร่วมกันทั้งหมด — ซึ่งลูกค้ารายที่ใช้หนักจะดูดยอดคงเหลือของคนอื่นจนหมด และไม่มีใครบอกได้ว่าใครใช้ไปเท่าไร — ให้เปิดบัญชีแยกต่อลูกค้าหนึ่งราย แล้วเติมเครดิตให้แต่ละบัญชีจากยอดคงเหลือของคุณเอง ลูกค้าของคุณไม่ต้องสมัครที่นี่และไม่ต้องจ่ายเงินให้เรา ความสัมพันธ์ทางการค้ายังเป็นของคุณ

externalId คือรหัสของคุณเองที่ใช้แทนลูกค้ารายนั้น การเรียกซ้ำด้วยค่าเดิมจะคืนบัญชีเดิมแทนที่จะสร้างบัญชีที่สอง การลองใหม่จึงปลอดภัย API key จะถูกส่งกลับเพียงครั้งเดียว ตอนสร้างครั้งแรก — เราเก็บไว้เป็นแฮชและไม่สามารถแสดงให้ดูอีกได้ จึงควรบันทึกไว้ทันทีที่ได้รับ บัญชีใหม่จะเริ่มต้นที่ยอดคงเหลือศูนย์

ย้ายเครดิตจากยอดคงเหลือ "ของคุณ" ไปยังบัญชีนั้น — เป็นการโอน ไม่ใช่การให้เปล่า คุณจึงแจกได้เท่าที่ซื้อไว้จริงเท่านั้น จะคืน 402 เมื่อยอดคงเหลือของคุณไม่พอ ส่วน :accountId รับได้ทั้งรหัสบัญชีของเราและ externalId ของคุณ

GET /api/v1/accounts จะแสดงรายการบัญชีของคุณพร้อมยอดคงเหลือและยอดใช้จ่ายสะสมของแต่ละบัญชี ส่วน GET /api/v1/accounts/:accountId/credits ใช้อ่านทีละบัญชี คีย์ของบัญชีที่จัดการให้จะมีเฉพาะขอบเขตการสร้างเท่านั้น — ไม่สามารถเปิดหรือเติมเครดิตให้บัญชีใดได้เลย

Yoh มีเซิร์ฟเวอร์ MCP ให้ เพื่อให้เอเจนต์เขียนโค้ด AI (Claude Code, Claude Desktop หรือไคลเอนต์ MCP ใดก็ได้) เปิดและแก้ไขสตอรี่ของคุณได้โดยตรง ทั้งเนื้อหาคลิปและบทพูด การเลื่อนและตัดบนไทม์ไลน์ เลเยอร์อิสระ และการสร้างใหม่กับการเรนเดอร์เมื่อคุณอนุมัติอย่างชัดเจนทุกครั้ง มันทำงานตามกฎเดียวกับตัวแก้ไขในเบราว์เซอร์ การแก้ไขจากเทอร์มินัลจึงลงตำแหน่งเดียวกับที่การลากจะได้

เชื่อมต่อ

สร้าง API key ที่ /api-keys (ถ้าต้องการแค่แก้ไขโดยไม่ใช้เครดิต ขอบเขต stories:read และ stories:write ก็เพียงพอ) จากนั้น:

claude mcp add --transport http yoh https://yoh.app/api/mcp \
  --header "Authorization: Bearer sk_live_YOUR_API_KEY"

หรือคอมมิตไฟล์ตั้งค่าโปรเจกต์ เพื่อให้ทั้งทีมได้การเชื่อมต่อทันทีที่เปิดรีโป โดยแต่ละคนใส่คีย์ของตัวเองผ่าน env:

{
  "mcpServers": {
    "yoh": {
      "type": "http",
      "url": "https://yoh.app/api/mcp",
      "headers": { "Authorization": "Bearer ${YOH_API_KEY}" },
      "timeout": 900000
    }
  }
}

จากนั้นก็คุยกับ Claude Code ได้เลย: "กระชับจังหวะของตอนที่ 3 — ตัดช่วงเงียบออก เลื่อนคำบรรยายให้ตรงจังหวะ แล้วเรนเดอร์ใหม่" รัน /mcp ใน Claude Code เพื่อตรวจสอบการเชื่อมต่อ

เอเจนต์ทำอะไรได้บ้าง

มันคงความปลอดภัยและถูกต้องอย่างไร

• เซิร์ฟเวอร์บังคับใช้กฎของตัวแก้ไข (การเลื่อนแบบสไลด์ ขอบเขตการตัด เลนคำบรรยาย แถวเลเยอร์) และเมื่อผิดกฎจะบอกช่วงที่อนุญาต แทนที่จะปรับค่าให้เงียบ ๆ
• เอเจนต์อ่านกฎทั้งหมดจากรีซอร์ส yoh://guide/timeline และพรอมต์ /mcp__yoh__edit-story ให้ขั้นตอนการทำงานที่ปลอดภัย
• การสร้างเป็นแบบอะซิงโครนัส เครื่องมือจะคืน jobId แล้วเอเจนต์จะ poll ด้วย get_job เหมือน REST API
• ตั้งค่า timeout ให้ยาวใน .mcp.json (เช่น 900000) เพื่อไม่ให้การเรนเดอร์หมดเวลาฝั่งไคลเอนต์

ตรวจสอบการเชื่อมต่อ

รีโปมีสโมกเทสต์มาให้ มันสื่อสารด้วยโปรโตคอลจริง ทดสอบกฎต่าง ๆ และพิสูจน์ว่าด่านการใช้เครดิตทำงานจริง โดยไม่ใช้เครดิตเลย และการเขียนเพียงอย่างเดียวที่ทำก็จะถูกย้อนกลับ:

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

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