fix(minimax-video-gen): 切换到 NewAPI 网关，升级 v1.2.3 → v1.3.0 (#25)

## 概述 / Summary 将默认全局技能 **minimax-video-gen（MiniMax 文生视频）** 从 MiniMax 原生 API 切换到 NewAPI 网关，已在本地 dev 环境验证通过。版本 `1.2.3 → 1.3.0`。 Switch the built-in skill **minimax-video-gen** from MiniMax's native API to the NewAPI gateway. Verified locally in dev. Version bumped `1.2.3 → 1.3.0`. ## 改动 / Changes - `provider: "minimax"` → `providerId: "desirecore-cloud"`（原生主机不支持 NewAPI 路径，必须用 providerId 指定网关 / native host doesn't support the NewAPI path) - endpoint `/video_generation` → `/video/generations`（带 s / with trailing "s"） - 轮询/状态值 `Success/Fail/Processing` → `completed/failed/queued/in_progress` - 移除 `file_id` 检索步骤，下载链接改为直接从 `data.metadata.url` 提取 / drop the `file_id` retrieval step, read the URL from `data.metadata.url` - 字段名 `resolution` → `size`；默认参数 `size=768P, duration=6` - 下载用 `curl -sL` 直连，不再经 media-proxy 代理 / download directly, no media-proxy 中英双语文档（SKILL.md / SKILL.zh-CN.md）已同步修改。 ## 影响 / Impact 合并后，已安装且未偏离该技能的线上客户端将通过 `marketSync` 的 git fetch + 10 分钟定时 `syncMarketSkillsOnly` 自动更新到 1.3.0（`compareSemver(1.2.3, 1.3.0) === -1` 触发更新）；已手动修改过该技能的用户会被跳过以保护本地改动。 Once merged, installed clients that haven't locally diverged will auto-update to 1.3.0 via marketSync git fetch + the 10-min `syncMarketSkillsOnly` timer. Users who modified the skill locally are skipped.
2026-07-23 06:03:45 +08:00 · 2026-06-09 18:40:10 +08:00
parent 329fb5fed1
commit 2cea1a3aa6
2 changed files with 148 additions and 102 deletions
--- a/skills/minimax-video-gen/SKILL.md
+++ b/skills/minimax-video-gen/SKILL.md
@@ -7,7 +7,7 @@ description: >-
  Use when 用户提到 生成视频、文生视频、AI 视频、创建视频、视频生成、
  动画生成、MiniMax 视频、海螺、Hailuo、图片变视频、图生视频。
 license: Complete terms in LICENSE.txt
-version: 1.2.3
+version: 1.3.0
 type: procedural
 risk_level: low
 status: enabled
@@ -24,7 +24,7 @@ requires:
    - Bash
 metadata:
  author: desirecore
-  updated_at: '2026-04-25'
+  updated_at: '2026-06-09'
  i18n:
    default_locale: en-US
    source_locale: zh-CN
@@ -70,21 +70,36 @@ market:
 1. **Must use HTTPS to access agent-service** — `https://127.0.0.1:${PORT}` with `-k` to skip certificate verification
 2. **Use Bash curl throughout** — do not use the HttpRequest tool or Python
 3. **Polling interval is 10 seconds** — use `sleep 10` to wait
+4. **Must use `providerId`** — do not use `provider`, or requests will route to the wrong upstream

 ## Full Execution Flow

 ### Prerequisites

- The user has already configured and enabled a MiniMax Provider (regular API or Token Plan) in Resource Manager → Compute and entered the API Key
+- The user has already configured and enabled a Provider with `video_gen` service in Resource Manager → Compute and entered the API Key
 - agent-service is running

-### Core Concept: Three-Step Asynchronous Flow
+### Core Concept: Four-Step Asynchronous Flow

-MiniMax video generation uses an asynchronous task model:
+Video generation uses an asynchronous task model via the NewAPI gateway:

-1. **Submit task**: POST to create a video generation task and receive a `task_id`
-2. **Poll status**: query the task status with `task_id` until `status` is `"Success"` or `"Fail"`
-3. **Download video**: use `file_id` to obtain the download URL
+1. **Submit task**: POST `/video/generations` to create a task, receive a `task_id`
+2. **Poll status**: GET `/videos/{task_id}` until `status` is `"completed"`
+3. **Download & upload**: download from `data.metadata.url`, upload to media-store
+4. **Display**: use `dc-media://` protocol to show the video
+
+### Provider Selection (Important)
+
+Use `providerId` (not `provider`) to target the correct gateway. When the provider is a NewAPI gateway (e.g. `desirecore-cloud`), use `providerId`. Do **not** use `provider: "minimax"` — this would route to the MiniMax native host, which does **not** support the NewAPI `/video/generations` path.
+
+```json
+{
+  "providerId": "desirecore-cloud",
+  "serviceType": "video_gen",
+  "endpoint": "/video/generations",
+  ...
+}
+```

 ### Model Selection and Fallback Strategy

@@ -101,17 +116,21 @@ MiniMax video generation uses an asynchronous task model:

 ### Step 1: Submit a Text-to-Video Task

+**Important**: The endpoint is `/video/generations` (with an "s"), NOT `/video_generation`.
+
 ```bash
 PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
-    "provider": "minimax",
+    "providerId": "desirecore-cloud",
    "serviceType": "video_gen",
-    "endpoint": "/video_generation",
+    "endpoint": "/video/generations",
    "body": {
      "model": "MiniMax-Hailuo-2.3",
-      "prompt": "Video content described by the user"
+      "prompt": "Video content described by the user",
+      "size": "768P",
+      "duration": 6
    },
    "responseType": "json"
  }'
@@ -119,10 +138,27 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \

 Optional parameters (add to the body):
 - `"duration"`: video length in seconds (6 or 10)
- `"resolution"`: `"768P"` or `"1080P"`
+- `"size"`: `"768P"` or `"1080P"` (use `size`, not `resolution`)

 Extract `data.task_id` from the JSON response.

+Successful response example:
+```json
+{
+  "success": true,
+  "data": {
+    "id": "task_xxx",
+    "task_id": "task_xxx",
+    "object": "video",
+    "model": "MiniMax-Hailuo-2.3",
+    "status": "queued",
+    "progress": 0,
+    "created_at": 1780995870
+  },
+  "statusCode": 200
+}
+```
+
 ### Step 1 (alternative): Image-to-Video

 ```bash
@@ -130,13 +166,14 @@ PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
-    "provider": "minimax",
+    "providerId": "desirecore-cloud",
    "serviceType": "video_gen",
-    "endpoint": "/video_generation",
+    "endpoint": "/video/generations",
    "body": {
      "model": "MiniMax-Hailuo-2.3",
      "prompt": "Describe the dynamic changes of the scene in the image",
-      "first_frame_image": "https://image-URL"
+      "first_frame_image": "https://image-URL",
+      "size": "768P"
    },
    "responseType": "json"
  }'
