@starreel/mcp 0.1.87 → 0.1.88

package/README.md

@@ -129,13 +129,33 @@ See the [API docs](https://api.shortreelai.com/docs/mcp).
 | Identity anchors | `generate_portraits_and_sheets` (portraits + character sheets = the consistency anchor) |
 | Storyboards | `quote_storyboards` → `generate_storyboards` → `get_storyboards` |
 | Frames & video | `quote_frames` → `generate_frames` · `quote_videos` → `generate_videos` |
-| Audio | `generate_tts` · `generate_bgm` (steerable via `prompt`) · `get_bgm_prompt_guide` · `generate_sfx` · voice management |
+| Audio | `generate_tts` · `generate_bgm` (steerable via `prompt`) · `get_bgm_prompt_guide` · `generate_sfx` · voice cloning · `design_voice` (a new voice from one sentence) |
 | Finishing | `compose_episode` (free) · `get_final_cut` · `render_multi_aspect` · posters & covers |
 | Localization | `translate_subtitles` · localization jobs |
 | Ads / MV modes | product library & product sheets · MV lyrics → story → script |
 
 Project types: `drama` / `ad` / `mv` / `brand_film`.
 
+## Design a voice from a description (no sample needed)
+
+When the narrator or a character has no fitting voice in the library and there is no authorized
+recording to clone, design one from a single sentence.
+
+| Step | Tool | Cost |
+|---|---|---|
+| 1. Describe, generate candidates | `design_voice` (`description`, optional preview `text`) → `design_id` | free |
+| 2. Wait and listen | `get_voice_design` (`design_id`) — about 1-3 minutes; when `done`, every candidate is downloaded as a local wav (`local_path`) for the customer to pick | free |
+| 3. Keep one | `save_designed_voice` (`design_id`, `index`, `name`) → `voice_id` (e.g. `lib:12`) | same as a voice clone; saving the same candidate twice charges once |
+| 4. Use it | `set_character_voice` (`character_id`, `voice_id`) — `generate_tts` then reads every line of that character with it | free |
+
+The narrator is a character too (`char_type` voiceover). Describe what you want rather than what
+you don't — age, gender, timbre, pace, mood — e.g. *"a middle-aged man, low and warm voice, slow pace,
+sentences trail downward"*. **Always make the customer pick one before dubbing**: the same
+description gives a different person every time (measured voice similarity as low as 0.23), while
+a saved voice is cloned for every line (0.85-0.90). Limits: one design at a time per account, 30 per
+24 h; preview sentence 14-28 characters; candidates are kept for 6 hours; never name a real person
+to imitate their voice.
+
 ## Billing is agent-safe by design
 
 - **Prepaid, never negative.** Costs are pre-authorized *before* any vendor call;

package/README.zh-CN.md

@@ -88,6 +88,36 @@ env = { "STARREEL_API_KEY" = "srk_live_xxx" }
 `quote_id` 调 `generate_*`。整集一次执行,不逐图打扰。长任务后台异步,用 `get_storyboards`/
 `get_final_cut` 轮询到完成。
 
+## 音色设计:没有声音样本,用一句话造一把专属声音
+
+旁白或某个角色在音色库里找不到合适的、手上也没有授权录音可以克隆时,用这组工具。
+典型场景:整部剧的旁白都是同一把播报腔,想换成贴合题材的声音。
+
+| 步骤 | 工具 | 费用 |
+|---|---|---|
+| ① 写描述,生成候选 | `design_voice`(`description`,可选试听句 `text`)→ 返回 `design_id` | 免费 |
+| ② 等待并试听 | `get_voice_design`(`design_id`)— 约 1~3 分钟;`done` 后每条候选下载为本地 wav(`local_path`),**交给客户试听挑选** | 免费 |
+| ③ 定样 | `save_designed_voice`(`design_id`、`index`、`name`)→ 返回 `voice_id`(形如 `lib:12`) | 与声音克隆同价;同一条重复保存不重复扣 |
+| ④ 用起来 | `set_character_voice`(`character_id`、`voice_id`)→ 之后 `generate_tts` 就用它念这个角色的全部台词 | 免费 |
+
+旁白也是一个角色(`char_type` 为 voiceover),按角色绑定即可。
+
+**描述怎么写**:写「要什么」,别写「不要什么」——模型对否定句不敏感。
+按 年龄 / 性别 / 音色 / 语速 / 情绪 几个维度各写一点即可,例如:
+
+- `一位中年男性,声音低沉温厚,语速偏慢,句尾自然下沉。`
+- `一位年轻女性,声音清澈,带一点气声,语速平缓,像在耳边轻声讲述。`
+- `一位老年男性,嗓音沙哑,说话慢,带着疲惫感。`
+
+**为什么一定要挑一条定下来**:同一句描述每次生成都是另一个人(实测相邻两次声纹相似度低至 0.23);
+定样之后整集走克隆,每句都是同一把声音(实测 0.85~0.90)。所以没有「按描述直接配整集」的工具,这是刻意的。
+
+**限制**:每个账号同时 1 个设计任务、24 小时 30 次;试听句 14~28 字(不填就用通用问候语);
+候选保留 6 小时;不要用真人/名人的名字去模仿特定人的声音(与声音克隆同一条授权红线)。
+
+可以直接对你的 agent 说:
+> 给这部剧的旁白设计一把声音:中年男性,低沉温厚,语速偏慢。生成几条让我听,我挑一条后绑到旁白上。
+
 ## 计费与安全
 
 - 预付制:必须有余额才能生成,账户**永不为负**;成本在调厂商**之前**预授权,不够返回 402。

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.87",
-    "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.87 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.88",
+    "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.88 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.87",
+  "version": "0.1.88",
   "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.87",
+  "version": "0.1.88",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.87",
+      "version": "0.1.88",
       "transport": {
         "type": "stdio"
       },