diff --git a/plugins/minimax-video/.claude-plugin/plugin.json b/plugins/minimax-video/.claude-plugin/plugin.json new file mode 100644 index 00000000..6a69e941 --- /dev/null +++ b/plugins/minimax-video/.claude-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "minimax-video", + "version": "0.1.0", + "description": "Generate videos with MiniMax-Hailuo-2.3 from a text prompt or a first-frame image, poll generation status, and download the finished file across the global and China API endpoints.", + "author": { + "name": "BuildWithClaude Community", + "url": "https://github.com/davepoon/buildwithclaude" + }, + "repository": "https://github.com/davepoon/buildwithclaude", + "license": "MIT", + "keywords": [ + "minimax", + "hailuo", + "video-generation", + "text-to-video", + "image-to-video", + "slash-commands" + ] +} diff --git a/plugins/minimax-video/README.md b/plugins/minimax-video/README.md new file mode 100644 index 00000000..a9b5780e --- /dev/null +++ b/plugins/minimax-video/README.md @@ -0,0 +1,48 @@ +# minimax-video + +Generate videos with **MiniMax-Hailuo-2.3** directly from Claude Code. This plugin +adds slash commands that wrap the MiniMax video-generation REST API, covering the +full asynchronous flow — create a task, poll its status, and download the result — +across both the global and China API hosts. + +## Commands + +| Command | Operation | Method & path | +| --- | --- | --- | +| `/minimax-video:text-to-video` | Create a task from a text prompt | `POST /v1/video_generation` | +| `/minimax-video:image-to-video` | Create a task from a first-frame image | `POST /v1/video_generation` | +| `/minimax-video:query-video` | Poll a task's status and read its `file_id` | `GET /v1/query/video_generation` | +| `/minimax-video:download-video` | Resolve a `file_id` to a download URL | `GET /v1/files/retrieve` | + +## Endpoints + +| Region | Base URL | Docs | +| --- | --- | --- | +| Global | `https://api.minimax.io` | https://platform.minimax.io/docs/api-reference/api-overview | +| China | `https://api.minimaxi.com` | https://platform.minimaxi.com/docs/api-reference/api-overview | + +Each command takes an optional `--region global|cn` flag (default `global`) that +selects the matching host. + +## Models + +Default: `MiniMax-Hailuo-2.3`. Also accepted: `MiniMax-Hailuo-2.3-Fast`, +`MiniMax-Hailuo-02`, `T2V-01-Director`, `T2V-01`, `I2V-01-Director`, `I2V-01-live`, +`I2V-01`. + +## Authentication + +Set your API key before running the commands: + +```bash +export MINIMAX_API_KEY="your-key" +``` + +Every request sends `Authorization: Bearer $MINIMAX_API_KEY`. A response is +successful when `base_resp.status_code` is `0`. + +## Typical flow + +1. `/minimax-video:text-to-video "a neon koi in a rainy alley"` → returns a `task_id`. +2. `/minimax-video:query-video ` → poll until status is success, read `file_id`. +3. `/minimax-video:download-video ./clip.mp4` → resolve and save the video. diff --git a/plugins/minimax-video/commands/download-video.md b/plugins/minimax-video/commands/download-video.md new file mode 100644 index 00000000..ce5ab339 --- /dev/null +++ b/plugins/minimax-video/commands/download-video.md @@ -0,0 +1,47 @@ +--- +description: Retrieve the download URL for a finished MiniMax video by file id and save the file. +category: integration-sync +argument-hint: [output_path] [--region global|cn] +allowed-tools: Bash +--- + +# Download Video (MiniMax-Hailuo) + +Resolve a finished video's `file_id` (returned by `/minimax-video:query-video`) into +a download URL and save the file locally. + +## Instructions + +1. Read the `file_id` from `$ARGUMENTS` (required); an optional second token is the + output path (default `./minimax-video.mp4`). +2. Choose the endpoint host by region: + - `global` (default): `https://api.minimax.io/v1/files/retrieve` + - `cn`: `https://api.minimaxi.com/v1/files/retrieve` +3. Authenticate with a Bearer token from the `MINIMAX_API_KEY` environment variable. +4. GET the file metadata with the `file_id` query parameter, read the download URL + from `file.download_url`, then fetch that URL to the output path. +5. Check `base_resp.status_code == 0` before downloading. + +## Request + +```bash +# region=global -> https://api.minimax.io ; region=cn -> https://api.minimaxi.com +curl -sS -G "https://api.minimax.io/v1/files/retrieve" \ + -H "Authorization: Bearer $MINIMAX_API_KEY" \ + --data-urlencode "file_id=205258526306433" + +# then download the resolved URL +curl -sS -L -o "./minimax-video.mp4" "" +``` + +## Response + +```json +{ + "file": { + "file_id": "205258526306433", + "download_url": "https://cdn.minimax.io/.../output.mp4" + }, + "base_resp": { "status_code": 0, "status_msg": "success" } +} +``` diff --git a/plugins/minimax-video/commands/image-to-video.md b/plugins/minimax-video/commands/image-to-video.md new file mode 100644 index 00000000..194da4ec --- /dev/null +++ b/plugins/minimax-video/commands/image-to-video.md @@ -0,0 +1,54 @@ +--- +description: Create a MiniMax-Hailuo-2.3 video-generation task from a first-frame image and return its task id. +category: integration-sync +argument-hint: [prompt] [--model MiniMax-Hailuo-2.3] [--region global|cn] +allowed-tools: Bash +--- + +# Image to Video (MiniMax-Hailuo) + +Animate a still image with the MiniMax video-generation endpoint. The image is +supplied as the `first_frame_image` (a public URL or a `data:` base64 string) and +becomes the opening frame of the clip. Returns the `task_id` for polling. + +## Instructions + +1. Parse `$ARGUMENTS`: the first token is the `first_frame_image`; any remaining + text is an optional `prompt` describing the motion. +2. Choose the endpoint host by region: + - `global` (default): `https://api.minimax.io/v1/video_generation` + - `cn`: `https://api.minimaxi.com/v1/video_generation` +3. Authenticate with a Bearer token from the `MINIMAX_API_KEY` environment variable. +4. Default `model` to `MiniMax-Hailuo-2.3`. Other accepted models: `MiniMax-Hailuo-2.3-Fast`, + `MiniMax-Hailuo-02`, `I2V-01-Director`, `I2V-01-live`, `I2V-01`. +5. `model` and `first_frame_image` are required. Optional fields: `prompt`, + `prompt_optimizer`, `fast_pretreatment`, `duration`, `resolution`, `callback_url`. +6. POST the request, then report the `task_id` (check `base_resp.status_code == 0`). + +## Request + +```bash +# region=global -> https://api.minimax.io ; region=cn -> https://api.minimaxi.com +curl -sS -X POST "https://api.minimax.io/v1/video_generation" \ + -H "Authorization: Bearer $MINIMAX_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "MiniMax-Hailuo-2.3", + "first_frame_image": "https://example.com/first-frame.jpg", + "prompt": "Slow push-in as the character turns toward the camera", + "prompt_optimizer": true, + "duration": 6, + "resolution": "1080P" + }' +``` + +## Response + +```json +{ + "task_id": "176843928495987", + "base_resp": { "status_code": 0, "status_msg": "success" } +} +``` + +Pass the returned `task_id` to `/minimax-video:query-video`. diff --git a/plugins/minimax-video/commands/query-video.md b/plugins/minimax-video/commands/query-video.md new file mode 100644 index 00000000..b3e53d12 --- /dev/null +++ b/plugins/minimax-video/commands/query-video.md @@ -0,0 +1,44 @@ +--- +description: Poll a MiniMax video-generation task by task id and report its status and file id. +category: integration-sync +argument-hint: [--region global|cn] +allowed-tools: Bash +--- + +# Query Video Generation (MiniMax-Hailuo) + +Check the status of a previously submitted video-generation task. When the task +finishes, the response carries the `file_id` needed to download the video. + +## Instructions + +1. Read the `task_id` from `$ARGUMENTS` (required). +2. Choose the endpoint host by region: + - `global` (default): `https://api.minimax.io/v1/query/video_generation` + - `cn`: `https://api.minimaxi.com/v1/query/video_generation` +3. Authenticate with a Bearer token from the `MINIMAX_API_KEY` environment variable. +4. Send a GET request with the `task_id` query parameter. +5. Report `status`; when it indicates success, surface the `file_id` and hand it to + `/minimax-video:download-video`. Also check `base_resp.status_code == 0`. + +## Request + +```bash +# region=global -> https://api.minimax.io ; region=cn -> https://api.minimaxi.com +curl -sS -G "https://api.minimax.io/v1/query/video_generation" \ + -H "Authorization: Bearer $MINIMAX_API_KEY" \ + --data-urlencode "task_id=176843928495123" +``` + +## Response + +```json +{ + "task_id": "176843928495123", + "status": "Success", + "file_id": "205258526306433", + "base_resp": { "status_code": 0, "status_msg": "success" } +} +``` + +Pass the returned `file_id` to `/minimax-video:download-video`. diff --git a/plugins/minimax-video/commands/text-to-video.md b/plugins/minimax-video/commands/text-to-video.md new file mode 100644 index 00000000..6ffad2a7 --- /dev/null +++ b/plugins/minimax-video/commands/text-to-video.md @@ -0,0 +1,53 @@ +--- +description: Create a MiniMax-Hailuo-2.3 video-generation task from a text prompt and return its task id. +category: integration-sync +argument-hint: [--model MiniMax-Hailuo-2.3] [--duration 6] [--resolution 1080P] [--region global|cn] +allowed-tools: Bash +--- + +# Text to Video (MiniMax-Hailuo) + +Submit a text prompt to the MiniMax video-generation endpoint and return the +`task_id` that identifies the asynchronous job. Follow up with `/minimax-video:query-video` +to poll status and `/minimax-video:download-video` to fetch the result. + +## Instructions + +1. Read the user's prompt from `$ARGUMENTS`. Choose the endpoint host by region: + - `global` (default): `https://api.minimax.io/v1/video_generation` + - `cn`: `https://api.minimaxi.com/v1/video_generation` +2. Authenticate with a Bearer token from the `MINIMAX_API_KEY` environment variable. +3. Default `model` to `MiniMax-Hailuo-2.3`. Other accepted models: `MiniMax-Hailuo-2.3-Fast`, + `MiniMax-Hailuo-02`, `T2V-01-Director`, `T2V-01`. +4. `model` and `prompt` are required. Optional fields: `prompt_optimizer`, + `fast_pretreatment`, `duration`, `resolution`, `callback_url`. +5. POST the request, then report the `task_id` from the response (also check + `base_resp.status_code`, where `0` means success). + +## Request + +```bash +# region=global -> https://api.minimax.io ; region=cn -> https://api.minimaxi.com +curl -sS -X POST "https://api.minimax.io/v1/video_generation" \ + -H "Authorization: Bearer $MINIMAX_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "MiniMax-Hailuo-2.3", + "prompt": "A neon koi swimming through a rainy Tokyo alley at night", + "prompt_optimizer": true, + "fast_pretreatment": false, + "duration": 6, + "resolution": "1080P" + }' +``` + +## Response + +```json +{ + "task_id": "176843928495123", + "base_resp": { "status_code": 0, "status_msg": "success" } +} +``` + +Pass the returned `task_id` to `/minimax-video:query-video`.