@@ -144,7 +181,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \

 ### Step 2: Poll the Task Status

-Call once every 10 seconds until `status` is `"Success"` or `"Fail"`. Replace `TASK_ID` with the `task_id` returned in Step 1.
+Call once every 10 seconds until `status` is `"completed"` or `"failed"`. Replace `TASK_ID` with the `task_id` returned in Step 1.

 ```bash
 PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
@@ -152,22 +189,24 @@ TASK_ID="task_id returned from step 1"
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d "{
-    \"provider\": \"minimax\",
+    \"providerId\": \"desirecore-cloud\",
    \"serviceType\": \"video_gen\",
-    \"endpoint\": \"/query/video_generation?task_id=${TASK_ID}\",
+    \"endpoint\": \"/videos/${TASK_ID}\",
    \"method\": \"GET\",
    \"responseType\": \"json\"
  }"
 ```

+In-progress statuses may be: `"queued"` or `"in_progress"`.
+
 Polling response (in progress):
 ```json
 {
  "success": true,
  "data": {
-    "task_id": "task_xxx",
-    "status": "Processing",
-    "file_id": ""
+    "id": "task_xxx",
+    "status": "in_progress",
+    "progress": 42
  }
 }
 ```
@@ -177,40 +216,23 @@ Polling response (completed):
 {
  "success": true,
  "data": {
-    "task_id": "task_xxx",
-    "status": "Success",
-    "file_id": "file_xxx"
+    "id": "task_xxx",
+    "status": "completed",
+    "progress": 100,
+    "metadata": {
+      "url": "https://.../output_aigc.mp4?..."
+    }
  }
 }
 ```

-### Step 3: Get the Video Download URL
+### Step 3: Download and Upload to media-store

-Replace `FILE_ID` with the `file_id` from the completed response in Step 2.
+Extract the video download URL from `data.metadata.url` in the completed Step 2 response. The URL is valid for 24 hours; download immediately.

 ```bash
 PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
