API 레퍼런스

세 번의 API 호출로 첫 번째 동영상 만들기: 생성 → 폴링 → 다운로드.

Sign in and create a key at API Keys. Choose stories:generate and stories:read for generation and polling, then copy the full key immediately — it is shown only once. Keep it in a server environment variable or secret manager. Your account needs enough credits; creating a key does not add credits.

curl https://www.yoh.app/api/v1/credits \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Submitting a generation request authorizes its credit charge; API integrations do not need an interactive price confirmation. To check cost first, POST the same body to /api/v1/stories/estimate. Optionally send X-Max-Generation-Credits with your maximum whole-number credits: exceeding it returns HTTP 409 before charging. Use the canonical host shown here; redirects from yoh.app can drop your Authorization header.

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

Replace YOUR_UNIQUE_REQUEST_ID with a unique ID for this operation. Reuse that ID and the identical body when retrying a queued generation request after a network failure. A new ID starts a new operation. Direct image/music requests may return a conflict on replay; inspect the asset before retrying. Poll the returned job every 20 seconds until completed or failed. A failed job is terminal; an error on a queued job can describe an automatic retry. For a text-only draft, use scope: "story" and omit renderVideo.

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

curl https://www.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 요청은 Bearer 스킴을 사용하여 Authorization 헤더에 API 키를 포함해야 합니다.

Authorization: Bearer sk_live_YOUR_API_KEY

API 키는 sk_live_로 시작합니다. API Keys page에서 키를 생성하고 관리할 수 있습니다. /api-keys

각 API 키에는 접근할 수 있는 엔드포인트를 제어하는 하나 이상의 범위가 부여됩니다. 스토리 텍스트 생성은 작업당 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 https://www.yoh.app/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 https://www.yoh.app/api/v1/stories/STORY_ID/clips/CLIP_ID/image \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
# Poll jobId until completed

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

POST /api/v1/stories/generate 호출 후 이 엔드포인트를 폴링합니다. 스토리 길이와 renderVideo 활성화 여부에 따라 작업은 보통 8–15분이 소요됩니다. 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를 사용하여 스토리에 대해 생성된 모든 에셋을 가져올 수 있습니다. 모든 에셋 엔드포인트에는 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"
  }]
}

스튜디오 에셋 패널이 기록하는 것과 동일한 라이브러리입니다. 캐릭터, 배경, 소품, 스타일 레퍼런스를 업로드한 뒤 반환된 id를 보관하면 생성 시 assets 배열의 seriesAssetId 로 해당 id를 넘겨 참조할 수 있습니다. 영상마다 이미지 링크를 새로 만들 필요가 없습니다. 전달한 이미지는 당사 스토리지에 다시 호스팅되므로 원래 업로드 URL이 만료돼도 id는 계속 동작합니다.

• 에셋을 하나만 보내거나 "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://www.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://www.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://www.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 https://www.yoh.app/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 키는최초 생성 시 단 한 번 돌아옵니다 — 저희는 해시만 저장하며 다시 보여줄 수 없으니 받는 즉시 보관하세요. 새 계정은 잔액 0으로 시작합니다.

최초 키를 분실했다면 소유 플랫폼의 키로 요청 본문 없이 이 엔드포인트를 호출하세요. 계정 ID 또는 externalId를 사용할 수 있습니다. 하나의 트랜잭션으로 기존 키를 모두 폐기하고 새 apiKey를 한 번만 반환합니다(201). 안전하게 보관하세요. 이 호출을 반복하면 키가 다시 교체됩니다. 일반 계정 생성 요청을 재시도해도 기존 키는 교체되지 않습니다.

크레딧을 당신의 잔액에서 그 계정으로 옮깁니다 — 지급이 아니라 이체이므로 실제로 구매한 만큼만 나눠줄 수 있습니다. 당신의 잔액이 부족하면 402를 반환합니다. :accountId에는 저희 계정 ID나 당신의 externalId 중 아무거나 넣을 수 있습니다.

GET /api/v1/accounts는 각 계정의 잔액과 누적 사용액을 함께 나열하고, GET /api/v1/accounts/:accountId/credits는 하나를 읽습니다. 관리형 계정 자신의 키는 생성 범위만 가지므로 계정을 발급하거나 충전할 수 없습니다.

Yoh는 MCP 서버를 제공하여 AI 코딩 에이전트(Claude Code, Claude Desktop 또는 모든 MCP 클라이언트)가 스토리를 직접 열고 편집할 수 있게 합니다. 클립 내용과 대사, 타임라인 이동과 트림, 프리폼 오버레이, 그리고 매번 명시적으로 승인한 경우에만 재생성과 렌더링을 수행합니다. 브라우저 편집기와 동일한 규칙을 따르므로 터미널에서 한 편집도 드래그했을 때와 정확히 같은 위치에 놓입니다.

연결

/api-keys에서 API 키를 만들고(크레딧을 쓰지 않고 편집만 하려면 stories:read와 stories:write 범위면 충분합니다) 다음을 실행하세요:

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

또는 프로젝트 설정을 커밋하면 팀 전체가 저장소를 열 때 연결을 갖게 됩니다. 키는 각자 환경 변수로 제공합니다:

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

그다음에는 Claude Code에 말만 하면 됩니다: "3화의 호흡을 조여줘 — 빈 구간을 잘라내고, 자막을 비트에 맞추고, 다시 렌더링해줘". Claude Code 안에서 /mcp를 실행하면 연결을 확인할 수 있습니다.

에이전트가 할 수 있는 일

안전하고 정확하게 유지되는 방식

• 서버가 편집기의 규칙(슬라이드 이동, 트림 경계, 자막 레인, 오버레이 행)을 강제하며, 위반 시 값을 조용히 잘라내지 않고 허용 범위를 알려줍니다.
• 에이전트는 yoh://guide/timeline 리소스에서 전체 규칙을 읽고, /mcp__yoh__edit-story 프롬프트가 안전한 작업 흐름을 제공합니다.
• 생성은 비동기입니다. 도구가 jobId를 반환하면 에이전트가 REST API와 동일하게 get_job으로 폴링합니다.
• .mcp.json에 긴 timeout(예: 900000)을 설정해 렌더링이 클라이언트에서 시간 초과되지 않게 하세요.

연결 확인하기

저장소에 스모크 테스트가 포함되어 있습니다. 실제 프로토콜로 통신하고 규칙을 검증하며 사용 게이트가 작동함을 증명합니다. 크레딧은 전혀 쓰지 않고, 유일한 쓰기 작업도 되돌립니다:

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

API 키 관리 엔드포인트는 API 키가 아닌 session authentication(로그인한 사용자 쿠키)를 사용합니다. 브라우저 기반 워크플로에는 API Keys page를 사용하거나, 유효한 세션으로 백엔드에서 프로그래밍 방식으로 이 엔드포인트를 호출하세요. /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 }

HTTP 409 with error.code = generation_budget_exceeded means your optional X-Max-Generation-Credits cap was exceeded. The response includes quote.credits; nothing was charged. Change the request or explicitly raise your budget to retry. A malformed cap returns 400. Other 409 conflicts can mean an idempotency key was reused with different input or work is already running. Template-version generation uses its own persisted quoteId contract; see its OpenAPI reference.

대부분의 엔드포인트는 기계가 읽을 수 있는 code가 포함된 error 객체를 반환합니다. 일부 전용 엔드포인트는 문자열 오류나 최상위 코드를 반환할 수 있으므로 항상 HTTP 상태를 확인하세요.

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