@starreel/mcp 0.1.256 → 0.1.257

package/SKILL.md

@@ -1559,6 +1559,23 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   with their timestamps (first frame becomes a soft constraint; ±1 s timing; same
   price). Shots whose first frame is a copy of the previous shot's last frame keep
   first-frame mode (`reason: strict-continuity`) so the seam stays exact.
+- **Storyboard grid reference (closed beta, `seedance-2.5` only)**:
+  `set_shot_storyboard_grid` (free) mounts one multi-panel storyboard image
+  (line art / stick figures, ideally ≤15 panels) on a shot; the video is then
+  generated as one multi-shot clip following the grid's story, action, shot
+  order, camera positions and blocking. The grid is sent as reference image 1,
+  **not** as the first frame, and is **not** matched panel-by-panel — when the
+  frames must match exactly, use keyframes instead. The platform drops the
+  first/last frame (they are mutually exclusive with the grid), appends the
+  shot's character portraits and scene image, and writes the asset-reference
+  block at the top of the prompt; the grid never defines faces or art style.
+  Write the shot's `video_prompt` as a synopsis plus per-panel details the
+  sketch cannot show (shot size, camera move, action, materials, style).
+  Advisories (>15 panels, more panels than seconds) do not block. Non-2.5
+  engine → 400; grid shots never join scene groups; mounting marks the
+  existing video stale. `quote_regenerate_shot_video` returns `storyboard_grid`
+  when the grid will be used. Read with `get_shot_storyboard_grid`, remove with
+  `clear_shot_storyboard_grid`. A 400 "未开启" means the project is not in the beta.
 - **Era contract**: `set_era_contract` / `get_era_contract` — see the project
   settings tier above. Non-contemporary projects must set this before frames.
 - **Lengthen a finished cut**: `quote_extend_final` (free, quote first) →

package/dist/tools/guide-data.js

@@ -274,7 +274,7 @@ export const PIPELINE = [
     },
     {
         step: '8 出视频',
-        tools: ['quote_videos', 'generate_videos', 'cancel_videos(停整集出视频:已派的照常出完扣费,未派的不再派·免费)', 'get_scene_group_plan', 'generate_scene_groups', 'quote_regenerate_shot_video', 'regenerate_shot_video', 'quote_edit_video_shot', 'edit_video_shot', 'upload_shot_footage(实拍素材镜:客户录屏/产品实拍直接当该镜视频,不出视频不扣费)', 'get_edit_capabilities', 'get_repaint_capabilities', 'quote_repaint_shot_video', 'repaint_shot_video', 'quote_reskin_shot_video', 'reskin_shot_video', 'get_repaint_status', 'restore_repaint_original', 'get_av_anchors(定妆视频锚现况:挂锚的镜首尾帧不送)', 'clear_character_av_anchor(客户确认后摘锚·免费)'],
+        tools: ['quote_videos', 'generate_videos', 'cancel_videos(停整集出视频:已派的照常出完扣费,未派的不再派·免费)', 'get_scene_group_plan', 'generate_scene_groups', 'quote_regenerate_shot_video', 'regenerate_shot_video', 'quote_edit_video_shot', 'edit_video_shot', 'upload_shot_footage(实拍素材镜:客户录屏/产品实拍直接当该镜视频,不出视频不扣费)', 'get_edit_capabilities', 'get_repaint_capabilities', 'quote_repaint_shot_video', 'repaint_shot_video', 'quote_reskin_shot_video', 'reskin_shot_video', 'get_repaint_status', 'restore_repaint_original', 'get_av_anchors(定妆视频锚现况:挂锚的镜首尾帧不送)', 'clear_character_av_anchor(客户确认后摘锚·免费)', 'set_shot_storyboard_grid(宫格分镜参考·内测·2.5:线稿宫格一次出一段多镜头,不严格对齐)', 'get_shot_storyboard_grid', 'clear_shot_storyboard_grid'],
         billing: '报价确认后扣点',
         note: 'video_engine 必须在出视频前定(写实真人剧 seedance-2.5 或降本 hailuo-3 / 动漫·风格化 seedance-2.5 或 wan3.0·wan 绝不用于写实真人;' + MODEL_AVAILABILITY_NOTE + ');切换不回溯已生成镜头。',
     },

package/dist/tools/produce.js