-FILE_ID="file_id returned from step 2"
-curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
-  -H "Content-Type: application/json" \
-  -d "{
-    \"provider\": \"minimax\",
-    \"serviceType\": \"video_gen\",
-    \"endpoint\": \"/files/retrieve?file_id=${FILE_ID}\",
-    \"method\": \"GET\",
-    \"responseType\": \"json\"
-  }"
-```
-
-Extract `data.file.download_url` from the response.
-
-### Step 4: Download and Upload to media-store
-
-The download URL is valid for 24 hours; you must download immediately and save it to the local media-store.
-
-```bash
-PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
-VIDEO_URL="download_url obtained in step 3"
+VIDEO_URL="data.metadata.url from step 2"
 curl -sL "$VIDEO_URL" -o /tmp/minimax-video.mp4 && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
  -F "file=@/tmp/minimax-video.mp4;type=video/mp4"
@@ -218,7 +240,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \

 Extract the `mediaId` field from the JSON response.

-### Step 5: Display the Video Using the dc-media Protocol
+### Step 4: Display the Video Using the dc-media Protocol

 Write Markdown image syntax directly in your reply (the frontend will automatically recognize the video extension and render a player):

@@ -228,15 +250,16 @@ Write Markdown image syntax directly in your reply (the frontend will automatica

 ### Error Handling

- `status: "Fail"`: video generation failed; explain to the user
- `success: false` + `error: "No matching provider found"`: No enabled MiniMax provider with `video_gen` service found
+- `status: "failed"`: video generation failed; explain to the user
+- `success: false` + `error: "No matching provider found"`: No enabled provider with `video_gen` service found
 - `success: false` + `error: "API Key not configured"`: API Key has not been entered
 - **Insufficient quota** (errors related to `statusCode: 429`, `insufficient_quota`, `balance`): text-to-video cannot fall back (the Fast model does not support T2V); inform the user of insufficient quota; image-to-video can switch to `MiniMax-Hailuo-2.3-fast` and retry from Step 1
 - Polling exceeds 10 minutes without completion: inform the user that the task may have timed out

 ### Notes

- MiniMax video generation is asynchronous and typically takes 2–10 minutes
+- Video generation is asynchronous and typically takes 2–10 minutes
 - A polling interval of 10 seconds is recommended
 - The download URL is valid for 24 hours
- If the user does not explicitly request otherwise, by default do not pass `duration` or `resolution` (use API defaults)
+- If the user does not explicitly request otherwise, by default pass `"size": "768P"` and `"duration": 6`
+- Do **not** proxy the download URL through media-proxy — use `curl -sL "$VIDEO_URL"` to download directly
--- a/skills/minimax-video-gen/SKILL.zh-CN.md
+++ b/skills/minimax-video-gen/SKILL.zh-CN.md
@@ -7,21 +7,36 @@
 1. **必须用 HTTPS 访问 agent-service** — `https://127.0.0.1:${PORT}` 加 `-k` 跳过证书验证
 2. **全程使用 Bash curl** — 不要使用 HttpRequest 工具或 Python
 3. **轮询间隔 10 秒** — 使用 `sleep 10` 等待
+4. **必须使用 `providerId`** — 不要使用 `provider`，否则会路由到错误的上游

 ## 完整执行流程

 ### 前置条件

- 用户已在资源管理器-算力中配置并启用 MiniMax Provider（常规 API 或 Token Plan）并填写 API Key
+- 用户已在资源管理器-算力中配置并启用支持 `video_gen` 服务的 Provider 并填写 API Key
 - agent-service 正在运行

-### 核心概念：三步异步流程
+### 核心概念：四步异步流程

-MiniMax 视频生成采用异步任务模式：
+视频生成通过 NewAPI 网关采用异步任务模式：

-1. **提交任务**：POST 创建视频生成任务，返回 `task_id`
-2. **轮询状态**：用 `task_id` 查询任务状态，直到 `status` 为 `"Success"` 或 `"Fail"`
-3. **下载视频**：用 `file_id` 获取下载 URL
+1. **提交任务**：POST `/video/generations` 创建任务，返回 `task_id`
+2. **轮询状态**：GET `/videos/{task_id}` 直到 `status` 为 `"completed"`
+3. **下载并上传**：从 `data.metadata.url` 下载视频，上传到 media-store
+4. **展示**：用 `dc-media://` 协议展示
+
+### Provider 选择（重要）
+
+使用 `providerId`（不是 `provider`）来指定正确的网关。当 Provider 是 NewAPI 网关（如 `desirecore-cloud`）时，使用 `providerId`。**不要**使用 `provider: "minimax"`——这会路由到 MiniMax 原生主机，原生主机**不支持** NewAPI 的 `/video/generations` 路径。
+
+```json
+{
+  "providerId": "desirecore-cloud",
+  "serviceType": "video_gen",
+  "endpoint": "/video/generations",
+  ...
+}
+```

 ### 模型选择与降级策略

@@ -38,17 +53,21 @@ MiniMax 视频生成采用异步任务模式：

 ### 第一步：提交文生视频任务

+**重要**：endpoint 是 `/video/generations`（带 "s"），不是 `/video_generation`。
+
 ```bash
 PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
-    "provider": "minimax",
+    "providerId": "desirecore-cloud",
    "serviceType": "video_gen",
-    "endpoint": "/video_generation",
+    "endpoint": "/video/generations",
    "body": {
      "model": "MiniMax-Hailuo-2.3",
-      "prompt": "用户描述的视频内容"
+      "prompt": "用户描述的视频内容",
+      "size": "768P",
+      "duration": 6
    },
    "responseType": "json"
  }'
@@ -56,10 +75,27 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \

 可选参数（加入 body 中）：
 - `"duration"`: 视频时长秒数（6 或 10）
- `"resolution"`: `"768P"` 或 `"1080P"`
+- `"size"`: `"768P"` 或 `"1080P"`（使用 `size`，不是 `resolution`）

 从 JSON 响应中提取 `data.task_id`。

+成功响应示例：
+```json
+{
+  "success": true,
+  "data": {
+    "id": "task_xxx",
+    "task_id": "task_xxx",
+    "object": "video",
+    "model": "MiniMax-Hailuo-2.3",
+    "status": "queued",
+    "progress": 0,
+    "created_at": 1780995870
+  },
+  "statusCode": 200
+}
+```
+
 ### 第一步（备选）：图生视频

 ```bash
@@ -67,13 +103,14 @@ PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d '{
-    "provider": "minimax",
+    "providerId": "desirecore-cloud",
    "serviceType": "video_gen",
-    "endpoint": "/video_generation",
+    "endpoint": "/video/generations",
    "body": {
      "model": "MiniMax-Hailuo-2.3",
      "prompt": "描述图片中场景的动态变化",
-      "first_frame_image": "https://图片URL"
+      "first_frame_image": "https://图片URL",
+      "size": "768P"
    },
    "responseType": "json"
  }'
