Riferimento API

Crea il tuo primo video in tre chiamate API: genera → verifica → scarica.

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
}

Tutte le richieste API devono includere la tua chiave API nell’intestazione Authorization utilizzando lo schema Bearer.

Authorization: Bearer sk_live_YOUR_API_KEY

Le chiavi API iniziano con sk_live_. Puoi creare e gestire le chiavi dalla API Keys page. /api-keys

A ogni chiave API sono assegnati uno o più ambiti che controllano a quali endpoint può accedere. La generazione del testo della storia costa 55 crediti per job; gli ambiti che producono anche video delle clip o un Render finale (incluso l’ambito predefinito, full) addebitano tali costi in anticipo. I Crediti vengono rimborsati se il job fallisce dopo tutti i tentativi.

Invia un prompt e restituisce immediatamente un jobId. Il video viene generato in modo asincrono. Verifica lo stato su GET /api/v1/stories/jobs/:jobId per monitorare l’avanzamento.

Corpo della richiesta

assets[] opzionale

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 opzionale

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 opzionale

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.

Altri campi opzionali

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

Risposta 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

Interroga questo endpoint dopo aver chiamato POST /api/v1/stories/generate. Il job richiede solitamente 8–15 minuti a seconda della lunghezza della storia e dell’attivazione di renderVideo. Si consiglia di verificare ogni 15–30 secondi.

Ciclo di vita dello stato del 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.

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.

Campi della risposta

Al termine di un lavoro, puoi recuperare tutti gli Asset generati per la storia utilizzando lo storyId restituito dal lavoro. Tutti gli endpoint degli Asset richiedono lo scope assets:read.

Ogni clip è un segmento di scena con il proprio video, immagine statica e audio generati dall’AI. Tutti i campi URL sono assoluti e accessibili pubblicamente.

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

La stessa libreria in cui scrive il pannello asset dello Studio. Carica un personaggio, uno sfondo, un oggetto o un riferimento di stile, conserva l’ID restituito e usalo al momento della generazione passando quell’ID come seriesAssetId nell’array degli asset — non serve creare un nuovo link immagine per ogni video. Le immagini che passi vengono ospitate sul nostro storage, quindi l’ID continua a funzionare anche dopo la scadenza del tuo URL di caricamento originale.

• Invia un singolo asset, o un array "assets" per inserirne fino a 100 contemporaneamente.
• Per impostazione predefinita, gli asset vengono uniti in base alla corrispondenza esatta del nome, quindi caricare nuovamente lo stesso catalogo è un’operazione idempotente — tranne per un personaggio il cui nome esiste già nella storia: in quel caso riceverai 409 SERIES_NAME_EXISTS con il personaggio esistente e nulla verrà salvato. Chiedi all’utente, poi invia seriesDuplicate "new" per aggiungerne un secondo, oppure passa ?mergeStrategy=exact per aggiornare quello esistente. ?mergeStrategy=fuzzy tollera i cambi di nome; insert crea sempre un nuovo asset.
• DELETE restituisce 409 SERIES_ASSET_IN_USE con gli episodi che usano ancora l’asset (storie: id, titolo, clipCount) e non rimuove nulla. Chiedi all’utente, poi invia confirm: true (nel body o ?confirm=true): gli episodi manterranno la propria copia e le loro clip non cambieranno. Un personaggio in un casting aperto restituisce 409 SERIES_ASSET_HIRED (hires) e non può essere rimosso finché l’ingaggio non termina.
• Imposta isHeroProduct su un oggetto (ad_spot) o isPrimaryBackground su una scena (news_analysis / persona_channel) per fissarli. Al momento della generazione, il pin si risolve automaticamente — non dovrai mai scrivere heroItemId a mano.

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 funziona ancora ed è invariato, ma gestisce solo i personaggi. È preferibile usare questo endpoint.

Carica e salva un’immagine di riferimento del personaggio per una serie, in modo che l’AI utilizzi un volto e uno stile coerenti in tutte le storie di quella serie. Questa operazione è idempotent: chiamarla più volte con lo stesso nome personaggio è sicuro.

Invia un video finito direttamente a un account collegato, così un'automazione può gestire genera → render → pubblica con un'unica credenziale. Collega prima gli account nell'app; questo endpoint pubblica su di essi.

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

