Referensi API

Buat video pertama Anda dalam tiga panggilan API: generate → poll → download.

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
}

Setiap permintaan API harus menyertakan API key Anda di header Authorization menggunakan skema Bearer.

Authorization: Bearer sk_live_YOUR_API_KEY

API key diawali dengan sk_live_. Anda dapat membuat dan mengelola key dari API Keys page. /api-keys

Setiap API key diberi satu atau beberapa scope yang mengatur endpoint mana yang dapat diakses. Pembuatan teks story menghabiskan 55 kredit per job; scope yang juga menghasilkan video klip atau render akhir (termasuk scope default, full) menagih biaya tersebut di muka sebagai tambahan. Kredit dikembalikan jika job gagal setelah semua percobaan ulang.

Mengirim prompt dan langsung mengembalikan jobId. Video dibuat secara asinkron. Poll GET /api/v1/stories/jobs/:jobId untuk memantau progres.

Isi permintaan

assets[] opsional

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 opsional

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 opsional

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

Respons 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

Poll endpoint ini setelah memanggil POST /api/v1/stories/generate. Job biasanya membutuhkan 8–15 menit tergantung panjang story dan apakah renderVideo diaktifkan. Disarankan polling setiap 15–30 detik.

Siklus status job

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.

Field respons

Setelah job selesai, Anda dapat mengambil semua aset yang dihasilkan untuk story menggunakan storyId yang dikembalikan oleh job. Semua endpoint aset memerlukan scope assets:read.

Setiap klip adalah segmen adegan dengan video hasil AI, gambar diam, dan audionya sendiri. Semua field URL bersifat absolut dan dapat diakses publik.

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

Pustaka yang sama dengan yang ditulis panel aset di studio. Unggah karakter, latar, properti, atau referensi gaya, simpan id yang dikembalikan, lalu rujuk saat generasi dengan mengirim id tersebut sebagai seriesAssetId di dalam array assets — tanpa perlu membuat tautan gambar baru untuk setiap video. Gambar yang Anda kirim di-host ulang di penyimpanan kami, sehingga id tetap berfungsi meski URL unggahan Anda sendiri kedaluwarsa.

• Kirim satu aset, atau array "assets" untuk menyimpan hingga 100 sekaligus.
• Secara bawaan aset digabung saat namanya sama persis, jadi mengunggah ulang katalog yang sama bersifat idempoten. Gunakan ?mergeStrategy=fuzzy untuk pencocokan yang toleran terhadap penggantian nama, atau insert untuk selalu membuat aset baru.
• Setel isHeroProduct pada properti (ad_spot) atau isPrimaryBackground pada adegan (news_analysis / persona_channel) untuk menyematkannya. Saat generasi, sematan diterjemahkan otomatis — Anda tidak perlu menulis heroItemId sendiri.

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 masih berfungsi dan tidak berubah, tetapi hanya menangani karakter. Gunakan endpoint ini.

Mengunggah dan menyimpan gambar referensi karakter untuk sebuah series agar AI menggunakan wajah/tampilan yang konsisten di semua story dalam series tersebut. Operasi ini bersifat idempotent — memanggilnya berkali-kali dengan nama karakter yang sama aman dilakukan.

Kirim video yang sudah jadi langsung ke akun yang terhubung, sehingga satu otomatisasi bisa menjalankan generate → render → terbit dengan satu kredensial. Hubungkan dulu akunnya di aplikasi; endpoint ini menerbitkan ke akun tersebut.

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

Untuk platform yang melayani banyak pelanggan. Alih-alih satu kunci dan satu kolam kredit untuk semua orang — di mana satu pelanggan yang sibuk menghabiskan saldo milik yang lain dan tak seorang pun tahu siapa memakai berapa — sediakan satu akun per pelanggan dan isi masing-masing dari saldo Anda sendiri. Pelanggan Anda tidak pernah mendaftar di sini atau membayar kami; hubungan komersialnya tetap milik Anda.

externalId adalah id Anda sendiri untuk pelanggan tersebut. Memanggil dua kali dengan id yang sama mengembalikan akun yang sudah ada alih-alih membuat yang kedua, jadi permintaan yang diulang tetap aman. Kunci API dikembalikan sekali saja, saat pertama dibuat — kami menyimpan hash-nya dan tidak bisa menampilkannya lagi, jadi simpanlah begitu Anda menerimanya. Akun baru dimulai dari saldo nol.

Memindahkan kredit dari saldo Anda sendiri ke saldo akun tersebut — sebuah transfer, bukan hibah, jadi Anda hanya bisa membagikan apa yang benar-benar Anda beli. Mengembalikan 402 bila saldo Anda sendiri tidak mencukupi. :accountId menerima id akun kami maupun externalId Anda.

GET /api/v1/accounts menampilkan akun-akun Anda beserta saldo dan total pemakaiannya; GET /api/v1/accounts/:accountId/credits membaca satu akun. Kunci milik akun terkelola hanya membawa cakupan generasi — ia tidak akan pernah bisa menyediakan atau mengisi akun.

Yoh menyediakan server MCP sehingga agen coding AI — Claude Code, Claude Desktop, atau klien MCP mana pun — dapat membuka dan menyunting cerita Anda secara langsung: isi klip dan dialog, pemindahan dan pemotongan timeline, overlay bebas, serta regenerasi dan render setiap kali Anda menyetujuinya secara eksplisit. Server ini mengikuti aturan yang sama dengan editor di browser, jadi suntingan dari terminal mendarat persis di tempat yang sama seperti jika Anda menyeretnya.

Hubungkan

Buat API key di /api-keys — untuk menyunting tanpa memakai kredit, cakupan stories:read dan stories:write sudah cukup — lalu jalankan:

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

Atau commit konfigurasi proyek agar satu tim langsung mendapat koneksinya saat membuka repo, dengan masing-masing menyediakan kunci sendiri lewat env:

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

Setelah itu cukup bicara ke Claude Code: "rapatkan tempo episode 3 — potong bagian kosong, geser teks agar pas di ketukan, lalu render ulang". Jalankan /mcp di dalam Claude Code untuk memeriksa koneksinya.

Apa yang bisa dilakukan agen

Bagaimana ia tetap aman dan benar

• Server menegakkan aturan editor (pemindahan slide, batas pemotongan, jalur teks, baris overlay) dan menjawab pelanggaran dengan rentang yang diizinkan, bukan diam-diam membatasi nilainya.
• Agen membaca seluruh aturan dari resource yoh://guide/timeline, dan prompt /mcp__yoh__edit-story memberinya alur kerja yang aman.
• Generasi bersifat asinkron — alat mengembalikan jobId yang di-poll agen dengan get_job, sama seperti REST API.
• Atur timeout panjang di .mcp.json (misalnya 900000) agar render tidak kehabisan waktu di sisi klien.

Verifikasi koneksi Anda

Repo menyertakan smoke test. Ia berbicara dengan protokol asli, menguji aturannya, dan membuktikan gerbang pengeluaran benar-benar bekerja — tanpa memakai kredit sama sekali, dan satu-satunya penulisan yang dilakukannya dikembalikan:

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 pengelolaan API key menggunakan session authentication (cookie pengguna yang sudah login), bukan API key. Gunakan API Keys page untuk alur kerja berbasis browser, atau panggil endpoint ini secara programatis dari backend Anda dengan sesi yang valid. /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 }

Semua error mengembalikan bentuk JSON yang konsisten dengan objek error berisi code yang dapat dibaca mesin.

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