Back to Details

ai-director

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AI Director - AI短剧生成全流程

AI Director - Full Workflow of AI Short Drama Generation

完整的AI短剧生成解决方案，从创意到成片，集成X2C平台账号管理和计费。
A complete AI short drama generation solution, from idea to finished video, integrated with X2C platform account management and billing.

👥 多用户支持

👥 Multi-user Support

本Skill支持多用户共享设备，每个用户拥有独立的X2C账号和配置。
用户凭证存储位置: 
credentials/{USER_ID}.json
调用脚本时需设置 
USER_ID
或 
TELEGRAM_USER_ID
环境变量：
bash
USER_ID=5470522468 node scripts/ad-account-manager.js check-binding
OpenClaw从聊天调用时会自动传递用户ID。
This Skill supports multi-user device sharing, each user has independent X2C account and configuration.
User credential storage path: 
credentials/{USER_ID}.json
You need to set the 
USER_ID
or 
TELEGRAM_USER_ID
environment variable when calling the script:
bash
USER_ID=5470522468 node scripts/ad-account-manager.js check-binding
OpenClaw will automatically pass the user ID when calling from chat.

🎯 模块概览

🎯 Module Overview

1. Ad Account Manager（账号管理）

1. Ad Account Manager

  • 功能: X2C平台账号绑定、验证
  • 脚本: 
    scripts/ad-account-manager.js
  • 独立使用: ✅ 可以单独调用
  • Function: X2C platform account binding, verification
  • Script: 
    scripts/ad-account-manager.js
  • Independent use: ✅ Can be called separately

2. Ad Writer（编剧）

2. Ad Writer

  • 功能: 从创意点子生成完整短剧脚本
  • 类型: 提示词工程（Agent 读取指南后生成）
  • 文档: 
    references/AD-WRITER-GUIDE.md
  • 依赖: ⚠️ 需要先绑定X2C账号
  • Function: Generate complete short drama scripts from creative ideas
  • Type: Prompt engineering (generated after Agent reads the guide)
  • Document: 
    references/AD-WRITER-GUIDE.md
  • Dependency: ⚠️ X2C account binding required first

3. Ad Producer（视频生产）

3. Ad Producer

  • 功能: 从剧本生成完整视频
  • 脚本: 
    scripts/ad-producer.js
  • 依赖: ⚠️ 需要先绑定X2C账号
  • Function: Generate complete video from script
  • Script: 
    scripts/ad-producer.js
  • Dependency: ⚠️ X2C account binding required first

🚀 快速开始

🚀 Quick Start

第一步：获取X2C API Key

Step 1: Get X2C API Key

用户必须自行完成以下步骤：
  1. 打开 https://www.x2creel.ai 注册/登录账号
  2. 进入个人中心 → API管理 → 创建/复制 API Key
  3. 将 API Key 发送给我
示例对话：
用户：我想生成视频
助手：好的，需要先绑定X2C账号。请打开 https://www.x2creel.ai 登录，然后在个人中心获取API Key发给我。
用户：x2c_sk_xxx...
助手：验证通过！你的账号已绑定，现在可以开始生成视频了～
Users must complete the following steps by themselves:
  1. Open https://www.x2creel.ai to register/login
  2. Go to Personal Center → API Management → Create/Copy API Key
  3. Send the API Key to the assistant
Sample conversation:
User: I want to generate a video
Assistant: Okay, you need to bind your X2C account first. Please open https://www.x2creel.ai to log in, then get the API Key in the personal center and send it to me.
User: x2c_sk_xxx...
Assistant: Verification passed! Your account has been bound, you can start generating videos now～

第二步：验证API Key（Agent自动执行）

Step 2: Verify API Key (automatically executed by Agent)

Agent 收到 API Key 后，调用 
ad-account-manager.js verify-key
验证有效性：
bash
node scripts/ad-account-manager.js verify-key x2c_sk_xxx
验证成功后将 key 保存到 
credentials/{USER_ID}.json
After the Agent receives the API Key, it calls 
ad-account-manager.js verify-key
to verify validity:
bash
node scripts/ad-account-manager.js verify-key x2c_sk_xxx
After successful verification, the key is saved to 
credentials/{USER_ID}.json

第三步：查看配置和定价

Step 3: View configuration and pricing

bash
node scripts/ad-producer.js config
bash
node scripts/ad-producer.js config

第四步：生成短剧

Step 4: Generate short drama

选项A - 仅编剧（Agent模式）： Agent 读取 
references/AD-WRITER-GUIDE.md
，根据用户创意生成剧本。
选项B - 全流程（剧本 + 视频）：
bash
node scripts/ad-producer.js full-workflow "一个程序员穿越到古代当宰相" --duration 120 --wait
Option A - Scriptwriting only (Agent mode): Agent reads 
references/AD-WRITER-GUIDE.md
and generates scripts based on user ideas.
Option B - Full workflow (script + video):
bash
node scripts/ad-producer.js full-workflow "A programmer travels back to ancient times to be the prime minister" --duration 120 --wait

⚠️ 重要规则

⚠️ Important Rules

