# STM-Minimax-H3 视频生成

模型 ID：`STM-Minimax-H3`

使用文本或参考图片生成视频。提交后返回 task_id，使用任务查询接口获取结果。

## 请求地址

POST /v1/videos

API 服务域名：https://api.storymo.art。

## 请求头

| 名称 | 必填 | 值 |
| --- | --- | --- |
| Authorization | 是 | Bearer YOUR_API_KEY |
| Content-Type | 是 | application/json |
| Idempotency-Key | 是 | 每次新任务使用独立值，例如 order-20261031-001；网络重试保持原值和参数 |

## 请求参数

| 参数 | 类型 | 必填 | 本模型填写方式 |
| --- | --- | --- | --- |
| model | string | 是 | 固定填写 `STM-Minimax-H3` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `16:9`、`9:16`。省略时平台默认 16:9，建议显式填写 |
| resolution | string | 否 | `480p`、`768p`。省略时平台默认 720p，该默认值不适用于本模型，必须显式填写支持的值 |
| duration | integer | 否 | 支持 5、6、7、8、9、10、11、12、13、14、15 秒；默认 5 秒 |
| references | array | 否 | 默认 []。参考素材格式见下方 |
| max_credits | number | 否 | 本次预计积分上限；超过上限返回 budget_exceeded |
| n | integer | 否 | 默认 1，目前仅支持 1 |

## 请求 JSON

```json
{
  "model": "STM-Minimax-H3",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "duration": 5
}
```


## 时长与清晰度组合

| 清晰度 | 可用时长（秒） |
| --- | --- |
| 480p | 5、6、7、8、9、10、11、12、13、14、15 |
| 768p | 5、6、7、8、9、10、11、12、13、14、15 |

## 参考素材

支持参考图片、音频。

- 图片：最多 9 个。
- 视频：不支持。
- 音频：最多 3 个。

references 每项必须包含 type，并在 url 与 file_id 中选择一种。file_id 来自文件上传接口；url 为可公开下载的 HTTPS 文件地址。参考数组总数最多 50，仍受本模型每类上限约束。

```json
[
  {
    "type": "image",
    "file_id": "上传返回的file_id"
  }
]
```


只需参考图片时，将 references 添加到上面的请求 JSON，prompt 正常描述即可。需要指明某个素材时，使用 <<<image_1>>>、<<<video_1>>>、<<<audio_1>>>；每种媒体按 references 中出现的顺序分别编号。显式引用存在时，仅引用到的素材会参与生成，提交顺序按提示词中的引用顺序确定。

## 报价

POST /v1/videos/quote

使用相同请求参数获取本次预计积分；报价无需 Idempotency-Key，不扣费。以 data.credits 为预计值，实际以任务记录为准。

## 提交响应

HTTP 202。

```json
{
  "code": "ok",
  "message": "success",
  "data": {
    "task_id": "task_example",
    "taskId": "task_example",
    "type": "video",
    "status": "queued",
    "credits": 20
  },
  "requestId": "req_example"
}
```


credits 为本次任务积分，上面的 20 仅为响应结构示例。taskId 是兼容字段，新接入使用 task_id。status=queued 表示排队，不能直接下载。

## 查询与下载

GET /v1/videos/{task_id}

携带相同 Authorization，每 3–5 秒查询一次。status 为 succeeded 时读取 data.outputs[0].url 下载视频；failed 或 canceled 时停止查询。


```json
{
  "code": "ok",
  "message": "success",
  "data": {
    "task_id": "task_example",
    "type": "video",
    "status": "succeeded",
    "progress": 100,
    "outputs": [
      {
        "type": "video",
        "url": "https://cdn.example.com/result.mp4"
      }
    ],
    "error": null,
    "credits": 20,
    "created_at": "2026-10-31T04:00:00.000Z",
    "completed_at": "2026-10-31T04:01:00.000Z"
  },
  "requestId": "req_example"
}
```


下载地址可能过期；重新查询任务可获取链接。下载文件时不要发送 API Key。

## 错误处理

400：参数、素材类型或数量不支持。401：API Key 无效。402：积分不足。403：会员权限不足。409：幂等冲突或提交尚未确定。500/503：服务异常。错误响应包含 code、message、data 和 requestId。超时后使用相同幂等键重试提交，收到 task_id 后只需查询任务。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。Python 示例需要 pip install requests；JavaScript 示例使用 Node.js 20+。示例 Idempotency-Key 需替换为本次新任务的独立值，超时重试保持原值。

### cURL

```bash
curl --request POST "https://api.storymo.art/v1/videos" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-730dbc8f-001' \
  --data '{
  "model": "STM-Minimax-H3",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "duration": 5
}'
```

### Python

```python
import os
import requests

api_origin = "https://api.storymo.art"
headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
  "Idempotency-Key": "order-730dbc8f-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "STM-Minimax-H3",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "duration": 5
}
response = requests.request("POST", api_origin + "/v1/videos", headers=headers, json=body, timeout=360)
response.raise_for_status()
result = response.json()
if result["code"] != "ok":
    raise RuntimeError(result)
print(result["data"])
```

### JavaScript

```javascript
const apiOrigin = "https://api.storymo.art";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
  "Idempotency-Key": "order-730dbc8f-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "STM-Minimax-H3",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```
