Referência da API

Crie o seu primeiro vídeo em três chamadas de API: gerar → consultar → descarregar.

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
}

Todos os pedidos de API devem incluir a sua chave de API no cabeçalho Authorization com o esquema Bearer.

Authorization: Bearer sk_live_YOUR_API_KEY

As chaves de API começam com sk_live_. Pode criar e gerir chaves a partir da API Keys page. /api-keys

Cada chave de API recebe um ou mais âmbitos que controlam a que endpoints pode aceder. A geração do texto da história custa 55 créditos por trabalho; os âmbitos que também produzem vídeos de clipes ou uma renderização final (incluindo o âmbito predefinido, full) cobram esses valores antecipadamente, além daquele custo. Os créditos são reembolsados se o trabalho falhar após todas as tentativas.

Submete um prompt e devolve um jobId imediatamente. O vídeo é gerado de forma assíncrona. Consulte GET /api/v1/stories/jobs/:jobId para acompanhar o progresso.

Corpo do pedido

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.

Outros campos opcionais

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

Resposta 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

Consulte este endpoint depois de chamar POST /api/v1/stories/generate. O trabalho demora normalmente 8–15 minutos, consoante a duração da história e se renderVideo está ativado. Recomendamos consultar a cada 15–30 segundos.

Ciclo de vida do estado do trabalho

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 resposta

Após a conclusão de um trabalho, pode obter todos os elementos gerados para a história com o storyId devolvido pelo trabalho. Todos os endpoints de elementos requerem o âmbito assets:read.

Cada clipe é um segmento de cena com o seu próprio vídeo, imagem estática e áudio gerados por IA. Todos os campos de URL são absolutos e acessíveis publicamente.

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

A mesma biblioteca em que o painel de elementos do estúdio escreve. Carregue uma personagem, fundo, objeto ou referência de estilo, guarde o ID devolvido e use-o no momento da geração, passando esse ID como seriesAssetId na matriz assets; não precisa de criar um novo link de imagem para cada vídeo. As imagens que envia são realojadas no nosso armazenamento, pelo que o ID continua a funcionar depois de o seu URL de carregamento expirar.

• Envie um elemento ou uma matriz "assets" para criar ou atualizar até 100 de uma só vez.
• Por predefinição, os elementos são fundidos quando o nome coincide exatamente, pelo que voltar a carregar o mesmo catálogo é idempotente. A exceção é uma personagem cujo nome a série já tem: nesse caso, a resposta é 409 SERIES_NAME_EXISTS com a personagem existente, e nada é guardado. Pergunte ao utilizador e, em seguida, envie seriesDuplicate "new" para adicionar uma segunda, ou passe ?mergeStrategy=exact para atualizar a existente. ?mergeStrategy=fuzzy tolera mudanças de nome; insert cria sempre um novo elemento.
• DELETE devolve 409 SERIES_ASSET_IN_USE com os episódios que ainda usam o elemento (stories: id, title, clipCount) e não remove nada. Pergunte ao utilizador e, em seguida, envie confirm: true (no corpo ou ?confirm=true): os episódios mantêm a sua própria cópia e os seus clipes não mudam. Uma personagem com uma contratação em aberto devolve 409 SERIES_ASSET_HIRED (hires) e só pode ser removida quando a contratação terminar.
• Defina isHeroProduct num objeto (ad_spot) ou isPrimaryBackground numa cena (news_analysis / persona_channel) para o fixar. No momento da geração, a fixação é resolvida automaticamente: nunca precisa de escrever heroItemId à mão.

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 ainda funciona e não foi alterado, mas apenas processa personagens. Prefira este endpoint.

Carrega e guarda uma imagem de referência de personagem para uma série, para que a IA use um rosto/aspeto consistente em todas as histórias dessa série. Esta operação é idempotent: chamá-la várias vezes com o mesmo nome de personagem é seguro.