在用户提供有效的 X2C API Key 之前，禁止执行任何视频生成或剧本生成操作！
如果用户要求生成视频但尚未绑定账号：
  1. 引导用户访问 https://www.x2creel.ai
  2. 告知获取API Key的步骤
  3. 收到有效Key后才可进入制作流程
Before the user provides a valid X2C API Key, it is forbidden to perform any video generation or script generation operations!
If the user requests to generate a video but has not bound an account:
  1. Guide the user to visit https://www.x2creel.ai
  2. Inform the steps to get the API Key
  3. Only enter the production process after receiving a valid key

📦 Ad Account Manager（账号管理）

📦 Ad Account Manager

命令列表

Command List

bash
undefined
bash
undefined

发送验证码

Send verification code

node scripts/ad-account-manager.js send-code user@example.com
node scripts/ad-account-manager.js send-code user@example.com

验证并获取 API Key

Verify and get API Key

node scripts/ad-account-manager.js verify user@example.com 123456
node scripts/ad-account-manager.js verify user@example.com 123456

检查绑定状态

Check binding status

node scripts/ad-account-manager.js check-binding
node scripts/ad-account-manager.js check-binding

查看配置选项

View configuration options

node scripts/ad-account-manager.js config
node scripts/ad-account-manager.js config

解绑账号

Unbind account

node scripts/ad-account-manager.js unbind
node scripts/ad-account-manager.js unbind

帮助

Help

node scripts/ad-account-manager.js help
undefined
node scripts/ad-account-manager.js help
undefined

直接绑定（如果已有 API Key）

Direct binding (if you already have an API Key)

bash
node scripts/ad-account-manager.js bind --key "x2c_sk_<REDACTED>xxx"
bash
node scripts/ad-account-manager.js bind --key "x2c_sk_<REDACTED>xxx"

🎭 Ad Character Manager（角色管理）

🎭 Ad Character Manager

管理自定义角色，可在视频制作中用作主角。制作时系统会根据性别自动匹配角色与剧本中的人物。
注意： 每个用户最多 5 个角色。
Manage custom characters that can be used as protagonists in video production. During production, the system will automatically match characters with the characters in the script according to gender.
Note: Each user can have up to 5 characters.

命令列表

Command List

bash
undefined
bash
undefined

查询角色列表

Query character list

node scripts/ad-character-manager.js list
node scripts/ad-character-manager.js list

创建角色

Create character

node scripts/ad-character-manager.js create <name> <gender> <image_url>
node scripts/ad-character-manager.js create <name> <gender> <image_url>

删除角色

Delete character

node scripts/ad-character-manager.js delete <character_id>
node scripts/ad-character-manager.js delete <character_id>

帮助

Help

node scripts/ad-character-manager.js help
undefined
node scripts/ad-character-manager.js help
undefined

参数说明

Parameter Description

参数说明必填选项
name角色显示名称✅-
gender性别✅male, female, other
image_url角色图片的公开 URL（最大 10MB）✅-
ParameterDescriptionRequiredOptions
nameCharacter display name✅-
genderGender✅male, female, other
image_urlPublic URL of character image (max 10MB)✅-

使用示例

Usage Example

bash
undefined
bash
undefined

查看当前角色

View current characters

node scripts/ad-character-manager.js list
node scripts/ad-character-manager.js list

创建女性角色

Create female character

node scripts/ad-character-manager.js create Alice female https://example.com/alice.png
node scripts/ad-character-manager.js create Alice female https://example.com/alice.png

创建男性角色

Create male character

node scripts/ad-character-manager.js create Bob male https://example.com/bob.png
node scripts/ad-character-manager.js create Bob male https://example.com/bob.png

删除角色

Delete character

node scripts/ad-character-manager.js delete <uuid>
undefined
node scripts/ad-character-manager.js delete <uuid>
undefined

API 接口

API Interface

Action说明
character/list查询角色列表
character/create创建角色
character/delete删除角色
ActionDescription
character/listQuery character list
character/createCreate character
character/deleteDelete character

✍️ Ad Writer（编剧）

✍️ Ad Writer

这是提示词工程模块，AI Agent 读取指南后自己生成剧本。
This is a prompt engineering module, the AI Agent generates the script by itself after reading the guide.

功能特性

Features

  • 斯皮尔伯格风格: 温情人性、视觉诗意、情感共鸣
  • 三线并行: 当下故事线、前史线、反派/外因线
  • 工业化流程: 严格遵循短剧市场物理生产限制
  • 完整剧本结构: 剧名、梗概、人物小传、大纲、分集、正集
  • Spielberg style: Warm humanity, visual poetry, emotional resonance
  • Three parallel storylines: current storyline, pre-history line, villain/external factor line
  • Industrial process: Strictly follow the physical production limits of the short drama market
  • **Complete script structure: drama name, synopsis, character biography, outline, episode breakdown, full script

使用方式

Usage

Agent 工作流程：
  1. 读取 
    references/AD-WRITER-GUIDE.md
    （完整编剧指南）
  2. 根据用户创意，按指南生成剧本
  3. 输出六部分完整剧本
