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 TypeUse CasesContent CreatorsMarketing videos, social media content, product showcases, promotional materialsDesignersDesign assets, style variants, visual concepts, mood boardsStudiosMulti-step creative pipelines (script → storyboard → video + music)BusinessesAdvertising, e-commerce product videos, corporate training contentGame DevelopersGame art assets, character concept art, cutscene animationsEducatorsTutorial videos, course illustrations, animated demonstrationsOne-Person CompaniesFull-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#

OperationSupportedScriptExampleCapability discovery✅check_capabilities.pyCheck available skills and points balanceFile upload✅upload_file.pyUpload reference image/video/audio (max 200MB)Workflow generation✅generate_workflow.pyGenerate workflow from natural language descriptionWorkflow execution✅execute_workflow.pyRun generated workflowSingle node execution✅execute_single_node.pyRetry specific failed nodeStatus query✅get_status.pyCheck execution progressResult download✅download_results.pyDownload generated files to local

Forbidden Operations#

OperationReasonUser authentication / registrationOut of scope — handled by web frontendPayment / billing / subscriptionOut of scope — user manages directly at voooai.comAccount settings / profileOut of scope — user manages directlyAnalytics / usage statisticsOut of scope — not creative workflowAdmin panel / system configOut of scope — admin onlyHomepage / dashboard featuresOut of scope — not workflow relatedDirect API calls bypassing scriptsSecurity risk — use provided scripts onlyManual workflow JSON constructionQuality risk — use generate_workflow.py onlyDeepfakes / non-consensual facial or voice mimicryContent safety — violates ethical guidelinesImpersonating real individuals without consentContent safety — privacy and legal concernsPolitical disinformation / election interferenceContent 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.

bash

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

upload_file.py#

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

bash

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.

bash

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.

bash

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

bash

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.

bash

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.

bash

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:

text

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:

text

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:

text

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:

text

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:

text

check_capabilities → present results to user

7. Typical Workflows#

Scenario 1: Basic Image/Video Generation#

bash

# 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)#

bash

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#

bash

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

bash

# 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)#

bash

# 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:

text

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#

StrategyWhen to UseCommandSingle-node retryOne node failed, others succeededexecute_single_node.py --node-id <failed_node>Parameter adjustmentEngine rejected paramsAdd --set-param to modifyFull retryMultiple nodes failed or workflow errorRe-run execute_workflow.py

Common Failure Scenarios#

Error CodeCauseResolutionINSUFFICIENT_POINTSNot enough creditsUser adds credits at voooai.com/subscriptionENGINE_TIMEOUTEngine took too longRetry, or try different engineINVALID_PARAMSBad parametersAdjust params with --set-param``CONTENT_BLOCKEDContent safety filterModify description to comply with guidelinesENGINE_UNAVAILABLEEngine temporarily downWait 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