@@ -1366,6 +1366,29 @@ export function registerProduceTools(server, client) {
         ...REVIEW_ARGS,
         ...ASSET_REVIEW_ARG,
     }, async ({ storyboard_id, quote_id, keyframe_ids, image_model, review_token, asset_review_token, acknowledge_review, auto_acknowledge }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/keyframes/generate`, { quote_id, keyframe_ids, image_model, review_token, asset_review_token, acknowledge_review, auto_acknowledge })));
+    server.tool('get_shot_storyboard_grid', '★**内测**·读**某一镜**挂的宫格分镜参考(故事板)。免费。回 grid(image_url / cells / advisories,null = 没挂)、'
+        + 'enabled(本剧是否在内测名单)、video_engine 与 engine_supported(只有 Seedance 2.5 支持宫格参考)、tips(宫格怎么画、提示词怎么写)。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/storyboard-grid`)));
+    server.tool('set_shot_storyboard_grid', '★**内测**·给**某一镜**挂一张**宫格分镜图**(故事板,Seedance 2.5 官方多模态能力):客户手画的线稿 / 火柴人多宫格,'
+        + '一张图里按从左到右、从上到下排好这一段的镜头顺序、动作、机位与站位,出视频时**一次出成一段多镜头视频**。免费(只挂载,出视频照常报价扣费)。'
+        + '\n★宫格作参考图「图片1」送(不是首帧),**不严格对齐**画面细节——它只管剧情、动作、镜头顺序、机位与站位;'
+        + '**要逐格严格对齐画面,改用关键帧**(set_shot_keyframes 单镜中间关键帧,或场景组关键帧),不是本工具。'
+        + '\n★出视频时平台自动:不送首尾帧(厂商规定与宫格互斥)、把本镜角色定妆图与场景图接在宫格之后、在提示词最前面写好素材指代'
+        + '(宫格图@图片1、角色图@图片N、场景图@图片M);宫格图不当身份参考,人物长相以定妆图为准,也不会沿用宫格的线稿画风。'
+        + '\n★本镜视频提示词(update_shot 的 video_prompt)请写:故事梗概 + 按格逐镜补齐宫格里画不出的信息(景别、运镜、动作、材质、风格);写实片可再写一句「宫格只作脚本参考」。'
+        + '\n★建议 ≤15 格(超过易画面静止、顺序错乱,会回 advisories 提示但不拦截);推荐线稿 / 火柴人,不要过度锐化的 AI 直出图,图上少写字;'
+        + '格数多于本镜秒数也会提示(动作会被挤压)。'
+        + '\n★前提:本镜或本剧视频引擎是 seedance-2.5,否则 400;挂了宫格的镜不并场景组。挂 / 换宫格会把本镜已有视频标为待重生。'
+        + '之后照常 quote_regenerate_shot_video(回 storyboard_grid 字段即确认本次按宫格出)→ regenerate_shot_video。'
+        + '回 400「本剧未开启」= 不在内测名单,别重试。传 file_path(本地图,自动上传)或 image_url 二选一。', {
+        storyboard_id: z.number().int().positive(),
+        cells: z.number().int().min(2).max(36).describe('宫格的格数,例如 3×3 填 9'),
+        file_path: z.string().optional().describe('本地宫格图路径(自动上传)'),
+        image_url: z.string().optional().describe('已上传的宫格图地址(与 file_path 二选一)'),
+    }, async ({ storyboard_id, cells, file_path, image_url }) => {
+        const url = file_path ? await client.uploadLocalFile(file_path, 'image') : image_url;
+        return jsonResult(await client.producePut(`/storyboards/${storyboard_id}/storyboard-grid`, { image_url: url, cells }));
+    });
+    server.tool('clear_shot_storyboard_grid', '★**内测**·清除**某一镜**的宫格分镜参考,本镜回到普通首帧出视频模式。免费。本镜已有视频会被标为待重生。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceDelete(`/storyboards/${storyboard_id}/storyboard-grid`)));
     server.tool('quote_extend_final', '★成片续写**报价**(免费·无副作用):在已有成片后面再接几轮 AI 生成的片段,把片子拉长。'
         + '回 rounds(轮数)/duration_per_round(每轮秒数)/max_rounds(上限)/estimated_points(预估点数)。'
         + '\n★**必须先 quote_extend_final 报价,再调 extend_final**' + MODE_DECIDES('报价确认') + '(派发前平台按同参整单报价过预算预检,超出硬上限回 402 BUDGET_WOULD_EXCEED、未扣费,那就停下问客户)' + '——每轮都真扣厂商的钱。'

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.256",
-    "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.256 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.257",
+    "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.257 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -17236,6 +17236,98 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/storyboard-grid": {
+      "get": {
+        "operationId": "get_shot_storyboard_grid",
+        "summary": "★**内测**·读**某一镜**挂的宫格分镜参考(故事板)",
+        "description": "★**内测**·读**某一镜**挂的宫格分镜参考(故事板)。免费。回 grid(image_url / cells / advisories,null = 没挂)、enabled(本剧是否在内测名单)、video_engine 与 engine_supported(只有 Seedance 2.5 支持宫格参考)、tips(宫格怎么画、提示词怎么写)。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "clear_shot_storyboard_grid",
+        "summary": "★**内测**·清除**某一镜**的宫格分镜参考,本镜回到普通首帧出视频模式",
+        "description": "★**内测**·清除**某一镜**的宫格分镜参考,本镜回到普通首帧出视频模式。免费。本镜已有视频会被标为待重生。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      }
+    },
     "/storyboards/{storyboard_id}/trim": {
       "put": {
         "operationId": "trim_shot",
@@ -18667,6 +18759,10 @@
     }
   },
   "x-unmapped-tools": [
+    {
+      "tool": "set_shot_storyboard_grid",
+      "reason": "unmappable: local file upload flow"
+    },
     {
       "tool": "upload_image",
       "reason": "unmappable: local file upload flow"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.256",
+  "version": "0.1.257",
   "mcpName": "ai.starreel/starreel",
   "description": "StarReel MCP server — drive the AI short-drama production pipeline (script → storyboards → frames → video → final cut) from Claude, Cursor, or any MCP client",
   "license": "MIT",

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "ai.starreel/starreel",
   "description": "Turn a script into a finished, downloadable short-drama episode — via MCP or REST.",
-  "version": "0.1.256",
+  "version": "0.1.257",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.256",
+      "version": "0.1.257",
       "transport": {
         "type": "stdio"
       },