用户指令示例：
帮我写一个短剧剧本：一个程序员意外拯救了CEO，却不知道对方的真实身份
Agent workflow:
  1. Read 
    references/AD-WRITER-GUIDE.md
    (complete scriptwriting guide)
  2. Generate the script according to the user's idea and the guide
  3. Output the complete script in six parts
Sample user instruction:
Write me a short drama script: a programmer accidentally saves the CEO, but doesn't know the other person's real identity

输出内容

Output Content

  1. 剧名
  2. 一句话梗概
  3. 人物小传
  4. 故事大纲
  5. 分集概况（1-30集）
  6. 剧本正集（完整台词和镜头描述）
  1. Drama name
  2. One-sentence synopsis
  3. Character biography
  4. Story outline
  5. Episode overview (1-30 episodes)
  6. Full script (complete lines and shot descriptions)

🎬 Ad Producer（视频生产）

🎬 Ad Producer

命令列表

Command List

bash
undefined
bash
undefined

查看配置和定价

View configuration and pricing

node scripts/ad-producer.js config
node scripts/ad-producer.js config

生成剧本

Generate script

node scripts/ad-producer.js generate-script "你的创意" --wait
node scripts/ad-producer.js generate-script "your idea" --wait

查询剧本状态

Query script status

node scripts/ad-producer.js script-status <project_id>
node scripts/ad-producer.js script-status <project_id>

生产视频

Produce video

node scripts/ad-producer.js produce-video <project_id> 1 --wait
node scripts/ad-producer.js produce-video <project_id> 1 --wait

查询视频进度

Query video progress

node scripts/ad-producer.js video-status <project_id> 1
node scripts/ad-producer.js video-status <project_id> 1

全流程（推荐）

Full workflow (recommended)

node scripts/ad-producer.js full-workflow "创意描述" --duration 120
undefined
node scripts/ad-producer.js full-workflow "idea description" --duration 120
undefined

生成选项

Generation Options

参数说明默认值
--modeshort_video / short_dramashort_video
--duration60 / 120 / 180 / 300120
--ratio9:16 / 16:99:16
--style风格名称-
--episodes集数（固定值，不可用户自定义）short_video=1, short_drama=10
--languagezh / enzh
--character-ids角色UUID数组（逗号分隔），用作主角-
--wait等待完成false
ParameterDescriptionDefault Value
--modeshort_video / short_dramashort_video
--duration60 / 120 / 180 / 300120
--ratio9:16 / 16:99:16
--styleStyle name-
--episodesNumber of episodes (fixed value, cannot be customized by users)short_video=1, short_drama=10
--languagezh / enzh
--character-idsArray of character UUIDs (comma separated), used as protagonists-
--waitWait for completionfalse

成本

Cost

项目积分美元
剧本（short_video）10$0.1
剧本（short_drama）100$1
视频 60s299$2.99
视频 120s599$5.99
视频 180s799$7.99
视频 300s999$9.99
ItemCreditsUSD
Script (short_video)10$0.1
Script (short_drama)100$1
Video 60s299$2.99
Video 120s599$5.99
Video 180s799$7.99
Video 300s999$9.99

🔄 完整工作流程

🔄 Complete Workflow

方案A：分步执行

Option A: Step-by-step execution

bash
undefined
bash
undefined

1. 绑定账号（首次使用）

1. Bind account (first use)

node scripts/ad-account-manager.js send-code your@email.com node scripts/ad-account-manager.js verify your@email.com 123456
node scripts/ad-account-manager.js send-code your@email.com node scripts/ad-account-manager.js verify your@email.com 123456

2. 查看定价

2. View pricing

node scripts/ad-producer.js config
node scripts/ad-producer.js config

3. 生成剧本

3. Generate script

node scripts/ad-producer.js generate-script "一个程序员穿越古代" --wait
node scripts/ad-producer.js generate-script "A programmer travels back to ancient times" --wait

→ 获得 project_id

→ Get project_id

4. 生产视频

4. Produce video

node scripts/ad-producer.js produce-video <project_id> 1 --wait
undefined
node scripts/ad-producer.js produce-video <project_id> 1 --wait
undefined

方案B：一键自动化

Option B: One-click automation

bash
node scripts/ad-producer.js full-workflow "一个程序员穿越到古代当宰相" \
  --mode short_video \
  --duration 120 \
  --ratio 9:16
bash
node scripts/ad-producer.js full-workflow "A programmer travels back to ancient times to be the prime minister" \
  --mode short_video \
  --duration 120 \
  --ratio 9:16

⚙️ 配置文件

⚙️ Configuration File

config.json
:
json
{
  "x2cApiKey": "x2c_sk_<REDACTED>your_api_key_here",
  "x2cEmail": "your@email.com",
  "x2cUserId": "user-uuid"
}
config.json
:
json
{
  "x2cApiKey": "x2c_sk_<REDACTED>your_api_key_here",
  "x2cEmail": "your@email.com",
  "x2cUserId": "user-uuid"
}

🛡️ 安全与隐私

🛡️ Security & Privacy

  • API keys 存储在本地 
    config.json
  • 显示时自动脱敏
  • 所有API调用使用 HTTPS
  • API keys are stored locally in 
    config.json
  • Automatic desensitization when displayed
  • All API calls use HTTPS

