Referencia de la API

Crea tu primer vídeo en tres llamadas a la API: generar → consultar → descargar.

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
}

Todas las solicitudes de la API deben incluir tu clave de API en la cabecera Authorization utilizando el esquema Bearer.

Authorization: Bearer sk_live_YOUR_API_KEY

Las claves de API comienzan por sk_live_. Puedes crear y gestionar tus claves desde la API Keys page. /api-keys

Cada clave de API tiene uno o más permisos que controlan a qué endpoints puede acceder. Generar el texto de la historia cuesta 55 créditos por tarea; los permisos que además producen vídeos de clips o un renderizado final (incluido el permiso predeterminado, full) cobran eso aparte y por adelantado. Los créditos se reembolsan si la tarea falla tras todos los reintentos.

Envía un prompt y devuelve un jobId de inmediato. El vídeo se genera de forma asíncrona. Consulta GET /api/v1/stories/jobs/:jobId para seguir el progreso.

Cuerpo de la solicitud

assets[] opcional

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 opcional

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 opcional

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.

Otros campos opcionales

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

Respuesta 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

Consulta este endpoint después de llamar a POST /api/v1/stories/generate. La tarea suele tardar entre 8 y 15 minutos, según la longitud de la historia y si renderVideo está activado. Recomendamos consultar cada 15–30 segundos.

Ciclo de vida del estado de la tarea

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.

Campos de la respuesta

Cuando termina una tarea, puedes obtener todos los recursos generados para la historia con el storyId que devuelve la tarea. Todos los endpoints de recursos requieren el permiso assets:read.

Cada clip es un segmento de escena con su propio vídeo, imagen fija y audio generados por IA. Todos los campos de URL son absolutos y de acceso público.