Per le piattaforme che servono molti clienti. Invece di avere un'unica chiave e un unico pool di crediti per tutti — dove un cliente attivo esaurisce il saldo per gli altri e nessuno può sapere chi ha speso cosa — configura un account per ogni cliente e ricarica ognuno dal tuo saldo. I tuoi clienti non si registrano mai qui né ci pagano; il rapporto commerciale resta tuo.

externalId è il tuo ID personale per il cliente. Chiamare due volte con lo stesso ID restituisce l'account esistente invece di crearne un secondo, quindi un tentativo di richiesta ripetuto è sicuro. La chiave API viene restituita una volta, alla prima creazione — memorizziamo un hash e non possiamo mostrarlo di nuovo, quindi conservalo quando lo ricevi. Un nuovo account inizia con un saldo pari a zero.

Se la chiave iniziale è andata persa, chiama questo endpoint con la chiave della piattaforma proprietaria e senza corpo della richiesta. Usa l'ID dell'account o l'externalId. Revoca in modo atomico le chiavi precedenti dell'account e restituisce una nuova apiKey una sola volta (201). Conservala in modo sicuro. Ripetere questa chiamata ruota nuovamente la chiave; i normali tentativi di provisioning dell'account non sostituiscono mai una chiave funzionante.

Sposta i crediti dal tuo saldo a quello dell'account — si tratta di un trasferimento, non di una concessione, quindi puoi distribuire solo ciò che hai effettivamente acquistato. Restituisce 402 quando il tuo saldo non è sufficiente. :accountId accetta sia il nostro ID account che il tuo externalId.

GET /api/v1/accounts elenca i tuoi account con i relativi saldi e la spesa totale; GET /api/v1/accounts/:accountId/credits ne legge uno. La chiave di un account gestito ha solo permessi di generazione — non può mai creare o ricaricare account autonomamente.

Yoh include un server MCP affinché gli agenti AI (Claude Code, Codex, Claude Desktop o qualsiasi client MCP) possano creare e modificare storie nel tuo account: scrivi una nuova storia da un’idea, aggiungi i suoi personaggi e genera il video, oppure cambia il contenuto delle clip e i dialoghi, sposta e taglia elementi nella timeline e aggiungi overlay a mano libera. Qualsiasi operazione che consumi crediti attende ogni volta la tua approvazione esplicita. Segue le stesse regole dell’Editor nel browser, quindi una modifica fatta da terminale apparirà esattamente come se avessi trascinato gli elementi.

Tre modi per usarlo

Scegli quella più adatta agli strumenti del tuo agent. La skill di Yoh qui sotto li insegna tutti e tre.

• MCP + browser (consigliato in Codex, Claude Code e nelle app Claude) L'agent lavora tramite questi strumenti MCP e gestisce una scheda del browser accanto: dopo ogni passaggio apre il link contenuto nella risposta (la tabella dello Script dopo una nuova storia, il pannello della clip dopo un video della clip, l'elenco Genera tutto mentre un'operazione è in corso, l'editor avanzato per la timeline e i livelli di testo, l'MP4 del render) e controlla il risultato sulla pagina reale. Accedi una volta in quel browser con lo stesso account della chiave API. MCP e la pagina condividono i medesimi dati: la pagina dell'episodio si aggiorna entro pochi secondi da una modifica MCP e l'agent ricarica l'editor avanzato dopo una modifica alla timeline. Ogni spesa passa attraverso un solo percorso: il preventivo MCP o la finestra di dialogo del prezzo dell'app.
• Solo browser (senza chiave API) L'agent lavora sulle pagine di yoh.app nel tuo browser, proprio come faresti tu: Crea → Storia, la tabella dello Script e il pannello della clip, l'editor del personaggio e il suo selettore di modelli, Genera tutto, l'editor avanzato, le versioni e l'esportazione. Ogni spesa passa attraverso la finestra di dialogo del prezzo dell'app e l'agent non inserisce mai i dati di pagamento o il tuo codice di accesso.
• Solo MCP (headless) Per script, CI e agenzie che creano molte varianti: quote → confirmToken per ogni spesa, monitoraggio con get_job / get_run, interruzione con cancel_generation, creazione di varianti con create_story_versions e generate_all_clips, e download dell'URL video di ogni render terminato. Nessun browser necessario.

Esempio in ogni modalità: un annuncio di 16 secondi in 9:16 in inglese e giapponese, scritto in una storia con il suo prodotto, generato, trasformato in versione giapponese e renderizzato due volte.

Connetti