🔧 故障排查

🔧 Troubleshooting

账号未绑定

Account not bound

❌ X2C Account Not Bound
解决方案:
bash
node scripts/ad-account-manager.js send-code your@email.com
node scripts/ad-account-manager.js verify your@email.com <code>
❌ X2C Account Not Bound
Solution:
bash
node scripts/ad-account-manager.js send-code your@email.com
node scripts/ad-account-manager.js verify your@email.com <code>

积分不足

Insufficient credits

❌ Error: Insufficient credits
解决方案: 访问 https://x2creel.ai 充值
❌ Error: Insufficient credits
Solution: Visit https://x2creel.ai to recharge

API Key 无效

Invalid API Key

❌ Error: Invalid or missing API key
解决方案:
bash
node scripts/ad-account-manager.js unbind
node scripts/ad-account-manager.js send-code your@email.com
❌ Error: Invalid or missing API key
Solution:
bash
node scripts/ad-account-manager.js unbind
node scripts/ad-account-manager.js send-code your@email.com

📊 X2C Open API

📊 X2C Open API

Base URL: 
https://eumfmgwxwjyagsvqloac.supabase.co/functions/v1/open-api
Base URL: 
https://eumfmgwxwjyagsvqloac.supabase.co/functions/v1/open-api

接口列表

Interface List

Action说明
auth/send-code发送验证码
auth/verify验证获取 API Key
config/get-options获取配置选项
character/list查询角色列表
character/create创建角色
character/delete删除角色
script/generate生成剧本
script/query查询剧本状态
video/produce生产视频
video/query查询视频进度
详细 API 文档见 
references/X2C-OPEN-API.md
ActionDescription
auth/send-codeSend verification code
auth/verifyVerify to get API Key
config/get-optionsGet configuration options
character/listQuery character list
character/createCreate character
character/deleteDelete character
script/generateGenerate script
script/queryQuery script status
video/produceProduce video
video/queryQuery video progress
For detailed API documentation, see 
references/X2C-OPEN-API.md

📚 文档参考

📚 Document Reference

  • 编剧指南: 
    references/AD-WRITER-GUIDE.md
  • 剧本示例: 
    references/example.md
  • X2C API: 
    references/X2C-OPEN-API.md
  • Scriptwriting Guide: 
    references/AD-WRITER-GUIDE.md
  • Script Example: 
    references/example.md
  • X2C API: 
    references/X2C-OPEN-API.md

🎓 最佳实践

🎓 Best Practices

成本优化

Cost Optimization

  1. 先用 short_video 测试
    • 60s 视频成本低（299 积分）
    • 确认风格满意后再做长视频
  2. 选择合适的时长
    • 60s: 简短宣传片
    • 120s: 标准短剧（推荐）
    • 180s-300s: 完整剧情
  1. Test with short_video first
    • 60s video cost is low (299 credits)
    • Confirm the style is satisfactory before making long videos
  2. Choose the appropriate duration
    • 60s: Short promotional video
    • 120s: Standard short drama (recommended)
    • 180s-300s: Complete plot

提高成功率

Improve Success Rate

  1. 创意要清晰具体
    • 明确主角、背景、冲突
    • 避免过于抽象的描述
  2. 选择合适的风格
    • 用 
      config
      命令查看可用风格
    • 3D古风、现代都市等
适用场景： 商业化部署、付费短剧生成服务、B端创作工具
  1. Clear and specific ideas
    • Clear protagonist, background, conflict
    • Avoid too abstract descriptions
  2. Choose the right style
    • Use the 
      config
      command to view available styles
    • 3D ancient style, modern urban, etc.
Applicable scenarios: Commercial deployment, paid short drama generation service, B-side creation tools

🔍 Quality Evaluator（质量评估）

🔍 Quality Evaluator

使用 Gemini 2.0 Flash 分析视频质量，按标准打分。
Use Gemini 2.0 Flash to analyze video quality and score according to standards.

评估维度

Evaluation Dimensions

维度一：单片段质量 (100分)
指标权重说明
时空一致性35%主体特征在镜头内保持稳定
动态动力学30%运动符合物理规律，无跳帧
视觉纯净度20%纹理清晰，无 AI 噪点
光影交互15%阴影随物体运动同步变化
维度二：合成视频质量 (100分)
指标权重说明
视觉流一致性30%镜头间色调匹配
剪辑节奏感25%转场自然，匹配 BGM
叙事匹配度25%准确传达剧本剧情
音画同步率20%音效与视觉契合
Dimension 1: Single clip quality (100 points)
IndicatorWeightDescription
Spatio-temporal consistency35%Subject characteristics remain stable in the shot
Dynamic dynamics30%Motion conforms to physical laws, no frame skipping
Visual purity20%Clear texture, no AI noise
Light and shadow interaction15%Shadows change synchronously with object movement
Dimension 2: Composite video quality (100 points)
IndicatorWeightDescription
Visual flow consistency30%Color tone matching between shots
Editing rhythm25%Natural transitions, matching BGM
Narrative matching degree25%Accurately convey the script plot
Audio and video synchronization rate20%Sound effects fit the vision

