# Dreamina API Gateway 使用文档

> 把本地 Dreamina（即梦）CLI 封装成 OpenAI 风格的 HTTP API。支持图片与视频全模型、参考内容上传、并发任务队列、API Key 管理。
>
> - 公网入口：`https://dream.aurustec.com`（主服务器 nginx 反代，TLS 由 Let's Encrypt 提供）
> - 本机服务：`http://192.168.1.54:8787`
> - 管理控制台：`https://dream.aurustec.com/admin`（admin / 见部署记录，请自行修改 config.json）
> - 本文档在线版：`https://dream.aurustec.com/docs`

---

## 0. 30 秒上手

```bash
# 1. 管理员登录拿 session token
curl -s https://dream.aurustec.com/admin/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"你的密码"}'

# 2. 用返回的 token 生成一个 API Key（key 只完整显示这一次）
curl -s https://dream.aurustec.com/admin/keys \
  -H "Authorization: Bearer <上面返回的token>" \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-app"}'

# 3. 文生图（同步风格，默认最多等 180 秒）
curl -s https://dream.aurustec.com/v1/images/generations \
  -H "Authorization: Bearer dk-xxxx" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"一只戴墨镜的橘猫","resolution_type":"2k","ratio":"1:1"}'
```

---

## 1. 认证

### 1.1 API 调用（/v1/*）

所有 `/v1/*` 端点需要 API Key，两种写法等价：

```
Authorization: Bearer dk-xxxxxxxxxxxxxxxx
X-Api-Key: dk-xxxxxxxxxxxxxxxx
```

Key 由管理员在 `/admin/keys` 生成，格式 `dk-` + 48 位十六进制。数据库只存哈希，**创建时只显示一次**。结果文件（`/v1/files/...`）也可以用任务查询返回的 `file_token` 以 `?token=` 方式直接嵌入 `<img>`/`<video>`。

### 1.2 管理员（/admin/*）

`POST /admin/login` 用账号密码换 session token（默认 12 小时有效），之后：

```
Authorization: Bearer st-xxxx
```

登录同时会种 HttpOnly Cookie，直接打开 `/admin` 网页控制台即可使用。

### 1.3 防爆破机制

- 登录接口按 **来源 IP** 与 **IP+用户名** 双重计数：连续失败 5 次 → 锁 15 分钟；每再多失败一次锁定时间翻倍（30m、1h、2h…上限 24h），重启服务不重置。
- 密码校验为 scrypt + 常数时间比较，账号错误时也执行同等开销计算，响应内容与耗时均不泄露"用户名是否存在"。
- 全局每 IP 限流（默认 600 次/分钟）。
- 锁定期间返回 `423`，提示剩余大约时长。

---

## 2. 通用约定

- **基底 URL**：`https://dream.aurustec.com`
- **错误格式**（OpenAI 风格）：

```json
{ "error": { "message": "invalid API key", "type": "authentication_error", "code": "invalid_api_key" } }
```

- **任务状态机**：`queued → submitting → generating → success | fail`
- 生成类接口都有 `wait` 参数（秒，0–600）：
  - 图片接口默认 `wait=180`，等到完成即返回 OpenAI 同步格式；超时返回任务对象（HTTP 200 + status 字段），可继续轮询。
  - 视频接口默认 `wait=0`，立即返回任务对象（视频生成耗时数分钟，建议异步轮询）。
- 任意任务可通过 `GET /v1/tasks/{id}` 轮询，成功后 `outputs[].url` 可直接下载。
- 并发：服务内部维护 CLI 子进程池（默认同时 3 个提交任务、4 个轮询），超过上限的请求自动排队，无需客户端限流。

---

## 3. 模型列表

`GET /v1/models`（需要 API Key）

### 图片模型（文生图 / 图生图）

| model | 分辨率 | 说明 |
|---|---|---|
| `3.0` / `3.1` | 1k, 2k | 旧代 |
| `4.0` / `4.1` / `4.5` / `4.6` / `4.7` | 2k, 4k | |
| `5.0` | 2k, 4k | 默认 |
| `5.0Pro` | 1.5k, 2k, 4k | 当前最强 |

别名兼容：`seedream-4.7`、`seedream5.0pro` 等写法都会被规范化。

### 视频模型

| model | 分辨率 | 时长(秒) | 支持命令 |
|---|---|---|---|
| `seedance2.0fast` | 720p | 4–15 | 文/图/首尾帧/全能参考 |
| `seedance2.0` | 720p | 4–15 | 同上 |
| `seedance2.0_vip` | 720p, 1080p, 4k | 4–15 | 同上（默认） |
| `seedance2.0fast_vip` | 720p | 4–15 | 同上，提速通道 |
| `seedance2.0mini` | 720p | 4–15 | 同上 |
| `seedance2.5` | 480p, 720p, 1080p | 4–30 | 同上，VIP 专属，支持纯音频输入 |
| `seedance1.5pro` | 720p | 5–12 | 图生视频 / 首尾帧 |
| `seedance1.0fast` | 720p | 5–10 | 仅图生视频 |
| `multiframe-story` | 720p, 1080p | 每段 1–8s | 多图故事（模型固定） |