{
  "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 misma biblioteca en la que escribe el panel de recursos del Studio. Sube un personaje, fondo, objeto o referencia de estilo, guarda el ID devuelto y haz referencia a él al generar pasando ese ID como seriesAssetId en el array de recursos; no es necesario crear un nuevo enlace de imagen por vídeo. Las imágenes que envías se alojan en nuestro almacenamiento, por lo que el ID sigue funcionando aunque tu URL de subida caduque.

• Envía un recurso o un array "assets" para insertar o actualizar hasta 100 a la vez.
• Por defecto, los recursos se fusionan si el nombre coincide exactamente, por lo que volver a subir el mismo catálogo es idempotente, excepto con un personaje cuyo nombre ya exista en la historia: eso devuelve 409 SERIES_NAME_EXISTS con el personaje existente y no guarda nada. Pregunta al usuario y luego envía seriesDuplicate "new" para añadir un segundo personaje, o pasa ?mergeStrategy=exact para actualizar el existente. ?mergeStrategy=fuzzy tolera cambios de nombre; insert siempre crea un nuevo recurso.
• DELETE devuelve 409 SERIES_ASSET_IN_USE con los episodios que aún usan el recurso (stories: id, title, clipCount) y no elimina nada. Pregunta al usuario y luego envía confirm: true (en el cuerpo o ?confirm=true): los episodios conservan su propia copia y sus clips no cambian. Un personaje con una contratación abierta devuelve 409 SERIES_ASSET_HIRED (hires) y no se puede eliminar hasta que la contratación termine.
• Establece isHeroProduct en un objeto (ad_spot) o isPrimaryBackground en una escena (news_analysis / persona_channel) para fijarlo. Al generar, el marcador se resuelve automáticamente; nunca tendrás que escribir 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 sigue funcionando y no ha cambiado, pero solo gestiona personajes. Es preferible usar este endpoint.

Sube y guarda una imagen de referencia de personaje para una historia, de modo que la IA mantenga la misma cara y el mismo estilo en todos sus episodios. Esta operación es idempotent: puedes llamarla varias veces con el mismo nombre de personaje sin problema.

Envía un vídeo terminado directamente a una cuenta conectada, para que una automatización pueda gestionar generar → renderizar → publicar con una sola credencial. Conecta primero las cuentas en la app; este endpoint publica en ellas.

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

Para plataformas que dan servicio a muchos clientes. En lugar de una clave y un fondo de créditos para todos —donde un cliente muy activo agota el saldo de los demás y nadie sabe quién ha gastado qué—, crea una cuenta por cliente y financia cada una desde tu propio saldo. Tus clientes nunca se registran aquí ni nos pagan a nosotros; la relación comercial sigue siendo tuya.

externalId es tu propio ID para el cliente. Si llamas dos veces con el mismo, se devuelve la cuenta existente en lugar de crear otra, así que reintentar la solicitud es seguro. La clave de API se devuelve una sola vez, al crearla por primera vez; guardamos un hash y no podemos volver a mostrarla, así que guárdala al recibirla. Una cuenta nueva empieza con saldo cero.

Si se ha perdido la clave inicial, llama a este endpoint con la clave de la plataforma propietaria y sin cuerpo en la solicitud. Usa el ID de la cuenta o el externalId. Revoca de forma atómica las claves anteriores de la cuenta y devuelve una nueva apiKey una sola vez (201). Guárdala de forma segura. Repetir esta llamada vuelve a rotar la clave; los reintentos normales de creación de cuenta nunca reemplazan una clave que funcione.

Mueve créditos de tu propio saldo al de la cuenta; es una transferencia, no una concesión, por lo que solo puedes repartir lo que hayas comprado realmente. Devuelve 402 cuando tu propio saldo no puede cubrirlo. :accountId acepta tanto nuestro ID de cuenta como tu externalId.

GET /api/v1/accounts enumera tus cuentas con sus respectivos saldos y gasto total; GET /api/v1/accounts/:accountId/credits lee una. La clave propia de una cuenta gestionada solo tiene permisos de generación; nunca puede crear ni financiar cuentas por sí misma.

Yoh incluye un servidor MCP para que los agentes de IA (Claude Code, Codex, Claude Desktop o cualquier cliente MCP) puedan crear y editar historias en tu cuenta: escribir una historia nueva a partir de una idea, añadir sus personajes y generar el vídeo, o cambiar el contenido y el diálogo de los clips, mover y recortar elementos en la línea de tiempo y añadir superposiciones libres. Todo lo que gasta créditos espera siempre tu aprobación explícita. Sigue las mismas reglas que el editor del navegador, así que una edición hecha desde la terminal queda exactamente donde la dejaría un arrastre.

Tres formas de usarlo

Elige la que mejor se adapte a las herramientas de tu agente. La skill yoh de abajo enseña las tres.

• MCP + navegador (recomendado en Codex, Claude Code y las apps de Claude) El agente hace el trabajo con estas herramientas MCP y maneja una pestaña del navegador a su lado (Claude in Chrome, el navegador de Codex): tras cada paso, abre el enlace que trae la respuesta (la tabla del guion tras una historia nueva, el panel del clip tras el vídeo de un clip, la lista de Generar todo mientras hay una ejecución en curso, el editor avanzado para la línea de tiempo y las capas de texto, el MP4 del renderizado) y comprueba el resultado en la página real. Inicia sesión una vez en ese navegador con la misma cuenta que la clave de API. El MCP y la página comparten los mismos datos: la página del episodio se actualiza sola a los pocos segundos de un cambio por MCP, y el agente recarga el editor avanzado tras un cambio en la línea de tiempo. Cada gasto pasa por una sola vía: el presupuesto del MCP o el diálogo de precio de la app.
• Solo navegador (sin clave de API) El agente usa las páginas de yoh.app en tu navegador, igual que lo harías tú: Crear → Historia, la tabla del guion y el panel del clip, el editor de personajes y su selector de modelo, Generar todo, el editor avanzado, las versiones y la exportación. Cada gasto pasa por el propio diálogo de precio de la app, y el agente nunca escribe datos de pago ni tu código de inicio de sesión.
• Solo MCP (headless) Para scripts, CI y agencias que hacen muchas variantes: quote → confirmToken en cada gasto, consulta get_job / get_run, detén con cancel_generation, crea variantes con create_story_versions y generate_all_clips, y descarga el videoUrl de cada renderizado terminado. No hace falta navegador.

Ejemplo en todos los modos: un anuncio de 16 segundos en 9:16 en inglés y japonés, escrito en una historia con su producto, generado, versionado al japonés y renderizado dos veces.

Conectar

Recomendado: inicia sesión con Yoh, sin clave de API. Usa exactamente esta dirección (yoh.app sin www redirige y el inicio de sesión comprueba la dirección). En Claude Code:

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

Luego escribe /mcp, elige yoh, pulsa Authenticate, inicia sesión en Yoh en el navegador que se abre con la cuenta que quieras usar y aprueba.

En Codex (CLI, extensión del IDE o la app de escritorio de ChatGPT), añade el servidor e inicia sesión; después pon tool_timeout_sec = 300 en [mcp_servers.yoh] de ~/.codex/config.toml y reinicia Codex:

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

• App de escritorio de Claude o claude.ai: Customize → Connectors → + Add → Add custom connector, llámalo Yoh, pega la dirección y luego Connect e inicia sesión. Actívalo en cada chat desde + → Connectors. En planes Team o Enterprise, primero lo añade un propietario.
• Cursor: añade yoh con esta dirección a ~/.cursor/mcp.json e inicia sesión cuando Cursor lo pida.
• ChatGPT: Plugins → + → Add custom MCP server, llámalo Yoh, pega la dirección e inicia sesión. Algunos planes necesitan que un administrador permita servidores propios.

Compruébalo: pide a tu agente que ejecute get_credits; debería mostrar tu saldo de Yoh. Puedes ver y desconectar las apps conectadas en Ajustes → Claves de API → Apps conectadas.

Para que tu agente vea las páginas que cambia: Claude Code con claude --chrome (la extensión Claude in Chrome), la app de escritorio de Claude con el conector Claude in Chrome, o Codex en la app de escritorio de ChatGPT con su navegador. El skill le dice al agente cuándo mirar.

O usa una clave de API (scripts, CI, apps sin inicio de sesión)

Crea una clave de API en /api-keys. Para crear historias nuevas y generar vídeo, incluye stories:generate; para editar sin gastar, bastan stories:read y stories:write. Después, en Claude Code:

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

O añade al repositorio una configuración de proyecto para que todo el equipo tenga la conexión al abrirlo; cada miembro aporta su propia clave mediante env:

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

En Codex, añade el servidor a ~/.codex/config.toml y configura YOH_API_KEY en tu 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

Instala la skill de Yoh

La skill enseña a tu agente a crear y editar bien una historia de Yoh: empezar en una serie, presupuestar antes de gastar y mirar los clips antes de juzgarlos. Es un solo archivo, al día con el servidor. Ejecuta la línea de tu agente, o descargar 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

Luego solo tienes que pedirlo: «haz una historia de 60 segundos sobre una enfermera del turno de noche que oye fantasmas» o «ajusta el ritmo del episodio 3: recorta los silencios, encaja los subtítulos en los tiempos y vuelve a renderizar». Ejecuta /mcp en Claude Code o Codex para comprobar la conexión.

Qué puede hacer el agente

Cómo se mantiene seguro y correcto

• El servidor aplica las reglas del editor (desplazamiento de clips, límites de recorte, pistas de subtítulos, filas de superposiciones) y, ante una infracción, responde con el rango permitido en lugar de ajustar el valor en silencio.
• El agente lee el conjunto completo de reglas del recurso yoh://guide/timeline, y el prompt /mcp__yoh__edit-story le proporciona un flujo de trabajo seguro.
• La generación es asíncrona: la mayoría de las herramientas devuelven un runId que el agente consulta con get_run; unas pocas (create_story, render_story, imágenes de personajes) devuelven un jobId para get_job, igual que la API REST.
• Establece un tiempo de espera largo en .mcp.json (por ejemplo 900000) para que un renderizado no agote el tiempo de espera en el lado del cliente.

Verifica tu conexión

El repositorio incluye un smoke test. Usa el protocolo real, pone a prueba las reglas y demuestra que el control de gasto funciona: nunca gasta créditos y su única escritura se revierte:

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

Los endpoints de gestión de claves de API usan session authentication (la cookie de la sesión iniciada), no una clave de API. Usa la API Keys page para hacerlo desde el navegador, o llama a estos endpoints mediante programación desde tu backend con una sesión válida. /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 mayoría de los endpoints devuelven un objeto error con un code legible por máquina. Los endpoints especializados pueden devolver un error de cadena o un código de nivel superior; comprueba siempre el estado HTTP.

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