文生图转视频技能

基于用户提供的文本内容与图像，创建视频生成任务。任务提交后立即生效；系统将自动轮询任务状态，并获取最终生成的视频链接。

适用场景

✅ 推荐在以下情况中使用：

• “请根据我的描述，将这张图片转为视频”
• “请根据我的要求，用这张图片帮我生成一个视频”
• “请使用这张图片，按请求生成视频”
• “基于文本和一张图片生成视频”

不适用场景

❌ 以下情况请勿使用本技能：

• 用户要求进行视频剪辑、裁剪或添加特效 → 请引导其使用专业视频编辑工具
• 用户要求录屏或截图 → 请引导其使用屏幕录制工具
• 用户仅想查询已有视频任务的进度 → 请指导其前往相关文件或系统中自行查看

前置条件

export MAGIC_API_KEY="your-key"

MAGIC_API_KEY 是远程视频服务客户端所需的环境变量。

整体工作流程（Agent 指南）

1. 从用户消息中提取完整的文本内容（TEXT）和图像地址或路径（IMAGE）。
2. 使用 video-create 子命令创建任务，读取标准输出（stdout）中的 JSON 结果，并从中提取 task_id。
3. 在聊天中明确告知用户该 task_id，输出格式为：“视频生成任务已创建，任务 ID：task_id。我将持续检查任务状态，并在视频链接就绪后第一时间通知您。”
4. 使用 video-wait 子命令并传入 --task-id 参数轮询任务状态，直至任务完成。当任务状态（task_status）等于 2 时，表示成功。
5. 从 video-wait 命令的标准输出中提取 video_url 字段值。
6. 在聊天中明确告知用户最终的视频链接 video_url。若发生超时，请同步向用户说明。

Python 客户端（分步示例与聊天输出）

步骤 1：创建视频任务并在聊天中展示 task_id

1. 获取用户期望生成视频所依据的文本内容，并存入变量 TEXT；同时获取图像地址，存入变量 IMAGE。

   • 若文本中包含英文双引号 "，请务必对其进行转义（例如将 " 替换为 "），以避免命令解析错误。

2. 执行以下命令（由 Agent 工具调用；其中 {baseDir} 将被替换为该技能所在目录路径）：

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

3. 读取命令的标准输出（stdout），其为 JSON 格式，例如：

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

4. 从 JSON 中解析出 task_id 字段（例如 “abc-123”），并在聊天中向用户明确反馈：

• 输出内容：“视频生成任务已创建，任务 ID：task_id。我将持续检查任务状态，并在视频链接就绪后第一时间通知您。”

步骤 2：轮询任务状态并在聊天中输出最终 video_url

1. 复用上一步获得的 task_id。

2. 执行如下命令（每 10 秒轮询一次，最长等待 600 秒；若超时，请提示用户稍后重试）：

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

3. 读取标准输出。任务成功时，JSON 输出示例如下：

   {
    "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. 从输出中解析关键字段：

• 任务状态（例如 task_status: 2），其中状态码 2 表示成功
• 视频链接（例如 video_url: "https://example.com/path/to/video.mp4"）

5. 推荐的聊天回复方式：

• 用自然语言汇总关键信息，例如：

  “任务已完成 ✅
  task_id：abc-123
  视频链接：https://example.com/path/to/video.mp4”

6. 若返回结果表明任务失败或超时（例如 success 字段为 false、video_url 为空，或 error 字段为 timeout）：

• 向用户解释失败原因（如可能，请附带具体错误信息），并提示其可稍后重试，或检查输入内容是否合规、API 配额是否充足等问题。

脚本输出要求

• Agent 必须始终做到：
  • 正确解析 stdout 中的 JSON 输出；
  • 在聊天中清晰、准确地向用户同步任务 ID 和最终视频链接。