另有 `image-upscale`（2k/4k/8k，4k/8k 需 VIP）。

> 部分模型首次使用需要在即梦网页端完成一次生成（合规确认），此时任务会返回 `AigcComplianceConfirmationRequired`，按提示去网页端操作一次即可。

---

## 4. 图片接口

### 4.1 文生图 `POST /v1/images/generations`

JSON 请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `prompt` | string | 是 | 提示词（≤8000 字符） |
| `model` | string | 否 | 见模型表，默认 `5.0` |
| `resolution_type` | string | 否 | `1k/1.5k/2k/4k`（受模型限制），默认 `2k` |
| `ratio` | string | 否 | `21:9 16:9 3:2 4:3 1:1 3:4 2:3 9:16`，默认 16:9 |
| `size` | string | 否 | OpenAI 风格 `1024x1024`，与 `ratio` 互斥，指定后按自定义宽高提交 |
| `n` | int | 否 | 1–10 张，默认 1 |
| `wait` | int | 否 | 0–600 秒，默认 180 |
| `session` | int | 否 | 即梦会话 ID，默认 0 |

```bash
curl -s $BASE/v1/images/generations \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"赛博朋克城市夜景","model":"5.0Pro","resolution_type":"2k","ratio":"16:9","n":2}'
```

成功响应（OpenAI 同步格式）：

```json
{
  "created": 1756636800,
  "data": [{ "url": "https://dream.aurustec.com/v1/files/task-xxx/a.png", "revised_prompt": null }],
  "task_id": "task-xxx"
}
```

`wait` 超时未完成时返回任务对象（此时转入第 6 节轮询流程）。

### 4.2 图生图 `POST /v1/images/edits`

**方式一：multipart 上传参考图（推荐，字段名 `image`，可重复）**

```bash
curl -s $BASE/v1/images/edits \
  -H "Authorization: Bearer $KEY" \
  -F 'image=@./cat.png' \
  -F 'image=@./bg.png' \
  -F 'prompt="把猫放进这个背景里"' \
  -F 'model=5.0' -F 'resolution_type=2k'
```

**方式二：JSON + 引用 URL（服务端自动下载）**

```bash
curl -s $BASE/v1/images/edits \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"改成水彩风格","image_urls":["https://example.com/cat.png"],"resolution_type":"2k"}'
```

参考图 1–10 张；其余参数同 4.1。

### 4.3 图片超清 `POST /v1/images/upscale`

```bash
curl -s $BASE/v1/images/upscale \
  -H "Authorization: Bearer $KEY" \
  -F 'image=@./photo.png' -F 'resolution_type=4k'
```

`resolution_type`: `2k / 4k / 8k`（4k、8k 需 VIP）。

---

## 5. 视频接口

统一入口：`POST /v1/videos/generations`（别名 `/v1/video/generations`）。

**自动路由规则**（不传 `type` 时）：

| 输入 | 命令 |
|---|---|
| 仅 prompt | text2video |
| 1 张图片 | image2video |
| first_frame + last_frame | frames2video |
| ≥2 张纯图片 | multiframe2video |
| 图片+视频+音频混合 | multimodal2video |

也可用 `type` 显式指定：`text2video / image2video / frames2video / multiframe2video / multimodal2video`。

### 5.1 文生视频

```bash
curl -s $BASE/v1/videos/generations \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"镜头推进，一只橘猫从沙发跳下","model":"seedance2.0fast","duration":5,"ratio":"16:9","video_resolution":"720p"}'
```

### 5.2 图生视频（multipart 单图）

```bash
curl -s $BASE/v1/videos/generations \
  -H "Authorization: Bearer $KEY" \
  -F 'image=@./first.png' \
  -F 'prompt="镜头慢慢推近"' \
  -F 'model=seedance2.0_vip' -F 'duration=5' -F 'video_resolution=720p'
```

### 5.3 首尾帧视频

```bash
curl -s $BASE/v1/videos/generations \
  -H "Authorization: Bearer $KEY" \
  -F 'first_frame=@./start.png' -F 'last_frame=@./end.png' \
  -F 'prompt="从春天过渡到冬天"' -F 'video_resolution=720p'
```

（JSON 传 URL 用 `first_frame_url` / `last_frame_url`）

### 5.4 多图故事视频（multiframe）

2 张图：只需 `prompt` + `duration`（转场时长 1–8s）：

```bash
curl -s $BASE/v1/videos/generations \
  -H "Authorization: Bearer $KEY" \
  -F 'image=@./a.png' -F 'image=@./b.png' \
  -F 'type=multiframe2video' -F 'prompt="角色转身"' -F 'video_resolution=1080p'
```

≥3 张图：必须为每个转场提供 `transition_prompt`（N 张图 N-1 个）：

