תיעוד 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 חייבות לכלול את מפתח ה-API בכותרת Authorization בסכימת Bearer.

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.

גוף הבקשה (Request body)

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 is the studio's resolution pills (default 720p; the story keeps the value you send and each clip makes what its model can, e.g. Seedance 2.5 up to 1080p, Kling and MiniMax H3 from 720p). qualityTier, modelStrategy and seed are API-only. 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.

שדות אופציונליים נוספים

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

תגובה (Response) 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 GET /api/runs/RUN_ID 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 GET /api/runs/RUN_ID 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 GET /api/runs/RUN_ID 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. משימה נמשכת בדרך כלל 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.

Stop. POST /api/v1/stories/jobs/:jobId/cancel (scope stories:write) stops a job the way the app's Stop does: no further paid step starts, work already sent to the provider finishes and is kept, and everything not delivered is refunded once. It answers { outcome: "cancelled" | "stopping" | "already_finished", status }; stopping means a clip is still in flight, so poll until the job reads cancelled (a final state too). POST /api/v1/runs/:runId/cancel stops a batch run (Generate All, started in the app or by /videos, /clips-all or /regenerate; a clip-images batch such as /storyboard) with the app's own Stop: no more clips start; clips never started are never charged. A single clip run's runId (a clip video, video edit or image) cannot be stopped: it answers 409 not_cancellable, and the run finishes and settles itself (a failure is refunded). MCP: cancel_generation.

Reading a job (changed 2026-10-20). A story job that rendered nothing (no render scope, no renderVideo) answers videoUrl: null; its first clip's video is firstClipVideoUrl, never the finished film. A failed clip image job answers failure { category, reason, message } like a clip video. A failed or cancelled job whose refund has not been settled yet says settlement: "pending". A 402 insufficient_credits carries required, balance and topUpUrl.

שדות התגובה

לאחר שמשימה מסתיימת אפשר לשלוף את כל הנכסים שנוצרו עבור הסיפור באמצעות ה-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 שמוחזר, ובזמן היצירה מפנים אליו על ידי העברת ה-id כ-seriesAssetId במערך assets; אין צורך ליצור קישור תמונה חדש לכל סרטון. תמונות שמועברות מאוחסנות מחדש אצלנו, כך שה-id ממשיך לעבוד גם אחרי שתוקף כתובת ההעלאה שלכם פג.

• אפשר לשלוח נכס אחד, או מערך "assets" כדי להוסיף או לעדכן עד 100 בבת אחת.
• כברירת מחדל נכסים מתמזגים לפי התאמת שם מדויקת, כך שהעלאה חוזרת של אותו קטלוג היא אידמפוטנטית. יוצא מן הכלל: דמות ששמה כבר קיים בסדרה מחזירה 409 SERIES_NAME_EXISTS עם הדמות הקיימת, ושום דבר לא נשמר. יש לשאול את המשתמש ואז לשלוח seriesDuplicate "new" כדי להוסיף דמות שנייה, או להעביר ?mergeStrategy=exact כדי לעדכן את הקיימת. ?mergeStrategy=fuzzy סובלני לשינויי שם; insert תמיד יוצר נכס חדש.
• DELETE מחזיר 409 SERIES_ASSET_IN_USE עם הפרקים שעדיין משתמשים בנכס (סיפורים: id, כותרת, clipCount) ולא מסיר דבר. שאלו את המשתמש, ואז שלחו confirm: true (בגוף הבקשה או ?confirm=true): הפרקים ישמרו עותק משלהם והקליפים שלהם לא ישתנו. דמות שנמצאת בתהליך שכירה פתוח תחזיר 409 SERIES_ASSET_HIRED (hires) ולא ניתן להסירה עד לסיום השכירה.
• כדי לנעוץ, מגדירים isHeroProduct בחפץ (ad_spot) או isPrimaryBackground בסצנה (news_analysis / persona_channel). בזמן היצירה הנעיצה מזוהה אוטומטית, כך שאין צורך לכתוב heroItemId ידנית.

