# 文件上传

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