@starreel/mcp 0.1.45 → 0.1.47
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.
- package/SKILL.md +57 -4
- package/dist/tools/produce.js +75 -15
- package/openapi.json +232 -8
- package/package.json +1 -1
- package/server.json +2 -2
package/SKILL.md
CHANGED
|
@@ -4,7 +4,7 @@ description: >-
|
|
|
4
4
|
Operating skill for any AI agent driving the StarReel short-drama production
|
|
5
5
|
pipeline (script → rewrite → extract → portraits + sheets → storyboards → frames →
|
|
6
6
|
video → voiceover → final cut) over MCP or REST. Covers the ordered workflow,
|
|
7
|
-
the
|
|
7
|
+
the eleven operating disciplines (prepaid billing, quote-before-spend, retryable
|
|
8
8
|
failure handling, content compliance, tenancy), and a failure playbook.
|
|
9
9
|
license: MIT
|
|
10
10
|
homepage: https://api.shortreelai.com/docs/mcp
|
|
@@ -28,10 +28,15 @@ One episode, the **full** pipeline — nothing skipped:
|
|
|
28
28
|
|
|
29
29
|
```
|
|
30
30
|
create_drama → set_script(raw) → rewrite_script(AI draft, user may edit)
|
|
31
|
-
→ extract_assets(cast/scenes/props)
|
|
32
|
-
→ storyboards →
|
|
31
|
+
→ [review_script] → extract_assets(cast/scenes/props)
|
|
32
|
+
→ storyboards → [review_storyboards]
|
|
33
|
+
→ generate_portraits_and_sheets(portraits + sheets = the shot consistency anchor)
|
|
34
|
+
→ frames → [review_frames] → videos → generate_tts(voiceover) → compose_episode → final cut (.mp4 link)
|
|
33
35
|
```
|
|
34
36
|
|
|
37
|
+
The three `[review_*]` steps are free and **enforced** — see discipline 11.
|
|
38
|
+
Nothing downstream of them runs until you have reviewed that layer.
|
|
39
|
+
|
|
35
40
|
`project_type` picks the flavor at `create_drama`: `drama` / `ad` / `mv` /
|
|
36
41
|
`brand_film`. MV replaces `rewrite_script` with
|
|
37
42
|
`set_mv_lyrics → generate_mv_story → generate_mv_script`, then rejoins the
|
|
@@ -77,7 +82,7 @@ Don't ask the user at every step. Sort work into three tiers:
|
|
|
77
82
|
and show a quote, then run on their OK** — neither silently skip them nor
|
|
78
83
|
auto-charge.
|
|
79
84
|
|
|
80
|
-
## The
|
|
85
|
+
## The eleven disciplines (hard rules)
|
|
81
86
|
|
|
82
87
|
These are not suggestions. Violating them wastes the user's money or produces
|
|
83
88
|
content that will be rejected.
|
|
@@ -166,6 +171,18 @@ content that will be rejected.
|
|
|
166
171
|
on hailuo-3 / wan3.0 / wan3.0-prime — `edit_video_shot` rejects
|
|
167
172
|
`start_sec`/`end_sec` on them. `edit_video_shot` also takes a per-call
|
|
168
173
|
`model` so one shot can be edited on a different engine than the drama's.
|
|
174
|
+
**How to choose (guide the customer proactively)**: ① realistic live-action
|
|
175
|
+
dramas → `seedance-2.5` (best instruction-following and face detail), or
|
|
176
|
+
`hailuo-3` to cut cost to ~1/3 (slower, ~6 min/shot); ② stylized / animated /
|
|
177
|
+
3D-cartoon dramas, empty shots and product shots → `wan3.0` (~40% cost,
|
|
178
|
+
2s-minimum billing), or `wan3.0-prime` when delivery speed matters;
|
|
179
|
+
③ NEVER pick wan3.0/prime for realistic live-action — WAN's output
|
|
180
|
+
moderation consistently rejects realistic human faces at 720p+ and retries
|
|
181
|
+
don't help. **Resolution by engine** (`video_resolution`): drafts/iteration →
|
|
182
|
+
480p on WAN dramas (cheapest) or 720p elsewhere; final delivery →
|
|
183
|
+
seedance stays 720p (HD tiers off sale), hailuo-3 → 1080p (= 2K, 112 pts/s),
|
|
184
|
+
WAN → 1080p (168 pts/s). hailuo-3 has no separate 480p tier (a 480p request
|
|
185
|
+
still bills at 768P).
|
|
169
186
|
**Set the drama engine before generating any video**:
|
|
170
187
|
switching never re-renders existing shots, and mixing engines inside one
|
|
171
188
|
drama risks style/identity drift.
|
|
@@ -202,6 +219,42 @@ content that will be rejected.
|
|
|
202
219
|
key in an environment variable or secrets manager, never in code or logs.
|
|
203
220
|
The 15-min token auto-re-exchanges; a leaked key is revoked in Settings.
|
|
204
221
|
|
|
222
|
+
11. **Review every layer before you spend on the next one — free, and three of
|
|
223
|
+
them are enforced.** Never run the pipeline straight through from
|
|
224
|
+
`rewrite_script` to `compose_episode`. A flaw in the rewritten draft gets
|
|
225
|
+
copied into character profiles, then storyboards, then frames, then video —
|
|
226
|
+
by the time you see it in the final cut, the whole episode has to be redone,
|
|
227
|
+
and every redo is another real charge. Reviewing costs nothing.
|
|
228
|
+
|
|
229
|
+
**Three hard gates** (the server returns `400` if you skip them):
|
|
230
|
+
|
|
231
|
+
| After you produce | Run | Before you call |
|
|
232
|
+
|---|---|---|
|
|
233
|
+
| the rewritten draft | `review_script` | `extract_assets`, `generate_storyboards` |
|
|
234
|
+
| storyboards | `review_storyboards` | `generate_frames` |
|
|
235
|
+
| shot frames | `review_frames` | `generate_videos` |
|
|
236
|
+
|
|
237
|
+
Each review returns `{ pass, error_count, warning_count, findings[],
|
|
238
|
+
review_token }`. Every finding carries `code` (problem type), `shots`
|
|
239
|
+
(which shot numbers), and `action` (which tool fixes it) — relay them to the
|
|
240
|
+
user verbatim, fix per `action`, then re-review. Pass the `review_token` to
|
|
241
|
+
the downstream `generate_*` call. If the artifact changes after the review,
|
|
242
|
+
the token expires by design — just re-review (still free). When a review has
|
|
243
|
+
errors the gate holds; only pass `acknowledge_review: true` when the user
|
|
244
|
+
knows what's wrong and explicitly chooses to proceed anyway. Never make that
|
|
245
|
+
call for them.
|
|
246
|
+
|
|
247
|
+
**Soft checkpoints** (not enforced, also free, still expected): `run_precheck`
|
|
248
|
+
before any image or video generation (it catches shots the vendor will
|
|
249
|
+
reject — pure wasted spend otherwise); `get_health_report` after
|
|
250
|
+
storyboards; `get_characters` after portraits to confirm every on-screen
|
|
251
|
+
character has an image and a sheet; `get_storyboards` after frames and after
|
|
252
|
+
videos to read `frame_status` / `video_status` / `fail_reason` / `fail_hint`
|
|
253
|
+
and fix failed shots before moving on; `get_pipeline_status` before the
|
|
254
|
+
final cut to confirm no shot is missing. `review_all` gives a whole-episode
|
|
255
|
+
checkup at any time (it issues no token — the gates want a review of the
|
|
256
|
+
*current* artifact).
|
|
257
|
+
|
|
205
258
|
## Script fidelity — auto two-pass rewriting
|
|
206
259
|
|
|
207
260
|
`rewrite_script` routes automatically based on what the user put into
|
package/dist/tools/produce.js
CHANGED
|
@@ -37,6 +37,19 @@ function jsonResult(data) {
|
|
|
37
37
|
}
|
|
38
38
|
const CONFIRM_HINT = '⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,' +
|
|
39
39
|
'用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。';
|
|
40
|
+
// ★分阶段审查硬闸(v0.9.1076):三个大额收费步必须先过本层审查才放行。
|
|
41
|
+
// 设计意图=防「盲推产废片」:改写稿的问题会被资产/分镜/出图逐层放大,等成片才发现
|
|
42
|
+
// 就是整集重来、且每次重来都真扣厂商的钱。审查全部免费,拦下来不花一分钱。
|
|
43
|
+
const REVIEW_GATE_HINT = (tool, layer) => `\n★【${layer}审查硬闸·免费】本步前必须先调 ${tool}:把返回的 findings 逐条原样告诉客户` +
|
|
44
|
+
`(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。` +
|
|
45
|
+
`未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。` +
|
|
46
|
+
`有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——` +
|
|
47
|
+
`带病推进大概率产出废片且照常扣费,不要替客户做这个决定。`;
|
|
48
|
+
/** 三个被闸的收费工具共用的参数(zod 形状,展开进各自 schema)。 */
|
|
49
|
+
const REVIEW_ARGS = {
|
|
50
|
+
review_token: z.string().optional().describe('★来自本层 review_* 工具的凭据(受闸项目必填;缺了会 400 并告诉你该调哪个审查工具)'),
|
|
51
|
+
acknowledge_review: z.boolean().optional().describe('审查有 error 时,客户已知情并明确要求照现状继续才传 true(默认拦截)'),
|
|
52
|
+
};
|
|
40
53
|
// 完整工作流顺序(照 get_pipeline_status 的 10 步真相走,不要跳步):
|
|
41
54
|
// create_drama → set_script(原始) → rewrite_script(AI改写) → [get_script/edit_rewritten_script 审改]
|
|
42
55
|
// → extract_assets(角色/场景/道具) → quote/generate_storyboards(先分镜·纯文本拆镜)
|
|
@@ -50,7 +63,19 @@ const WORKFLOW_HINT = '★三档执行策略(别把三档混着问客户):' +
|
|
|
50
63
|
'★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——' +
|
|
51
64
|
'角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,' +
|
|
52
65
|
'定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。' +
|
|
53
|
-
'
|
|
66
|
+
'★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。' +
|
|
67
|
+
'**三道硬闸(不过会被 400 拒)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);' +
|
|
68
|
+
'②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。' +
|
|
69
|
+
'每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),' +
|
|
70
|
+
'按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。' +
|
|
71
|
+
'有 error 时默认拦截,只有客户明确知情并坚持才带 acknowledge_review:true——别替客户做这个决定。' +
|
|
72
|
+
'**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱);' +
|
|
73
|
+
'分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;' +
|
|
74
|
+
'出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);' +
|
|
75
|
+
'出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。' +
|
|
76
|
+
'★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——' +
|
|
77
|
+
'而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。' +
|
|
78
|
+
'②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→' +
|
|
54
79
|
'★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——' +
|
|
55
80
|
'把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。' +
|
|
56
81
|
'改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——' +
|
|
@@ -59,7 +84,7 @@ const WORKFLOW_HINT = '★三档执行策略(别把三档混着问客户):' +
|
|
|
59
84
|
'且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改' +
|
|
60
85
|
'(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;' +
|
|
61
86
|
'误重跑用 get_script(include_previous=1) 回捞上一版。' +
|
|
62
|
-
'generate_portraits_and_sheets(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→videos→generate_tts→compose;' +
|
|
87
|
+
'generate_portraits_and_sheets(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→★review_frames→videos→generate_tts→compose;' +
|
|
63
88
|
'★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;资产在分镜后建更省更准(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。' +
|
|
64
89
|
'广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script。' +
|
|
65
90
|
'★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,' +
|
|
@@ -72,11 +97,12 @@ const WORKFLOW_HINT = '★三档执行策略(别把三档混着问客户):' +
|
|
|
72
97
|
'建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。' +
|
|
73
98
|
'★图片模型默认香蕉2(Nano Banana 2 = gemini-3.1-flash-image·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认香蕉2;' +
|
|
74
99
|
'可选 gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0)/gpt-image-2(ChatGPT Image2);generate_frames 可临时覆盖某次。' +
|
|
75
|
-
'★视频引擎四选一(drama级·AI
|
|
76
|
-
'hailuo-3(
|
|
77
|
-
'wan3.0(
|
|
78
|
-
'wan3.0
|
|
79
|
-
'
|
|
100
|
+
'★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):' +
|
|
101
|
+
'【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);' +
|
|
102
|
+
'②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);' +
|
|
103
|
+
'③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;' +
|
|
104
|
+
'【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);' +
|
|
105
|
+
'create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。' +
|
|
80
106
|
'★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。' +
|
|
81
107
|
'★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);' +
|
|
82
108
|
'generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是"拒绝"),尾帧用 frame_type=last_frame 可批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。' +
|
|
@@ -116,7 +142,7 @@ const PROJECT_SETTINGS_FIELDS = {
|
|
|
116
142
|
'gemini-3.1-flash-image(香蕉2·默认·71点)/gemini-3-pro-image(香蕉Pro·精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·31点)/' +
|
|
117
143
|
'doubao-seedream-5-0-260128(Seedream 5.0)/gpt-image-2(ChatGPT Image 2)。建剧即定、整剧统一;generate_frames 可临时覆盖某次出图'),
|
|
118
144
|
// drama 级视频引擎(整剧统一,单镜/批量/场景组/重生全走它)
|
|
119
|
-
video_engine: z.enum(VIDEO_ENGINES).optional().describe('视频引擎(★drama级·整剧统一·AI
|
|
145
|
+
video_engine: z.enum(VIDEO_ENGINES).optional().describe('视频引擎(★drama级·整剧统一·AI必须按剧选型主动引导:写实真人剧→seedance-2.5 或降本 hailuo-3;风格化/动画/3D卡通/空镜/产品镜→wan3.0(赶交付 wan3.0-prime);写实真人剧绝不选 wan——720p+ 真人脸被厂商审核一致拒):' +
|
|
120
146
|
'seedance-2.5(默认·全能力:帧链/场景组/就地编辑/延长/参考图锚·720p约212点/秒) / ' +
|
|
121
147
|
'hailuo-3(MiniMax H3:约1/3成本 720p 70点/秒·原生对白与音效·支持2K·单镜约6分钟·支持就地编辑(强保真)与成片续写·关键帧组/时间戳区间暂不可用;编辑/续写输入视频另按秒计费) / ' +
|
|
122
148
|
'wan3.0(WAN 3.0:约4折成本 720p 84点/秒·原生对白与音效·支持1080P·单次最长30秒·最短2秒计费·支持就地编辑(强语义)与成片续写·关键帧组/时间戳区间暂不可用;★写实真人720p+可能被厂商审核拒绝,风格化/动画剧适用) / ' +
|
|
@@ -175,7 +201,9 @@ export function registerProduceTools(server, client) {
|
|
|
175
201
|
style: z.string().optional().describe('风格描述'),
|
|
176
202
|
description: z.string().optional(),
|
|
177
203
|
aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('画幅比例(默认 9:16 竖屏短剧)。★drama级锁定:建剧即定、之后所有出图/出视频/成片都用它,别中途改(改了已生成内容画幅不一致、漂移)'),
|
|
178
|
-
video_resolution: z.enum(VIDEO_RESOLUTIONS).optional().describe('视频分辨率(默认 720p;成本随分辨率上升)'
|
|
204
|
+
video_resolution: z.enum(VIDEO_RESOLUTIONS).optional().describe('视频分辨率(默认 720p;成本随分辨率上升)。按引擎选:' +
|
|
205
|
+
'seedance-2.5 在售 480p/720p(高清档停售);hailuo-3 选 720p(=768P 70点/秒)或 1080p(=2K 112点/秒),无独立 480p 档;' +
|
|
206
|
+
'wan3.0/prime 三档全售(42/84/168,prime 63/126/252 点/秒)。草稿迭代用低档,成片交付才上高清'),
|
|
179
207
|
setting_brief: z
|
|
180
208
|
.string()
|
|
181
209
|
.optional()
|
|
@@ -241,7 +269,8 @@ export function registerProduceTools(server, client) {
|
|
|
241
269
|
// ---------- 提取(角色/场景/道具) ----------
|
|
242
270
|
server.tool('extract_assets', '从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)。后台异步,文本步后付不欠费。' +
|
|
243
271
|
'前置:已 rewrite_script 产出改写稿(新项目强制;人物档案从改写稿提取才与剧本、分镜自洽)。' +
|
|
244
|
-
'★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60 秒当失败判据。' +
|
|
272
|
+
'★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60 秒当失败判据。' +
|
|
273
|
+
REVIEW_GATE_HINT('review_script', '改写稿') + WORKFLOW_HINT, { episode_id: z.number().int().positive(), ...REVIEW_ARGS }, async ({ episode_id, review_token, acknowledge_review }) => jsonResult(await client.producePost(`/episodes/${episode_id}/extract`, { review_token, acknowledge_review })));
|
|
245
274
|
// ---------- 完整工作流进度 ----------
|
|
246
275
|
server.tool('get_pipeline_status', '查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 ' +
|
|
247
276
|
'done/partial/pending/not_required)。照它按序推进、不跳步。免费。' +
|
|
@@ -270,11 +299,15 @@ export function registerProduceTools(server, client) {
|
|
|
270
299
|
'优化的**正常**时长,别因「一镜偏长」觉得有问题就重拆。已有分镜时后端会拦,确认重拆才带 confirm_replace=true。' +
|
|
271
300
|
'★典型耗时 5~10 分钟(生产实测 7~8.4 分钟;**单次 LLM 调用就可能 3~7 分钟**)。' +
|
|
272
301
|
'**60 秒、甚至 3 分钟内查不到分镜都是正常的**——用 get_run_status 判断是否还在跑。' +
|
|
273
|
-
'running:true 就继续等;重发一次等于把整集分镜重来一遍。' +
|
|
302
|
+
'running:true 就继续等;重发一次等于把整集分镜重来一遍。' +
|
|
303
|
+
REVIEW_GATE_HINT('review_script', '改写稿') + CONFIRM_HINT, {
|
|
274
304
|
episode_id: z.number().int().positive(),
|
|
275
305
|
quote_id: z.string().describe('来自 quote_storyboards'),
|
|
276
306
|
confirm_replace: z.boolean().optional().describe('本集已有分镜时必须 true 才重拆(会替换整集所有分镜,已出图白费)'),
|
|
277
|
-
|
|
307
|
+
...REVIEW_ARGS,
|
|
308
|
+
}, async ({ episode_id, quote_id, confirm_replace, review_token, acknowledge_review }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/generate`, {
|
|
309
|
+
quote_id, review_token, acknowledge_review, ...(confirm_replace ? { confirm_replace } : {}),
|
|
310
|
+
})));
|
|
278
311
|
server.tool('get_storyboards', '读某一集的分镜列表(供审阅/查进度)。含每镜首帧(first_frame_image)与视频(video_url)是否就绪。' +
|
|
279
312
|
'★每镜还带**结构化状态**:frame_status/video_status(ready/pending/authorizing/rejected/failed/none/not_required)、' +
|
|
280
313
|
'★not_required=旁白/片尾卡镜:帧与视频由成片层渲染,本镜不需要生成——数补齐进度时把它当已完成,别重试。' +
|
|
@@ -306,6 +339,24 @@ export function registerProduceTools(server, client) {
|
|
|
306
339
|
'出现时应先按提示改分镜再出图,而不是重试。\n' +
|
|
307
340
|
'⚠️ 它**不**检查首帧是否处在"动作发生前"(平台暂无该契约字段),也不替代 get_health_report。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/precheck`)));
|
|
308
341
|
server.tool('get_health_report', '(★推荐·免费诊断)读分镜出体检报告:时长超标/母题覆盖不足/问题镜。纯读、免费。出图前查,识别问题先改再出、别出了片才发现。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/health-report`)));
|
|
342
|
+
// ---------- 分阶段审查(三道硬闸的凭据来源;全部免费) ----------
|
|
343
|
+
// 每层审查返回 { pass, error_count, warning_count, findings[], review_token }。
|
|
344
|
+
// findings 每条 = { level, code, shots?, count?, action } —— code 是稳定问题类型码、
|
|
345
|
+
// action 直接告诉你该调哪个工具去修,照着做即可,不需要理解平台内部判据。
|
|
346
|
+
server.tool('review_script', '【第①道硬闸·免费】审查 AI 改写稿:对白行长度、情绪转折完整性、开场钩子、末场悬念。' +
|
|
347
|
+
'★extract_assets 与 generate_storyboards 之前必须先跑本工具——人物档案和分镜都从改写稿派生,' +
|
|
348
|
+
'稿子里的问题会被逐层放大到定妆图/出图/出视频,等成片才发现就是整集重来。' +
|
|
349
|
+
'把 findings 逐条告诉客户、按 action 修完(改稿走 edit_rewritten_script)后复审,再拿 review_token 往下走。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/script`)));
|
|
350
|
+
server.tool('review_storyboards', '【第②道硬闸·免费】审查分镜:禁区词(会被厂商审核拒、白扣费)、镜头时长分布、相邻构图重复、' +
|
|
351
|
+
'同场景角色站位漂移、情绪曲线峰谷、关键镜标记。★generate_frames 之前必须先跑本工具——' +
|
|
352
|
+
'分镜里的问题一旦整集出图就变成整集废图,单镜修不回来。按 findings.action 用 update_shot/split_shot 修完再复审。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/storyboards`)));
|
|
353
|
+
server.tool('review_frames', '【第③道硬闸·免费】审查镜头图片层:角色身份锚覆盖(缺定妆图的角色在镜头里必漂)、出图失败率、' +
|
|
354
|
+
'孤儿角色变体、场景图被人物污染。★generate_videos 之前必须先跑本工具——出视频是全链最贵的一步,' +
|
|
355
|
+
'拿着漂移的首帧整集出视频是最典型的废片形态。按 findings.action 修完(多为 generate_character_portraits / ' +
|
|
356
|
+
'generate_shot_frame 单镜重生)再复审。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/frames`)));
|
|
357
|
+
server.tool('review_all', '(推荐·免费)三层一次跑完的整体体检:剧本+分镜+镜头图片。开工前摸底、交付前复查用。' +
|
|
358
|
+
'★它**不发 review_token** —— 进收费步前仍需对应层的 review_script / review_storyboards / review_frames 各跑一次' +
|
|
359
|
+
'(闸认的是「针对当前产出物刚审过」,不是「审过一次」)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/all`)));
|
|
309
360
|
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 } : {})));
|
|
310
361
|
server.tool('enhance_shot_prompts', '(可选增强·★非必须·有副作用)AI 批量增强全集 image_prompt。★会**改写已有 prompt**(含手调的);且**务必 generate_frames 之前**做——' +
|
|
311
362
|
'出图后再改 prompt 会让图陈旧、要重生浪费钱。非跑通一部片的必需,客户点名再做。后台异步,文本步后付。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/enhance-prompts`)));
|
|
@@ -331,14 +382,18 @@ export function registerProduceTools(server, client) {
|
|
|
331
382
|
'★尾帧能批量出:frame_type=last_frame 会给「已有首帧且缺尾帧」的镜批量补尾帧(尾帧只在想固定某镜结尾画面/大运镜时才需,常规只出首帧)。' +
|
|
332
383
|
'★响应里的 frames_planned 是**计划数,不是已成功数**——本接口在后台派发循环开跑之前就返回了。' +
|
|
333
384
|
'真实进度只看 get_storyboards 的 first_frame_image / get_jobs 的逐条生成记录;' +
|
|
334
|
-
'余额不足(402)会中止整批,此时轮询再久也不会有结果,应去查余额而不是继续等。' +
|
|
385
|
+
'余额不足(402)会中止整批,此时轮询再久也不会有结果,应去查余额而不是继续等。' +
|
|
386
|
+
REVIEW_GATE_HINT('review_storyboards', '分镜') + CONFIRM_HINT, {
|
|
335
387
|
episode_id: z.number().int().positive(),
|
|
336
388
|
quote_id: z.string().describe('来自 quote_frames'),
|
|
389
|
+
...REVIEW_ARGS,
|
|
337
390
|
frame_type: FRAME_TYPE_ARG.optional().describe('默认 first_frame,须与报价时一致'),
|
|
338
391
|
image_model: z.string().optional().describe('临时覆盖本次出图模型(不传=用 drama 级设定,默认香蕉2)。可选:' +
|
|
339
392
|
'gemini-3.1-flash-image(Nano Banana 2·默认·71点)/gemini-3-pro-image(Nano Banana Pro·更精细·175点)/' +
|
|
340
393
|
'gemini-3.1-flash-lite-image(Nano Banana 2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream 5.0)/gpt-image-2(ChatGPT Image 2)'),
|
|
341
|
-
}, async ({ episode_id, quote_id, frame_type, image_model }) => jsonResult(await client.producePost(`/episodes/${episode_id}/frames/generate`, {
|
|
394
|
+
}, async ({ episode_id, quote_id, frame_type, image_model, review_token, acknowledge_review }) => jsonResult(await client.producePost(`/episodes/${episode_id}/frames/generate`, {
|
|
395
|
+
quote_id, frame_type, image_model, review_token, acknowledge_review,
|
|
396
|
+
})));
|
|
342
397
|
// ---------- 单镜出帧/重生(改某一镜的画面走这里,别去外部平台出图再传回来) ----------
|
|
343
398
|
server.tool('quote_shot_frame', '报价:重画/补出**某一镜的某一帧**要多少点(一帧=一张图)。返回 estimated_points、quote_id。零扣费。' +
|
|
344
399
|
'客户说「第 N 镜画错了/要改」时用它,而不是拿别的图像平台出图再 upload_shot_frame。' +
|
|
@@ -367,7 +422,12 @@ export function registerProduceTools(server, client) {
|
|
|
367
422
|
server.tool('quote_videos', '报价:给某一集所有分镜批量出视频要多少点(与实际扣费同函数,较准)。返回 estimated_points、quote_id。零扣费。' +
|
|
368
423
|
'⚠️ 视频是大额花费,务必把点数清楚告诉用户并等其确认。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/videos/quote`)));
|
|
369
424
|
server.tool('generate_videos', '确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)。' +
|
|
370
|
-
'要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url 逐镜填充即完成。' +
|
|
425
|
+
'要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url 逐镜填充即完成。' +
|
|
426
|
+
REVIEW_GATE_HINT('review_frames', '镜头图片') + CONFIRM_HINT, {
|
|
427
|
+
episode_id: z.number().int().positive(),
|
|
428
|
+
quote_id: z.string().describe('来自 quote_videos'),
|
|
429
|
+
...REVIEW_ARGS,
|
|
430
|
+
}, async ({ episode_id, quote_id, review_token, acknowledge_review }) => jsonResult(await client.producePost(`/episodes/${episode_id}/videos/generate`, { quote_id, review_token, acknowledge_review })));
|
|
371
431
|
// ---------- 成片(compose/终拼) ----------
|
|
372
432
|
server.tool('compose_episode', '把某一集所有镜头视频拼成一条成片(终拼)。**免费**(纯拼接,无需报价确认),后台异步。' +
|
|
373
433
|
'发起前有终拼预检:缺视频的镜或仍在生成中的视频任务会 400 硬阻断并列出问题镜(blockers),' +
|
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.
|
|
6
|
-
"description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → portraits & sheets → storyboards → 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). 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.
|
|
5
|
+
"version": "0.1.47",
|
|
6
|
+
"description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → portraits & sheets → storyboards → 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). 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.47 tool surface (operationIds match MCP tool names 1:1)."
|
|
7
7
|
},
|
|
8
8
|
"servers": [
|
|
9
9
|
{
|
|
@@ -2743,7 +2743,7 @@
|
|
|
2743
2743
|
"post": {
|
|
2744
2744
|
"operationId": "extract_assets",
|
|
2745
2745
|
"summary": "从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)",
|
|
2746
|
-
"description": "从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)。后台异步,文本步后付不欠费。前置:已 rewrite_script 产出改写稿(新项目强制;人物档案从改写稿提取才与剧本、分镜自洽)。★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60
|
|
2746
|
+
"description": "从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)。后台异步,文本步后付不欠费。前置:已 rewrite_script 产出改写稿(新项目强制;人物档案从改写稿提取才与剧本、分镜自洽)。★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60 秒当失败判据。\n★【改写稿审查硬闸·免费】本步前必须先调 review_script:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**三道硬闸(不过会被 400 拒)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。有 error 时默认拦截,只有客户明确知情并坚持才带 acknowledge_review:true——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱);分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——别回头整篇替换剧本或在设定字段里另写一套,两套真相源打架是一致性事故的头号根源。★★**改写成功一次后就别再重跑 rewrite_script**:它是从原稿整篇重来,当前稿的所有修正全丢,且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;误重跑用 get_script(include_previous=1) 回捞上一版。generate_portraits_and_sheets(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→★review_frames→videos→generate_tts→compose;★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;资产在分镜后建更省更准(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★分镜后的剧目级资产别漏——尤其 generate_motion_templates(动作模板:从分镜抽取统一全片运动语言,漏了动作会散乱)与 generate_color_script(色彩脚本:统一色调);分镜后、出图前一并做,仍走报价确认。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认香蕉2(Nano Banana 2 = gemini-3.1-flash-image·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认香蕉2;可选 gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0)/gpt-image-2(ChatGPT Image2);generate_frames 可临时覆盖某次。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\"),尾帧用 frame_type=last_frame 可批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/色彩脚本/动作模板/场景图/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(AI 铺钩子造情感点),两种客户各得其所、无需手动切换。要覆盖默认用 update_project_settings 的 rewrite_pipeline(auto/two_pass/single_forced)与 fidelity_enforce(1=保真硬闸)。客户说「AI 把我的剧本改偏了」时的处置:①确认完整原稿已进 set_script;②rewrite_pipeline 设 two_pass 强制保真后重跑 rewrite_script;③客户确认角色外观后用 update_character 的 profile_locked=1 锁定档案,防后续提取覆盖外貌导致定妆图换脸。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。",
|
|
2747
2747
|
"tags": [
|
|
2748
2748
|
"episodes"
|
|
2749
2749
|
],
|
|
@@ -2758,6 +2758,24 @@
|
|
|
2758
2758
|
}
|
|
2759
2759
|
}
|
|
2760
2760
|
],
|
|
2761
|
+
"requestBody": {
|
|
2762
|
+
"required": false,
|
|
2763
|
+
"content": {
|
|
2764
|
+
"application/json": {
|
|
2765
|
+
"schema": {
|
|
2766
|
+
"type": "object",
|
|
2767
|
+
"properties": {
|
|
2768
|
+
"review_token": {
|
|
2769
|
+
"type": "string"
|
|
2770
|
+
},
|
|
2771
|
+
"acknowledge_review": {
|
|
2772
|
+
"type": "boolean"
|
|
2773
|
+
}
|
|
2774
|
+
}
|
|
2775
|
+
}
|
|
2776
|
+
}
|
|
2777
|
+
}
|
|
2778
|
+
},
|
|
2761
2779
|
"responses": {
|
|
2762
2780
|
"200": {
|
|
2763
2781
|
"description": "StarReel envelope",
|
|
@@ -2837,7 +2855,7 @@
|
|
|
2837
2855
|
"post": {
|
|
2838
2856
|
"operationId": "generate_frames",
|
|
2839
2857
|
"summary": "确认后批量出帧:后台异步",
|
|
2840
|
-
"description": "确认后批量出帧:后台异步。用 get_storyboards 轮询,first_frame_image/last_frame_image 逐镜填充即完成。★图片生成较慢——每张几十秒到数分钟(尤其高清模型),整集可能十几分钟。轮询看 frame_status:**pending=还在生成(继续耐心等,别当失败、别重复调 generate_frames,重复触发=白花钱)**、ready=完成、failed=才是真失败。别因为「等了一会儿还没出」就判定生成失败或重试。出视频前必须先出帧,否则视频会退化成无一致性锚点的画面。frame_type 要与 quote_frames 用的一致(默认 first_frame)。★这是**批量补缺帧**:只给「缺该帧」的镜出图,已有首帧的镜会跳过——这是正常设计、不是\"系统拒绝重出\"。要**重出/重画某一镜已有的帧**(如换了定妆图要让新图生效),用 generate_shot_frame(单镜重生,平台带身份锚),不是这个工具、更不是自制图 upload_shot_frame。★尾帧能批量出:frame_type=last_frame 会给「已有首帧且缺尾帧」的镜批量补尾帧(尾帧只在想固定某镜结尾画面/大运镜时才需,常规只出首帧)。★响应里的 frames_planned 是**计划数,不是已成功数**——本接口在后台派发循环开跑之前就返回了。真实进度只看 get_storyboards 的 first_frame_image / get_jobs 的逐条生成记录;余额不足(402)
|
|
2858
|
+
"description": "确认后批量出帧:后台异步。用 get_storyboards 轮询,first_frame_image/last_frame_image 逐镜填充即完成。★图片生成较慢——每张几十秒到数分钟(尤其高清模型),整集可能十几分钟。轮询看 frame_status:**pending=还在生成(继续耐心等,别当失败、别重复调 generate_frames,重复触发=白花钱)**、ready=完成、failed=才是真失败。别因为「等了一会儿还没出」就判定生成失败或重试。出视频前必须先出帧,否则视频会退化成无一致性锚点的画面。frame_type 要与 quote_frames 用的一致(默认 first_frame)。★这是**批量补缺帧**:只给「缺该帧」的镜出图,已有首帧的镜会跳过——这是正常设计、不是\"系统拒绝重出\"。要**重出/重画某一镜已有的帧**(如换了定妆图要让新图生效),用 generate_shot_frame(单镜重生,平台带身份锚),不是这个工具、更不是自制图 upload_shot_frame。★尾帧能批量出:frame_type=last_frame 会给「已有首帧且缺尾帧」的镜批量补尾帧(尾帧只在想固定某镜结尾画面/大运镜时才需,常规只出首帧)。★响应里的 frames_planned 是**计划数,不是已成功数**——本接口在后台派发循环开跑之前就返回了。真实进度只看 get_storyboards 的 first_frame_image / get_jobs 的逐条生成记录;余额不足(402)会中止整批,此时轮询再久也不会有结果,应去查余额而不是继续等。\n★【分镜审查硬闸·免费】本步前必须先调 review_storyboards:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。",
|
|
2841
2859
|
"tags": [
|
|
2842
2860
|
"episodes"
|
|
2843
2861
|
],
|
|
@@ -2873,6 +2891,12 @@
|
|
|
2873
2891
|
},
|
|
2874
2892
|
"image_model": {
|
|
2875
2893
|
"type": "string"
|
|
2894
|
+
},
|
|
2895
|
+
"review_token": {
|
|
2896
|
+
"type": "string"
|
|
2897
|
+
},
|
|
2898
|
+
"acknowledge_review": {
|
|
2899
|
+
"type": "boolean"
|
|
2876
2900
|
}
|
|
2877
2901
|
},
|
|
2878
2902
|
"required": [
|
|
@@ -3587,11 +3611,199 @@
|
|
|
3587
3611
|
}
|
|
3588
3612
|
}
|
|
3589
3613
|
},
|
|
3614
|
+
"/episodes/{episode_id}/review/all": {
|
|
3615
|
+
"post": {
|
|
3616
|
+
"operationId": "review_all",
|
|
3617
|
+
"summary": "(推荐·免费)三层一次跑完的整体体检:剧本+分镜+镜头图片",
|
|
3618
|
+
"description": "(推荐·免费)三层一次跑完的整体体检:剧本+分镜+镜头图片。开工前摸底、交付前复查用。★它**不发 review_token** —— 进收费步前仍需对应层的 review_script / review_storyboards / review_frames 各跑一次(闸认的是「针对当前产出物刚审过」,不是「审过一次」)。",
|
|
3619
|
+
"tags": [
|
|
3620
|
+
"episodes"
|
|
3621
|
+
],
|
|
3622
|
+
"parameters": [
|
|
3623
|
+
{
|
|
3624
|
+
"name": "episode_id",
|
|
3625
|
+
"in": "path",
|
|
3626
|
+
"required": true,
|
|
3627
|
+
"schema": {
|
|
3628
|
+
"type": "integer",
|
|
3629
|
+
"exclusiveMinimum": 0
|
|
3630
|
+
}
|
|
3631
|
+
}
|
|
3632
|
+
],
|
|
3633
|
+
"responses": {
|
|
3634
|
+
"200": {
|
|
3635
|
+
"description": "StarReel envelope",
|
|
3636
|
+
"content": {
|
|
3637
|
+
"application/json": {
|
|
3638
|
+
"schema": {
|
|
3639
|
+
"type": "object",
|
|
3640
|
+
"properties": {
|
|
3641
|
+
"code": {
|
|
3642
|
+
"type": "integer"
|
|
3643
|
+
},
|
|
3644
|
+
"message": {
|
|
3645
|
+
"type": "string"
|
|
3646
|
+
},
|
|
3647
|
+
"data": {
|
|
3648
|
+
"description": "Operation result payload"
|
|
3649
|
+
}
|
|
3650
|
+
}
|
|
3651
|
+
}
|
|
3652
|
+
}
|
|
3653
|
+
}
|
|
3654
|
+
},
|
|
3655
|
+
"402": {
|
|
3656
|
+
"description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
|
|
3657
|
+
}
|
|
3658
|
+
}
|
|
3659
|
+
}
|
|
3660
|
+
},
|
|
3661
|
+
"/episodes/{episode_id}/review/frames": {
|
|
3662
|
+
"post": {
|
|
3663
|
+
"operationId": "review_frames",
|
|
3664
|
+
"summary": "【第③道硬闸·免费】审查镜头图片层:角色身份锚覆盖(缺定妆图的角色在镜头里必漂)、出图失败率、孤儿角色变体、场景图被人物污染",
|
|
3665
|
+
"description": "【第③道硬闸·免费】审查镜头图片层:角色身份锚覆盖(缺定妆图的角色在镜头里必漂)、出图失败率、孤儿角色变体、场景图被人物污染。★generate_videos 之前必须先跑本工具——出视频是全链最贵的一步,拿着漂移的首帧整集出视频是最典型的废片形态。按 findings.action 修完(多为 generate_character_portraits / generate_shot_frame 单镜重生)再复审。",
|
|
3666
|
+
"tags": [
|
|
3667
|
+
"episodes"
|
|
3668
|
+
],
|
|
3669
|
+
"parameters": [
|
|
3670
|
+
{
|
|
3671
|
+
"name": "episode_id",
|
|
3672
|
+
"in": "path",
|
|
3673
|
+
"required": true,
|
|
3674
|
+
"schema": {
|
|
3675
|
+
"type": "integer",
|
|
3676
|
+
"exclusiveMinimum": 0
|
|
3677
|
+
}
|
|
3678
|
+
}
|
|
3679
|
+
],
|
|
3680
|
+
"responses": {
|
|
3681
|
+
"200": {
|
|
3682
|
+
"description": "StarReel envelope",
|
|
3683
|
+
"content": {
|
|
3684
|
+
"application/json": {
|
|
3685
|
+
"schema": {
|
|
3686
|
+
"type": "object",
|
|
3687
|
+
"properties": {
|
|
3688
|
+
"code": {
|
|
3689
|
+
"type": "integer"
|
|
3690
|
+
},
|
|
3691
|
+
"message": {
|
|
3692
|
+
"type": "string"
|
|
3693
|
+
},
|
|
3694
|
+
"data": {
|
|
3695
|
+
"description": "Operation result payload"
|
|
3696
|
+
}
|
|
3697
|
+
}
|
|
3698
|
+
}
|
|
3699
|
+
}
|
|
3700
|
+
}
|
|
3701
|
+
},
|
|
3702
|
+
"402": {
|
|
3703
|
+
"description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
|
|
3704
|
+
}
|
|
3705
|
+
}
|
|
3706
|
+
}
|
|
3707
|
+
},
|
|
3708
|
+
"/episodes/{episode_id}/review/script": {
|
|
3709
|
+
"post": {
|
|
3710
|
+
"operationId": "review_script",
|
|
3711
|
+
"summary": "【第①道硬闸·免费】审查 AI 改写稿:对白行长度、情绪转折完整性、开场钩子、末场悬念",
|
|
3712
|
+
"description": "【第①道硬闸·免费】审查 AI 改写稿:对白行长度、情绪转折完整性、开场钩子、末场悬念。★extract_assets 与 generate_storyboards 之前必须先跑本工具——人物档案和分镜都从改写稿派生,稿子里的问题会被逐层放大到定妆图/出图/出视频,等成片才发现就是整集重来。把 findings 逐条告诉客户、按 action 修完(改稿走 edit_rewritten_script)后复审,再拿 review_token 往下走。",
|
|
3713
|
+
"tags": [
|
|
3714
|
+
"episodes"
|
|
3715
|
+
],
|
|
3716
|
+
"parameters": [
|
|
3717
|
+
{
|
|
3718
|
+
"name": "episode_id",
|
|
3719
|
+
"in": "path",
|
|
3720
|
+
"required": true,
|
|
3721
|
+
"schema": {
|
|
3722
|
+
"type": "integer",
|
|
3723
|
+
"exclusiveMinimum": 0
|
|
3724
|
+
}
|
|
3725
|
+
}
|
|
3726
|
+
],
|
|
3727
|
+
"responses": {
|
|
3728
|
+
"200": {
|
|
3729
|
+
"description": "StarReel envelope",
|
|
3730
|
+
"content": {
|
|
3731
|
+
"application/json": {
|
|
3732
|
+
"schema": {
|
|
3733
|
+
"type": "object",
|
|
3734
|
+
"properties": {
|
|
3735
|
+
"code": {
|
|
3736
|
+
"type": "integer"
|
|
3737
|
+
},
|
|
3738
|
+
"message": {
|
|
3739
|
+
"type": "string"
|
|
3740
|
+
},
|
|
3741
|
+
"data": {
|
|
3742
|
+
"description": "Operation result payload"
|
|
3743
|
+
}
|
|
3744
|
+
}
|
|
3745
|
+
}
|
|
3746
|
+
}
|
|
3747
|
+
}
|
|
3748
|
+
},
|
|
3749
|
+
"402": {
|
|
3750
|
+
"description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
|
|
3751
|
+
}
|
|
3752
|
+
}
|
|
3753
|
+
}
|
|
3754
|
+
},
|
|
3755
|
+
"/episodes/{episode_id}/review/storyboards": {
|
|
3756
|
+
"post": {
|
|
3757
|
+
"operationId": "review_storyboards",
|
|
3758
|
+
"summary": "【第②道硬闸·免费】审查分镜:禁区词(会被厂商审核拒、白扣费)、镜头时长分布、相邻构图重复、同场景角色站位漂移、情绪曲线峰谷、关键镜标记",
|
|
3759
|
+
"description": "【第②道硬闸·免费】审查分镜:禁区词(会被厂商审核拒、白扣费)、镜头时长分布、相邻构图重复、同场景角色站位漂移、情绪曲线峰谷、关键镜标记。★generate_frames 之前必须先跑本工具——分镜里的问题一旦整集出图就变成整集废图,单镜修不回来。按 findings.action 用 update_shot/split_shot 修完再复审。",
|
|
3760
|
+
"tags": [
|
|
3761
|
+
"episodes"
|
|
3762
|
+
],
|
|
3763
|
+
"parameters": [
|
|
3764
|
+
{
|
|
3765
|
+
"name": "episode_id",
|
|
3766
|
+
"in": "path",
|
|
3767
|
+
"required": true,
|
|
3768
|
+
"schema": {
|
|
3769
|
+
"type": "integer",
|
|
3770
|
+
"exclusiveMinimum": 0
|
|
3771
|
+
}
|
|
3772
|
+
}
|
|
3773
|
+
],
|
|
3774
|
+
"responses": {
|
|
3775
|
+
"200": {
|
|
3776
|
+
"description": "StarReel envelope",
|
|
3777
|
+
"content": {
|
|
3778
|
+
"application/json": {
|
|
3779
|
+
"schema": {
|
|
3780
|
+
"type": "object",
|
|
3781
|
+
"properties": {
|
|
3782
|
+
"code": {
|
|
3783
|
+
"type": "integer"
|
|
3784
|
+
},
|
|
3785
|
+
"message": {
|
|
3786
|
+
"type": "string"
|
|
3787
|
+
},
|
|
3788
|
+
"data": {
|
|
3789
|
+
"description": "Operation result payload"
|
|
3790
|
+
}
|
|
3791
|
+
}
|
|
3792
|
+
}
|
|
3793
|
+
}
|
|
3794
|
+
}
|
|
3795
|
+
},
|
|
3796
|
+
"402": {
|
|
3797
|
+
"description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
|
|
3798
|
+
}
|
|
3799
|
+
}
|
|
3800
|
+
}
|
|
3801
|
+
},
|
|
3590
3802
|
"/episodes/{episode_id}/rewrite": {
|
|
3591
3803
|
"post": {
|
|
3592
3804
|
"operationId": "rewrite_script",
|
|
3593
3805
|
"summary": "AI 改写:把原始剧本改写成可拍稿(读 content → 写 script_content)",
|
|
3594
|
-
"description": "AI 改写:把原始剧本改写成可拍稿(读 content → 写 script_content)。按项目类型自动选改写 agent★保真自动路由:原稿已是剧本形态时自动走两步保真(台词逐句机器锁定、AI 不加戏,剧作缺口进 dramaturgy_suggestions 由客户决定);原稿是小说/大纲则走创作型改写。(广告走 ad 改写;MV 不走标准改写会被拦)。后台异步(分钟级),文本步按 token 后付、不欠费,无需报价。完成后用 get_script 审阅、edit_rewritten_script 改稿。★典型耗时 2~4 分钟(生产实测 ≈169 秒)。**60 秒内查不到结果是正常的,不是失败**——用 get_run_status 判断还在不在跑,别急着重发。★★**本工具是\"从原稿整篇重来\",不是\"再改一版\"**:已有可拍稿时重跑会把当前稿连同已做的所有修正一起覆盖,而且新一版**不保证保留旧版已经改好的地方**(生产三版实测:上一版拆好的长旁白段下一版又合回去、上一版正确的年代服装下一版漂走)。响应里的 overwrites_existing_script=true 就是这个意思。所以**首次改写成功之后,后续所有修改一律用 edit_rewritten_script 点改**——免费、秒级、只动指定的那几场,其余逐字不变,结果确定不抽卡;只有\"要一个完全不同的版本\"才重跑本工具。误重跑后用 get_script(include_previous=1) 取回上一版。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 →
|
|
3806
|
+
"description": "AI 改写:把原始剧本改写成可拍稿(读 content → 写 script_content)。按项目类型自动选改写 agent★保真自动路由:原稿已是剧本形态时自动走两步保真(台词逐句机器锁定、AI 不加戏,剧作缺口进 dramaturgy_suggestions 由客户决定);原稿是小说/大纲则走创作型改写。(广告走 ad 改写;MV 不走标准改写会被拦)。后台异步(分钟级),文本步按 token 后付、不欠费,无需报价。完成后用 get_script 审阅、edit_rewritten_script 改稿。★典型耗时 2~4 分钟(生产实测 ≈169 秒)。**60 秒内查不到结果是正常的,不是失败**——用 get_run_status 判断还在不在跑,别急着重发。★★**本工具是\"从原稿整篇重来\",不是\"再改一版\"**:已有可拍稿时重跑会把当前稿连同已做的所有修正一起覆盖,而且新一版**不保证保留旧版已经改好的地方**(生产三版实测:上一版拆好的长旁白段下一版又合回去、上一版正确的年代服装下一版漂走)。响应里的 overwrites_existing_script=true 就是这个意思。所以**首次改写成功之后,后续所有修改一律用 edit_rewritten_script 点改**——免费、秒级、只动指定的那几场,其余逐字不变,结果确定不抽卡;只有\"要一个完全不同的版本\"才重跑本工具。误重跑后用 get_script(include_previous=1) 取回上一版。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**三道硬闸(不过会被 400 拒)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。有 error 时默认拦截,只有客户明确知情并坚持才带 acknowledge_review:true——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱);分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——别回头整篇替换剧本或在设定字段里另写一套,两套真相源打架是一致性事故的头号根源。★★**改写成功一次后就别再重跑 rewrite_script**:它是从原稿整篇重来,当前稿的所有修正全丢,且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;误重跑用 get_script(include_previous=1) 回捞上一版。generate_portraits_and_sheets(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→★review_frames→videos→generate_tts→compose;★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;资产在分镜后建更省更准(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★分镜后的剧目级资产别漏——尤其 generate_motion_templates(动作模板:从分镜抽取统一全片运动语言,漏了动作会散乱)与 generate_color_script(色彩脚本:统一色调);分镜后、出图前一并做,仍走报价确认。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认香蕉2(Nano Banana 2 = gemini-3.1-flash-image·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认香蕉2;可选 gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0)/gpt-image-2(ChatGPT Image2);generate_frames 可临时覆盖某次。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\"),尾帧用 frame_type=last_frame 可批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/色彩脚本/动作模板/场景图/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(AI 铺钩子造情感点),两种客户各得其所、无需手动切换。要覆盖默认用 update_project_settings 的 rewrite_pipeline(auto/two_pass/single_forced)与 fidelity_enforce(1=保真硬闸)。客户说「AI 把我的剧本改偏了」时的处置:①确认完整原稿已进 set_script;②rewrite_pipeline 设 two_pass 强制保真后重跑 rewrite_script;③客户确认角色外观后用 update_character 的 profile_locked=1 锁定档案,防后续提取覆盖外貌导致定妆图换脸。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。",
|
|
3595
3807
|
"tags": [
|
|
3596
3808
|
"episodes"
|
|
3597
3809
|
],
|
|
@@ -3889,7 +4101,7 @@
|
|
|
3889
4101
|
"put": {
|
|
3890
4102
|
"operationId": "set_script",
|
|
3891
4103
|
"summary": "给某一集设置**原始剧本**(content)",
|
|
3892
|
-
"description": "给某一集设置**原始剧本**(content)。这是 AI 改写的输入,不是最终可拍稿。免费。梗概/大纲/自己写好的成品稿都放这里,设完**必须调 rewrite_script 做 AI 改写**——不能跳过改写直接把稿子贴进 edit_rewritten_script(会被拒)。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 →
|
|
4104
|
+
"description": "给某一集设置**原始剧本**(content)。这是 AI 改写的输入,不是最终可拍稿。免费。梗概/大纲/自己写好的成品稿都放这里,设完**必须调 rewrite_script 做 AI 改写**——不能跳过改写直接把稿子贴进 edit_rewritten_script(会被拒)。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**三道硬闸(不过会被 400 拒)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。有 error 时默认拦截,只有客户明确知情并坚持才带 acknowledge_review:true——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱);分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——别回头整篇替换剧本或在设定字段里另写一套,两套真相源打架是一致性事故的头号根源。★★**改写成功一次后就别再重跑 rewrite_script**:它是从原稿整篇重来,当前稿的所有修正全丢,且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;误重跑用 get_script(include_previous=1) 回捞上一版。generate_portraits_and_sheets(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→★review_frames→videos→generate_tts→compose;★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;资产在分镜后建更省更准(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★分镜后的剧目级资产别漏——尤其 generate_motion_templates(动作模板:从分镜抽取统一全片运动语言,漏了动作会散乱)与 generate_color_script(色彩脚本:统一色调);分镜后、出图前一并做,仍走报价确认。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认香蕉2(Nano Banana 2 = gemini-3.1-flash-image·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认香蕉2;可选 gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0)/gpt-image-2(ChatGPT Image2);generate_frames 可临时覆盖某次。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\"),尾帧用 frame_type=last_frame 可批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/色彩脚本/动作模板/场景图/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(AI 铺钩子造情感点),两种客户各得其所、无需手动切换。要覆盖默认用 update_project_settings 的 rewrite_pipeline(auto/two_pass/single_forced)与 fidelity_enforce(1=保真硬闸)。客户说「AI 把我的剧本改偏了」时的处置:①确认完整原稿已进 set_script;②rewrite_pipeline 设 two_pass 强制保真后重跑 rewrite_script;③客户确认角色外观后用 update_character 的 profile_locked=1 锁定档案,防后续提取覆盖外貌导致定妆图换脸。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。",
|
|
3893
4105
|
"tags": [
|
|
3894
4106
|
"episodes"
|
|
3895
4107
|
],
|
|
@@ -4255,7 +4467,7 @@
|
|
|
4255
4467
|
"post": {
|
|
4256
4468
|
"operationId": "generate_storyboards",
|
|
4257
4469
|
"summary": "确认后拆镜:后台跑(分钟级),立即返回 status:generating",
|
|
4258
|
-
"description": "确认后拆镜:后台跑(分钟级),立即返回 status:generating。用 get_storyboards 轮询。★注意:拆镜会**替换整集所有已有分镜**(已调好/已出图的全丢、要重花钱重来)。每镜 5-7 秒是对 AI 出视频优化的**正常**时长,别因「一镜偏长」觉得有问题就重拆。已有分镜时后端会拦,确认重拆才带 confirm_replace=true。★典型耗时 5~10 分钟(生产实测 7~8.4 分钟;**单次 LLM 调用就可能 3~7 分钟**)。**60 秒、甚至 3 分钟内查不到分镜都是正常的**——用 get_run_status 判断是否还在跑。running:true
|
|
4470
|
+
"description": "确认后拆镜:后台跑(分钟级),立即返回 status:generating。用 get_storyboards 轮询。★注意:拆镜会**替换整集所有已有分镜**(已调好/已出图的全丢、要重花钱重来)。每镜 5-7 秒是对 AI 出视频优化的**正常**时长,别因「一镜偏长」觉得有问题就重拆。已有分镜时后端会拦,确认重拆才带 confirm_replace=true。★典型耗时 5~10 分钟(生产实测 7~8.4 分钟;**单次 LLM 调用就可能 3~7 分钟**)。**60 秒、甚至 3 分钟内查不到分镜都是正常的**——用 get_run_status 判断是否还在跑。running:true 就继续等;重发一次等于把整集分镜重来一遍。\n★【改写稿审查硬闸·免费】本步前必须先调 review_script:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。",
|
|
4259
4471
|
"tags": [
|
|
4260
4472
|
"episodes"
|
|
4261
4473
|
],
|
|
@@ -4281,6 +4493,12 @@
|
|
|
4281
4493
|
"type": "string",
|
|
4282
4494
|
"description": "来自 quote_storyboards"
|
|
4283
4495
|
},
|
|
4496
|
+
"review_token": {
|
|
4497
|
+
"type": "string"
|
|
4498
|
+
},
|
|
4499
|
+
"acknowledge_review": {
|
|
4500
|
+
"type": "boolean"
|
|
4501
|
+
},
|
|
4284
4502
|
"confirm_replace": {
|
|
4285
4503
|
"type": "boolean"
|
|
4286
4504
|
}
|
|
@@ -4531,7 +4749,7 @@
|
|
|
4531
4749
|
"post": {
|
|
4532
4750
|
"operationId": "generate_videos",
|
|
4533
4751
|
"summary": "确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)",
|
|
4534
|
-
"description": "确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)。要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url
|
|
4752
|
+
"description": "确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)。要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url 逐镜填充即完成。\n★【镜头图片审查硬闸·免费】本步前必须先调 review_frames:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。",
|
|
4535
4753
|
"tags": [
|
|
4536
4754
|
"episodes"
|
|
4537
4755
|
],
|
|
@@ -4556,6 +4774,12 @@
|
|
|
4556
4774
|
"quote_id": {
|
|
4557
4775
|
"type": "string",
|
|
4558
4776
|
"description": "来自 quote_videos"
|
|
4777
|
+
},
|
|
4778
|
+
"review_token": {
|
|
4779
|
+
"type": "string"
|
|
4780
|
+
},
|
|
4781
|
+
"acknowledge_review": {
|
|
4782
|
+
"type": "boolean"
|
|
4559
4783
|
}
|
|
4560
4784
|
},
|
|
4561
4785
|
"required": [
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@starreel/mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.47",
|
|
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.
|
|
5
|
+
"version": "0.1.47",
|
|
6
6
|
"websiteUrl": "https://starreel.ai",
|
|
7
7
|
"packages": [
|
|
8
8
|
{
|
|
9
9
|
"registryType": "npm",
|
|
10
10
|
"identifier": "@starreel/mcp",
|
|
11
|
-
"version": "0.1.
|
|
11
|
+
"version": "0.1.47",
|
|
12
12
|
"transport": {
|
|
13
13
|
"type": "stdio"
|
|
14
14
|
},
|