Start from your own video (MP4, MOV or WebM, up to 1 GB and 10 minutes; free): POST /api/v1/series/:seriesId/uploads makes a draft episode and answers a one-time upload.url that takes one PUT of the file, straight to storage (upload.command is the curl line). Then POST /api/v1/stories/:storyId/upload verifies it, fills an empty title and description from the video, sets its style, picks a cover and cuts it into editable clips; it answers verifying until the check is done, so call it again. GET /api/v1/stories/:storyId/upload reports cutting (with progress) until ready, and links.upload is the page that shows it.

curl -X POST https://www.yoh.app/api/v1/series/series_abc/uploads \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"trip.mp4"}'
# → { "storyId": "story_123", "upload": { "url": "https://…", "command": "curl --fail-with-body -sS -X PUT -T <path-to-video> '…'" }, "links": { … } }

curl --fail-with-body -sS -X PUT -T ./trip.mp4 "<upload.url>"

curl -X POST https://www.yoh.app/api/v1/stories/story_123/upload \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
# → { "status": "cutting", "title": "…", "cut": { "progress": 10, … }, "links": { "upload": "…", "workspace": "…" } }

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 מוחזר פעם אחת, ביצירה הראשונה — אנחנו שומרים רק גיבוב (hash) ולא יכולים להציג אותו שוב, לכן יש לשמור אותו מיד כשמקבלים אותו. חשבון חדש מתחיל ביתרה אפס.

אם המפתח הראשוני אבד, קראו לנקודת קצה זו עם מפתח הפלטפורמה הבעלים וללא גוף בקשה. השתמשו ב-ID של החשבון או ב-externalId. הפעולה מבטלת באופן אטומי את המפתחות הקודמים של החשבון ומחזירה apiKey חדש פעם אחת (201). שמרו אותו בצורה מאובטחת. חזרה על קריאה זו תחליף את המפתח שוב; ניסיונות חוזרים רגילים להקצת חשבון לעולם לא יחליפו מפתח תקין.

מעביר קרדיטים מהיתרה שלכם ליתרת החשבון — זוהי העברה, לא מענק, כך שתוכלו לחלק רק את מה שקניתם בפועל. מחזיר 402 כאשר היתרה שלכם אינה מכסה זאת. :accountId מקבל את ה-ID של החשבון אצלנו או את ה-externalId שלכם.

GET /api/v1/accounts מציג את רשימת החשבונות שלכם עם היתרה וההוצאה המצטברת של כל אחד; GET /api/v1/accounts/:accountId/credits קורא חשבון בודד. מפתח של חשבון מנוהל כולל הרשאות יצירה בלבד — הוא לעולם לא יוכל להקצות או לממן חשבונות בעצמו.

Yoh מספק שרת MCP כך שסוכני AI (כמו Claude Code, Codex, Claude Desktop או כל לקוח MCP אחר) יוכלו ליצור ולערוך סיפורים בחשבון שלכם: לכתוב סיפור חדש מרעיון, להוסיף את הדמויות שלו וליצור את הווידאו, או לשנות תוכן של קליפ ודיאלוג, להזיז ולחתוך בציר הזמן ולהוסיף שכבות (overlays). כל פעולה שצורכת קרדיטים ממתינה לאישור מפורש שלכם בכל פעם. הסוכן פועל לפי אותם כללים של העורך בדפדפן, כך שעריכה מהטרמינל תתבצע בדיוק באותו מקום שבו הייתה מתבצעת גרירה ידנית.

שלוש דרכים לשימוש

בחרו את האפשרות שמתאימה לכלים של הסוכן שלכם. מיומנות ה-Yoh למטה מלמדת את שלושתן.

