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