magic-text2video

Create a text-to-video job from user-provided copy. Submits to the remote video service via one API key.

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.

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

3. 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"
  }

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

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

3. 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"
}

4. Parse the key fields from stdout:

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

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

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