Envie um vídeo terminado diretamente para uma conta ligada, para que uma automatização possa fazer gerar → renderizar → publicar com uma única credencial. Ligue primeiro as contas na app; este endpoint publica nelas.

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 servem muitos clientes. Em vez de uma chave e uma reserva de créditos para todos (em que um cliente com muita atividade esgota o saldo dos restantes e ninguém consegue saber quem gastou o quê), crie uma conta por cliente e financie cada uma a partir do seu próprio saldo. Os seus clientes nunca se registam aqui nem nos pagam; a relação comercial continua a ser sua.

externalId é o seu próprio ID para o cliente. Chamar duas vezes com o mesmo devolve a conta existente em vez de criar uma segunda, pelo que repetir um pedido é seguro. A chave de API é devolvida uma única vez, na primeira criação; guardamos apenas um hash e não a podemos voltar a mostrar, por isso guarde-a quando a receber. Uma nova conta começa com saldo zero.

Se a chave inicial se perdeu, chame este endpoint com a chave da plataforma proprietária e sem corpo no pedido. Use o ID da conta ou o externalId. Revoga atomicamente as chaves anteriores da conta e devolve uma nova apiKey uma única vez (201). Guarde-a em segurança. Repetir esta chamada volta a substituir a chave; as novas tentativas normais de criação de conta nunca substituem uma chave que funciona.

Move créditos do seu próprio saldo para o da conta: é uma transferência, não uma oferta, pelo que só pode distribuir o que realmente comprou. Devolve 402 quando o seu saldo não chega. :accountId aceita o nosso ID de conta ou o seu externalId.

GET /api/v1/accounts lista as suas contas com o saldo e o gasto total de cada uma; GET /api/v1/accounts/:accountId/credits lê uma conta. A chave própria de uma conta gerida só tem âmbitos de geração; nunca pode criar nem financiar contas.

O Yoh disponibiliza um servidor MCP para que agentes de IA (Claude Code, Codex, Claude Desktop ou qualquer cliente MCP) possam criar e editar histórias na sua conta: escrever uma nova história a partir de uma ideia, adicionar as personagens e gerar o vídeo, ou alterar o conteúdo e o diálogo dos clipes, movimentos e cortes na linha temporal e sobreposições livres. Tudo o que gasta créditos aguarda sempre a sua aprovação explícita. Segue as mesmas regras do editor no navegador, pelo que uma edição feita no terminal fica exatamente onde ficaria com um arrastamento.

Três formas de o utilizar

Escolha a que melhor se adapta às ferramentas do seu agente. A skill do Yoh abaixo ensina as três.

• MCP + navegador (recomendado no Codex, Claude Code e nas apps Claude) O agente faz o trabalho através destas ferramentas MCP e controla um separador do navegador ao lado (Claude no Chrome, navegador do Codex): após cada passo, abre a ligação que vem na resposta (a tabela do guião após uma nova história, o painel do clipe após um vídeo de clipe, a lista Gerar tudo enquanto uma execução decorre, o editor avançado para a linha temporal e as camadas de texto, o MP4 da renderização) e verifica o resultado na página real. Inicie sessão uma vez nesse navegador com a mesma conta da chave de API. O MCP e a página partilham os mesmos dados: a página do episódio atualiza-se poucos segundos após uma alteração feita por MCP, e o agente recarrega o editor avançado após uma alteração na linha temporal. Cada gasto passa por um único caminho: o orçamento do MCP ou a janela de preço da app.
• Apenas navegador (sem chave de API) O agente usa as páginas de yoh.app no seu navegador, tal como o faria: Criar → História, a tabela do guião e o painel do clipe, o editor de personagens e o seletor de modelos, Gerar tudo, o editor avançado, versões e exportação. Cada gasto passa pela janela de preço da própria app, e o agente nunca escreve dados de pagamento nem o seu código de início de sessão.
• Apenas MCP (headless) Para scripts, CI e agências que criam muitas variantes: quote → confirmToken para cada gasto, consulta com get_job / get_run, paragem com cancel_generation, variantes com create_story_versions e generate_all_clips, e transferência do videoUrl de cada renderização terminada. Não é preciso navegador.

Exemplo em todos os modos: um anúncio de 16 segundos em 9:16 em inglês e japonês, escrito numa história com o seu produto, gerado, versionado para japonês e renderizado duas vezes.

Ligar

