Dokumentacja API

Stwórz swój pierwszy film w trzech wywołaniach API: generuj → odpytuj → pobierz.

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
}

Wszystkie zapytania API muszą zawierać twój klucz API w nagłówku Authorization przy użyciu schematu Bearer.

Authorization: Bearer sk_live_YOUR_API_KEY

Klucze API zaczynają się od sk_live_. Możesz tworzyć klucze i zarządzać nimi na API Keys page. /api-keys

Każdy klucz API ma przypisany jeden lub więcej zakresów, które kontrolują dostęp do poszczególnych punktów końcowych. Generowanie tekstu historii kosztuje 55 kredytów za zadanie; zakresy obejmujące również generowanie klipów wideo lub końcowy Render (w tym domyślny zakres „full”) pobierają opłaty za te elementy z góry. Kredyty są zwracane, jeśli zadanie nie powiedzie się po wszystkich próbach.

Przesyła prompt i natychmiast zwraca jobId. Wideo jest generowane asynchronicznie. Odpytuj GET /api/v1/stories/jobs/:jobId, aby śledzić postępy.

Treść żądania (body)

assets[] opcjonalne

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 opcjonalne

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 opcjonalne

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.

Inne opcjonalne pola

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

Odpowiedź 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

Odpytuj ten punkt końcowy po wywołaniu POST /api/v1/stories/generate. Zadanie trwa zazwyczaj 8–15 minut w zależności od długości historii i tego, czy funkcja renderVideo jest włączona. Zalecamy odpytywanie co 15–30 sekund.

Cykl życia statusu zadania

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.

Pola odpowiedzi

Po zakończeniu zadania możesz pobrać wszystkie zasoby wygenerowane dla historii, używając storyId zwróconego przez zadanie. Wszystkie punkty końcowe zasobów wymagają zakresu assets:read.

Każdy klip to segment sceny z własnym wideo wygenerowanym przez AI, nieruchomym obrazem i dźwiękiem. Wszystkie pola URL są absolutne i publicznie dostępne.

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

To ta sama biblioteka, do której zapisuje panel zasobów w Studio. Prześlij postać, tło, przedmiot lub referencję stylu, zachowaj zwrócone ID i odwołuj się do niego podczas generowania, przekazując to ID jako seriesAssetId w tablicy assets — nie musisz tworzyć nowego linku do obrazu dla każdego wideo. Przesłane obrazy są hostowane na naszym serwerze, więc ID działa nawet po wygaśnięciu twojego oryginalnego URL.

• Wyślij jeden zasób lub tablicę „assets”, aby dodać lub zaktualizować do 100 elementów naraz.
• Domyślnie zasoby są łączone na podstawie dokładnego dopasowania nazwy, więc ponowne przesłanie tego samego katalogu jest idempotentne — z wyjątkiem postaci, której nazwa już istnieje w historii: wtedy system zwraca 409 SERIES_NAME_EXISTS z istniejącą postacią i nic nie zapisuje. Zapytaj użytkownika, a następnie wyślij seriesDuplicate „new”, aby dodać drugą postać, lub przekaż ?mergeStrategy=exact, aby zaktualizować istniejącą. ?mergeStrategy=fuzzy toleruje zmiany nazw; insert zawsze tworzy nowy zasób.
• DELETE zwraca 409 SERIES_ASSET_IN_USE z listą odcinków, które wciąż używają zasobu (Historie: id, tytuł, clipCount) i nic nie usuwa. Zapytaj użytkownika, a następnie wyślij confirm: true (w body lub ?confirm=true): Odcinki zachowają własną kopię, a ich klipy się nie zmienią. Postać w trakcie aktywnego zatrudnienia zwraca 409 SERIES_ASSET_HIRED (hires) i nie może zostać usunięta do czasu zakończenia umowy.
• Ustaw isHeroProduct dla przedmiotu (ad_spot) lub isPrimaryBackground dla sceny (news_analysis / persona_channel), aby je przypiąć. Podczas generowania przypięcie zostanie rozwiązane automatycznie — nigdy nie musisz wpisywać heroItemId ręcznie.

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 wciąż działa i pozostaje bez zmian, ale obsługuje tylko postacie. Zalecamy korzystanie z tego endpointu.

Przesyła i zapisuje obraz referencyjny postaci dla serii, aby AI używało spójnej twarzy/Stylu we wszystkich historiach w tej serii. Ta operacja jest idempotent — wielokrotne wywołanie z tą samą nazwą postaci jest bezpieczne.

Prześlij gotowe wideo bezpośrednio na połączone konto, aby automatyzacja mogła przeprowadzić proces generuj → renderuj → opublikuj przy użyciu jednych danych uwierzytelniających. Najpierw połącz konta w aplikacji; ten punkt końcowy publikuje na nich materiały.

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