使用方式

Usage

bash
undefined
bash
undefined

评估单个视频

Evaluate a single video

node scripts/quality-evaluator.js <video_url> --prompt "原始提示词"
node scripts/quality-evaluator.js <video_url> --prompt "original prompt"

JSON 输出

JSON output

node scripts/quality-evaluator.js <video_url> --json
undefined
node scripts/quality-evaluator.js <video_url> --json
undefined

输出示例

Output Example

json
{
  "total_score": 75,
  "pass": false,
  "issues": ["人物面部不一致", "光影不自然"],
  "suggestions": ["简化角色描述", "明确光源方向"],
  "prompt_improvements": "改进后的提示词..."
}
json
{
  "total_score": 75,
  "pass": false,
  "issues": ["Inconsistent character faces", "Unnatural light and shadow"],
  "suggestions": ["Simplify character description", "Clarify light source direction"],
  "prompt_improvements": "Improved prompt..."
}

🔄 Auto-Iterate（自动迭代）

🔄 Auto-Iterate

自动评估 + 改进提示词 + 重新生成，直到质量达标。
Automatic evaluation + prompt improvement + re-generation until the quality meets the standard.

规则

Rules

  • 及格线: 80 分
  • 最大迭代: 5 次
  • 每次迭代：生成 → 评估 → 如果不及格则改进提示词重试
  • Pass line: 80 points
  • Maximum iterations: 5 times
  • Each iteration: generate → evaluate → if failed, improve the prompt and try again

使用方式

Usage

bash
node scripts/auto-iterate.js "你的创意" \
  --duration 60 \
  --style "吉卜力" \
  --threshold 80 \
  --max-iterations 5
bash
node scripts/auto-iterate.js "your idea" \
  --duration 60 \
  --style "Ghibli" \
  --threshold 80 \
  --max-iterations 5

配置要求

Configuration Requirements

config.json
需要包含：
json
{
  "x2cApiKey": "x2c_sk_<REDACTED>xxx",
  "geminiApiKey": "your_gemini_api_key"
}
适用场景： 商业化部署、付费短剧生成服务、B端创作工具
config.json
needs to include:
json
{
  "x2cApiKey": "x2c_sk_<REDACTED>xxx",
  "geminiApiKey": "your_gemini_api_key"
}
Applicable scenarios: Commercial deployment, paid short drama generation service, B-side creation tools

📋 用户参数确认格式（强制）

📋 User Parameter Confirmation Format (Mandatory)

当用户要求创建视频时，必须用文字让用户直接回复选项来确认参数。必须等用户确认全部参数后才能开始生成：
📋 参数确认

请回复你的选择：

🎬 模式：短剧(10集) 或 短视频(1集)

⏱️ 时长/价格：60秒/299、120秒/599、180秒/799、300秒/999

📐 比例：竖屏(9:16) 或 横屏(16:9)

🎨 风格：3D古风 / 2D漫剧 / 吉卜力 / 皮克斯 / 写实 / 二次元 / 国风水墨

📂 分类：玄幻 / 悬疑 / 科幻 / 都市 / 热门 / 霸总 / 仙侠

例如：「短剧、180秒、竖屏、3D古风、仙侠」

**语言**: 中文 / English
When a user requests to create a video, you must use text to let the user directly reply to the option to confirm the parameters. You must wait for the user to confirm all parameters before starting generation:
📋 Parameter Confirmation

Please reply with your choice:

🎬 Mode: Short drama (10 episodes) or Short video (1 episode)

⏱️ Duration/Price: 60s/299, 120s/599, 180s/799, 300s/999

📐 Ratio: Vertical (9:16) or Horizontal (16:9)

🎨 Style: 3D ancient style / 2D comic drama / Ghibli / Pixar / Realistic / Anime / Chinese ink wash

📂 Category: Fantasy / Suspense / Sci-fi / Urban / Popular / CEO romance / Xianxia

Example: "Short drama, 180s, vertical, 3D ancient style, Xianxia"

**Language**: Chinese / English

⚡ 异步任务处理（重要！）

⚡ Asynchronous Task Processing (Important!)

当用户要求生成视频时，必须使用异步方式，不要等待完成！
When a user requests to generate a video, you must use asynchronous mode, do not wait for completion!

流程：

Process:

  1. 启动任务，不等待
bash
undefined
  1. Start the task, do not wait
bash
undefined

启动视频生成，返回project_id

Start video generation, return project_id

USER_ID=$USER_ID node scripts/ad-producer.js full-workflow "主题" --mode short_video --duration 60 --style "风格" --language zh

2. **添加任务到跟踪列表**（必须！）
```bash
USER_ID=$USER_ID node scripts/ad-producer.js full-workflow "theme" --mode short_video --duration 60 --style "style" --language zh

2. **Add task to tracking list (Mandatory!)**
```bash

视频开始生成后，立即调用：

Immediately call after the video starts generating:

/opt/storyclaw/add-video-task.sh "$USER_ID" "$project_id" "$CHAT_ID"
/opt/storyclaw/add-video-task.sh "$USER_ID" "$project_id" "$CHAT_ID"

