VoooAI - NL2Workflow Creative Platform

1. Overview

VoooAI is a multi-media creative platform with 70+ built-in AI skills. The Agent acts as a relay (搬运工) — forwarding user requests to VoooAI's backend, which handles all creative decisions via its multi-role AI system (Analyst + Expert + Reviewer).

Core Capabilities:

• Image Generation: Text-to-image, image-to-image, style transfer, concept art, storyboards
• Video Generation: Text-to-video, image-to-video, video editing, digital human, AI anchor
• Music Generation: Full songs, instrumentals, background music, soundtracks
• Workflow Orchestration: Multi-step automated pipelines (script → storyboard → video + music)

1.1 Who Should Use This Skill?

| User Type | Use Cases |

|-----------|-----------|

| Content Creators | Marketing videos, social media content, product showcases, promotional materials |

| Designers | Design assets, style variants, visual concepts, mood boards |

| Studios | Multi-step creative pipelines (script → storyboard → video + music) |

| Businesses | Advertising, e-commerce product videos, corporate training content |

| Game Developers | Game art assets, character concept art, cutscene animations |

| Educators | Tutorial videos, course illustrations, animated demonstrations |

| One-Person Companies | Full-stack content creation (posters, videos, music — all-in-one) |

1.2 When NOT to Use This Skill

This skill is exclusively for creative workflow operations. The following are explicitly out of scope:

• ❌ User account management (registration, login, profile changes)
• ❌ Billing, subscription, or payment operations
• ❌ Admin panel or system configuration
• ❌ Analytics, statistics, or usage data queries
• ❌ Homepage or dashboard features
• ❌ Direct parameter tuning (let the backend AI system handle optimization)

For these operations, direct users to https://voooai.com

2. Authentication

VOOOAI_ACCESS_KEY

• Source: User's VoooAI account page at https://voooai.com
• Format: vooai_ prefix + 40 random alphanumeric characters (46 total)
• Example: vooai_abc123def456ghi789jkl012mno345pqrs678

Scope (What the Key Allows)

• ✅ Capability discovery (check_capabilities.py)
• ✅ File upload (upload_file.py)
• ✅ Workflow generation (generate_workflow.py)
• ✅ Workflow execution (execute_workflow.py, execute_single_node.py)
• ✅ Status query (get_status.py)
• ✅ Result download (download_results.py)

Scope (What the Key DOES NOT Allow)

• ❌ Billing / payment / subscription management
• ❌ Admin / system administration
• ❌ User account settings / profile changes
• ❌ Analytics / statistics access

Storage

• Environment variable: export VOOOAI_ACCESS_KEY="vooai_..."
• Never hardcode in source code

3. Scope and Restrictions

Allowed Operations

• Capability discovery, file upload, workflow generation/execution, status query, result download

Forbidden Operations (Explicit Deny List)

If user requests these, inform them to visit voooai.com directly:

• ❌ Homepage / dashboard features
• ❌ User registration / login / authentication
• ❌ Subscription / payment / billing management
• ❌ Admin panel / system administration
• ❌ Analytics / statistics
• ❌ Account settings / profile management

Content Moderation (Explicit Deny List)

• ❌ Creating deepfakes or non-consensual facial/voice mimicry
• ❌ Impersonating real individuals without explicit consent
• ❌ Generating political disinformation or election interference content

> Content Safety Note: Digital human and talking-head features are intended for legitimate

> creative use cases (marketing presenters, educational hosts, fictional characters).

> Users must label AI-generated content per applicable synthetic media regulations.

4. Scope Boundaries

This section provides a clear table-based definition of what this skill can and cannot do.

Supported Operations

| Operation | Supported | Script | Example |

|-----------|-----------|--------|---------|

| Capability discovery | ✅ | check_capabilities.py | Check available skills and points balance |

| File upload | ✅ | upload_file.py | Upload reference image/video/audio (max 200MB) |

| Workflow generation | ✅ | generate_workflow.py | Generate workflow from natural language description |

| Workflow execution | ✅ | execute_workflow.py | Run generated workflow |

| Single node execution | ✅ | execute_single_node.py | Retry specific failed node |

| Status query | ✅ | get_status.py | Check execution progress |

| Result download | ✅ | download_results.py | Download generated files to local |

