---
name: yiran-skill-media
description: 统一多媒体生成技能。支持图片、音乐、文生视频和图生视频，按资源类型自动路由到最优 provider，支持多级降级。资源生成规范：所有生成的资源必须存放在当前工作目录下，调用时通过 --output-dir 传入当前工作目录的绝对路径，通过 --name 传入资源的中文名称。
---

# 统一多媒体生成

## 资源生成规范（必须遵守）

1. **`--output-dir` 必填** — 传入当前工作目录的绝对路径。你在哪个目录工作，就传哪个路径。
2. **`--name` 必填** — 传入资源的中文名称，用于生成文件名。名称应简洁准确，能体现资源内容。

**所有生成的资源文件必须存放在当前工作目录下。** 不允许省略，不允许猜测路径。

## 一键脚本

```bash
_S="skills/yiran-skill-media/scripts"

# 图片生成
bash "$_S/image.sh" "a sunset landscape" --name 日落风景 --output-dir "$(pwd)" [--aspect-ratio 16:9]

# 音乐生成
bash "$_S/music.sh" "epic opening" --name 开场音乐 --output-dir "$(pwd)" [--instrumental]

# 文生视频 (Text-to-Video)
bash "$_S/video.sh" "a sunset timelapse" --name 日落延时 --output-dir "$(pwd)" [--duration 6] [--resolution 768P] [--aspect-ratio 16:9]

# 图生视频 (Image-to-Video)
bash "$_S/i2v.sh" "cat running toward camera" --name 猫咪跑步 --first-frame-image "https://example.com/cat.jpg" --output-dir "$(pwd)"
```

## 参数说明

### image.sh

| 参数 | 必填 | 说明 |
|------|------|------|
| `--output-dir` | 是 | 输出目录的绝对路径 |
| `--name` | 是 | 资源中文名称（如：日落风景、产品封面） |
| `prompt` | 是 | 图片描述 |
| `--aspect-ratio` | 否 | 比例，默认 16:9。可选：1:1, 16:9, 9:16, 4:3, 3:4 等 |

### music.sh

| 参数 | 必填 | 说明 |
|------|------|------|
| `--output-dir` | 是 | 输出目录的绝对路径 |
| `--name` | 是 | 资源中文名称 |
| `prompt` | 是 | 音乐风格/情绪描述 |
| `--lyrics` | 否 | 歌词文本 |
| `--instrumental` | 否 | 纯音乐模式 |

### video.sh — 文生视频

| 参数 | 必填 | 说明 |
|------|------|------|
| `--output-dir` | 是 | 输出目录的绝对路径 |
| `--name` | 是 | 资源中文名称 |
| `prompt` | 是 | 视频内容描述（支持运镜指令如 `[推进]`、`[左摇]`） |
| `--duration` | 否 | 视频时长（秒），默认 6，可选 6 或 10 |
| `--resolution` | 否 | MiniMax 分辨率：768P/1080P（默认 768P） |
| `--aspect-ratio` | 否 | 即梦降级时使用：16:9/9:16/4:3/1:1（默认 16:9） |

### i2v.sh — 图生视频

| 参数 | 必填 | 说明 |
|------|------|------|
| `--output-dir` | 是 | 输出目录的绝对路径 |
| `--name` | 是 | 资源中文名称 |
| `--first-frame-image` | 是 | 首帧图片的公网 URL（JPG/PNG/WebP，<20MB） |
| `prompt` | 否 | 基于首帧图像的动作/变化描述 |
| `--duration` | 否 | 视频时长，默认 6 |
| `--resolution` | 否 | 分辨率，默认 768P |

**注意**：视频生成为异步任务，耗时较长（通常 1-5 分钟），脚本会自动轮询等待完成。

## 架构

```
image.sh              →  图片生成入口
music.sh              →  音乐生成入口
video.sh              →  文生视频入口 (Text-to-Video)
i2v.sh                →  图生视频入口 (Image-to-Video)
generate.py           →  统一路由调度（优先级数组，依次尝试）
config.json           →  provider 配置中心（优先级列表）
providers/
  vapi_image.py       →  VAPI 图片
  minimax_image.py    →  MiniMax 图片
  jimeng_image.py     →  即梦 图片 4.0（异步）
  minimax_music.py    →  MiniMax 音乐
  minimax_video.py    →  MiniMax 视频（文生+图生）
  jimeng_video.py     →  即梦 视频 3.0（异步）
```

## 详细 API 参考

- [references/image-api.md](references/image-api.md)
- [references/music-api.md](references/music-api.md)