参数: user_id, project_id, chat_id (Telegram用户ID)

Parameters: user_id, project_id, chat_id (Telegram user ID)


3. **完成后自动通知**
- cron job每2分钟检查一次 /tmp/active-video-tasks.json
- 完成后自动发送消息通知用户

3. **Automatic notification after completion**
- Cron job checks /tmp/active-video-tasks.json every 2 minutes
- Automatically send a message to notify the user after completion

关键点：

Key points:

  • 不要用 --wait 参数，会阻塞
  • 启动任务后立即返回"正在生成，稍等"
  • 必须调用 add-video-task.sh 添加任务到跟踪列表
  • 创建cron job监控进度
  • 完成后通过对应渠道通知用户
用户创建短剧时，以下5个参数只能从配置选项中选取，不允许自定义值：
  1. 模式: 
    short_video
    或 
    short_drama
  2. 时长: 
    60
    / 
    120
    / 
    180
    / 
    300
  3. 比例: 
    9:16
    或 
    16:9
  4. 风格: 
    3D古风
    / 
    2D漫剧
    / 
    吉卜力
    / 
    皮克斯
    / 
    写实风格
    / 
    二次元
    / 
    国风水墨
  5. 分类:
    • 中文: 
      玄幻异能
      / 
      悬疑惊悚
      / 
      科幻末世
      / 
      都市复仇
      / 
      热门综合
      / 
      霸总甜宠
      / 
      仙侠古装
    • 英文: 
      Werewolf & Shifter
      / 
      Suspense & Horror
      / 
      Power & Revenge
      / 
      Sweet & CEO
      / 
      Magic & Fantasy
      / 
      AI Drama Lab
如果用户提供的任何一项不在配置列表中，必须提示用户从列表中重新选择，不得自行替换或忽略。
集数规则（强制）：
  • short_video
    → 固定1集，不询问用户
  • short_drama
    → 固定10集，不询问用户
  • 不允许用户自定义集数，引导流程中不展示集数选项
  • Do not use --wait parameter, it will block
  • Return "Generating, please wait" immediately after starting the task
  • Must call add-video-task.sh to add the task to the tracking list
  • Create a cron job to monitor progress
  • Notify users through the corresponding channel after completion
When a user creates a short drama, the following 5 parameters can only be selected from the configuration options, custom values are not allowed:
  1. Mode: 
    short_video
    or 
    short_drama
  2. Duration: 
    60
    / 
    120
    / 
    180
    / 
    300
  3. Ratio: 
    9:16
    or 
    16:9
  4. Style: 
    3D ancient style
    / 
    2D comic drama
    / 
    Ghibli
    / 
    Pixar
    / 
    Realistic
    / 
    Anime
    / 
    Chinese ink wash
  5. Category:
    • Chinese: 
      Fantasy power
      / 
      Suspense thriller
      / 
      Sci-fi apocalypse
      / 
      Urban revenge
      / 
      Popular comprehensive
      / 
      CEO romance
      / 
      Xianxia ancient costume
    • English: 
      Werewolf & Shifter
      / 
      Suspense & Horror
      / 
      Power & Revenge
      / 
      Sweet & CEO
      / 
      Magic & Fantasy
      / 
      AI Drama Lab
If any item provided by the user is not in the configuration list, you must prompt the user to reselect from the list, and you are not allowed to replace or ignore it yourself.
Episode rule (Mandatory):
  • short_video
    → Fixed 1 episode, do not ask the user
  • short_drama
    → Fixed 10 episodes, do not ask the user
  • Users are not allowed to customize the number of episodes, and the episode option is not displayed in the guidance process

🎬 视频生产流程（强制）

🎬 Video Production Process (Mandatory)

重要规则：同一集只能发起一次制作

Important rule: Only one production can be initiated for the same episode

每个episode只能提交一次 
produce-video
命令！
  • ✅ 可以多次查询 
    video-status
  • ❌ 不能重复提交 
    produce-video
如果任务失败，等待第三方系统修复，不要重复提交。
Only one 
produce-video
command can be submitted per episode!
  • ✅ Can query 
    video-status
    multiple times
  • ❌ Cannot submit 
    produce-video
    repeatedly
If the task fails, wait for the third-party system to fix it, do not submit repeatedly.

short_video (1集)

short_video (1 episode)

1. 生成剧本
2. 视频生成 → 完成后通知用户
1. Generate script
2. Video generation → Notify user after completion

short_drama (10集) - 必须逐集生产

short_drama (10 episodes) - Must be produced episode by episode

1. 生成剧本 (10集)
2. 等待剧本完成
3. EP1 视频生成 → 等待完成
4. EP2 视频生成 → 等待完成
5. EP3 视频生成 → 等待完成
...
10. EP10 视频生成 → 等待完成
11. 全部完成 → 通知用户
关键点：
  • 必须等上一集完成后再开始下一集，不能并行
  • 每集生成完成后记录状态
  • 全部10集完成后统一通知用户