Forbidden Operations

| Operation | Reason |

|-----------|--------|

| User authentication / registration | Out of scope — handled by web frontend |

| Payment / billing / subscription | Out of scope — user manages directly at voooai.com |

| Account settings / profile | Out of scope — user manages directly |

| Analytics / usage statistics | Out of scope — not creative workflow |

| Admin panel / system config | Out of scope — admin only |

| Homepage / dashboard features | Out of scope — not workflow related |

| Direct API calls bypassing scripts | Security risk — use provided scripts only |

| Manual workflow JSON construction | Quality risk — use generate_workflow.py only |

| Deepfakes / non-consensual facial or voice mimicry | Content safety — violates ethical guidelines |

| Impersonating real individuals without consent | Content safety — privacy and legal concerns |

| Political disinformation / election interference | Content safety — harmful content prohibition |

5. Available Scripts

All scripts located at {baseDir}/scripts/. Required env: VOOOAI_ACCESS_KEY.

check_capabilities.py

Discover platform capabilities and points balance.

python3 {baseDir}/scripts/check_capabilities.py
python3 {baseDir}/scripts/check_capabilities.py --summary

upload_file.py

Upload image/video/audio file (max 200MB).

python3 {baseDir}/scripts/upload_file.py /path/to/file.png
python3 {baseDir}/scripts/upload_file.py /path/to/video.mp4

• Supported: jpg, png, webp, gif, mp4, mov, avi, mkv, webm, mp3, wav, flac, m4a

generate_workflow.py

Generate workflow from natural language description.

python3 {baseDir}/scripts/generate_workflow.py "生成一个咖啡产品宣传视频"
python3 {baseDir}/scripts/generate_workflow.py "基于这张图生成视频" --reference-urls https://example.com/ref.jpg
python3 {baseDir}/scripts/generate_workflow.py "生成分镜图" --skill-id storyboard-basic
python3 {baseDir}/scripts/generate_workflow.py "测试描述" --analyze-only  # analysis only

execute_workflow.py

Execute a generated workflow.

python3 {baseDir}/scripts/execute_workflow.py '{"nodes": [...], "connections": [...]}'
python3 {baseDir}/scripts/execute_workflow.py /path/to/workflow.json
cat workflow.json | python3 {baseDir}/scripts/execute_workflow.py --from-stdin
python3 {baseDir}/scripts/execute_workflow.py workflow.json --set-param node_1.prompt="新提示词"

execute_single_node.py

Execute/retry a single node (for debugging or partial retry).

python3 {baseDir}/scripts/execute_single_node.py workflow.json --node-id node_1
cat workflow.json | python3 {baseDir}/scripts/execute_single_node.py --from-stdin --node-id node_2
python3 {baseDir}/scripts/execute_single_node.py workflow.json --node-id node_1 --set-param node_1.prompt="修改后的提示词"

get_status.py

Query execution status.

python3 {baseDir}/scripts/get_status.py exec_abc123                            # single query
python3 {baseDir}/scripts/get_status.py exec_abc123 --poll                     # poll until complete
python3 {baseDir}/scripts/get_status.py exec_abc123 --poll --timeout 600       # custom timeout

download_results.py

Download execution results to local.

python3 {baseDir}/scripts/download_results.py exec_abc123
python3 {baseDir}/scripts/download_results.py exec_abc123 --output-dir ~/Downloads/project
python3 {baseDir}/scripts/download_results.py exec_abc123 --prefix "storyboard"
python3 {baseDir}/scripts/download_results.py exec_abc123 --no-download        # list URLs only
python3 {baseDir}/scripts/download_results.py --urls https://a.com/1.png       # direct URL download

6. Usage Patterns

This section describes common trigger patterns to help the Agent understand when and how to invoke VoooAI.

Pattern 1: Direct Media Generation

User expressions:

• "Generate an image of a sunset over mountains"
• "画一只戴眼镜的猫"
• "做个海报宣传我的产品"
• "Create a video of a dancing robot"
• "帮我做首轻松的背景音乐"

Execution flow:

check_capabilities → generate_workflow → execute_workflow → get_status (poll) → download_results

Pattern 2: Reference-Based Creation

User expressions:

