# Storymo-image-2(稳定渠道) 图片生成

模型 ID：`Storymo-image-2`

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

## 请求地址

POST /v1/images

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

## 请求头

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

## 请求参数

| 参数 | 类型 | 必填 | 本模型填写方式 |
| --- | --- | --- | --- |
| model | string | 是 | 固定填写 `Storymo-image-2` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`。省略时平台默认 1:1，建议显式填写 |
| resolution | string | 否 | `1K`、`2K`、`4K`。省略时平台默认 2K |
| references | array | 否 | 默认 []。参考素材格式见下方 |
| max_credits | number | 否 | 本次预计积分上限；超过上限返回 budget_exceeded |
| n | integer | 否 | 默认 1，目前仅支持 1 |

## 请求 JSON

```json
{
  "model": "Storymo-image-2",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}
```



## 参考素材

支持参考图片。

- 图片：可使用；数量以参数校验结果为准。
- 视频：不支持。
- 音频：不支持。

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

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


只需参考图片时，将 references 添加到上面的请求 JSON，prompt 正常描述即可。

## 报价

POST /v1/images/quote

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

## 提交响应

HTTP 202。

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


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

## 查询与下载

GET /v1/images/{task_id}

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


```json
{
  "code": "ok",
  "message": "success",
  "data": {
    "task_id": "task_example",
    "type": "image",
    "status": "succeeded",
    "progress": 100,
    "outputs": [
      {
        "type": "image",
        "url": "https://cdn.example.com/result.png"
      }
    ],
    "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/images" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-cd90d82e-001' \
  --data '{
  "model": "Storymo-image-2",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}'
```

### 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-cd90d82e-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "Storymo-image-2",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}
response = requests.request("POST", api_origin + "/v1/images", 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-cd90d82e-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/images", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "Storymo-image-2",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# Storymo-image-2(低价渠道) 图片生成

模型 ID：`Storymo-image-2-Special`

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

## 请求地址

POST /v1/images

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

## 请求头

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

## 请求参数

| 参数 | 类型 | 必填 | 本模型填写方式 |
| --- | --- | --- | --- |
| model | string | 是 | 固定填写 `Storymo-image-2-Special` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`。省略时平台默认 1:1，建议显式填写 |
| resolution | string | 否 | `1K`、`2K`、`4K`。省略时平台默认 2K |
| references | array | 否 | 默认 []。参考素材格式见下方 |
| max_credits | number | 否 | 本次预计积分上限；超过上限返回 budget_exceeded |
| n | integer | 否 | 默认 1，目前仅支持 1 |

## 请求 JSON

```json
{
  "model": "Storymo-image-2-Special",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}
```



## 参考素材

支持参考图片。

- 图片：可使用；数量以参数校验结果为准。
- 视频：不支持。
- 音频：不支持。

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

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


只需参考图片时，将 references 添加到上面的请求 JSON，prompt 正常描述即可。

## 报价

POST /v1/images/quote

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

## 提交响应

HTTP 202。

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


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

## 查询与下载

GET /v1/images/{task_id}

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


```json
{
  "code": "ok",
  "message": "success",
  "data": {
    "task_id": "task_example",
    "type": "image",
    "status": "succeeded",
    "progress": 100,
    "outputs": [
      {
        "type": "image",
        "url": "https://cdn.example.com/result.png"
      }
    ],
    "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/images" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-6eeeb94c-001' \
  --data '{
  "model": "Storymo-image-2-Special",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}'
```

### 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-6eeeb94c-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "Storymo-image-2-Special",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}
response = requests.request("POST", api_origin + "/v1/images", 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-6eeeb94c-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/images", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "Storymo-image-2-Special",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# seedance-2-fast 视频生成

模型 ID：`seedance-2-fast`

使用文本或参考图片生成视频。提交后返回 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 | 是 | 固定填写 `seedance-2-fast` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `16:9`、`9:16`、`3:4`。省略时平台默认 16:9，建议显式填写 |
| resolution | string | 否 | `480p`、`720p`。省略时平台默认 720p |
| duration | integer | 否 | 支持 4、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": "seedance-2-fast",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```


## 时长与清晰度组合

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

## 参考素材

支持参考图片、视频、音频。

- 图片：最多 9 个。
- 视频：最多 3 个。
- 音频：最多 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-4aa61261-001' \
  --data '{
  "model": "seedance-2-fast",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-4aa61261-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "seedance-2-fast",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-4aa61261-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "seedance-2-fast",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# seedance 2.0 视频生成

模型 ID：`seedance 2.0`

使用文本或参考图片生成视频。提交后返回 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 | 是 | 固定填写 `seedance 2.0` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `16:9`、`9:16`、`3:4`。省略时平台默认 16:9，建议显式填写 |
| resolution | string | 否 | `480p`、`720p`、`1080p`。省略时平台默认 720p |
| duration | integer | 否 | 支持 4、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": "seedance 2.0",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```


## 时长与清晰度组合

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

## 参考素材

支持参考图片、视频、音频。

- 图片：最多 9 个。
- 视频：最多 3 个。
- 音频：最多 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-fdcb9f31-001' \
  --data '{
  "model": "seedance 2.0",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-fdcb9f31-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "seedance 2.0",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-fdcb9f31-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "seedance 2.0",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# seedance2.0-mini 视频生成

模型 ID：`seedance2.0-mini`

使用文本或参考图片生成视频。提交后返回 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 | 是 | 固定填写 `seedance2.0-mini` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `16:9`、`9:16`、`3:4`。省略时平台默认 16:9，建议显式填写 |
| resolution | string | 否 | `480p`、`720p`。省略时平台默认 720p |
| duration | integer | 否 | 支持 4、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": "seedance2.0-mini",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```


## 时长与清晰度组合

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

## 参考素材

支持参考图片、视频、音频。

- 图片：最多 9 个。
- 视频：最多 3 个。
- 音频：最多 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-c3a6c2c2-001' \
  --data '{
  "model": "seedance2.0-mini",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-c3a6c2c2-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "seedance2.0-mini",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-c3a6c2c2-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "seedance2.0-mini",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# kling v3 视频生成

模型 ID：`kling v3`

使用文本或参考图片生成视频。提交后返回 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 | 是 | 固定填写 `kling v3` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `16:9`、`9:16`、`3:4`。省略时平台默认 16:9，建议显式填写 |
| resolution | string | 否 | `720p`、`1080p`。省略时平台默认 720p |
| duration | integer | 否 | 支持 4、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": "kling v3",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```


## 时长与清晰度组合

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

## 参考素材

支持参考图片。本模型不支持混合媒体参考或提示词显式引用；请只使用单一类型参考素材。

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

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

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


只需参考图片时，将 references 添加到上面的请求 JSON，prompt 正常描述即可。

## 报价

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-77615ba1-001' \
  --data '{
  "model": "kling v3",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-77615ba1-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "kling v3",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-77615ba1-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "kling v3",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# kling_v3-omni 视频生成

模型 ID：`kling_v3-omni`

使用文本或参考图片生成视频。提交后返回 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 | 是 | 固定填写 `kling_v3-omni` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `16:9`、`9:16`、`3:4`。省略时平台默认 16:9，建议显式填写 |
| resolution | string | 否 | `720p`、`1080p`。省略时平台默认 720p |
| duration | integer | 否 | 支持 3、4、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": "kling_v3-omni",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```


## 时长与清晰度组合

| 清晰度 | 可用时长（秒） |
| --- | --- |
| 720p | 3、4、5、6、7、8、9、10、11、12、13、14、15 |
| 1080p | 3、4、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-763cb925-001' \
  --data '{
  "model": "kling_v3-omni",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-763cb925-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "kling_v3-omni",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-763cb925-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "kling_v3-omni",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# seedance-2.5-720p-LM 视频生成

模型 ID：`seedance-2.5-720p-LM`

使用文本或参考图片生成视频。提交后返回 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 | 是 | 固定填写 `seedance-2.5-720p-LM` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `16:9`、`9:16`、`3:4`。省略时平台默认 16:9，建议显式填写 |
| resolution | string | 否 | `720p`。省略时平台默认 720p |
| duration | integer | 否 | 支持 4、5、6、7、8、9、10、11、12、13、14、15、16、17、18、19、20、21、22、23、24、25、26、27、28、29、30 秒；默认 5 秒 |
| references | array | 否 | 默认 []。参考素材格式见下方 |
| max_credits | number | 否 | 本次预计积分上限；超过上限返回 budget_exceeded |
| n | integer | 否 | 默认 1，目前仅支持 1 |

## 请求 JSON

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


## 时长与清晰度组合

| 清晰度 | 可用时长（秒） |
| --- | --- |
| 720p | 4、5、6、7、8、9、10、11、12、13、14、15、16、17、18、19、20、21、22、23、24、25、26、27、28、29、30 |

## 参考素材

支持参考图片、视频、音频。

- 图片：最多 30 个。
- 视频：最多 10 个。
- 音频：最多 10 个。

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-78b3cc70-001' \
  --data '{
  "model": "seedance-2.5-720p-LM",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-78b3cc70-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "seedance-2.5-720p-LM",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-78b3cc70-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "seedance-2.5-720p-LM",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# seedance-2.5-1080p-LM 视频生成

模型 ID：`seedance-2.5-1080p-LM`

使用文本或参考图片生成视频。提交后返回 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 | 是 | 固定填写 `seedance-2.5-1080p-LM` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `16:9`、`9:16`、`3:4`、`4:3`、`1:1`。省略时平台默认 16:9，建议显式填写 |
| resolution | string | 否 | `1080p`。省略时平台默认 720p，该默认值不适用于本模型，必须显式填写支持的值 |
| duration | integer | 否 | 支持 4、5、6、7、8、9、10、11、12、13、14、15、16、17、18、19、20、21、22、23、24、25、26、27、28、29、30 秒；默认 5 秒 |
| references | array | 否 | 默认 []。参考素材格式见下方 |
| max_credits | number | 否 | 本次预计积分上限；超过上限返回 budget_exceeded |
| n | integer | 否 | 默认 1，目前仅支持 1 |

## 请求 JSON

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


## 时长与清晰度组合

| 清晰度 | 可用时长（秒） |
| --- | --- |
| 1080p | 4、5、6、7、8、9、10、11、12、13、14、15、16、17、18、19、20、21、22、23、24、25、26、27、28、29、30 |

## 参考素材

支持参考图片、视频、音频。

- 图片：最多 30 个。
- 视频：最多 10 个。
- 音频：最多 10 个。

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-272ba934-001' \
  --data '{
  "model": "seedance-2.5-1080p-LM",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "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-272ba934-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "seedance-2.5-1080p-LM",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "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-272ba934-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "seedance-2.5-1080p-LM",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# seedance-2.0-720p-LM 视频生成

模型 ID：`seedance-2.0-720p-LM`

使用文本或参考图片生成视频。提交后返回 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 | 是 | 固定填写 `seedance-2.0-720p-LM` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `16:9`、`9:16`、`3:4`、`4:3`、`1:1`。省略时平台默认 16:9，建议显式填写 |
| resolution | string | 否 | `720p`。省略时平台默认 720p |
| duration | integer | 否 | 支持 4、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": "seedance-2.0-720p-LM",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```


## 时长与清晰度组合

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

## 参考素材

支持参考图片、视频、音频。

- 图片：最多 9 个。
- 视频：最多 3 个。
- 音频：最多 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-db16ef0e-001' \
  --data '{
  "model": "seedance-2.0-720p-LM",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-db16ef0e-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "seedance-2.0-720p-LM",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-db16ef0e-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "seedance-2.0-720p-LM",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# 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);
```


---

# seedance-2.5-Flash-GW 视频生成

模型 ID：`seedance-2.5-Flash-GW`

使用文本或参考图片生成视频。提交后返回 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 | 是 | 固定填写 `seedance-2.5-Flash-GW` |
| prompt | string | 是 | 1–20000 字符的生成描述，不可为空 |
| aspect_ratio | string | 否 | `16:9`、`9:16`、`3:4`。省略时平台默认 16:9，建议显式填写 |
| resolution | string | 否 | `480p`、`720p`。省略时平台默认 720p |
| duration | integer | 否 | 支持 4、5、6、7、8、9、10、11、12、13、14、15、16、17、18、19、20、21、22、23、24、25、26、27、28、29、30 秒；默认 5 秒 |
| references | array | 否 | 默认 []。参考素材格式见下方 |
| max_credits | number | 否 | 本次预计积分上限；超过上限返回 budget_exceeded |
| n | integer | 否 | 默认 1，目前仅支持 1 |

## 请求 JSON

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


## 时长与清晰度组合

| 清晰度 | 可用时长（秒） |
| --- | --- |
| 480p | 4、5、6、7、8、9、10、11、12、13、14、15、16、17、18、19、20、21、22、23、24、25、26、27、28、29、30 |
| 720p | 4、5、6、7、8、9、10、11、12、13、14、15、16、17、18、19、20、21、22、23、24、25、26、27、28、29、30 |

## 参考素材

支持参考图片、视频、音频。

- 图片：最多 10 个。
- 视频：最多 5 个。
- 音频：最多 5 个。

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-8fb3f100-001' \
  --data '{
  "model": "seedance-2.5-Flash-GW",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-8fb3f100-001"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "seedance-2.5-Flash-GW",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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-8fb3f100-001"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "seedance-2.5-Flash-GW",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# API 快速开始

通过 HTTP API 生成图片与视频，支持文本生成、参考素材生成、积分查询、文件上传和任务查询。

## 接口地址

API 服务域名：https://api.storymo.art。所有接口的公共前缀为 https://api.storymo.art/v1。

## 认证

请求头 Authorization: Bearer YOUR_API_KEY。API Key 可在网站“开发者 API”页面创建。

完整密钥仅在创建时显示一次。密钥关联用户账户，生成任务使用该账户的积分。创建时可设置有效期和累计积分额度，并可在开发者页面调整。额度留空表示不限，0 表示不允许生成；额度不增加账户余额。实际生成扣费计入密钥额度，失败退款后恢复，查询、报价和上传不占积分额度。过期或撤销返回 HTTP 401；额度不足返回 HTTP 402、code=api_key_quota_exceeded。请不要将 API Key 提供给他人，否则可能造成账户积分被盗用；因自行泄露或分享密钥造成的损失由您自行承担。文档页面及 Markdown 下载无需登录。

## 调用流程

- 从左侧选择具体图片或视频模型，查看该模型的 ID 和可用参数。
- 需要本地参考素材时，先调用 POST /files 获取 file_id。
- 调用图片或视频报价接口查看积分。
- 提交生成请求，保存返回的 task_id。
- 每 3–5 秒查询任务，完成后下载 outputs 中的 url。

## 请求头

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| Authorization | string | 是 | Bearer YOUR_API_KEY |
| Content-Type | string | JSON 请求必填 | application/json；文件上传由客户端自动生成 multipart/form-data boundary |
| Idempotency-Key | string | 生成请求必填 | 1–100 位字母、数字或 ._:-，每个新任务独立；超时重试使用原值 |

## 统一参数

图片与视频均使用 model、prompt、aspect_ratio、resolution、references。视频额外使用 duration（整数秒）。各模型可用值不同，见左侧模型页面。

## 统一响应

- code：成功为 ok，失败为错误码。
- message：用户可读的说明。
- data：本接口返回数据，失败时可能为 null。
- requestId：本次请求标识，排查问题时可提供此值；响应头同时提供 X-Request-Id。

## HTTP 状态

200 查询或报价成功；201 上传成功；202 生成已接收；400 参数错误；401 Key 不可用；402 账户积分或密钥额度不足；403 无权限；404 任务不存在；409 幂等冲突；413 文件过大；500/503 服务异常。

## 提交重试

同一账户、同一种任务、同一 Idempotency-Key、同一请求参数会重放首次结果。JSON 对象字段顺序不影响幂等，数组顺序会影响。收到 task_id 后只需查询任务。网络超时后使用原请求与原 Key 重试；修改参数或创建新作品使用新 Key。submission_uncertain 表示提交结果需核实，请保存 Key、requestId 联系平台。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。Python 需要 requests，JavaScript 使用 Node.js 20+。

### cURL

```bash
curl --request GET "https://api.storymo.art/v1/models?type=all" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY"
```

### Python

```python
import os
import requests

api_origin = "https://api.storymo.art"
headers = {
  "Authorization": "Bearer YOUR_API_KEY"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
response = requests.request("GET", api_origin + "/v1/models?type=all", headers=headers, 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"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/models?type=all", {
  method: "GET",
  headers,
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# 模型发现

GET /v1/models

获取当前账户可用的图片、视频模型及其参数。

## 认证

请求头 Authorization: Bearer YOUR_API_KEY。API Key 可在网站“开发者 API”页面创建。

## 查询参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 否 | image、video 或 all；默认 video |

## 响应 data.models[]

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 生成请求的 model 值 |
| type | string | image 或 video |
| name | string | 模型显示名称 |
| description | string | 模型说明 |
| resolutions | string[] | 清晰度枚举，例如 1K、2K、4K 或 720p、1080p |
| aspect_ratios | string[] | 比例枚举，例如 16:9 |
| durations | integer[] | 可选时长（秒），图片为空数组 |
| supports | object | image/video/audio 参考能力，multimodal 为混合媒体/显式引用能力 |
| reference_limits | object | image/video/audio 各类型最大数量；null 表示未设置数量配置 |
| parameter_combinations | object[] | 可用 duration 与 resolution 组合；空数组表示无组合表，仍需满足其他枚举 |
| billing_type | string | per_use、per_resolution 或 per_second 等计费方式；具体费用使用报价接口 |
| member_only | boolean | 是否会员专用 |

只有当前账户可用且已启用的模型会返回。未配置的能力枚举可能为空，此时可以通过报价接口验证参数。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。Python 需要 requests，JavaScript 使用 Node.js 20+。

### cURL

```bash
curl --request GET "https://api.storymo.art/v1/models?type=all" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY"
```

### Python

```python
import os
import requests

api_origin = "https://api.storymo.art"
headers = {
  "Authorization": "Bearer YOUR_API_KEY"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
response = requests.request("GET", api_origin + "/v1/models?type=all", headers=headers, 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"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/models?type=all", {
  method: "GET",
  headers,
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# 积分余额

GET /v1/balance

## 认证

请求头 Authorization: Bearer YOUR_API_KEY。API Key 可在网站“开发者 API”页面创建。

## 请求参数

无需请求体或查询参数。

## 返回字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.credits | number | 当前账户可用积分 |

本接口不扣积分，也不预留余额。并发生成可能改变余额。积分不是人民币金额。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。Python 需要 requests，JavaScript 使用 Node.js 20+。

### cURL

```bash
curl --request GET "https://api.storymo.art/v1/balance" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY"
```

### Python

```python
import os
import requests

api_origin = "https://api.storymo.art"
headers = {
  "Authorization": "Bearer YOUR_API_KEY"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
response = requests.request("GET", api_origin + "/v1/balance", headers=headers, 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"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/balance", {
  method: "GET",
  headers,
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# 文件上传

POST /v1/files

上传本地参考素材，获得可在图片或视频生成中使用的 file_id。

## 认证

请求头 Authorization: Bearer YOUR_API_KEY。API Key 可在网站“开发者 API”页面创建。

## 请求格式

multipart/form-data，字段名 file，每次上传一个文件。客户端自动生成 Content-Type 和 boundary。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| file | binary | 是 | 图片、视频或音频；最大 100 MiB（104857600 字节） |

MIME 必须为 image/*、video/* 或 audio/*，例如 image/png、video/mp4、audio/mpeg。生成时仍受具体模型的媒体格式和数量限制。上传不创建生成任务。

## 成功响应

HTTP 201。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| file_id | string | 文件标识，用于 references[].file_id |
| fileId | string | file_id 的兼容别名 |
| url | string | 当前下载链接，可能有有效期 |
| filename | string | 原文件名 |
| size | integer | 文件字节数 |
| mime_type | string | 媒体 MIME 类型 |

## 用于生成请求

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

file_id 只可由当前账户使用，参考项的 type 必须与文件媒体类型一致。file_id 是不透明标识，可能以 cloud:// 等形式开头。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。Python 需要 requests，JavaScript 使用 Node.js 20+。

### cURL

```bash
curl --request POST "https://api.storymo.art/v1/files" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY" \
  --form "file=@./reference.png;type=image/png"
```

### Python

```python
import os
import requests

with open("reference.png", "rb") as file:
    response = requests.post(
        "https://api.storymo.art" + "/v1/files",
        headers={"Authorization": "Bearer " + os.environ["DRAMAGEN_API_KEY"]},
        files={"file": ("reference.png", file, "image/png")},
        timeout=120,
    )
response.raise_for_status()
print(response.json()["data"]["file_id"])
```

### JavaScript

```javascript
import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("file", new Blob([await readFile("reference.png")], {type: "image/png"}), "reference.png");
const response = await fetch("https://api.storymo.art" + "/v1/files", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.DRAMAGEN_API_KEY}`},
  body: form,
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data.file_id);
```


---

# 图片报价

POST /v1/images/quote

## 认证

请求头 Authorization: Bearer YOUR_API_KEY。API Key 可在网站“开发者 API”页面创建。

请求头 Content-Type: application/json。无需 Idempotency-Key。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| model | string | 是 | 具体模型页面中的模型 ID |
| resolution | string | 否 | 默认 2K，支持范围见该模型页面 |
| aspect_ratio | string | 否 | 默认 1:1，支持范围见该模型页面 |
| prompt | string | 否 | 可传入最终生成描述，用于校验引用；省略时仅校验其他参数 |
| references | array | 否 | 与生成请求相同的参考素材；会校验文件归属和数量 |
| max_credits | number | 否 | 预计积分超过此值返回 budget_exceeded |

## 返回字段

- credits：预计积分。
- charged：固定 false，报价不扣费。
- type、model、resolution、aspect_ratio：本次报价参数。

实际提交时按当前账户和模型配置计算积分。报价不创建任务、不锁定价格或预留余额。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。Python 需要 requests，JavaScript 使用 Node.js 20+。

### cURL

```bash
curl --request POST "https://api.storymo.art/v1/images/quote" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "Storymo-image-2",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}'
```

### Python

```python
import os
import requests

api_origin = "https://api.storymo.art"
headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "Storymo-image-2",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}
response = requests.request("POST", api_origin + "/v1/images/quote", 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"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/images/quote", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "Storymo-image-2",
  "prompt": "一只橘猫坐在窗边，柔和的晨光，细腻的毛发",
  "aspect_ratio": "1:1",
  "resolution": "2K"
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# 图片任务查询

GET /v1/images/{task_id}

## 认证

请求头 Authorization: Bearer YOUR_API_KEY。API Key 可在网站“开发者 API”页面创建。

## 路径参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| task_id | string | 是 | 提交接口返回的 task_id；拼接 URL 时编码 |

无请求体。只能查询当前账户的图片任务；任务不存在、类型错误或不属于当前账户均返回 404。

## 返回 data 字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| task_id | string | 任务 ID |
| taskId | string | 兼容别名 |
| type | string | image |
| status | string | queued、running、succeeded、failed、canceled |
| progress | number | 参考进度；以 status 判断是否完成 |
| outputs | array | 成功时包含 {type,url}；其他状态或链接不可用时为空 |
| imageUrl | string/null | 兼容的结果链接，推荐统一读取 outputs |
| error | object/null | 失败时包含 code、message、error_id |
| credits | number | 任务记录的积分，不代表退款后的净额 |
| created_at | string | 创建时间，通常为 ISO 8601 |
| completed_at | string/null | 终结时间，未完成时可能为 null |

## 轮询与下载

- queued：排队中，继续查询。
- running：生成中，继续查询。
- succeeded：已完成，下载 outputs[0].url。
- failed：失败，停止查询并显示 error。
- canceled：已取消，停止查询。

建议每 3–5 秒查询一次；网络错误退避到 10–30 秒。等待超时可保留 task_id 稍后续查，不需重新创建任务。成功但 outputs 为空时稍后重查；持续为空可联系平台。下载链接可能过期，重新查询获取链接。下载请求不带 API Key。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。设置 TASK_ID 为提交返回的 task_id。Python 需要 requests，JavaScript 使用 Node.js 20+。

### cURL

```bash
curl --request GET "https://api.storymo.art/v1/images/${TASK_ID}" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY"
```

### Python

```python
import os
import requests

api_origin = "https://api.storymo.art"
headers = {
  "Authorization": "Bearer YOUR_API_KEY"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
response = requests.request("GET", api_origin + "/v1/images/{task_id}".replace("{task_id}", requests.utils.quote(os.environ["TASK_ID"], safe="")), headers=headers, 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"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/images/{task_id}".replace("{task_id}", encodeURIComponent(process.env.TASK_ID)), {
  method: "GET",
  headers,
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# 视频报价

POST /v1/videos/quote

## 认证

请求头 Authorization: Bearer YOUR_API_KEY。API Key 可在网站“开发者 API”页面创建。

请求头 Content-Type: application/json。无需 Idempotency-Key。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| model | string | 是 | 具体模型页面中的模型 ID |
| resolution | string | 否 | 默认 720p，支持范围见该模型页面 |
| aspect_ratio | string | 否 | 默认 16:9，支持范围见该模型页面 |
| duration | integer | 否 | 整数秒，默认 5；支持范围见该模型页面 |
| prompt | string | 否 | 可传入最终生成描述，用于校验引用；省略时仅校验其他参数 |
| references | array | 否 | 与生成请求相同的参考素材；会校验文件归属和数量 |
| max_credits | number | 否 | 预计积分超过此值返回 budget_exceeded |

## 返回字段

- credits：预计积分。
- charged：固定 false，报价不扣费。
- type、model、resolution、aspect_ratio、duration：本次报价参数。

实际提交时按当前账户和模型配置计算积分。报价不创建任务、不锁定价格或预留余额。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。Python 需要 requests，JavaScript 使用 Node.js 20+。

### cURL

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

### Python

```python
import os
import requests

api_origin = "https://api.storymo.art"
headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
body = {
  "model": "seedance-2-fast",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
response = requests.request("POST", api_origin + "/v1/videos/quote", 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"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos/quote", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "seedance-2-fast",
  "prompt": "雨后的城市街道，镜头缓慢向前推进，路面倒映霓虹灯光",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}),
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# 视频任务查询

GET /v1/videos/{task_id}

## 认证

请求头 Authorization: Bearer YOUR_API_KEY。API Key 可在网站“开发者 API”页面创建。

## 路径参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| task_id | string | 是 | 提交接口返回的 task_id；拼接 URL 时编码 |

无请求体。只能查询当前账户的视频任务；任务不存在、类型错误或不属于当前账户均返回 404。

## 返回 data 字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| task_id | string | 任务 ID |
| taskId | string | 兼容别名 |
| type | string | video |
| status | string | queued、running、succeeded、failed、canceled |
| progress | number | 参考进度；以 status 判断是否完成 |
| outputs | array | 成功时包含 {type,url}；其他状态或链接不可用时为空 |
| videoUrl | string/null | 兼容的结果链接，推荐统一读取 outputs |
| error | object/null | 失败时包含 code、message、error_id |
| credits | number | 任务记录的积分，不代表退款后的净额 |
| created_at | string | 创建时间，通常为 ISO 8601 |
| completed_at | string/null | 终结时间，未完成时可能为 null |

## 轮询与下载

- queued：排队中，继续查询。
- running：生成中，继续查询。
- succeeded：已完成，下载 outputs[0].url。
- failed：失败，停止查询并显示 error。
- canceled：已取消，停止查询。

建议每 3–5 秒查询一次；网络错误退避到 10–30 秒。等待超时可保留 task_id 稍后续查，不需重新创建任务。成功但 outputs 为空时稍后重查；持续为空可联系平台。下载链接可能过期，重新查询获取链接。下载请求不带 API Key。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。设置 TASK_ID 为提交返回的 task_id。Python 需要 requests，JavaScript 使用 Node.js 20+。

### cURL

```bash
curl --request GET "https://api.storymo.art/v1/videos/${TASK_ID}" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY"
```

### Python

```python
import os
import requests

api_origin = "https://api.storymo.art"
headers = {
  "Authorization": "Bearer YOUR_API_KEY"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
response = requests.request("GET", api_origin + "/v1/videos/{task_id}".replace("{task_id}", requests.utils.quote(os.environ["TASK_ID"], safe="")), headers=headers, 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"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/videos/{task_id}".replace("{task_id}", encodeURIComponent(process.env.TASK_ID)), {
  method: "GET",
  headers,
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```


---

# 错误码与重试

错误响应包括 code、message、data 和 requestId。客户端同时检查 HTTP 状态与 code。

| code | HTTP 状态 | 处理方式 |
| --- | --- | --- |
| invalid_api_key | 401 | 检查 Key 是否正确、撤销、过期或账户不可用 |
| invalid_parameters | 400 | 按 message 修正请求参数 |
| VIP_MODEL_REQUIRED | 403 | 使用有权限的模型或开通会员 |
| api_key_quota_exceeded | 402 | API Key 剩余积分额度不足，在开发者页面提高额度或使用其他密钥 |
| budget_exceeded | 400 | 预计积分超过 max_credits，调整参数或预算 |
| insufficient_credits | 402 | 充值并核对提交结果后再操作 |
| not_found | 404 | 检查任务 ID、媒体类型和账户 |
| idempotency_conflict | 409 | 同一幂等键使用了不同参数 |
| LOCKED | 409 | 同一请求正在提交，稍后原样重试 |
| submission_uncertain | 409 | 保留原 Key 和 requestId 联系平台核实，避免重复生成 |
| generation_failed | 400/500 | 生成校验或提交失败，查看 message 和任务信息 |
| VIDEO_REFERENCE_LIMIT_EXCEEDED | 400 | 素材数量超过本模型上限 |
| UNSUPPORTED_VIDEO_REFERENCE_MEDIA | 400 | 模型不支持该参考媒体 |
| UNRESOLVED_VIDEO_REFERENCE | 400 | 提示词引用没有对应素材 |
| service_unavailable | 500/503 | 服务暂不可用，退避后使用原幂等键重试 |

## 请求超时

生成提交超时不代表未入队；使用相同 Key 和请求参数重试。已获得 task_id 时继续查询。任务查询超时不会重新生成或额外扣费。

## 文件与代理错误

文件超过 100 MiB 返回 413；代理限制、无效 JSON 等错误可能返回纯文本或 HTML，客户端应保留 HTTP 状态与响应原文。

## 积分核对

失败后的退款按平台任务处理结果执行。任务 credits 是原记录金额，不是退款状态；需要核查可提供 task_id 和 requestId。

## 调用示例

设置环境变量 DRAMAGEN_API_KEY（用户密钥）。Python 需要 requests，JavaScript 使用 Node.js 20+。

### cURL

```bash
curl --request GET "https://api.storymo.art/v1/models" \
  --header "Authorization: Bearer $DRAMAGEN_API_KEY"
```

### Python

```python
import os
import requests

api_origin = "https://api.storymo.art"
headers = {
  "Authorization": "Bearer YOUR_API_KEY"
}
headers["Authorization"] = "Bearer " + os.environ["DRAMAGEN_API_KEY"]
response = requests.request("GET", api_origin + "/v1/models", headers=headers, 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"
};
headers.Authorization = `Bearer ${process.env.DRAMAGEN_API_KEY}`;
const response = await fetch(apiOrigin + "/v1/models", {
  method: "GET",
  headers,
});
const result = await response.json();
if (!response.ok || result.code !== "ok") throw new Error(JSON.stringify(result));
console.log(result.data);
```