• MCP + דפדפן (מומלץ ב-Codex, ב-Claude Code ובאפליקציות Claude) הסוכן מבצע את העבודה דרך כלי ה-MCP האלה ומפעיל לצידו לשונית דפדפן (Claude in Chrome, הדפדפן של Codex): אחרי כל שלב הוא פותח את הקישור שמגיע עם התשובה (טבלת התסריט אחרי סיפור חדש, פאנל הקליפ אחרי סרטון קליפ, רשימת "יצירת הכול" בזמן ריצה, העורך המתקדם לציר הזמן ולשכבות טקסט, קובץ ה-MP4 של הרינדור) ובודק את התוצאה בדף האמיתי. יש להתחבר פעם אחת בדפדפן הזה עם אותו חשבון של מפתח ה-API. ה-MCP והדף חולקים את אותם נתונים: דף הפרק מתרענן בעצמו תוך שניות משינוי ב-MCP, והסוכן טוען מחדש את העורך המתקדם אחרי שינוי בציר הזמן. כל הוצאה עוברת בנתיב אחד בלבד: הצעת המחיר של ה-MCP או חלון המחיר באפליקציה.
• דפדפן בלבד (ללא מפתח API) הסוכן עובד בדפי yoh.app בדפדפן שלכם, בדיוק כמו שאתם הייתם עובדים: יצירה ← סיפור, טבלת התסריט ופאנל הקליפ, עורך הדמויות ובורר המודלים שלו, יצירת הכול, העורך המתקדם, גרסאות וייצוא. כל הוצאה עוברת דרך חלון המחיר של האפליקציה עצמה, והסוכן אף פעם לא מקליד פרטי תשלום או את קוד ההתחברות שלכם.
• MCP בלבד (headless) לסקריפטים, ל-CI ולסוכנויות שמפיקות הרבה גרסאות: quote ← confirmToken לכל הוצאה, בדיקת סטטוס עם get_job / get_run, עצירה עם cancel_generation, יצירת גרסאות עם create_story_versions ו-generate_all_clips, והורדת ה-videoUrl של כל רינדור שהסתיים. אין צורך בדפדפן.

דוגמה בכל מצב: פרסומת של 16 שניות ביחס 9:16 באנגלית וביפנית, שנכתבת לתוך סיפור עם המוצר שלה, נוצרת, מקבלת גרסה ביפנית ומרונדרת פעמיים.

חיבור

מומלץ: התחברות עם Yoh, בלי מפתח API. השתמשו בכתובת הזו בדיוק (yoh.app בלי www מפנה הלאה, וההתחברות בודקת את הכתובת). ב-Claude Code:

claude mcp add --transport http --scope user yoh https://www.yoh.app/api/mcp

אחר כך הקלידו /mcp, בחרו yoh ואז Authenticate, התחברו ל-Yoh בדפדפן שנפתח עם החשבון שבו תרצו להשתמש, ואשרו.

ב-Codex (CLI, תוסף IDE או אפליקציית ChatGPT למחשב), הוסיפו את השרת והתחברו, ואז הגדירו tool_timeout_sec = 300 תחת [mcp_servers.yoh] בקובץ ~/.codex/config.toml והפעילו את Codex מחדש:

codex mcp add yoh --url https://www.yoh.app/api/mcp
codex mcp login yoh

• אפליקציית Claude למחשב או claude.ai: Customize → Connectors → + Add → Add custom connector, קראו לו Yoh, הדביקו את הכתובת, ואז Connect והתחברו. הפעילו אותו בכל צ׳אט דרך + → Connectors. בתוכניות Team או Enterprise, בעלים מוסיף אותו קודם.
• Cursor: הוסיפו את yoh עם הכתובת הזו לקובץ ~/.cursor/mcp.json, והתחברו כש-Cursor מבקש.
• ChatGPT: Plugins → + → Add custom MCP server, קראו לו Yoh, הדביקו את הכתובת והתחברו. בחלק מהתוכניות מנהל צריך לאשר שרתים מותאמים.

בדיקה: בקשו מהסוכן להריץ get_credits; הוא אמור להציג את יתרת ה-Yoh שלכם. אפשר לראות ולנתק אפליקציות מחוברות בהגדרות → מפתחות API → אפליקציות מחוברות.

כדי שהסוכן יראה את הדפים שהוא משנה: Claude Code עם claude --chrome (התוסף Claude in Chrome), אפליקציית Claude למחשב עם המחבר Claude in Chrome, או Codex באפליקציית ChatGPT למחשב עם הדפדפן שלה. ה-skill אומר לסוכן מתי להסתכל.

או השתמשו במפתח API (סקריפטים, CI, אפליקציות בלי התחברות)

צרו מפתח API בכתובת /api-keys. כדי ליצור סיפורים חדשים וליצור וידאו, כללו את stories:generate; כדי לערוך ללא הוצאת קרדיטים, stories:read ו-stories:write מספיקים. לאחר מכן, ב-Claude Code:

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