• "Based on this image, generate a video"
• "把这张图变成动画"
• "用这首歌做个MV"
• "Convert this sketch to a realistic image"
• "参考这个风格做一组产品图"

Execution flow:

upload_file → generate_workflow (with --reference-urls) → execute_workflow → get_status (poll) → download_results

Pattern 3: Complex Multi-Step Workflows

User expressions:

• "Create a short drama about a detective"
• "帮我做个产品广告，从脚本到成片"
• "一句话生成短剧"
• "Make a complete promotional video with storyboard and music"
• "从剧本到分镜到视频帮我全流程做出来"

Execution flow:

generate_workflow (backend handles decomposition) → execute_workflow → get_status (poll, may take 3-5+ min) → download_results

Pattern 4: Failure Recovery & Retry

User expressions:

• "Retry with different parameters"
• "这个节点重新执行一下"
• "把提示词改一下再试"
• "换个风格重新生成"

Execution flow:

get_status (identify failed node) → execute_single_node (with --set-param if needed) → get_status (poll) → download_results

Pattern 5: Exploration & Discovery

User expressions:

• "What can you generate?"
• "你能做什么？"
• "有哪些创作能力？"
• "Show me available AI skills"
• "我还有多少积分？"

Execution flow:

check_capabilities → present results to user

7. Typical Workflows

Scenario 1: Basic Image/Video Generation

# 1. Check capabilities and points
python3 {baseDir}/scripts/check_capabilities.py --summary

# 2. Generate workflow (user confirms points_cost before proceeding)
python3 {baseDir}/scripts/generate_workflow.py "一个宇航员在月球上弹吉他"
# → Review estimated_points, ask user to confirm

# 3. Execute workflow
python3 {baseDir}/scripts/execute_workflow.py '<template_data_json>'

# 4. Poll status
python3 {baseDir}/scripts/get_status.py EXEC_ID --poll

# 5. Download results
python3 {baseDir}/scripts/download_results.py EXEC_ID --output-dir ./output

Scenario 2: With Reference Media (URL)

python3 {baseDir}/scripts/generate_workflow.py "根据这张图生成视频" \
  --reference-urls https://example.com/reference.jpg
# Then execute, poll, download as above

Scenario 3: With Local File Upload

# 1. Upload local file first
python3 {baseDir}/scripts/upload_file.py /path/to/reference.png
# → Returns file_url

# 2. Generate workflow with uploaded URL
python3 {baseDir}/scripts/generate_workflow.py "基于这张图生成视频" \
  --reference-urls <file_url_from_upload>
# Then execute, poll, download as above

Scenario 4: Failed Node Retry

# 1. Check which node failed
python3 {baseDir}/scripts/get_status.py EXEC_ID
# → Identify failed node_id from node_statuses

# 2. Retry single node (optionally adjust params)
python3 {baseDir}/scripts/execute_single_node.py workflow.json \
  --node-id failed_node_id \
  --set-param failed_node_id.some_param="adjusted_value"

# 3. Poll new execution
python3 {baseDir}/scripts/get_status.py NEW_EXEC_ID --poll

Scenario 5: Multi-Step Creative Pipeline (Short Drama / Product Ad)

# Complex workflow: script → storyboard → video + music (all handled by backend)
# Example: "帮我做个咖啡产品广告，从脚本到成片"

# 1. Check capabilities and points (complex workflows cost more)
python3 {baseDir}/scripts/check_capabilities.py --summary

# 2. Generate multi-step workflow (backend auto-decomposes)
python3 {baseDir}/scripts/generate_workflow.py "制作一个30秒的咖啡产品广告，包含脚本、分镜、视频和背景音乐"
# → Backend returns multi-node workflow (script → storyboard → video → music → composite)
# → Review estimated_points (typically 80-200+ for complex pipelines), ask user to confirm

# 3. Execute full pipeline
python3 {baseDir}/scripts/execute_workflow.py '<template_data_json>'

# 4. Poll status (complex workflows take 3-5+ minutes)
python3 {baseDir}/scripts/get_status.py EXEC_ID --poll --timeout 600

# 5. Download all outputs (storyboard images, video clips, music, final composite)
python3 {baseDir}/scripts/download_results.py EXEC_ID --output-dir ./output/product_ad

8. User Interaction Guidelines

Points Confirmation (CRITICAL)

