magic-text2video（魔术文字 2 视频）

Text to Video Skill

Create a video generation task from text. The job is submitted immediately; Polling to obtain task status and video URL.

When to Use

✅ USE this skill when:

• "把这段文字生成视频"
• "帮我把这段文案做成视频"
• "用这段文字生成一个视频"
• User provides a script or paragraph and asks to turn it into video

When NOT to Use

❌ DON'T use this skill when:

• User asks for video editing, trimming, or effects → use video-editing tools
• User asks for screen recording or capture → use recording tools
• User asks only for video status of an existing job → explain where to find files instead

Prerequisites

export MAGIC_API_KEY="your-key"

MAGIC_API_KEY is required by the remote video service client.

Overall Flow (Agent Guidance)

1. Extract the full text from the user's message, denoted as TEXT (i.e., the script to be used for video generation).
2. Use the video-create subcommand to create a task, read the JSON from stdout, and extract the task_id.
3. Explicitly inform the user of the task_id in the chat (optionally include the original JSON output for debugging).
4. Use the video-wait subcommand with the task_id as --task-id, polling until successful.
5. 从 video-wait 的 stdout 中提取 video_url.
6. Explicitly inform the user of the final video_url in the chat (you may also include the original output).

Python Client (Step-by-step with Chat Output)

Step 1: Create a video task and print the task_id to the chat

1. Extract the text the user wants to generate a video from and assign it to TEXT.

- If the text contains double quotes ", properly escape them before constructing the command (for example, by replacing " with \") to avoid shell parsing errors.

1. Run the following command (executed by the agent/tool; {baseDir} will be replaced with the Skill directory):

python3 {baseDir}/scripts/media_gen_client.py video-create \
  --text  "TEXT"

1. Read the stdout from this command. The expected output will be JSON, for example:

   {
    "biz_code": 10000,
    "msg": "Success",
    "data": {
        "task_id": "2032443088023777280"
    },
    "trace_id": "664c6e22-1edd-11f1-bf4c-8262dce7d13f"
  }

1. Parse the task_id from stdout (e.g., "abc-123"), and inform the user in the chat: "A text-to-video task has been created, task_id: abc-123. I will keep polling for the task status, and send you the video URL once it is ready."

Step 2: Poll the task until success and output video_url in the chat

1. Use the task_id obtained in the previous step and refer to it as task_id.

1. Run the following command to poll the task status (check every 10 seconds and wait up to 600 seconds); if it times out, wait a while and retry:

python3 {baseDir}/scripts/media_gen_client.py video-wait --task-id YOUR_TASK_ID --poll 10 --timeout 600

1. Read the stdout from this command. When the task succeeds, the script should output information including the video_url, for example:

   {
    "biz_code": 10000,
    "msg": "Success",
    "data": {
        "task_id": "1234567890",
        "task_status": 2,
        "video_url": "https://www.magiclight.com/examplevideo.mp4"
    },
    "trace_id": "c89aeca8-1edd-11f1-bf4c-8262dce7d13f"
}

1. Parse the key fields from stdout:

• status (e.g., 2)
• video_url (e.g., "https://example.com/path/to/video.mp4")

1. In the chat, respond to the user as follows:

• Optionally (but recommended for debugging), first display the full JSON output inside a code block.
• Then summarize the key information in natural language, for example:

> "Task completed ✅ > task_id: abc-123 > Video URL: https://example.com/path/to/video.mp4"

1. If the stdout indicates that the task failed or timed out (for example, if the status is "failed" or there is no video_url):

• Explain the reason for failure in the chat (include any error message, if available).
• Inform the user that they can retry later, or check their input, quota, etc.

Expected Script Output Contract

• The agent must always:

- Parse the stdout JSON. - Clearly communicate the task_id and video_url to the user in the chat. - If necessary, optionally display the raw JSON output in a code block.