调用 
config/get-options
API可获取最新配置列表（风格和分类可能会更新）。
1. Generate script (10 episodes)
2. Wait for script completion
3. EP1 video generation → Wait for completion
4. EP2 video generation → Wait for completion
5. EP3 video generation → Wait for completion
...
10. EP10 video generation → Wait for completion
11. All completed → Notify user
Key points:
  • Must wait for the previous episode to complete before starting the next one, cannot be parallel
  • Record status after each episode is generated
  • Notify the user uniformly after all 10 episodes are completed
Call the 
config/get-options
API to get the latest configuration list (styles and categories may be updated).

⚠️ Agent 输出规范

⚠️ Agent Output Specification

  1. 链接必须完整输出，不得截断（视频 URL 带签名很长，但必须完整）
  2. 使用代码块 ``` 包裹长链接，避免被聊天软件截断
  3. 关键信息（Project ID、Video URL）必须清晰展示
  1. Links must be output completely, not truncated (video URLs with signatures are very long, but must be complete)
  2. Use code blocks ``` to wrap long links to avoid being truncated by chat software
  3. Key information (Project ID, Video URL) must be clearly displayed

📢 视频完成通知规则

📢 Video Completion Notification Rule

短剧(10集)模式下，当前集完成后必须询问用户是否继续制作下一集！
当一集视频生成完成后：
  1. 展示视频链接
  2. 展示本集积分消耗
  3. 询问用户是否继续制作下一集
示例回复：
🎉 视频生成完成！

📊 积分消耗：599积分

继续制作下一集吗？
- 是，继续EP3
- 暂时停止
注意：
  • short_video (1集) 无需询问
  • 短剧模式必须询问
  • 用户选择"是"后，再发起下一集的制作
In short drama (10 episodes) mode, you must ask the user whether to continue producing the next episode after the current episode is completed!
When an episode video is generated:
  1. Display the video link
  2. Display the credit consumption of this episode
  3. Ask the user whether to continue producing the next episode
Sample reply:
🎉 Video generation completed!

📊 Credit consumption: 599 credits

Continue to produce the next episode?
- Yes, continue EP3
- Pause for now
Note:
  • No need to ask for short_video (1 episode)
  • Must ask for short drama mode
  • After the user selects "Yes", initiate the production of the next episode

⚠️ 视频失败处理规则

⚠️ Video Failure Handling Rule

视频生成失败后，禁止自动重试生成！
原因：每次生成都会扣除用户积分，自动重试会导致额外扣费。
处理流程：
  1. 查询失败原因（通过 
    video-status
    命令查看 status 和 progress）
  2. 将失败原因告知用户
  3. 等待用户指示是否重试或调整参数
示例回复：
❌ 视频生成失败
原因: 人物生成失败 (character step failed at 14%)
当前余额: 20,013 积分

请选择：
- 重试生成（将从余额中扣除相应积分）
- 更换风格/参数后重试
- 取消任务
After video generation fails, automatic retry generation is prohibited!
Reason: Each generation will deduct user credits, automatic retry will lead to additional deductions.
Handling process:
  1. Query the failure reason (view status and progress through the 
    video-status
    command)
  2. Inform the user of the failure reason
  3. Wait for the user's instruction to retry or adjust parameters
Sample reply:
❌ Video generation failed
Reason: Character generation failed (character step failed at 14%)
Current balance: 20,013 credits

Please choose:
- Retry generation (corresponding credits will be deducted from the balance)
- Retry after changing style/parameters
- Cancel task

🔄 多集短剧生产规则（short_drama）

🔄 Multi-episode Short Drama Production Rule (short_drama)

视频必须逐集生产，不能同时启动多集。 流程：
  1. 生成剧本时必须传 
    total_episodes
    参数（如 
    "total_episodes": 10
    ），否则只会生成1集
  2. 调用 
    video/produce
    启动第1集视频制作
  3. 轮询第1集状态，等待完成
  4. 第1集完成后，调用 
    video/produce
    启动第2集
  5. 重复直到所有集完成
  6. 每集完成后通知用户进度（如 "EP3/10 完成"）
  7. 全部完成后发送总积分报告
Videos must be produced episode by episode, multiple episodes cannot be started at the same time. Process:
  1. Must pass the 
    total_episodes
    parameter when generating the script (e.g. 
    "total_episodes": 10
    ), otherwise only 1 episode will be generated
  2. Call 
    video/produce
    to start the production of the first episode video
  3. Poll the status of the first episode, wait for completion
  4. After the first episode is completed, call 
    video/produce
    to start the second episode
  5. Repeat until all episodes are completed
  6. Notify the user of the progress after each episode is completed (e.g. "EP3/10 completed")
  7. Send a total credit report after all are completed

🎬 视频播放优化

🎬 Video Playback Optimization

CDN返回的视频URL末尾带有 
&response-content-disposition=attachment
，会导致浏览器强制下载而非播放。
规则：拿到视频URL后，必须去掉 
&response-content-disposition=attachment
参数，然后可以直接在浏览器中播放，无需下载到本地。
流程：
  1. 获取视频URL（从 
    video-status
    命令）
  2. 去掉 
    &response-content-disposition=attachment
  3. 直接 
    browser navigate
    到清理后的URL → 即可播放
  4. 询问用户是否需要下载视频（默认不下载，只播放）
  5. 如用户要下载/发送到Telegram：下载+压缩到16MB以下（480p, crf 32）再发送