When generate_workflow.py returns points_warning or estimated_points:

1. MUST show estimated cost to user before execution
2. MUST wait for user confirmation
3. NEVER auto-execute when points_warning exists

Example interaction:

Agent: "This workflow will cost approximately 45 points. You have 50 points available. Proceed? (yes/no)"
User: "yes"
Agent: [Then execute]

Multiple Options

When backend returns multiple plans or options:

• Present all options to user with clear descriptions
• Let user choose, do not auto-select

Ambiguous Parameters

When user description is vague:

• Ask clarifying questions about key parameters (duration, style, resolution)
• Do not guess or fill in creative details yourself

Post-Failure Decisions

When execution fails:

• Present failure reason clearly
• Offer options: retry, adjust parameters, change engine, or abort
• Let user decide next action

Core Principle

Agent MUST NOT make any points-consuming decision on behalf of the user.

9. Failure Handling and Retry

Diagnosis Steps

1. Run get_status.py EXEC_ID to get detailed error info
2. Check failed_nodes list and error_message
3. Review node_statuses for per-node status

Retry Strategies

| Strategy | When to Use | Command |

|----------|-------------|---------|

| Single-node retry | One node failed, others succeeded | execute_single_node.py --node-id |

| Parameter adjustment | Engine rejected params | Add --set-param to modify |

| Full retry | Multiple nodes failed or workflow error | Re-run execute_workflow.py |

Common Failure Scenarios

| Error Code | Cause | Resolution |

|------------|-------|------------|

| INSUFFICIENT_POINTS | Not enough credits | User adds credits at voooai.com/subscription |

| ENGINE_TIMEOUT | Engine took too long | Retry, or try different engine |

| INVALID_PARAMS | Bad parameters | Adjust params with --set-param |

| CONTENT_BLOCKED | Content safety filter | Modify description to comply with guidelines |

| ENGINE_UNAVAILABLE | Engine temporarily down | Wait and retry, or use alternative engine |

Known Limitations

• Status synchronization may lag — poll with patience
• Complex workflows (short dramas) may take 3-5+ minutes
• After 5-minute timeout, tell user to check results at voooai.com

10. Output Formats

check_capabilities.py: {success, points_balance, points_warning, available_engines, available_skills}

generate_workflow.py: {success, template_data, explanation, metadata: {node_count, engine_nodes, estimated_points}, points_warning}

execute_workflow.py: {success, execution_id, status, message}

get_status.py: {success, execution_id, status, progress, result_urls[]}

Status values: pending | running | completed | failed

download_results.py: {success, output_dir, downloaded_files[], total_count}

11. Core Principles

Agent is a Relay (搬运工)

• Forward user descriptions verbatim to the API
• NEVER rewrite, expand, embellish, or translate user prompts
• NEVER decompose tasks yourself (send "make 5 episodes" as ONE request)
• NEVER construct workflow JSON manually — always use generate_workflow.py

Trust the Backend

VoooAI's PlannerAgent (Analyst + Expert + Reviewer) handles:

• Task decomposition and planning
• Engine/model selection
• Prompt engineering and optimization
• Workflow structure design

Points Awareness

• ALWAYS check points_warning before execution
• ALWAYS inform user of estimated cost
• ALWAYS get user confirmation for costly operations

Scope Awareness

• ONLY operate workflow-related features
• NEVER attempt homepage, billing, admin, or account operations
• If user requests out-of-scope operation → direct them to voooai.com

12. Polling Strategy

• Interval: 10 seconds (do not poll more frequently)
• Timeout: 300 seconds (5 minutes default)
• Completion: status: "completed" → results in outputs
• Failure: status: "failed" → check error_message
• Post-timeout: Tell user to check at https://voooai.com

13. Error Reference

HTTP Codes: 400 (bad request) | 401 (unauthorized) | 403 (forbidden) | 429 (rate limit) | 500 (server error)

Error Codes:

• INVALID_ACCESS_KEY — Key must start with vooai_
• INSUFFICIENT_POINTS — Add credits at voooai.com/subscription
• MEMBERSHIP_REQUIRED — Engine requires higher tier
• RATE_LIMIT_EXCEEDED — Wait and retry
• ENGINE_UNAVAILABLE — Try alternative engine

Website: https://voooai.com | Support: support@voooai.com