```bash
curl -s $BASE/v1/videos/generations \
  -H "Authorization: Bearer $KEY" \
  -F 'image=@./a.png' -F 'image=@./b.png' -F 'image=@./c.png' \
  -F 'type=multiframe2video' -F 'video_resolution=1080p' \
  -F 'transition_prompt="白天到黄昏"' -F 'transition_prompt="黄昏到夜晚"' \
  -F 'transition_duration=3' -F 'transition_duration=5'
```

### 5.5 全能参考视频（multimodal，图片+视频+音频任意组合）

```bash
curl -s $BASE/v1/videos/generations \
  -H "Authorization: Bearer $KEY" \
  -F 'image=@./hero.png' -F 'audio=@./music.mp3' \
  -F 'type=multimodal2video' -F 'model=seedance2.0fast' \
  -F 'duration=5' -F 'video_resolution=720p'
```

JSON 引用 URL 字段：`image_urls[] / video_urls[] / audio_urls[]`。seedance2.5 支持纯音频输入。

### 5.6 视频通用参数

| 字段 | 说明 |
|---|---|
| `model` | 见模型表；不同命令默认值不同 |
| `duration` | 秒，按模型校验范围 |
| `video_resolution` | 必填（默认 720p），按模型校验 |
| `ratio` | 1:1 3:4 16:9 4:3 9:16 21:9（image2video/frames2video 由输入图推断，不接受） |
| `wait` | 默认 0，立即返回任务 |

---

## 6. 任务查询与文件下载

```bash
# 查询单个任务
curl -s $BASE/v1/tasks/task-xxx -H "Authorization: Bearer $KEY"

# 任务列表 / 按状态过滤
curl -s "$BASE/v1/tasks?status=success&limit=20" -H "Authorization: Bearer $KEY"

# 删除任务记录（不取消远端生成）
curl -s -X DELETE $BASE/v1/tasks/task-xxx -H "Authorization: Bearer $KEY"

# 下载结果（带 Key）
curl -s -O $BASE/v1/files/task-xxx/a.png -H "Authorization: Bearer $KEY"
```

任务对象：

```json
{
  "id": "task-xxx",
  "type": "text2image",
  "status": "success",
  "submit_id": "3f6eb41f425d23a3",
  "model": "5.0",
  "outputs": [{ "file": "a.png", "url": "https://dream.aurustec.com/v1/files/task-xxx/a.png", "size": 2330112 }],
  "file_token": "st-...",
  "error": null
}
```

`file_token`（24h 有效）用法：`{url}?token={file_token}`，方便在网页 `<img src>` 中直接使用。

`GET /v1/credit`：查询当前即梦账户积分（等价 `dreamina user_credit`）。

---

## 7. 管理接口

| 方法 & 路径 | 说明 |
|---|---|
| `POST /admin/login` | `{username, password}` → `{token}` |
| `GET /admin/me` | 当前会话信息 |
| `GET /admin/stats` | 任务统计、并发配置、Key 数量 |
| `GET /admin/keys` | Key 列表（不含完整 key） |
| `POST /admin/keys` | `{name}` → 生成新 key（完整 key 仅此一次返回） |
| `PATCH /admin/keys/{id}` | `{enabled: bool, name: string}` 启停/改名 |
| `DELETE /admin/keys/{id}` | 删除 key（立即失效） |
| `GET /admin/tasks?limit=50` | 全部任务列表 |
| `DELETE /admin/tasks` | 清理已完成任务记录 |

---

## 8. 状态码

| 码 | 含义 |
|---|---|
| 200 / 201 | 成功 |
| 400 | 参数错误 / 生成失败（`error.message` 有具体原因） |
| 401 | API Key 或管理员会话无效 |
| 404 | 任务/文件/端点不存在 |
| 413 | 上传过大（默认单请求 150MB） |
| 423 | 登录锁定中（防爆破触发） |
| 429 | 触发限流 |
| 500 | 服务内部错误（看 data/service.log） |

---

## 9. 运维备忘

- 服务目录：`D:\dreamina_cli_to_api`（`server.js`、`config.json`、`data/`）
- 开机自启：计划任务 `DreaminaAPI`（SYSTEM，watchdog 5 秒自动拉起）→ `start_service.bat`
- 手动重启：`schtasks /end /tn DreaminaAPI && schtasks /run /tn DreaminaAPI`
- 日志：`data/service.log`；即梦 CLI 日志：`~/.dreamina_cli/logs/`
- 改并发：`config.json` 的 `max_concurrent_cli` / `poll_concurrency`，重启生效
- 改管理员密码：修改 `config.json` 的 `admin_pass_hash`（scrypt，`salt:hash` 格式）
- 公网链路：路由器 443 → 主服务器(192.168.1.253) nginx（SNI 按 `dream.aurustec.com` 分流）→ 本机 192.168.1.54:8787
- 积分消耗与即梦网页端 Agent 模式标准一致，调用前留意 `GET /v1/credit`