@@ -81,7 +118,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \

 ### 第二步：轮询任务状态

-每隔 10 秒调用一次，直到 `status` 为 `"Success"` 或 `"Fail"`。将 `TASK_ID` 替换为第一步返回的 `task_id`。
+每隔 10 秒调用一次，直到 `status` 为 `"completed"` 或 `"failed"`。将 `TASK_ID` 替换为第一步返回的 `task_id`。

 ```bash
 PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
@@ -89,22 +126,24 @@ TASK_ID="第一步返回的task_id"
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
  -H "Content-Type: application/json" \
  -d "{
-    \"provider\": \"minimax\",
+    \"providerId\": \"desirecore-cloud\",
    \"serviceType\": \"video_gen\",
-    \"endpoint\": \"/query/video_generation?task_id=${TASK_ID}\",
+    \"endpoint\": \"/videos/${TASK_ID}\",
    \"method\": \"GET\",
    \"responseType\": \"json\"
  }"
 ```

+处理中状态可能为：`"queued"` 或 `"in_progress"`。
+
 轮询响应（进行中）：
 ```json
 {
  "success": true,
  "data": {
-    "task_id": "task_xxx",
-    "status": "Processing",
-    "file_id": ""
+    "id": "task_xxx",
+    "status": "in_progress",
+    "progress": 42
  }
 }
 ```