או לבצע commit לקובץ הגדרות של הפרויקט, כך שכל הצוות יקבל את החיבור בפתיחת ה-repo, וכל אחד יספק מפתח משלו דרך env:

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

ב-Codex, הוסיפו את השרת ל-~/.codex/config.toml והגדירו את YOH_API_KEY ב-shell שלכם:

# export YOH_API_KEY=sk_live_YOUR_API_KEY
[mcp_servers.yoh]
url = "https://www.yoh.app/api/mcp"
bearer_token_env_var = "YOH_API_KEY"
tool_timeout_sec = 300

התקנת מיומנות ה-Yoh

המיומנות מלמדת את הסוכן שלכם איך ליצור ולערוך סיפור ב-Yoh בצורה טובה: להתחיל בסדרה, לתמחר לפני שמוציאים קרדיטים, ולהסתכל על הקליפים לפני ששופטים אותם. זהו קובץ אחד, שנשמר מעודכן מול השרת. הריצו את השורה עבור הסוכן שלכם, או הורדת SKILL.md

# Claude Code
mkdir -p ~/.claude/skills/yoh && curl -fsSL https://www.yoh.app/skills/yoh/SKILL.md -o ~/.claude/skills/yoh/SKILL.md

# Codex
mkdir -p ~/.agents/skills/yoh && curl -fsSL https://www.yoh.app/skills/yoh/SKILL.md -o ~/.agents/skills/yoh/SKILL.md

ואז פשוט מבקשים: "ליצור סיפור של 60 שניות על אחות במשמרת לילה ששומעת רוחות רפאים", או "להדק את הקצב של פרק 3: לחתוך שתיקות, להזיז את הכתוביות לנקודות הקצב ולרנדר מחדש". כדי לבדוק את החיבור, מריצים /mcp ב-Claude Code או ב-Codex.

מה הסוכן יכול לעשות

איך המערכת נשארת בטוחה ומדויקת

• השרת אוכף את חוקי העורך (הזזה שמסיטה את הקליפים שאחרי, גבולות חיתוך, נתיבי כתוביות, שורות שכבות) ועונה על חריגה עם הטווח המותר במקום לתקן אותה בשקט.
• הסוכן קורא את מערכת החוקים המלאה מהמשאב yoh://guide/timeline, והפרומפט /mcp__yoh__edit-story נותן לו תהליך עבודה בטוח.
• היצירה אסינכרונית: רוב הכלים מחזירים runId שהסוכן בודק באמצעות get_run; כמה מהם (create_story, render_story, איורי דמויות) מחזירים jobId עבור get_job, כמו ב-REST API.
• מומלץ להגדיר timeout ארוך ב-.mcp.json (למשל 900000) כדי שרינדור לא ייקטע בגלל timeout בצד הלקוח.

בדיקת החיבור

בדיקת smoke מצורפת למאגר. היא מדברת בפרוטוקול האמיתי, מפעילה את החוקים ומוכיחה שמחסום ההוצאה עובד; היא אף פעם לא מוציאה קרדיטים, והכתיבה היחידה שלה מבוטלת:

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 משתמשות ב-session authentication (קוקי של משתמש מחובר), ולא במפתח API. השתמשו ב-API Keys page עבור תהליך עבודה מבוסס דפדפן, או קראו לנקודות קצה אלו תכנותית מה-backend שלכם עם סשן תקף. /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.

Story create (POST /api/v1/stories/generate and /estimate, MCP create_story / estimate_story) checks the series before pricing: 404 series_not_found when the key's user cannot open that seriesId, 403 series_forbidden when they can open it but may not add episodes to it. Nothing is charged.

Rate limits are per key: 5 generation calls, 60 reads and 60 writes a minute. Each call counts once: an MCP tool call is one call even when it runs several v1 steps, and POST /stories/:id/swap-asset is one generation call for every clip it switches.

רוב נקודות הקצה מחזירות אובייקט error עם code קריא למכונה. נקודות קצה ייעודיות עשויות להחזיר שגיאת מחרוזת או קוד ברמה העליונה; בדקו תמיד את סטטוס ה-HTTP.

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