Dla platform obsługujących wielu klientów. Zamiast jednego klucza i jednej puli kredytów dla wszystkich — gdzie jeden aktywny klient zużywa saldo pozostałych i nikt nie wie, kto ile wydał — utwórz konto dla każdego klienta i zasilaj je z własnego salda. Twoi klienci nigdy nie rejestrują się tutaj ani nam nie płacą; relacja handlowa pozostaje po twojej stronie.

externalId to twój własny identyfikator klienta. Dwukrotne wywołanie z tym samym identyfikatorem zwróci istniejące konto zamiast tworzyć drugie, więc ponowienie żądania jest bezpieczne. Klucz API jest zwracany tylko raz, przy pierwszym utworzeniu — przechowujemy tylko hash i nie możemy go ponownie wyświetlić, więc zapisz go po otrzymaniu. Nowe konto zaczyna z zerowym saldem.

Jeśli początkowy klucz został zgubiony, wywołaj tę końcówkę z kluczem platformy właściciela i pustym body żądania. Użyj ID konta lub externalId. Operacja ta cofa poprzednie klucze konta i zwraca jednorazowo nowy apiKey (201). Przechowuj go bezpiecznie. Powtórzenie tego wywołania ponownie zmieni klucz; normalne ponowienia tworzenia konta nigdy nie zastępują działającego klucza.

Przenosi kredyty z twojego salda na saldo konta — jest to transfer, a nie przyznanie środków, więc możesz przekazać tylko to, co faktycznie kupiłeś. Zwraca 402, gdy twoje saldo nie pokrywa kwoty. :accountId akceptuje nasze ID konta lub twoje externalId.

GET /api/v1/accounts wyświetla listę twoich kont wraz z saldem i wydatkami; GET /api/v1/accounts/:accountId/credits odczytuje jedno z nich. Własny klucz zarządzanego konta posiada uprawnienia wyłącznie do generowania — nigdy nie może sam tworzyć ani zasilać kont.

Yoh udostępnia serwer MCP, dzięki czemu agenci AI (Claude Code, Codex, Claude Desktop lub dowolny klient MCP) mogą tworzyć i edytować historie na twoim koncie: napisać nową historię na podstawie pomysłu, dodać postacie i wygenerować wideo, lub zmieniać treść klipów i dialogi, przesuwać i przycinać elementy na Osi czasu oraz dodawać dowolne nakładki. Każda czynność wymagająca wydania kredytów wymaga twojej wyraźnej zgody za każdym razem. Agent przestrzega tych samych zasad co Edytor w przeglądarce, więc edycja z poziomu terminala trafi dokładnie tam, gdzie trafiłaby po przeciągnięciu myszką.

Trzy sposoby użycia

Wybierz ten, który pasuje do narzędzi twojego agenta. Poniższa umiejętność Yoh uczy wszystkich trzech.

• MCP + przeglądarka (zalecane w Codex, Claude Code i aplikacjach Claude) Agent wykonuje pracę za pomocą narzędzi MCP i steruje kartą przeglądarki obok (Claude w Chrome, przeglądarka Codex): po każdym kroku otwiera link zawarty w odpowiedzi (tabelę scenariusza po nowej historii, panel klipu po wideo, listę Generuj wszystko podczas pracy, zaawansowany edytor dla Osi czasu i warstw tekstowych, plik MP4 po renderowaniu) i sprawdza wynik na prawdziwej stronie. Zaloguj się raz w tej przeglądarce na to samo konto, co klucz API. MCP i strona współdzielą te same dane: strona odcinka odświeża się w ciągu kilku sekund od zmiany w MCP, a agent przeładowuje zaawansowany edytor po zmianie na Osi czasu. Każdy wydatek przechodzi tylko jedną ścieżką: wycenę MCP lub okno płatności w aplikacji.
• Tylko przeglądarka (bez klucza API) Agent obsługuje strony yoh.app w twojej przeglądarce tak, jak Ty: Stwórz → Historia, tabela scenariusza i panel klipu, edytor postaci i wybór modelu, Generuj wszystko, zaawansowany edytor, wersje i eksport. Każdy wydatek przechodzi przez własne okno płatności aplikacji, a agent nigdy nie wpisuje danych płatniczych ani twojego kodu logowania.
• Tylko MCP (headless) Dla skryptów, CI i agencji tworzących wiele wariantów: wycena → confirmToken dla każdego wydatku, odpytywanie get_job / get_run, zatrzymywanie przez cancel_generation, tworzenie wariantów za pomocą create_story_versions i generate_all_clips oraz pobieranie videoUrl każdego gotowego Renderu. Przeglądarka nie jest potrzebna.

Przykład w każdym trybie: 16-sekundowa reklama 9:16 w języku angielskim i japońskim, zapisana w historii wraz z produktem, wygenerowana, przetworzona na wersję japońską i wyrenderowana dwukrotnie.

Połącz