@@ -114,40 +153,23 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
 {
  "success": true,
  "data": {
-    "task_id": "task_xxx",
-    "status": "Success",
-    "file_id": "file_xxx"
+    "id": "task_xxx",
+    "status": "completed",
+    "progress": 100,
+    "metadata": {
+      "url": "https://.../output_aigc.mp4?..."
+    }
  }
 }
 ```

-### 第三步：获取视频下载链接
+### 第三步：下载并上传到 media-store

-将 `FILE_ID` 替换为第二步完成响应中的 `file_id`。
+从第二步完成响应的 `data.metadata.url` 提取视频下载地址。下载 URL 有 24 小时时效，必须立即下载。

 ```bash
 PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
-FILE_ID="第二步返回的file_id"
-curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
-  -H "Content-Type: application/json" \
-  -d "{
-    \"provider\": \"minimax\",
-    \"serviceType\": \"video_gen\",
-    \"endpoint\": \"/files/retrieve?file_id=${FILE_ID}\",
-    \"method\": \"GET\",
-    \"responseType\": \"json\"
-  }"
-```
-
-从响应中提取 `data.file.download_url`。
-
-### 第四步：下载并上传到 media-store
-
-下载 URL 有 24 小时时效，必须立即下载并保存到本地 media-store。
-
-```bash
-PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
-VIDEO_URL="第三步获取的download_url"
+VIDEO_URL="第二步返回的 data.metadata.url"
 curl -sL "$VIDEO_URL" -o /tmp/minimax-video.mp4 && \
 curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
  -F "file=@/tmp/minimax-video.mp4;type=video/mp4"
@@ -155,7 +177,7 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \

 从 JSON 响应中提取 `mediaId` 字段。

-### 第五步：用 dc-media 协议展示视频
+### 第四步：用 dc-media 协议展示视频

 在你的回复文本中直接写 Markdown 图片语法（前端会自动识别视频扩展名并渲染播放器）：

@@ -165,15 +187,16 @@ curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \

 ### 错误处理

- `status: "Fail"`：视频生成失败，向用户说明
- `success: false` + `error: "未找到匹配的供应商"`：未找到已启用且支持 `video_gen` 服务的 MiniMax Provider
+- `status: "failed"`：视频生成失败，向用户说明
+- `success: false` + `error: "未找到匹配的供应商"`：未找到已启用且支持 `video_gen` 服务的 Provider
 - `success: false` + `error: "未配置 API Key"`：未填写 API Key
 - **额度不足**（`statusCode: 429`、`insufficient_quota`、`balance` 相关错误）：文生视频无法降级（Fast 模型不支持 T2V），告知用户额度不足；图生视频可换用 `MiniMax-Hailuo-2.3-fast` 从第一步重试
 - 轮询超过 10 分钟未完成：告知用户任务可能超时

 ### 注意事项

- MiniMax 视频生成是异步的，通常需要 2-10 分钟
+- 视频生成是异步的，通常需要 2-10 分钟
 - 轮询间隔建议 10 秒
 - 下载 URL 有 24 小时时效
- 如果用户未明确要求，默认不传 duration 和 resolution（使用 API 默认值）
+- 如果用户未明确要求，默认传 `"size": "768P"` 和 `"duration": 6`
+- **不要**通过 media-proxy 代理下载 URL——用 `curl -sL "$VIDEO_URL"` 直接下载