The video URL returned by CDN has 
&response-content-disposition=attachment
at the end, which will cause the browser to force download instead of playing.
Rule: After getting the video URL, you must remove the 
&response-content-disposition=attachment
parameter, then it can be played directly in the browser without downloading to the local.
Process:
  1. Get the video URL (from the 
    video-status
    command)
  2. Remove 
    &response-content-disposition=attachment
  3. Directly 
    browser navigate
    to the cleaned URL → can be played
  4. Ask the user if they need to download the video (no download by default, only play)
  5. If the user wants to download/send to Telegram: download + compress to below 16MB (480p, crf 32) before sending

📱 WebChat 消息推送

📱 WebChat Message Push

WebChat 是 StoryClaw 设备的网页聊天渠道，通过 
webchat-stream-ws.sh
脚本推送消息。
WebChat is the web chat channel of StoryClaw devices, which pushes messages through the 
webchat-stream-ws.sh
script.

脚本位置

Script Location

/opt/storyclaw/webchat-stream-ws.sh
/opt/storyclaw/webchat-stream-ws.sh

使用方法

Usage

bash
undefined
bash
undefined

发送新消息（INSERT 模式）

Send new message (INSERT mode)

webchat-stream-ws.sh <user_id> --file <message_file> <agent_id>
webchat-stream-ws.sh <user_id> --file <message_file> <agent_id>

更新现有消息（UPDATE 模式）

Update existing message (UPDATE mode)

webchat-stream-ws.sh <user_id> --update <message_id> --file <message_file> <agent_id>
undefined
webchat-stream-ws.sh <user_id> --update <message_id> --file <message_file> <agent_id>
undefined

参数说明

Parameter Description

参数说明
user_idWebChat 用户 ID（32位hex）
message_id已有消息的 ID，用于更新
message_file包含消息内容的文件路径（必须用 --file 传递，避免 $ 符号丢失）
agent_id目标 agent ID（如 
director
）
ParameterDescription
user_idWebChat user ID (32-bit hex)
message_idExisting message ID, used for update
message_fileFile path containing message content (must be passed with --file to avoid loss of $ symbol)
agent_idTarget agent ID (e.g. 
director
)

示例

Example

bash
undefined
bash
undefined

1. 发送确认消息并获取 message_id

1. Send confirmation message and get message_id

echo "正在生成视频..." > /tmp/msg.txt MSG_ID=$(webchat-stream-ws.sh "180d08e23cdac976b4" --file /tmp/msg.txt "director") echo "Message ID: $MSG_ID"
echo "Generating video..." > /tmp/msg.txt MSG_ID=$(webchat-stream-ws.sh "180d08e23cdac976b4" --file /tmp/msg.txt "director") echo "Message ID: $MSG_ID"

2. 任务完成后更新消息

2. Update message after task completion

echo "✅ 视频生成完成！" > /tmp/result.txt webchat-stream-ws.sh "180d08e23cdac976b4" --update "$MSG_ID" --file /tmp/result.txt "director"
undefined
echo "✅ Video generation completed!" > /tmp/result.txt webchat-stream-ws.sh "180d08e23cdac976b4" --update "$MSG_ID" --file /tmp/result.txt "director"
undefined

注意事项

Notes

  1. 必须使用 --file 模式 — 直接传文本会导致 
    $
    符号丢失
  2. message_id 用于原地更新 — 避免产生多条消息
  3. 异步任务配合 — 视频生成等长时间任务，先发送"处理中"消息，任务完成后再 update
  1. Must use --file mode — passing text directly will cause loss of 
    $
    symbol
  2. message_id is used for in-place update — avoid generating multiple messages
  3. Cooperate with asynchronous tasks — for long tasks such as video generation, send a "processing" message first, then update after the task is completed

视频任务进度推送

Video Task Progress Push

使用 
add-video-task.sh
添加任务时，chat_id 格式决定通知渠道：
bash
undefined
When using 
add-video-task.sh
to add a task, the chat_id format determines the notification channel:
bash
undefined

WebChat 推送（chat_id 格式：webchat:<user_id>:<agent_id>）

WebChat push (chat_id format: webchat:<user_id>:<agent_id>)

add-video-task.sh "180d08e23cdac976b4" "project-id" "webchat:180d08e23cdac976b4:director"
add-video-task.sh "180d08e23cdac976b4" "project-id" "webchat:180d08e23cdac976b4:director"

Telegram 推送（chat_id 为纯数字）

Telegram push (chat_id is pure number)

add-video-task.sh "5470522468" "project-id" "5470522468"

`check-video-tasks.sh` 会每2分钟检查任务状态，根据 chat_id 格式自动选择推送渠道。

---

**版本：** 2.1.2 (X2C Open API + WebChat 推送支持)
add-video-task.sh "5470522468" "project-id" "5470522468"

`check-video-tasks.sh` will check the task status every 2 minutes, and automatically select the push channel according to the chat_id format.

---

**Version:** 2.1.2 (X2C Open API + WebChat push support)