Zalecane: zaloguj się przez Yoh, bez klucza API. Użyj dokładnie tego adresu (yoh.app bez www przekierowuje, a logowanie sprawdza adres). W Claude Code:

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

Potem wpisz /mcp, wybierz yoh, następnie Authenticate, zaloguj się do Yoh w otwartej przeglądarce kontem, którego chcesz używać, i zatwierdź.

W Codex (CLI, rozszerzenie IDE lub aplikacja ChatGPT na komputer) dodaj serwer i zaloguj się, potem ustaw tool_timeout_sec = 300 w sekcji [mcp_servers.yoh] w ~/.codex/config.toml i uruchom Codex ponownie:

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

• Aplikacja Claude na komputer lub claude.ai: Customize → Connectors → + Add → Add custom connector, nazwij go Yoh, wklej adres, potem Connect i zaloguj się. Włącz go w każdym czacie przez + → Connectors. W planach Team lub Enterprise najpierw dodaje go właściciel.
• Cursor: dodaj yoh z tym adresem do ~/.cursor/mcp.json i zaloguj się, gdy Cursor o to poprosi.
• ChatGPT: Plugins → + → Add custom MCP server, nazwij go Yoh, wklej adres i zaloguj się. W niektórych planach administrator musi najpierw zezwolić na własne serwery.

Sprawdź: poproś agenta o uruchomienie get_credits; powinien pokazać Twoje saldo Yoh. Połączone aplikacje zobaczysz i odłączysz w Ustawienia → Klucze API → Połączone aplikacje.

Aby agent widział strony, które zmienia: Claude Code z claude --chrome (rozszerzenie Claude in Chrome), aplikacja Claude na komputer z łącznikiem Claude in Chrome albo Codex w aplikacji ChatGPT na komputer z jej przeglądarką. Skill mówi agentowi, kiedy patrzeć.

Albo użyj klucza API (skrypty, CI, aplikacje bez logowania)

Utwórz klucz API w /api-keys. Aby tworzyć nowe historie i generować wideo, uwzględnij uprawnienie stories:generate; do edycji bez wydawania środków wystarczą stories:read i stories:write. Następnie w Claude Code:

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

Możesz też dodać konfigurację projektu do repozytorium, aby cały zespół uzyskał połączenie po jego otwarciu, przy czym każdy członek podaje własny klucz przez env:

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

W Codex dodaj serwer do ~/.codex/config.toml i ustaw YOH_API_KEY w swojej powłoce:

# 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

Zainstaluj umiejętność Yoh

Umiejętność uczy twojego agenta, jak dobrze tworzyć i edytować historię Yoh: zaczynać w serii, wyceniać przed wydaniem kredytów i sprawdzać klipy przed ich oceną. To jeden plik, aktualizowany na bieżąco z serwerem. Uruchom wiersz poleceń dla swojego agenta lub pobierz 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

Potem po prostu poproś: „stwórz 60-sekundową historię o pielęgniarce z nocnej zmiany, która słyszy duchy” lub „popraw tempo 3. Odcinka: usuń ciszę, dopasuj napisy do rytmu i wyrenderuj ponownie”. Uruchom /mcp w Claude Code lub Codex, aby sprawdzić połączenie.

Co potrafi agent

Jak dbamy o bezpieczeństwo i poprawność

• Serwer wymusza zasady Edytora (przesuwanie slajdów, granice przycinania, ścieżki napisów, rzędy nakładek) i w razie naruszenia zwraca dozwolony zakres zamiast cichego przycięcia wartości.
• Agent czyta pełny zestaw reguł z zasobu yoh://guide/timeline, a prompt /mcp__yoh__edit-story zapewnia mu bezpieczny schemat pracy.
• Generowanie jest asynchroniczne — większość narzędzi zwraca runId, który agent sprawdza przez get_run; niektóre (create_story, render_story, grafika postaci) zwracają jobId dla get_job, tak samo jak w REST API.
• Ustaw długi timeout w .mcp.json (na przykład 900000), aby proces renderowania nie wygasł po stronie klienta.

Zweryfikuj swoje połączenie

Test dymny jest dostarczany wraz z repozytorium. Obsługuje on prawdziwy protokół, sprawdza reguły i potwierdza, że bramka płatności działa — nigdy nie zużywa kredytów, a jego jedyny zapis jest cofany:

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

Punkty końcowe zarządzania kluczami API używają session authentication (pliku cookie zalogowanego użytkownika), a nie klucza API. Użyj API Keys page dla przepływu w przeglądarce lub wywołuj te punkty programowo ze swojego backendu z ważną sesją. /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.

Większość punktów końcowych zwraca obiekt error z kodem code czytelnym dla maszyny. Specjalistyczne punkty mogą zwracać błąd jako ciąg znaków lub kod najwyższego poziomu; zawsze sprawdzaj status HTTP.

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