AI Director - Full Workflow of AI Short Drama Generation

👥 Multi-user Support

credentials/{USER_ID}.json

USER_ID

TELEGRAM_USER_ID

USER_ID=5470522468 node scripts/ad-account-manager.js check-binding

🎯 Module Overview

1. Ad Account Manager

• Function: X2C platform account binding, verification
• Script:

  scripts/ad-account-manager.js

• Independent use: ✅ Can be called separately

2. Ad Writer

• 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

• Function: Generate complete video from script
• Script:

  scripts/ad-producer.js

• Dependency: ⚠️ X2C account binding required first

🚀 Quick Start

Step 1: Get X2C API Key

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

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～

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

ad-account-manager.js verify-key

node scripts/ad-account-manager.js verify-key x2c_sk_xxx

credentials/{USER_ID}.json

Step 3: View configuration and pricing

node scripts/ad-producer.js config

Step 4: Generate short drama

references/AD-WRITER-GUIDE.md

node scripts/ad-producer.js full-workflow "A programmer travels back to ancient times to be the prime minister" --duration 120 --wait

⚠️ Important Rules

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

Command List

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

# Verify and get API Key
node scripts/ad-account-manager.js verify user@example.com 123456

# Check binding status
node scripts/ad-account-manager.js check-binding

# View configuration options
node scripts/ad-account-manager.js config

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

# Help
node scripts/ad-account-manager.js help

Direct binding (if you already have an API Key)

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

🎭 Ad Character Manager

Command List

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

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

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

# Help
node scripts/ad-character-manager.js help

Parameter Description

Usage Example

# View current characters
node scripts/ad-character-manager.js list

# Create female character
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

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

API Interface

✍️ Ad Writer

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

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

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. 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

Command List

# View configuration and pricing
node scripts/ad-producer.js config

# Generate script
node scripts/ad-producer.js generate-script "your idea" --wait

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

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

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

# Full workflow (recommended)
node scripts/ad-producer.js full-workflow "idea description" --duration 120

Generation Options

Cost

🔄 Complete Workflow

Option A: Step-by-step execution

# 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

# 2. View pricing
node scripts/ad-producer.js config

# 3. Generate script
node scripts/ad-producer.js generate-script "A programmer travels back to ancient times" --wait
# → Get project_id

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

Option B: One-click automation

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

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

🛡️ Security & Privacy

• 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

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

Invalid API Key

❌ Error: Invalid or missing API key

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

📊 X2C Open API

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

Interface List

references/X2C-OPEN-API.md

📚 Document Reference

• Scriptwriting Guide:

  references/AD-WRITER-GUIDE.md

• Script Example:

  references/example.md

• X2C API:

  references/X2C-OPEN-API.md

🎓 Best Practices

Cost Optimization

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. 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.

🔍 Quality Evaluator

Evaluation Dimensions

Usage

# Evaluate a single video
node scripts/quality-evaluator.js <video_url> --prompt "original prompt"

# JSON output
node scripts/quality-evaluator.js <video_url> --json

Output Example

{
  "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

Rules

• Pass line: 80 points
• Maximum iterations: 5 times
• Each iteration: generate → evaluate → if failed, improve the prompt and try again

Usage

node scripts/auto-iterate.js "your idea" \
  --duration 60 \
  --style "Ghibli" \
  --threshold 80 \
  --max-iterations 5

Configuration Requirements

config.json

{
  "x2cApiKey": "x2c_sk_<REDACTED>xxx",
  "geminiApiKey": "your_gemini_api_key"
}

📋 User Parameter Confirmation Format (Mandatory)

📋 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. **Start the task, do not wait**
```bash
# Start video generation, return project_id
USER_ID=$USER_ID node scripts/ad-producer.js full-workflow "theme" --mode short_video --duration 60 --style "style" --language zh

1. Add task to tracking list (Mandatory!)

# Immediately call after the video starts generating:
/opt/storyclaw/add-video-task.sh "$USER_ID" "$project_id" "$CHAT_ID"
# Parameters: user_id, project_id, chat_id (Telegram user ID)

1. 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:

• 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

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

• 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

produce-video

• ✅ Can query

  video-status

  multiple times
• ❌ Cannot submit

  produce-video

  repeatedly

short_video (1 episode)

1. Generate script
2. Video generation → Notify user after completion

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

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

• 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

config/get-options

⚠️ Agent Output Specification

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

1. Display the video link
2. Display the credit consumption of this episode
3. Ask the user whether to continue producing the next episode

🎉 Video generation completed!

📊 Credit consumption: 599 credits

Continue to produce the next episode?
- Yes, continue EP3
- Pause for now

• 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. 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

❌ 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

🔄 Multi-episode Short Drama Production Rule (short_drama)

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

&response-content-disposition=attachment

&response-content-disposition=attachment

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 Message Push

webchat-stream-ws.sh

Script Location

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

Usage

# Send new message (INSERT mode)
webchat-stream-ws.sh <user_id> --file <message_file> <agent_id>

# Update existing message (UPDATE mode)
webchat-stream-ws.sh <user_id> --update <message_id> --file <message_file> <agent_id>

Parameter Description

director

Example

# 1. Send confirmation message and get message_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. Update message after task completion
echo "✅ Video generation completed!" > /tmp/result.txt
webchat-stream-ws.sh "180d08e23cdac976b4" --update "$MSG_ID" --file /tmp/result.txt "director"

Notes

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

# WebChat push (chat_id format: webchat:<user_id>:<agent_id>)
add-video-task.sh "180d08e23cdac976b4" "project-id" "webchat:180d08e23cdac976b4:director"

# Telegram push (chat_id is pure number)
add-video-task.sh "5470522468" "project-id" "5470522468"

check-video-tasks.sh