@starreel/mcp 0.1.115 → 0.1.117

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/SKILL.md +16 -2
  2. package/dist/tools/guide-data.js +1 -1
  3. package/dist/tools/produce.js +15 -4
  4. package/openapi.json +263 -177
  5. package/package.json +1 -1
  6. package/server.json +2 -2
package/SKILL.md CHANGED
@@ -80,8 +80,8 @@ announces a condensed version as MCP `instructions` at connect time.
80
80
  | A novel / outline / synopsis (not yet a screenplay) | `set_script` → `rewrite_script` (creative rewrite builds hooks and beats) → `review_script` | — |
81
81
  | A finished screenplay (scene headers + dialogue lines) | `set_script` → `rewrite_script` (auto two-pass fidelity: dialogue byte-locked) → `review_script`; force with `rewrite_pipeline: "two_pass"`, `fidelity_enforce: 1` | pasting it into `edit_rewritten_script` (400) |
82
82
  | Wants to rewrite on another AI / says our rewrite "changed too much" | `get_script_format_spec` → external rewrite → `check_script_format` → `adopt_external_script` (exit A) or `set_script` + `rewrite_script` (exit B) | skipping the check; `edit_rewritten_script` |
83
- | A finished **shot list** (per-shot seconds / shot size / camera move) | `get_storyboard_table_spec` (the contract: shot-size / camera-move vocabulary, body layout, text-card syntax, a prompt for the external AI) → `check_storyboard_table` (same parser as the import; clear `errors`, read every `warning` — a missing duration, an unrecognised shot size or an empty body all get imported as-is) → `import_storyboard_table` (defaults to `auto_complete`: one background batch fills the professional fields and expands every shot's platform-built base description into full image / video prompts — metered text, tell the customer first; `auto_complete: false` imports only) → `get_autofill_status` until `done` → `review_storyboards` | `rewrite_script` + `generate_storyboards` — strips every production parameter (measured: 8 shots / 36 s became 20 shots / 109 s); importing without the check; reviewing before the completion batch finishes (the token expires when shots change) |
84
- | **Structured data** — their own tool / spreadsheet export, or an external AI producing JSON (cast + scenes + shots in one go) | `get_bulk_import_spec` (contract + template + worked example + enums, same source as the validator) → `check_bulk_import` (same zod schema; unresolved character / scene references, dead shots and stage directions inside dialogue are surfaced) → `bulk_import_storyboards` (`mode: "replace"` only with the customer's explicit OK; defaults to `auto_complete`: professional fields for every shot, full image / video prompts only for shots that had no `image_prompt` — prompts you supply yourself are kept verbatim — metered text, tell the customer first) → `get_autofill_status` until `done` → `review_storyboards` | converting the JSON to text for `import_storyboard_table`; hand-building shots with `update_shot`; reviewing before the completion batch finishes |
83
+ | A finished **shot list** (per-shot seconds / shot size / camera move) | `get_storyboard_table_spec` (the contract: shot-size / camera-move vocabulary, body layout, text-card syntax, a prompt for the external AI) → `check_storyboard_table` (same parser as the import; clear `errors`, read every `warning` — a missing duration, an unrecognised shot size or an empty body all get imported as-is) → `import_storyboard_table` (defaults to `auto_complete`: one background batch fills the professional fields and expands every shot's platform-built base description into full image / video prompts — metered text, tell the customer first; `auto_complete: false` imports only **and generates no composition contract** — read `contract_coverage` in the receipt and follow the remedy its `note` gives (normally `autofill_storyboards`) before generating frames) → `get_autofill_status` until `done` → `review_storyboards` | `rewrite_script` + `generate_storyboards` — strips every production parameter (measured: 8 shots / 36 s became 20 shots / 109 s); importing without the check; reviewing before the completion batch finishes (the token expires when shots change) |
84
+ | **Structured data** — their own tool / spreadsheet export, or an external AI producing JSON (cast + scenes + shots in one go) | `get_bulk_import_spec` (contract + template + worked example + enums, same source as the validator) → `check_bulk_import` (same zod schema; unresolved character / scene references, dead shots and stage directions inside dialogue are surfaced) → `bulk_import_storyboards` (`mode: "replace"` only with the customer's explicit OK; defaults to `auto_complete`: professional fields for every shot, full image / video prompts only for shots that had no `image_prompt` — prompts you supply yourself are kept verbatim — metered text, tell the customer first; `auto_complete: false` imports only **and generates no composition contract** (visible head count, person / body-part / prop subject and shot size are then only inferred from text) — read `contract_coverage` in the receipt and follow the remedy its `note` gives (normally `autofill_storyboards`) before generating frames) → `get_autofill_status` until `done` → `review_storyboards` | converting the JSON to text for `import_storyboard_table`; hand-building shots with `update_shot`; reviewing before the completion batch finishes |
85
85
  | Their own portraits / scene / prop / shot images | `upload_image` · `set_character_portrait` · `upload_scene_image` · `upload_prop_sheet` · `upload_shot_frame` — **check the image before uploading** (see *Customer-supplied images* below); after a portrait swap, `generate_character_sheet` for that character (the old sheet is invalidated and **not** regenerated automatically) | rendering a "fix" elsewhere and uploading it — use `generate_shot_frame`; uploading a group photo, a captioned/watermarked image, or a multi-view sheet as a portrait; uploading a scene photo with people in it |
86
86
  | Their own **footage** for a shot (screen recording, product b-roll, an existing clip) | `upload_shot_footage` → that shot is no longer AI-generated (frames/video skipped, final cut uses the clip as-is, duration written back from the clip); **it overwrites whatever AI video that shot already had**, and afterwards every AI video call on it (including `edit_video_shot`) is refused with **409** until you `clear_shot_footage` or pass `replace_user_footage: true` | pasting an externally AI-generated clip to "fix" a shot — it carries none of this film's identity / style anchors; use `regenerate_shot_video` instead |
87
87
  | A clip that should **drive the motion** of an AI shot (a blocking/previz pass, a dance or action reference) | `edit_video_shot` with `reference_video_urls` — the shot keeps its AI video and borrows the clip's movement. To make the clip itself the source and restyle it in place, `upload_shot_footage` it first, then `edit_video_shot` with `replace_user_footage: true` | `upload_shot_footage` alone — that registers the clip as the finished shot, so nothing gets restyled and every later AI call on it returns 409 |
@@ -324,6 +324,20 @@ content that will be rejected.
324
324
  **9.4%** of the time versus **40.2%** with one. `generate_shot_frame` does accept
325
325
  `allow_missing_terminal: true` for the rare shot that genuinely should barely change,
326
326
  but reach for the text fix first.
327
+ **If an emotional shot comes out with a blank, neutral face**, set the expression
328
+ explicitly: `update_shot` with `expression_hint` (one concrete sentence about the
329
+ face, ≤120 characters, written as what the face *does* — not "don't smile"), then
330
+ regenerate that shot's first frame (and its video). Without it the platform only
331
+ infers an expression from emotion words in the dialogue / atmosphere, which most
332
+ shots do not have — measured on 624 production shots with characters over 30 days,
333
+ **96 rated emotion intensity ≥7 still got no expression at all**. The hint always
334
+ overrides the inference in the **first-frame image** prompt and is read back by
335
+ `get_shot_prompts`. Two enhancements — delivering it as its own block the identity
336
+ locks do not discard, and sending it into the **video** prompt to hold the expression
337
+ through the clip — are **rolled out per drama and not yet on everywhere** (elsewhere the
338
+ video prompt does not carry it; the clip only inherits whatever face the first frame has),
339
+ so on other dramas the face may still come out flat: regenerate one first frame and
340
+ look before paying for more, and do not promise the customer it will take effect.
327
341
  **Then join the seams, before `review_frames`.** Each shot's first frame should pick
328
342
  up where the previous shot's last frame left off; otherwise the cut is a visible jump.
329
343
  The platform joins them automatically only when a batch runs from the website —
package/dist/tools/guide-data.js CHANGED
@@ -57,7 +57,7 @@ export const ENTRY_POINTS = [
57
57
  'import_storyboard_table(不传 content 则读本集原始内容;本集已有分镜要 confirm_replace:true)',
58
58
  ],
59
59
  avoid: '绝不走 set_script→rewrite_script→generate_storyboards:改写会把秒数/景别/运镜/STYLE/字卡当非剧情内容剥掉(生产实测 8 镜 36 秒被拆成 20 镜 109 秒)。',
60
- note: '导入默认带 auto_complete(后台 AI 填专业字段 + 把每镜基础描述扩写成出图/视频提示词,文本步后付、调用前告知客户;auto_complete:false 只导入)——回执 started 后用 `get_autofill_status` 轮询到 done 再 `review_storyboards`;`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲,不出图不出视频)。',
60
+ note: '导入默认带 auto_complete(后台 AI 填专业字段 + 把每镜基础描述扩写成出图/视频提示词,文本步后付、调用前告知客户;auto_complete:false 只导入,但**不会生成构图契约**,回执 contract_coverage 会报缺几镜和可行补法,按它的 note 处理)——回执 started 后用 `get_autofill_status` 轮询到 done 再 `review_storyboards`;`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲,不出图不出视频)。',
61
61
  free: false,
62
62
  flow: 'get_storyboard_table_spec → 外部工具按范本整理 → check_storyboard_table(errors 清零) → import_storyboard_table(默认 auto_complete) → get_autofill_status 到 done → review_storyboards',
63
63
  },
package/dist/tools/produce.js CHANGED
@@ -411,7 +411,7 @@ export function registerProduceTools(server, client) {
411
411
  '秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。' +
412
412
  '★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段' +
413
413
  '(镜头意图/节拍/潜台词/J-L cut/声线等,只填空)并把每镜由平台拼的基础描述扩写成完整出图/视频提示词——客户导完即可出图。' +
414
- '文本步按 token 后付,**调用前告知客户**;只想导入不补传 auto_complete:false。回执 auto_complete.started=true 后' +
414
+ '文本步按 token 后付,**调用前告知客户**;只想导入不补传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 auto_complete.started=true 后' +
415
415
  '用 get_autofill_status 轮询到 done(每镜数十秒)**再** review_storyboards——补全会改镜,先审查的 token 会失效。', {
416
416
  episode_id: z.number().int().positive(),
417
417
  content: z.string().optional().describe('分镜表全文;不传则用本集「原始内容」'),
@@ -458,7 +458,7 @@ export function registerProduceTools(server, client) {
458
458
  '★导入后:语速律会抬高装不下台词的镜(回执 speech_duration_raised / speech_duration_overflow)。' +
459
459
  '★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(只填空),' +
460
460
  '并只给**没填 image_prompt、由平台拼了基础描述**的镜扩写完整出图/视频提示词(客户自己写的绝不覆盖;回执 auto_complete.prompt_shots)。' +
461
- '文本步按 token 后付,**调用前告知客户**;只想导入传 auto_complete:false。回执 started=true 后用 get_autofill_status 轮询到 done **再** review_storyboards。', {
461
+ '文本步按 token 后付,**调用前告知客户**;只想导入传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 started=true 后用 get_autofill_status 轮询到 done **再** review_storyboards。', {
462
462
  episode_id: z.number().int().positive(),
463
463
  payload: z.record(z.string(), z.unknown()).describe('通过 check_bulk_import 的载荷对象:{ mode, episode_meta?, characters?, scenes?, storyboards }'),
464
464
  auto_complete: z.boolean().optional().describe('导入后自动补全(专业字段 + 平台拼基础描述的镜写出图/视频提示词;文本步后付)。不传=跟随剧目开关(默认开);false=只导入'),
@@ -684,7 +684,8 @@ export function registerProduceTools(server, client) {
684
684
  server.tool('review_all', '(推荐·免费)三层一次跑完的整体体检:剧本+分镜+镜头图片。开工前摸底、交付前复查用。' +
685
685
  '★它**不发 review_token** —— 进收费步前仍需对应层的 review_script / review_storyboards / review_frames 各跑一次' +
686
686
  '(闸认的是「针对当前产出物刚审过」,不是「审过一次」)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/all`)));
687
- server.tool('autofill_storyboards', '(推荐)AI 一键给全集分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付。', { episode_id: z.number().int().positive(), overwrite: z.boolean().optional().describe('true=覆盖已有字段(默认 false 只填空缺)') }, async ({ episode_id, overwrite }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/autofill`, overwrite ? { overwrite } : {})));
687
+ server.tool('autofill_storyboards', '(推荐)AI 一键给全集分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付。' +
688
+ '★平台开启契约自动补全时,也会尝试给**没有构图契约**的镜补上契约(是否开启以导入回执 contract_coverage 的 note 为准;可见人数/主体范围/景别,出图与审核都按它判;默认 overwrite:false 时已有契约不动,**overwrite:true 会连已有契约一起重写**)——导入时关了 auto_complete、回执 contract_coverage 的 note 指向本工具的,出图前调一次。本集已有补全在跑时本次**不排队**(防重复点击重复扣费),新导入的镜要等 get_autofill_status 到 done 后再调。', { episode_id: z.number().int().positive(), overwrite: z.boolean().optional().describe('true=覆盖已有字段(默认 false 只填空缺)') }, async ({ episode_id, overwrite }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/autofill`, overwrite ? { overwrite } : {})));
688
689
  server.tool('enhance_shot_prompts', '(可选增强·★非必须·有副作用)AI 批量增强全集 image_prompt。★会**改写已有 prompt**(含手调的);且**务必 generate_frames 之前**做——' +
689
690
  '出图后再改 prompt 会让图陈旧、要重生浪费钱。非跑通一部片的必需,客户点名再做。后台异步,文本步后付。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/enhance-prompts`)));
690
691
  server.tool('complete_ending_motifs', '(可选增强·★非必须·条件性)给结尾段补全缺失的视觉母题(嫁接视觉回响到结尾镜)。' +
@@ -1276,7 +1277,7 @@ export function registerProduceTools(server, client) {
1276
1277
  const suffix = qs.toString() ? `?${qs.toString()}` : '';
1277
1278
  return jsonResult(await client.produceGet(`/episodes/${episode_id}/dialogue-coverage${suffix}`));
1278
1279
  });
1279
- server.tool('update_shot', '逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、时长(duration)、成片变速(speed_factor)、角色绑定(character_ids)与画外音标记(character_presence)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。' +
1280
+ server.tool('update_shot', '逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、角色绑定(character_ids)与画外音标记(character_presence)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。' +
1280
1281
  '**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);' +
1281
1282
  '改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids)。' +
1282
1283
  '★★原声镜(厂商原生音频)改 dialogue 后,本镜视频会被标记「待重生」——因为台词是**烤进视频人声**的,' +
@@ -1324,6 +1325,13 @@ export function registerProduceTools(server, client) {
1324
1325
  video_prompt: z.string().optional().describe('视频(动态/运镜/表演)提示词**正文**(全量覆盖本镜现值)。★同 image_prompt:先读现值、保留 @char/@scene 标记'),
1325
1326
  first_frame_prompt: z.string().optional().describe('本镜**开始时**画面是什么样(首帧目标状态正文,全量覆盖现值)。送达提示词里作为 [START FRAME] 段排在最前,优先级高于 image_prompt——所以 image_prompt 改了不生效时,往往是这条在压着它。★同 image_prompt:先 get_shot_prompts 读现值、原样保留 @char/@scene 标记'),
1326
1327
  last_frame_prompt: z.string().optional().describe('本镜**结束时**画面是什么样(尾帧目标状态正文,全量覆盖现值)。送达提示词里作为 [END FRAME] 段。★★出尾帧被 TERMINAL_DESC_GATE 拦下时就是补这一条:写清结束时的状态(什么变了/变成什么样),再重新出尾帧。不补而直接重试必然重复被拒且照常扣费。get_shot_prompts 的 terminal_desc_missing=true 即本镜需要它'),
1328
+ expression_hint: z.string().max(120).nullable().optional().describe('本镜角色的**面部表情/神态**(≤120 字,一句具体的面部描述,如「眼眶泛红、强忍泪水、嘴角紧抿」)。' +
1329
+ '填了就**压过**平台按台词/氛围的反推——反推只有 7 种预设情绪、且台词里没有情绪词时什么都不加,剧本神态写在动作或旁白里的镜常常因此画成平静脸。' +
1330
+ '它总会压过平台反推并送进**出图**提示词;但「作为独立表情块送达、不被身份锁当成五官描述作废」与「送进视频提示词、整段保持首帧表情」两项**目前按剧灰度开放**' +
1331
+ '(未开放的剧,视频提示词里不会出现它,视频只能沿用首帧上的表情),' +
1332
+ '未开放的剧里写了也可能画不出来——花钱重生前先出一张首帧看效果,别向客户承诺一定生效。' +
1333
+ '★写正向的面部状态,别写「不要笑/不要哭」这类否定式(模型会把名词当正向线索)。★改完不会自动重出,要让画面跟上需重生本镜首帧再重生视频。' +
1334
+ '★超 120 字直接拒(不悄悄截断);null 或空串 = 清空,回到平台反推。现值用 get_shot_prompts 读'),
1327
1335
  }, async ({ storyboard_id, ...fields }) => {
1328
1336
  const payload = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
1329
1337
  return jsonResult(await client.producePut(`/storyboards/${storyboard_id}`, payload));
@@ -1332,6 +1340,9 @@ export function registerProduceTools(server, client) {
1332
1340
  'first_frame_prompt=开始时什么样 / last_frame_prompt=结束时什么样),供直接微调后用 update_shot 写回。免费。' +
1333
1341
  '★回执里的 terminal_desc_missing=true 表示本镜标为「状态改变」却三处都没说终态——' +
1334
1342
  '出尾帧会被前置闸拦下,修法是把结束状态写进 last_frame_prompt(别重试出图,重试必然重复被拒且照常扣费)。' +
1343
+ '★同时回 expression_hint(本镜作者指定的面部表情,null=未指定、由平台按台词反推),改它用 update_shot。' +
1344
+ 'expression_inferred 是拆镜 AI 在剧本没写神态时按本镜内容推断的表情(只读;null=没推断,或本镜台词/动作/氛围/描述/强度改过、推断已过期不再使用);它优先级低于 expression_hint——' +
1345
+ '推断不合意就用 update_shot 写 expression_hint 覆盖它。' +
1335
1346
  '★逐镜按需:改哪镜读哪镜(整集列表 get_storyboards 不含提示词)。' +
1336
1347
  '★返回的 asset_tokens 是正文里的补充参考标记(@char:N / @scene:M),改写时原样保留即可:' +
1337
1348
  '本镜注入谁的定妆图由绑定决定(get_storyboards 的 character_ids / scene_id),删标记不会让已绑定的人消失;' +
package/openapi.json CHANGED
@@ -2,8 +2,8 @@
2
2
  "openapi": "3.1.0",
3
3
  "info": {
4
4
  "title": "StarReel Production API",
5
- "version": "0.1.115",
6
- "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`). For video, quote == actual charge. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.115 tool surface (operationIds match MCP tool names 1:1)."
5
+ "version": "0.1.117",
6
+ "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`). For video, quote == actual charge. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.117 tool surface (operationIds match MCP tool names 1:1)."
7
7
  },
8
8
  "servers": [
9
9
  {
@@ -730,39 +730,46 @@
730
730
  "type": "string"
731
731
  },
732
732
  "creative_contract": {
733
- "type": "object",
734
- "properties": {
735
- "version": {
736
- "type": "number",
737
- "const": 1
738
- },
739
- "speech": {
740
- "type": "string",
741
- "enum": [
742
- "unspecified",
743
- "forbidden",
744
- "required"
745
- ]
746
- },
747
- "music": {
748
- "type": "string",
749
- "enum": [
750
- "unspecified",
751
- "forbidden"
752
- ]
733
+ "anyOf": [
734
+ {
735
+ "type": "object",
736
+ "properties": {
737
+ "version": {
738
+ "type": "number",
739
+ "const": 1
740
+ },
741
+ "speech": {
742
+ "type": "string",
743
+ "enum": [
744
+ "unspecified",
745
+ "forbidden",
746
+ "required"
747
+ ]
748
+ },
749
+ "music": {
750
+ "type": "string",
751
+ "enum": [
752
+ "unspecified",
753
+ "forbidden"
754
+ ]
755
+ },
756
+ "pacing": {
757
+ "type": "string",
758
+ "enum": [
759
+ "unspecified",
760
+ "quiet"
761
+ ]
762
+ }
763
+ },
764
+ "required": [
765
+ "version"
766
+ ],
767
+ "additionalProperties": false
753
768
  },
754
- "pacing": {
755
- "type": "string",
756
- "enum": [
757
- "unspecified",
758
- "quiet"
759
- ]
769
+ {
770
+ "type": "null"
760
771
  }
761
- },
762
- "required": [
763
- "version"
764
- ],
765
- "additionalProperties": false
772
+ ]
766
773
  },
767
774
  "image_model": {
768
775
  "type": "string"
@@ -1070,39 +1077,46 @@
1070
1077
  "type": "string"
1071
1078
  },
1072
1079
  "creative_contract": {
1073
- "type": "object",
1074
- "properties": {
1075
- "version": {
1076
- "type": "number",
1077
- "const": 1
1078
- },
1079
- "speech": {
1080
- "type": "string",
1081
- "enum": [
1082
- "unspecified",
1083
- "forbidden",
1084
- "required"
1085
- ]
1086
- },
1087
- "music": {
1088
- "type": "string",
1089
- "enum": [
1090
- "unspecified",
1091
- "forbidden"
1092
- ]
1080
+ "anyOf": [
1081
+ {
1082
+ "type": "object",
1083
+ "properties": {
1084
+ "version": {
1085
+ "type": "number",
1086
+ "const": 1
1087
+ },
1088
+ "speech": {
1089
+ "type": "string",
1090
+ "enum": [
1091
+ "unspecified",
1092
+ "forbidden",
1093
+ "required"
1094
+ ]
1095
+ },
1096
+ "music": {
1097
+ "type": "string",
1098
+ "enum": [
1099
+ "unspecified",
1100
+ "forbidden"
1101
+ ]
1102
+ },
1103
+ "pacing": {
1104
+ "type": "string",
1105
+ "enum": [
1106
+ "unspecified",
1107
+ "quiet"
1108
+ ]
1109
+ }
1110
+ },
1111
+ "required": [
1112
+ "version"
1113
+ ],
1114
+ "additionalProperties": false
1093
1115
  },
1094
- "pacing": {
1095
- "type": "string",
1096
- "enum": [
1097
- "unspecified",
1098
- "quiet"
1099
- ]
1116
+ {
1117
+ "type": "null"
1100
1118
  }
1101
- },
1102
- "required": [
1103
- "version"
1104
- ],
1105
- "additionalProperties": false
1119
+ ]
1106
1120
  },
1107
1121
  "image_model": {
1108
1122
  "type": "string"
@@ -3309,9 +3323,16 @@
3309
3323
  ]
3310
3324
  },
3311
3325
  "bgm_volume_db": {
3312
- "type": "number",
3313
- "minimum": -60,
3314
- "maximum": 0
3326
+ "anyOf": [
3327
+ {
3328
+ "type": "number",
3329
+ "minimum": -60,
3330
+ "maximum": 0
3331
+ },
3332
+ {
3333
+ "type": "null"
3334
+ }
3335
+ ]
3315
3336
  }
3316
3337
  }
3317
3338
  }
@@ -3611,9 +3632,16 @@
3611
3632
  "type": "object",
3612
3633
  "properties": {
3613
3634
  "gain_db": {
3614
- "type": "number",
3615
- "minimum": -60,
3616
- "maximum": 0
3635
+ "anyOf": [
3636
+ {
3637
+ "type": "number",
3638
+ "minimum": -60,
3639
+ "maximum": 0
3640
+ },
3641
+ {
3642
+ "type": "null"
3643
+ }
3644
+ ]
3617
3645
  },
3618
3646
  "fade_in_ms": {
3619
3647
  "type": "integer",
@@ -4053,8 +4081,15 @@
4053
4081
  "type": "object",
4054
4082
  "properties": {
4055
4083
  "delivery_id": {
4056
- "type": "integer",
4057
- "exclusiveMinimum": 0
4084
+ "anyOf": [
4085
+ {
4086
+ "type": "integer",
4087
+ "exclusiveMinimum": 0
4088
+ },
4089
+ {
4090
+ "type": "null"
4091
+ }
4092
+ ]
4058
4093
  },
4059
4094
  "client_accepted": {
4060
4095
  "type": "boolean"
@@ -4419,7 +4454,11 @@
4419
4454
  "type": "object",
4420
4455
  "properties": {
4421
4456
  "era": {
4422
- "type": "string"
4457
+ "type": [
4458
+ "string",
4459
+ "null"
4460
+ ],
4461
+ "description": "modern / republican / historical / fantasy(也收中文「现代 / 民国 / 古代 / 仙侠」)。传 null 清空本集契约"
4423
4462
  },
4424
4463
  "positive": {
4425
4464
  "type": "array",
@@ -6990,7 +7029,7 @@
6990
7029
  "post": {
6991
7030
  "operationId": "autofill_storyboards",
6992
7031
  "summary": "(推荐)AI 一键给全集分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)",
6993
- "description": "(推荐)AI 一键给全集分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付。",
7032
+ "description": "(推荐)AI 一键给全集分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付。★平台开启契约自动补全时,也会尝试给**没有构图契约**的镜补上契约(是否开启以导入回执 contract_coverage 的 note 为准;可见人数/主体范围/景别,出图与审核都按它判;默认 overwrite:false 时已有契约不动,**overwrite:true 会连已有契约一起重写**)——导入时关了 auto_complete、回执 contract_coverage 的 note 指向本工具的,出图前调一次。本集已有补全在跑时本次**不排队**(防重复点击重复扣费),新导入的镜要等 get_autofill_status 到 done 后再调。",
6994
7033
  "tags": [
6995
7034
  "episodes"
6996
7035
  ],
@@ -7052,7 +7091,7 @@
7052
7091
  "post": {
7053
7092
  "operationId": "bulk_import_storyboards",
7054
7093
  "summary": "把一份结构化 JSON 一次性建成本集的分镜(按 storyboard_number 去重更新)",
7055
- "description": "把一份结构化 JSON 一次性建成本集的分镜(按 storyboard_number 去重更新)。**不建角色/场景/道具**——它们由 extract_assets 从剧本提取,导入只按名字绑定已有的(回执 characters_unmatched / char_refs_unresolved 列出没绑上的;先 extract 再导)。免费·确定性·不调 AI。★三步走:① get_bulk_import_spec 取契约与成品示例;② check_bulk_import 自检到 errors 清零;③ 再调本工具。★mode=merge(默认)保留未提到的镜;mode=replace 替换本集**全部**分镜(旧镜与已生成图/视频归档可恢复、不会自动重挂)——replace 必须先得到客户明确同意。★image_prompt / video_prompt 想自己写就直接写在每镜里,**逐字照用不被覆盖**;没填的镜平台拼基础描述(回执 base_prompts_built 是拼了几镜),导入后可用 get_shot_prompts 读、update_shot 改。(frame_visual_contract 是内部帧契约,导入时忽略。)★导入后:语速律会抬高装不下台词的镜(回执 speech_duration_raised / speech_duration_overflow)。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(只填空),并只给**没填 image_prompt、由平台拼了基础描述**的镜扩写完整出图/视频提示词(客户自己写的绝不覆盖;回执 auto_complete.prompt_shots)。文本步按 token 后付,**调用前告知客户**;只想导入传 auto_complete:false。回执 started=true 后用 get_autofill_status 轮询到 done **再** review_storyboards。",
7094
+ "description": "把一份结构化 JSON 一次性建成本集的分镜(按 storyboard_number 去重更新)。**不建角色/场景/道具**——它们由 extract_assets 从剧本提取,导入只按名字绑定已有的(回执 characters_unmatched / char_refs_unresolved 列出没绑上的;先 extract 再导)。免费·确定性·不调 AI。★三步走:① get_bulk_import_spec 取契约与成品示例;② check_bulk_import 自检到 errors 清零;③ 再调本工具。★mode=merge(默认)保留未提到的镜;mode=replace 替换本集**全部**分镜(旧镜与已生成图/视频归档可恢复、不会自动重挂)——replace 必须先得到客户明确同意。★image_prompt / video_prompt 想自己写就直接写在每镜里,**逐字照用不被覆盖**;没填的镜平台拼基础描述(回执 base_prompts_built 是拼了几镜),导入后可用 get_shot_prompts 读、update_shot 改。(frame_visual_contract 是内部帧契约,导入时忽略。)★导入后:语速律会抬高装不下台词的镜(回执 speech_duration_raised / speech_duration_overflow)。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(只填空),并只给**没填 image_prompt、由平台拼了基础描述**的镜扩写完整出图/视频提示词(客户自己写的绝不覆盖;回执 auto_complete.prompt_shots)。文本步按 token 后付,**调用前告知客户**;只想导入传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 started=true 后用 get_autofill_status 轮询到 done **再** review_storyboards。",
7056
7095
  "tags": [
7057
7096
  "episodes"
7058
7097
  ],
@@ -7291,7 +7330,7 @@
7291
7330
  "post": {
7292
7331
  "operationId": "import_storyboard_table",
7293
7332
  "summary": "【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent",
7294
- "description": "【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent。免费。★三步走，别直接导：① get_storyboard_table_spec 取范本（景别/运镜白名单、正文落点、字卡语法、外部 AI 提示词）；② check_storyboard_table 自检到 errors 清零、逐条看 warnings（缺秒数/景别没认出/没画面叙述都会原样建进去）；③ 再调本工具。★什么时候用:客户交来的不是剧本而是成品分镜表(逐镜写了秒数/景别/运镜,常见于给电视台/品牌方的样片)。走 set_script→rewrite_script→generate_storyboards 那条路会把这些制作参数当非剧情内容剥掉(生产实测:8 镜 36 秒的表跑完变成 20 镜 109 秒,STYLE 块与数据卡全丢),所以这类客户必须走本工具。★声明格式(每镜一行,字段用 | 或全角 ｜ 分隔):`[镜 001 | 4s | 微距 | 固定]`,也认客户已有的加粗写法 `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(不必让客户重打一遍)。顺序 = 镜号|秒数|景别|运镜|标记;标记 `不切` 表示该镜绝不可再拆、`★` 表示关键镜;运镜的「横移」映射 tracking、「摇」映射 pan(两者在反光面上的倒影行为不同,别混)。`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲黑底卡,不出图不出视频)。★道具:`[道具] 名A、名B` 行按**本剧道具库里的道具名**绑定 prop_ids,正文里完整出现的道具名也自动绑;回执 prop_names_unresolved 列出没绑上的名字(先建道具再导,或改名)。★不传 content 时读本集「原始内容」。没有任何逐镜声明会被 400 拒(那是剧本不是分镜表,请走正常拆镜)。★本集已有分镜时返回 409 并告知镜数,确认要替换再带 confirm_replace:true(旧镜转已删除状态、可恢复)。秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(镜头意图/节拍/潜台词/J-L cut/声线等,只填空)并把每镜由平台拼的基础描述扩写成完整出图/视频提示词——客户导完即可出图。文本步按 token 后付,**调用前告知客户**;只想导入不补传 auto_complete:false。回执 auto_complete.started=true 后用 get_autofill_status 轮询到 done(每镜数十秒)**再** review_storyboards——补全会改镜,先审查的 token 会失效。",
7333
+ "description": "【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent。免费。★三步走，别直接导：① get_storyboard_table_spec 取范本（景别/运镜白名单、正文落点、字卡语法、外部 AI 提示词）；② check_storyboard_table 自检到 errors 清零、逐条看 warnings（缺秒数/景别没认出/没画面叙述都会原样建进去）；③ 再调本工具。★什么时候用:客户交来的不是剧本而是成品分镜表(逐镜写了秒数/景别/运镜,常见于给电视台/品牌方的样片)。走 set_script→rewrite_script→generate_storyboards 那条路会把这些制作参数当非剧情内容剥掉(生产实测:8 镜 36 秒的表跑完变成 20 镜 109 秒,STYLE 块与数据卡全丢),所以这类客户必须走本工具。★声明格式(每镜一行,字段用 | 或全角 ｜ 分隔):`[镜 001 | 4s | 微距 | 固定]`,也认客户已有的加粗写法 `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(不必让客户重打一遍)。顺序 = 镜号|秒数|景别|运镜|标记;标记 `不切` 表示该镜绝不可再拆、`★` 表示关键镜;运镜的「横移」映射 tracking、「摇」映射 pan(两者在反光面上的倒影行为不同,别混)。`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲黑底卡,不出图不出视频)。★道具:`[道具] 名A、名B` 行按**本剧道具库里的道具名**绑定 prop_ids,正文里完整出现的道具名也自动绑;回执 prop_names_unresolved 列出没绑上的名字(先建道具再导,或改名)。★不传 content 时读本集「原始内容」。没有任何逐镜声明会被 400 拒(那是剧本不是分镜表,请走正常拆镜)。★本集已有分镜时返回 409 并告知镜数,确认要替换再带 confirm_replace:true(旧镜转已删除状态、可恢复)。秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(镜头意图/节拍/潜台词/J-L cut/声线等,只填空)并把每镜由平台拼的基础描述扩写成完整出图/视频提示词——客户导完即可出图。文本步按 token 后付,**调用前告知客户**;只想导入不补传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 auto_complete.started=true 后用 get_autofill_status 轮询到 done(每镜数十秒)**再** review_storyboards——补全会改镜,先审查的 token 会失效。",
7295
7334
  "tags": [
7296
7335
  "episodes"
7297
7336
  ],
@@ -8185,8 +8224,16 @@
8185
8224
  "type": "object",
8186
8225
  "properties": {
8187
8226
  "variant_id": {
8188
- "type": "integer",
8189
- "exclusiveMinimum": 0
8227
+ "anyOf": [
8228
+ {
8229
+ "type": "integer",
8230
+ "exclusiveMinimum": 0
8231
+ },
8232
+ {
8233
+ "type": "null"
8234
+ }
8235
+ ],
8236
+ "description": "传 null 解除关联"
8190
8237
  }
8191
8238
  },
8192
8239
  "required": [
@@ -8955,31 +9002,38 @@
8955
9002
  "type": "string"
8956
9003
  },
8957
9004
  "era_contract": {
8958
- "type": "object",
8959
- "properties": {
8960
- "era": {
8961
- "type": "string",
8962
- "description": "modern / republican / historical / fantasy(也收中文「现代 / 民国 / 古代 / 仙侠」)"
8963
- },
8964
- "positive": {
8965
- "type": "array",
8966
- "items": {
8967
- "type": "string"
9005
+ "anyOf": [
9006
+ {
9007
+ "type": "object",
9008
+ "properties": {
9009
+ "era": {
9010
+ "type": "string",
9011
+ "description": "modern / republican / historical / fantasy(也收中文「现代 / 民国 / 古代 / 仙侠」)"
9012
+ },
9013
+ "positive": {
9014
+ "type": "array",
9015
+ "items": {
9016
+ "type": "string"
9017
+ },
9018
+ "description": "本场额外的正向约束(可留空,平台自带该档基线)"
9019
+ },
9020
+ "negative": {
9021
+ "type": "array",
9022
+ "items": {
9023
+ "type": "string"
9024
+ },
9025
+ "description": "本场额外的禁止项(可留空)"
9026
+ }
8968
9027
  },
8969
- "description": "本场额外的正向约束(可留空,平台自带该档基线)"
9028
+ "required": [
9029
+ "era"
9030
+ ],
9031
+ "additionalProperties": false
8970
9032
  },
8971
- "negative": {
8972
- "type": "array",
8973
- "items": {
8974
- "type": "string"
8975
- },
8976
- "description": "本场额外的禁止项(可留空)"
9033
+ {
9034
+ "type": "null"
8977
9035
  }
8978
- },
8979
- "required": [
8980
- "era"
8981
- ],
8982
- "additionalProperties": false
9036
+ ]
8983
9037
  }
8984
9038
  }
8985
9039
  }
@@ -9474,8 +9528,8 @@
9474
9528
  "/storyboards/{storyboard_id}": {
9475
9529
  "put": {
9476
9530
  "operationId": "update_shot",
9477
- "summary": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、时长(duration)、成片变速(speed_factor)、角色绑定(character_ids)与画外音标记(character_presence)",
9478
- "description": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、时长(duration)、成片变速(speed_factor)、角色绑定(character_ids)与画外音标记(character_presence)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids)。★★原声镜(厂商原生音频)改 dialogue 后,本镜视频会被标记「待重生」——因为台词是**烤进视频人声**的,不重生就终拼,成片里念的仍是改动前的台词(典型现象:台词像是跑到了别的镜头上)。compose_episode 会以 advisory `stale_video_after_edit` 列出这些镜;正确处置是先 regenerate_shot_video 再终拼。★也可直接改本镜的四条提示词正文(image_prompt/video_prompt/first_frame_prompt/last_frame_prompt):改前先用 get_shot_prompts 读现值,别凭空覆盖——正文里的 @char:N / @scene:M 是出图时的补充参考标记,照原样保留即可。★注入谁的定妆图由 character_ids 决定、背景由 scene_id 决定:删标记不会让已绑定的人从画面消失,要让某人不出现就改 character_ids,他只有声音(画外音)就用 character_presence 标 voice_only;反过来别给未绑定的角色写 @char 标记——会把他的图注入进来。★★【出尾帧被拦下就是来改这里】出尾帧若报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」(TERMINAL_DESC_GATE),修法是把**结束时画面是什么样**写进本镜 last_frame_prompt,然后重新出尾帧。别去重试出图——这类镜(action_motion_class=state_change 却没写终态)的尾帧历史成功率 9.4%,有终态描述的是 40.2%;不补描述就重生,送厂商的提示词里根本没有终态段,画出来仍和首帧一样、还是会被拒,而每次重生都照常扣费。get_shot_prompts 的 terminal_desc_missing=true 就是这个信号。",
9531
+ "summary": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、角色绑定(character_ids)与画外音标记(chara",
9532
+ "description": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、角色绑定(character_ids)与画外音标记(character_presence)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids)。★★原声镜(厂商原生音频)改 dialogue 后,本镜视频会被标记「待重生」——因为台词是**烤进视频人声**的,不重生就终拼,成片里念的仍是改动前的台词(典型现象:台词像是跑到了别的镜头上)。compose_episode 会以 advisory `stale_video_after_edit` 列出这些镜;正确处置是先 regenerate_shot_video 再终拼。★也可直接改本镜的四条提示词正文(image_prompt/video_prompt/first_frame_prompt/last_frame_prompt):改前先用 get_shot_prompts 读现值,别凭空覆盖——正文里的 @char:N / @scene:M 是出图时的补充参考标记,照原样保留即可。★注入谁的定妆图由 character_ids 决定、背景由 scene_id 决定:删标记不会让已绑定的人从画面消失,要让某人不出现就改 character_ids,他只有声音(画外音)就用 character_presence 标 voice_only;反过来别给未绑定的角色写 @char 标记——会把他的图注入进来。★★【出尾帧被拦下就是来改这里】出尾帧若报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」(TERMINAL_DESC_GATE),修法是把**结束时画面是什么样**写进本镜 last_frame_prompt,然后重新出尾帧。别去重试出图——这类镜(action_motion_class=state_change 却没写终态)的尾帧历史成功率 9.4%,有终态描述的是 40.2%;不补描述就重生,送厂商的提示词里根本没有终态段,画出来仍和首帧一样、还是会被拒,而每次重生都照常扣费。get_shot_prompts 的 terminal_desc_missing=true 就是这个信号。",
9479
9533
  "tags": [
9480
9534
  "storyboards"
9481
9535
  ],
@@ -9498,89 +9552,96 @@
9498
9552
  "type": "object",
9499
9553
  "properties": {
9500
9554
  "product_text_contract": {
9501
- "type": "object",
9502
- "properties": {
9503
- "version": {
9504
- "type": "number",
9505
- "const": 1
9506
- },
9507
- "strategy": {
9508
- "type": "string",
9509
- "enum": [
9510
- "generate_with_review",
9511
- "original_media",
9512
- "postproduction"
9513
- ]
9514
- },
9515
- "targets": {
9516
- "type": "array",
9517
- "items": {
9518
- "type": "object",
9519
- "properties": {
9520
- "asset_kind": {
9521
- "type": "string",
9522
- "enum": [
9523
- "prop",
9524
- "product"
9525
- ]
9526
- },
9527
- "asset_id": {
9528
- "type": "integer",
9529
- "exclusiveMinimum": 0
9530
- },
9531
- "reference_url": {
9532
- "type": "string",
9533
- "format": "uri"
9534
- },
9535
- "region": {
9555
+ "anyOf": [
9556
+ {
9557
+ "type": "object",
9558
+ "properties": {
9559
+ "version": {
9560
+ "type": "number",
9561
+ "const": 1
9562
+ },
9563
+ "strategy": {
9564
+ "type": "string",
9565
+ "enum": [
9566
+ "generate_with_review",
9567
+ "original_media",
9568
+ "postproduction"
9569
+ ]
9570
+ },
9571
+ "targets": {
9572
+ "type": "array",
9573
+ "items": {
9536
9574
  "type": "object",
9537
9575
  "properties": {
9538
- "x": {
9539
- "type": "number"
9576
+ "asset_kind": {
9577
+ "type": "string",
9578
+ "enum": [
9579
+ "prop",
9580
+ "product"
9581
+ ]
9582
+ },
9583
+ "asset_id": {
9584
+ "type": "integer",
9585
+ "exclusiveMinimum": 0
9540
9586
  },
9541
- "y": {
9542
- "type": "number"
9587
+ "reference_url": {
9588
+ "type": "string",
9589
+ "format": "uri"
9543
9590
  },
9544
- "width": {
9545
- "type": "number"
9591
+ "region": {
9592
+ "type": "object",
9593
+ "properties": {
9594
+ "x": {
9595
+ "type": "number"
9596
+ },
9597
+ "y": {
9598
+ "type": "number"
9599
+ },
9600
+ "width": {
9601
+ "type": "number"
9602
+ },
9603
+ "height": {
9604
+ "type": "number"
9605
+ }
9606
+ },
9607
+ "required": [
9608
+ "x",
9609
+ "y",
9610
+ "width",
9611
+ "height"
9612
+ ],
9613
+ "additionalProperties": false
9546
9614
  },
9547
- "height": {
9548
- "type": "number"
9615
+ "exact_text": {
9616
+ "type": "string",
9617
+ "minLength": 1,
9618
+ "maxLength": 256
9549
9619
  }
9550
9620
  },
9551
9621
  "required": [
9552
- "x",
9553
- "y",
9554
- "width",
9555
- "height"
9622
+ "asset_kind",
9623
+ "asset_id",
9624
+ "reference_url",
9625
+ "region",
9626
+ "exact_text"
9556
9627
  ],
9557
9628
  "additionalProperties": false
9558
9629
  },
9559
- "exact_text": {
9560
- "type": "string",
9561
- "minLength": 1,
9562
- "maxLength": 256
9563
- }
9564
- },
9565
- "required": [
9566
- "asset_kind",
9567
- "asset_id",
9568
- "reference_url",
9569
- "region",
9570
- "exact_text"
9571
- ],
9572
- "additionalProperties": false
9630
+ "minItems": 1,
9631
+ "maxItems": 4
9632
+ }
9573
9633
  },
9574
- "minItems": 1,
9575
- "maxItems": 4
9634
+ "required": [
9635
+ "version",
9636
+ "strategy",
9637
+ "targets"
9638
+ ],
9639
+ "additionalProperties": false
9640
+ },
9641
+ {
9642
+ "type": "null"
9576
9643
  }
9577
- },
9578
- "required": [
9579
- "version",
9580
- "strategy",
9581
- "targets"
9582
- ],
9583
- "additionalProperties": false
9644
+ ]
9584
9645
  },
9585
9646
  "continuity_intent": {
9586
9647
  "type": "string",
@@ -9663,8 +9724,15 @@
9663
9724
  "exclusiveMinimum": 0
9664
9725
  },
9665
9726
  "speed_factor": {
9666
- "type": "number",
9667
- "exclusiveMinimum": 0
9727
+ "anyOf": [
9728
+ {
9729
+ "type": "number",
9730
+ "exclusiveMinimum": 0
9731
+ },
9732
+ {
9733
+ "type": "null"
9734
+ }
9735
+ ]
9668
9736
  },
9669
9737
  "image_prompt": {
9670
9738
  "type": "string"
@@ -9677,6 +9745,17 @@
9677
9745
  },
9678
9746
  "last_frame_prompt": {
9679
9747
  "type": "string"
9748
+ },
9749
+ "expression_hint": {
9750
+ "anyOf": [
9751
+ {
9752
+ "type": "string",
9753
+ "maxLength": 120
9754
+ },
9755
+ {
9756
+ "type": "null"
9757
+ }
9758
+ ]
9680
9759
  }
9681
9760
  }
9682
9761
  }
@@ -10727,8 +10806,15 @@
10727
10806
  ]
10728
10807
  },
10729
10808
  "generation_id": {
10730
- "type": "integer",
10731
- "exclusiveMinimum": 0
10809
+ "anyOf": [
10810
+ {
10811
+ "type": "integer",
10812
+ "exclusiveMinimum": 0
10813
+ },
10814
+ {
10815
+ "type": "null"
10816
+ }
10817
+ ]
10732
10818
  },
10733
10819
  "media_version": {
10734
10820
  "type": "string"
@@ -10797,7 +10883,7 @@
10797
10883
  "get": {
10798
10884
  "operationId": "get_shot_prompts",
10799
10885
  "summary": "读某一镜的四条提示词**正文**(image_prompt=首帧画面 / video_prompt=动态表演 / first_frame_prompt=开始时什么样 / last_frame_prompt=结束时什么样),供直接微调后用 u",
10800
- "description": "读某一镜的四条提示词**正文**(image_prompt=首帧画面 / video_prompt=动态表演 / first_frame_prompt=开始时什么样 / last_frame_prompt=结束时什么样),供直接微调后用 update_shot 写回。免费。★回执里的 terminal_desc_missing=true 表示本镜标为「状态改变」却三处都没说终态——出尾帧会被前置闸拦下,修法是把结束状态写进 last_frame_prompt(别重试出图,重试必然重复被拒且照常扣费)。★逐镜按需:改哪镜读哪镜(整集列表 get_storyboards 不含提示词)。★返回的 asset_tokens 是正文里的补充参考标记(@char:N / @scene:M),改写时原样保留即可:本镜注入谁的定妆图由绑定决定(get_storyboards 的 character_ids / scene_id),删标记不会让已绑定的人消失;带 #变体 的标记是那张变体图的唯一来源;给未绑定的角色写标记会把他的图注入进来。★这是分镜表里的正文层;出图/出视频时平台还会在其上拼身份锚、一致性约束与参考图指令(不在此处,也无需你写)。改完提示词不会自动重出图/视频,要让画面跟上得再 regen 对应镜。",
10886
+ "description": "读某一镜的四条提示词**正文**(image_prompt=首帧画面 / video_prompt=动态表演 / first_frame_prompt=开始时什么样 / last_frame_prompt=结束时什么样),供直接微调后用 update_shot 写回。免费。★回执里的 terminal_desc_missing=true 表示本镜标为「状态改变」却三处都没说终态——出尾帧会被前置闸拦下,修法是把结束状态写进 last_frame_prompt(别重试出图,重试必然重复被拒且照常扣费)。★同时回 expression_hint(本镜作者指定的面部表情,null=未指定、由平台按台词反推),改它用 update_shot。expression_inferred 是拆镜 AI 在剧本没写神态时按本镜内容推断的表情(只读;null=没推断,或本镜台词/动作/氛围/描述/强度改过、推断已过期不再使用);它优先级低于 expression_hint——推断不合意就用 update_shot 写 expression_hint 覆盖它。★逐镜按需:改哪镜读哪镜(整集列表 get_storyboards 不含提示词)。★返回的 asset_tokens 是正文里的补充参考标记(@char:N / @scene:M),改写时原样保留即可:本镜注入谁的定妆图由绑定决定(get_storyboards 的 character_ids / scene_id),删标记不会让已绑定的人消失;带 #变体 的标记是那张变体图的唯一来源;给未绑定的角色写标记会把他的图注入进来。★这是分镜表里的正文层;出图/出视频时平台还会在其上拼身份锚、一致性约束与参考图指令(不在此处,也无需你写)。改完提示词不会自动重出图/视频,要让画面跟上得再 regen 对应镜。",
10801
10887
  "tags": [
10802
10888
  "storyboards"
10803
10889
  ],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starreel/mcp",
3
- "version": "0.1.115",
3
+ "version": "0.1.117",
4
4
  "mcpName": "ai.starreel/starreel",
5
5
  "description": "StarReel MCP server — drive the AI short-drama production pipeline (script → storyboards → frames → video → final cut) from Claude, Cursor, or any MCP client",
6
6
  "license": "MIT",
package/server.json CHANGED
@@ -2,13 +2,13 @@
2
2
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
3
3
  "name": "ai.starreel/starreel",
4
4
  "description": "Turn a script into a finished, downloadable short-drama episode — via MCP or REST.",
5
- "version": "0.1.115",
5
+ "version": "0.1.117",
6
6
  "websiteUrl": "https://starreel.ai",
7
7
  "packages": [
8
8
  {
9
9
  "registryType": "npm",
10
10
  "identifier": "@starreel/mcp",
11
- "version": "0.1.115",
11
+ "version": "0.1.117",
12
12
  "transport": {
13
13
  "type": "stdio"
14
14
  },