Consigliato: accedi con Yoh, senza chiave API. Usa esattamente questo indirizzo (yoh.app senza www reindirizza, e l’accesso controlla l’indirizzo). In Claude Code:

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

Poi digita /mcp, scegli yoh, poi Authenticate, accedi a Yoh nel browser che si apre con l’account che vuoi usare e approva.

In Codex (CLI, estensione IDE o app desktop di ChatGPT), aggiungi il server e accedi, poi imposta tool_timeout_sec = 300 sotto [mcp_servers.yoh] in ~/.codex/config.toml e riavvia Codex:

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

• App desktop di Claude o claude.ai: Customize → Connectors → + Add → Add custom connector, chiamalo Yoh, incolla l’indirizzo, poi Connect e accedi. Attivalo in ogni chat da + → Connectors. Nei piani Team o Enterprise lo aggiunge prima un proprietario.
• Cursor: aggiungi yoh con questo indirizzo in ~/.cursor/mcp.json, poi accedi quando Cursor lo chiede.
• ChatGPT: Plugins → + → Add custom MCP server, chiamalo Yoh, incolla l’indirizzo e accedi. Alcuni piani richiedono che un amministratore consenta i server personalizzati.

Verifica: chiedi al tuo agente di eseguire get_credits; dovrebbe mostrare il tuo saldo Yoh. Puoi vedere e scollegare le app collegate in Impostazioni → Chiavi API → App collegate.

Per far vedere al tuo agente le pagine che modifica: Claude Code con claude --chrome (l’estensione Claude in Chrome), l’app desktop di Claude con il connettore Claude in Chrome, oppure Codex nell’app desktop di ChatGPT con il suo browser. Lo skill dice all’agente quando guardare.

Oppure usa una chiave API (script, CI, app senza accesso)

Crea una chiave API su /api-keys. Per creare nuove storie e generare video, includi storie:generate; per modificare senza spendere, sono sufficienti storie:read e storie:write. Poi in Claude Code:

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

Oppure salva una configurazione di progetto così l’intero team ottiene la connessione all’apertura della repo, con ogni membro che fornisce la propria chiave tramite env:

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

In Codex, aggiungi il server a ~/.codex/config.toml e imposta YOH_API_KEY nella tua 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

Installa la skill di Yoh

La skill insegna al tuo agent come creare e modificare bene una storia di Yoh: iniziare in una serie, valutare il prezzo prima di spendere e guardare le clip prima di giudicarle. È un unico file, tenuto aggiornato con il server. Esegui la riga per il tuo agent, oppure scarica 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

Poi chiedi semplicemente: "crea una storia di 60 secondi su un infermiere del turno di notte che sente i fantasmi", oppure "velocizza il ritmo dell’episodio 3: taglia i tempi morti, sposta i sottotitoli sui beat e avvia il render". Esegui /mcp in Claude Code o Codex per verificare la connessione.

Cosa può fare l’agente

Come garantisce sicurezza e correttezza

• Il server applica le regole dell’Editor (spostamenti, limiti di ritaglio, corsie dei sottotitoli, righe degli overlay) e risponde a una violazione indicando l’intervallo consentito invece di troncare i valori silenziosamente.
• L’agente legge il set completo di regole dalla risorsa yoh://guide/timeline, e il prompt /mcp__yoh__edit-story gli fornisce un flusso di lavoro sicuro.
• La generazione è asincrona — la maggior parte degli strumenti restituisce un runId che l’agente controlla con get_run; alcuni (create_story, render_story, character art) restituiscono un jobId per get_job, come nelle API REST.
• Imposta un timeout lungo in .mcp.json (ad esempio 900000) affinché il render non vada in timeout lato client.

Verifica la tua connessione

Uno smoke test viene fornito con il repo. Utilizza il protocollo reale, mette alla prova le regole e dimostra che il blocco della spesa funziona: non consuma mai crediti e l'unica operazione di scrittura viene annullata:

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

Gli endpoint per la gestione delle API key utilizzano session authentication (cookie dell’utente loggato), non una API key. Usa la API Keys page per una procedura via browser, oppure chiama questi endpoint a livello di codice dal tuo backend con una sessione valida. /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.

La maggior parte degli endpoint restituisce un oggetto error con un code leggibile dalla macchina. Gli endpoint specializzati potrebbero restituire un errore in formato stringa o un codice di primo livello; controlla sempre lo stato HTTP.

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