Recomendado: entre com o Yoh, sem chave de API. Use exatamente este endereço (yoh.app sem www redireciona, e o login confere o endereço). No Claude Code:

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

Depois digite /mcp, escolha yoh, depois Authenticate, entre no Yoh no navegador que abrir com a conta que você quer usar e aprove.

No Codex (CLI, extensão do IDE ou app de desktop do ChatGPT), adicione o servidor e entre; depois defina tool_timeout_sec = 300 em [mcp_servers.yoh] no ~/.codex/config.toml e reinicie o Codex:

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

• App de desktop do Claude ou claude.ai: Customize → Connectors → + Add → Add custom connector, chame de Yoh, cole o endereço, depois Connect e entre. Ative em cada chat por + → Connectors. Nos planos Team ou Enterprise, um proprietário adiciona primeiro.
• Cursor: adicione yoh com este endereço ao ~/.cursor/mcp.json e entre quando o Cursor pedir.
• ChatGPT: Plugins → + → Add custom MCP server, chame de Yoh, cole o endereço e entre. Alguns planos exigem que um administrador permita servidores personalizados.

Confira: peça ao seu agente para rodar get_credits; ele deve mostrar seu saldo no Yoh. Você vê e desconecta apps conectados em Configurações → Chaves de API → Apps conectados.

Para o seu agente ver as páginas que ele muda: Claude Code com claude --chrome (a extensão Claude in Chrome), o app de desktop do Claude com o conector Claude in Chrome, ou o Codex no app de desktop do ChatGPT com o navegador dele. O skill diz ao agente quando olhar.

Ou use uma chave de API (scripts, CI, apps sem login)

Crie uma chave de API em /api-keys. Para criar novas histórias e gerar vídeo, inclua stories:generate; para editar sem gastar, bastam stories:read e stories:write. Depois, no Claude Code:

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

Ou faça commit de uma configuração de projeto para que toda a equipa receba a ligação ao abrir o repositório, com cada membro a fornecer a sua própria chave via env:

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

No Codex, adicione o servidor a ~/.codex/config.toml e defina YOH_API_KEY na sua 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

Instalar a skill do Yoh

A skill ensina o seu agente a criar e editar bem uma história Yoh: começar numa série, orçamentar antes de gastar e observar os clipes antes de os julgar. É um ficheiro único, mantido atualizado com o servidor. Execute a linha para o seu agente, ou descarregar 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

Depois, basta pedir: “cria uma história de 60 segundos sobre uma enfermeira do turno da noite que ouve fantasmas” ou “aperta o ritmo do episódio 3: corta os tempos mortos, alinha as legendas com as batidas e volta a renderizar”. Execute /mcp no Claude Code ou no Codex para verificar a ligação.

O que o agente pode fazer

Como se mantém seguro e correto

• O servidor aplica as regras do editor (movimentos de slides, limites de corte, faixas de legendas, linhas de sobreposição) e responde a uma violação com o intervalo permitido em vez de restringir silenciosamente.
• O agente lê o conjunto completo de regras do recurso yoh://guide/timeline, e o prompt /mcp__yoh__edit-story fornece-lhe um fluxo de trabalho seguro.
• A geração é assíncrona: a maioria das ferramentas devolve um runId que o agente consulta com get_run; algumas (create_story, render_story, arte de personagem) devolvem um jobId para get_job, tal como na API REST.
• Defina um tempo de espera (timeout) longo no ficheiro .mcp.json (por exemplo 900000) para que uma renderização não expire no lado do cliente.

Verifique a sua ligação

O repositório inclui um teste de fumo (smoke test). Fala o protocolo real, põe as regras à prova e confirma que o bloqueio de gastos funciona; nunca gasta créditos e a sua única escrita é revertida:

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

Os endpoints de gestão de chaves de API usam session authentication (cookie do utilizador com sessão iniciada), não uma chave de API. Utilize a API Keys page para um fluxo no navegador ou chame estes endpoints programaticamente a partir do seu backend com uma sessão 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.

A maioria dos endpoints devolve um objeto error com um code legível por máquina. Endpoints especializados podem devolver um erro em formato de texto ou um código de nível superior; verifique sempre o estado HTTP.

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