# 开发文档



## 选择你的起点

- https://noveadream.com/developers/zh/quickstart/
- https://noveadream.com/developers/zh/models/
- https://noveadream.com/developers/zh/nai/

## 找到适合你的模型

- [GPT Image 2](https://noveadream.com/developers/zh/images/?model=gpt-image-2): gpt-image-2. 图片生成、编辑与参数示例。
- [GPT Image 2.5 SFW](https://noveadream.com/developers/zh/images/?model=gpt-image-2.5-sunburst): gpt-image-2.5-sunburst. 图片生成、编辑与参数示例。
- [Seedream 5.0 Pro](https://noveadream.com/developers/zh/images/?model=seedream-5.0-pro): seedream-5.0-pro. 图片生成、编辑与参数示例。
- [Qwen Edit 2511](https://noveadream.com/developers/zh/images/?model=qwen-edit-2511): qwen-edit-2511. 图片生成、编辑与参数示例。

## 一个请求，开始创作

图片、视频和 NovelAI 使用同一个站内 API Key。不同类型有各自的请求与返回格式。

```bash
curl --fail-with-body 'https://noveadream.com/v1/models' \
  -H "Authorization: Bearer $NOVEA_API_KEY"
```

---

# 快速开始

准备 Key，选择模型，发起你的第一次图片请求。

## 01 / 准备 API Key

登录后在「我的 API Key」创建密钥，并确认账号余额、会员权益和模型权限。阅读文档无需登录。

```bash
export NOVEA_API_KEY="sk-your-key"
export REQUEST_ID="$(uuidgen)"
```

```powershell
$env:NOVEA_API_KEY = "sk-your-key"
$env:REQUEST_ID = [guid]::NewGuid().ToString()
```

## 02 / 确认可用模型

```bash
curl --fail-with-body 'https://noveadream.com/v1/models' \
  -H "Authorization: Bearer $NOVEA_API_KEY"
```

使用 data[].id 中的模型 ID。公开模型介绍不代表每个账号都能使用所有模型。

## 03 / 生成图片

```bash
curl --fail-with-body 'https://noveadream.com/v1/images/generations' \
  -H "Authorization: Bearer $NOVEA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $REQUEST_ID" \
  -d '{
  "model": "gpt-image-2",
  "prompt": "A ceramic teapot on a sunlit table, soft shadows",
  "size": "1024x1024",
  "quality": "medium",
  "n": 1,
  "response_format": "url"
}'
```

网络重试复用 REQUEST_ID；新生成使用新的值。

## 04 / 保存结果

```json
{
  "created": 1791300000,
  "data": [
    {
      "url": "https://example.com/result.png"
    }
  ]
}
```

从 data[].url 下载成图。example.com 是示例占位地址。若返回 generation_pending，原任务仍可能执行中，请复用原幂等键，避免重复提交。

---

# 模型广场

按创作任务选择模型。查看接入方式，也可以直接进入工作台。

## 探索模型

- [GPT Image 2](https://noveadream.com/developers/zh/images/?model=gpt-image-2): gpt-image-2. 图片生成、编辑与参数示例。
- [GPT Image 2.5 SFW](https://noveadream.com/developers/zh/images/?model=gpt-image-2.5-sunburst): gpt-image-2.5-sunburst. 图片生成、编辑与参数示例。
- [Seedream 5.0 Pro](https://noveadream.com/developers/zh/images/?model=seedream-5.0-pro): seedream-5.0-pro. 图片生成、编辑与参数示例。
- [Qwen Edit 2511](https://noveadream.com/developers/zh/images/?model=qwen-edit-2511): qwen-edit-2511. 图片生成、编辑与参数示例。
- [NovelAI V4.5](https://noveadream.com/developers/zh/images/?model=nai-v4.5): nai-v4.5. 图片生成、编辑与参数示例。
- [NovelAI V5](https://noveadream.com/developers/zh/images/?model=nai-v5): nai-v5. 图片生成、编辑与参数示例。
- [Nano Banana 2](https://noveadream.com/developers/zh/images/?model=nano-banana-2-sfw): nano-banana-2-sfw. 网页工作台图片模型。
- [Seedance 2.5](https://noveadream.com/developers/zh/videos/?model=seedance-2.5): seedance-2.5. 视频生成与异步任务查询。
- [Seedance 2.0](https://noveadream.com/developers/zh/videos/?model=seedance-2.0): seedance-2.0. 视频生成与异步任务查询。
- [Seedance 2.0 Fast](https://noveadream.com/developers/zh/videos/?model=seedance-2.0-fast): seedance-2.0-fast. 视频生成与异步任务查询。
- [MiniMax H3](https://noveadream.com/developers/zh/videos/?model=minimax-h3): minimax-h3. 视频生成与异步任务查询。
- [MiniMax H3 SFW](https://noveadream.com/developers/zh/videos/?model=minimax-h3-sfw): minimax-h3-sfw. 视频生成与异步任务查询。
- [Wan 2.2 Anime](https://noveadream.com/developers/zh/videos/?model=wan-2.2-anime): wan-2.2-anime. 视频生成与异步任务查询。
- [Wan 2.2 Real](https://noveadream.com/developers/zh/videos/?model=wan-2.2-real): wan-2.2-real. 视频生成与异步任务查询。
- [gpt-6-sol](https://noveadream.com/developers/zh/text/?model=gpt-6-sol): gpt-6-sol. 对话与文本生成；是否可用以账号模型列表为准。
- [gpt-6-astra](https://noveadream.com/developers/zh/text/?model=gpt-6-astra): gpt-6-astra. 对话与文本生成；是否可用以账号模型列表为准。
- [gpt-5.6-sol](https://noveadream.com/developers/zh/text/?model=gpt-5.6-sol): gpt-5.6-sol. 对话与文本生成；是否可用以账号模型列表为准。
- [deepseek-v4.1-flash](https://noveadream.com/developers/zh/text/?model=deepseek-v4.1-flash): deepseek-v4.1-flash. 对话与文本生成；是否可用以账号模型列表为准。

## 模型价格

查看各模型的价格，或让价格助手根据你的数量和参数计算。

[查看模型价格](https://noveadream.com/developers/zh/pricing/)

---

# 模型价格



## 价格助手

## 全部模型价格

### GPT Image 2

按输出张数计费；Seedream 第一张参考图免费，之后每张参考图每次请求加收 ¥0.0198。会员权益抵扣前的钱包标准价。

- 1k: ¥0.066
- 2k: ¥0.099
- 4k: ¥0.132

### GPT Image 2.5 SFW

按输出张数计费；Seedream 第一张参考图免费，之后每张参考图每次请求加收 ¥0.0198。会员权益抵扣前的钱包标准价。

- 1k: ¥0.066
- 2k: ¥0.066
- 4k: ¥0.066

### Seedream 5.0 Pro

按输出张数计费；Seedream 第一张参考图免费，之后每张参考图每次请求加收 ¥0.0198。会员权益抵扣前的钱包标准价。

- 1k: ¥0.297
- 2k: ¥0.594

### Qwen Edit 2511

按输出张数计费；Seedream 第一张参考图免费，之后每张参考图每次请求加收 ¥0.0198。会员权益抵扣前的钱包标准价。

- 1k: ¥0.099

### Nano Banana 2

按输出张数计费；Seedream 第一张参考图免费，之后每张参考图每次请求加收 ¥0.0198。会员权益抵扣前的钱包标准价。

- 1k: ¥0.1452
- 2k: ¥0.165
- 4k: ¥0.165

### NovelAI V4.5

普通单张：V4.5 ¥0.0198，V5 ¥0.0396。尺寸、步数、批量和参考图会改变费用。V5 API 可使用钱包；网页 V5 需要会员。这里计算钱包价，不读取个人会员额度。

- 1024 × 1024, 23 步: ¥0.0198

### NovelAI V5

普通单张、无参考图且不超过 1024×1024 像素：23 步以内基础费 ¥0.0396；24–28 步每增加一步加 ¥0.0396 ÷ 23；超过 28 步为 28 步基础费加点数费用（每点 ¥0.0264）。基础费按钱包最小记账单位向上取整。更大尺寸、批量和参考功能另计点数；会员权益抵扣前的钱包价。

- 1024 × 1024, 23 步: ¥0.0396
- 1024 × 1024, 24 步: ¥0.041329
- 1024 × 1024, 28 步: ¥0.04822
- 1024 × 1024, 29 步: ¥0.89302

### Seedance 2.5

按分辨率、比例、时长和参考视频计算。预估费用与预扣分开展示；按用量计费的任务完成后结算。会员权益抵扣前的钱包标准价。

- 480p, 5s, 16:9: ¥4.25964
- 720p, 5s, 16:9: ¥9.15948
- 1080p, 5s, 16:9: ¥22.51788

### Seedance 2.0

按分辨率、比例、时长和参考视频计算。预估费用与预扣分开展示；按用量计费的任务完成后结算。会员权益抵扣前的钱包标准价。

- 480p, 5s, 16:9: ¥2.78454
- 720p, 5s, 16:9: ¥5.98752
- 1080p, 5s, 16:9: ¥14.81964

### Seedance 2.0 Fast

按分辨率、比例、时长和参考视频计算。预估费用与预扣分开展示；按用量计费的任务完成后结算。会员权益抵扣前的钱包标准价。

- 480p, 5s, 16:9: ¥2.2275
- 720p, 5s, 16:9: ¥4.79028

### MiniMax H3

按分辨率、比例、时长和参考视频计算。预估费用与预扣分开展示；按用量计费的任务完成后结算。会员权益抵扣前的钱包标准价。

- 480p, 5s, 16:9: ¥0.95898
- 720p, 5s, 16:9: ¥1.90872

### MiniMax H3 SFW

按分辨率、比例、时长和参考视频计算。预估费用与预扣分开展示；按用量计费的任务完成后结算。会员权益抵扣前的钱包标准价。

- 768p, 5s, 16:9: ¥0.66
- 1080p, 5s, 16:9: ¥0.66

### Wan 2.2 Anime

按分辨率、比例、时长和参考视频计算。预估费用与预扣分开展示；按用量计费的任务完成后结算。会员权益抵扣前的钱包标准价。

- 480p, 5s, 16:9: ¥0.924
- 720p, 5s, 16:9: ¥1.188

### Wan 2.2 Real

按分辨率、比例、时长和参考视频计算。预估费用与预扣分开展示；按用量计费的任务完成后结算。会员权益抵扣前的钱包标准价。

- 480p, 5s, 16:9: ¥0.924
- 720p, 5s, 16:9: ¥1.188

### gpt-6-sol

按当前标准分组的公开费率计算：未缓存输入、缓存输入、输出分别计费；部分模型按次计费。缺少配置时不猜价。

当前快照无费率。

### gpt-6-astra

按当前标准分组的公开费率计算：未缓存输入、缓存输入、输出分别计费；部分模型按次计费。缺少配置时不猜价。

当前快照无费率。

### gpt-5.6-sol

按当前标准分组的公开费率计算：未缓存输入、缓存输入、输出分别计费；部分模型按次计费。缺少配置时不猜价。

当前快照无费率。

### deepseek-v4.1-flash

按当前标准分组的公开费率计算：未缓存输入、缓存输入、输出分别计费；部分模型按次计费。缺少配置时不猜价。

当前快照无费率。

---

# 图片生成与编辑

使用文字或参考图片创建图像，以 URL 或 Base64 获取结果。

## 构建请求

### GPT Image 2

- quality: low / auto → 1K; medium → 2K; high → 4K
- n: 1
- size: WIDTHxHEIGHT；宽高为 8 的倍数，且满足对应档位像素上限。
- image[]: 编辑接口上传 1–4 张图片。

POST /v1/images/generations

```json
{
  "model": "gpt-image-2",
  "prompt": "A ceramic teapot on a sunlit table",
  "aspect_ratio": "1:1",
  "quality": "medium",
  "n": 1,
  "response_format": "url"
}
```

### GPT Image 2.5 SFW

- quality: low / auto → 1K
- n: 1
- size: 宽高为 16 的倍数；总像素 655360–1048576，宽高比不超过 3:1，单边不超过 3840。
- image[]: 编辑接口上传 1–4 张图片。

POST /v1/images/generations

```json
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "A ceramic teapot on a sunlit table",
  "aspect_ratio": "1:1",
  "quality": "low",
  "n": 1,
  "response_format": "url"
}
```

### Seedream 5.0 Pro

- quality: low / auto → 1K; medium → 2K
- aspect_ratio: 1:1 / 16:9 / 9:16 / 4:3 / 3:4
- n: 1
- image_urls / image[]: 1–10 张；smart 比例仅限提供参考图时使用。

POST /v1/images/generations

```json
{
  "model": "seedream-5.0-pro",
  "prompt": "A ceramic teapot on a sunlit table",
  "aspect_ratio": "1:1",
  "quality": "low",
  "n": 1,
  "response_format": "url"
}
```

### Qwen Edit 2511

- mode: reference
- image_urls / image[]: 必填，1–2 张图片。
- resolution: 固定 720p，不使用 quality 切换。
- n: 1

POST /v1/images/generations

```json
{
  "model": "qwen-edit-2511",
  "prompt": "Change the background to a quiet garden",
  "mode": "reference",
  "aspect_ratio": "1:1",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "n": 1,
  "response_format": "url"
}
```

### NovelAI V4.5

- n: 1–4
- aspect_ratio: 按比例映射为服务端预设尺寸。
- image[]: 编辑时只接受 1 张图片。
- quality: 不适用；精细参数见 NovelAI 文档。

POST /v1/images/generations

```json
{
  "model": "nai-v4.5",
  "prompt": "watercolor, a quiet garden",
  "aspect_ratio": "1:1",
  "n": 1,
  "response_format": "url"
}
```

### NovelAI V5

- model: nai-diffusion-5-full
- action: generate / img2img / infill
- parameters.steps: 1–50
- parameters.n_samples: 1–4
- parameters.v4_prompt.caption.char_captions: 最多 32 个，推荐自动位置。

POST /ai/generate-image

```json
{
  "model": "nai-diffusion-5-full",
  "input": "watercolor, a quiet garden",
  "action": "generate",
  "parameters": {
    "width": 1024,
    "height": 1024,
    "steps": 23,
    "n_samples": 1,
    "scale": 5,
    "seed": 42,
    "negative_prompt": ""
  }
}
```

### Nano Banana 2

- 接口: 仅网页工作台，暂未开放公共 API。
- resolution: 1K / 2K / 4K
- aspect_ratio: smart / 1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 21:9
- 参考图: 最多 14 张账号内图片。
- 生成数量: 1



## 通用参数

| 字段 | 说明 |
| --- | --- |
| model | 必填，使用当前 Key 可用的模型 ID。 |
| prompt | 必填，描述目标画面。 |
| n | 生成数量，首次接入建议使用 1。 |
| size / quality | 尺寸和质量取值随模型变化，不能跨模型照搬。 |
| response_format | url \| b64_json |
| image_urls | 部分模型支持的公网参考图 URL 数组。 |

## 上传参考图编辑

```bash
curl --fail-with-body https://noveadream.com/v1/images/edits \
  -H "Authorization: Bearer $NOVEA_API_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -F "model=gpt-image-2" \
  -F "prompt=Change the background to a quiet garden" \
  -F "image[]=@reference.png"
```

multipart 上传让客户端设置 Content-Type 边界，不要手动指定 application/json。多个文件可重复使用 image[]。

## 读取结果

```json
{
  "created": 1791300000,
  "data": [{ "url": "https://example.com/result.png" }]
}
```

选择 b64_json 时读取 data[].b64_json。结果链接应及时下载保存，不要作为永久存储地址。

---

# 视频生成

创建任务、保存 ID、查询结果。视频生成采用异步流程。

## 创建视频任务

### Seedance 2.5

- model: seedance-2.5
- resolution: 480p / 720p / 1080p
- duration: 4–30
- aspect_ratio: 示例提供横屏、竖屏与正方形。
- Idempotency-Key: 重试同一次生成时保持不变。

POST /v1/videos

```json
{
  "model": "seedance-2.5",
  "prompt": "A slow camera move through a peaceful garden",
  "duration": 5,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

### Seedance 2.0

- model: seedance-2.0
- resolution: 480p / 720p / 1080p
- duration: 4–15
- aspect_ratio: 示例提供横屏、竖屏与正方形。
- Idempotency-Key: 重试同一次生成时保持不变。

POST /v1/videos

```json
{
  "model": "seedance-2.0",
  "prompt": "A slow camera move through a peaceful garden",
  "duration": 5,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

### Seedance 2.0 Fast

- model: seedance-2.0-fast
- resolution: 480p / 720p
- duration: 4–15
- aspect_ratio: 示例提供横屏、竖屏与正方形。
- Idempotency-Key: 重试同一次生成时保持不变。

POST /v1/videos

```json
{
  "model": "seedance-2.0-fast",
  "prompt": "A slow camera move through a peaceful garden",
  "duration": 5,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

### MiniMax H3

- model: minimax-h3
- resolution: 480p / 720p
- duration: 4–15
- aspect_ratio: 示例提供横屏、竖屏与正方形。
- Idempotency-Key: 重试同一次生成时保持不变。

POST /v1/videos

```json
{
  "model": "minimax-h3",
  "prompt": "A slow camera move through a peaceful garden",
  "duration": 5,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

### MiniMax H3 SFW

- model: minimax-h3-sfw
- resolution: 768p / 1080p
- duration: 4–30
- aspect_ratio: 示例提供横屏、竖屏与正方形。
- Idempotency-Key: 重试同一次生成时保持不变。

POST /v1/videos

```json
{
  "model": "minimax-h3-sfw",
  "prompt": "A slow camera move through a peaceful garden",
  "duration": 5,
  "resolution": "768p",
  "aspect_ratio": "16:9"
}
```

### Wan 2.2 Anime

- model: wan-2.2-anime
- resolution: 480p / 720p
- duration: 5
- aspect_ratio: 示例提供横屏、竖屏与正方形。
- Idempotency-Key: 重试同一次生成时保持不变。

POST /v1/videos

```json
{
  "model": "wan-2.2-anime",
  "prompt": "A slow camera move through a peaceful garden",
  "duration": 5,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

### Wan 2.2 Real

- model: wan-2.2-real
- resolution: 480p / 720p
- duration: 5
- aspect_ratio: 示例提供横屏、竖屏与正方形。
- Idempotency-Key: 重试同一次生成时保持不变。

POST /v1/videos

```json
{
  "model": "wan-2.2-real",
  "prompt": "A slow camera move through a peaceful garden",
  "duration": 5,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

## 查询与下载

```bash
curl --fail-with-body 'https://noveadream.com/v1/videos/video_12345' \
  -H "Authorization: Bearer $NOVEA_API_KEY"
```

video_12345 为占位 ID，应替换为创建请求实际返回的 id。completed 后下载，failed 后停止轮询。建议查询间隔从 5 秒开始，并对限流退避。

```bash
curl --fail-with-body https://noveadream.com/v1/videos/video_12345/content \
  -H "Authorization: Bearer $NOVEA_API_KEY" \
  -o result.mp4
```

## MiniMax H3 参考素材

全能参考模式支持图片、视频和音频；首尾帧模式只接收图片。参考音频和视频分别填写累计时长，不能把首尾帧字段与全能参考混用。

```json
{
  "model": "minimax-h3-sfw",
  "mode": "all-reference",
  "prompt": "Follow the motion of the reference video",
  "duration": 8,
  "resolution": "768p",
  "aspect_ratio": "9:16",
  "reference_video_urls": [
    "https://example.com/motion.mp4"
  ],
  "input_video_seconds": 6
}
```

---

# NovelAI 接入

使用 NovelAI 图片请求格式，一次提交即可获取图片。

## 直接生成图片

接入地址为 https://noveadream.com，使用站内 API Key。POST /ai/generate-image 接受 input、model、action、parameters，无需先报价或传 model_variant。默认返回 ZIP；Accept: application/json 返回 images 数组中的 Base64 图片。

```bash
curl --fail-with-body 'https://noveadream.com/ai/generate-image' \
  -H "Authorization: Bearer $NOVEA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "input": "watercolor, a quiet garden",
  "model": "nai-diffusion-5-full",
  "action": "generate",
  "parameters": {
    "width": 1024,
    "height": 1024,
    "steps": 23,
    "n_samples": 1,
    "scale": 5,
    "seed": 42,
    "sampler": "k_euler_ancestral",
    "negative_prompt": ""
  }
}' --output images.zip
```

## 模型与版本

| 模型 | model（官方格式） | 角色数上限 |
| --- | --- | --- |
| NAI V4.5 Full | nai-diffusion-4-5-full | 6 |
| NAI V4.5 Curated | nai-diffusion-4-5-curated | 6 |
| NAI V5 Full | nai-diffusion-5-full | 32 |
| NAI V4 Full | nai-diffusion-4-full | 6 |
| NAI V4 Curated | nai-diffusion-4-curated-preview | 6 |
| NAI Anime V3 / Furry V3 | nai-diffusion-3 / nai-diffusion-furry-3 | 0 |

角色使用 parameters.v4_prompt / v4_negative_prompt 的 caption.char_captions。use_coords: false 为自动位置。提示词原样传递，不额外补质量词或负面词。

## 兼容范围与客户端

支持 generate、img2img、infill、角色提示词及支持模型的 Precise Reference；image 和 mask 直接传 Base64。尺寸为 64 的倍数，最多 3145728 像素、单边 3072，1–50 步、1–4 张，seed 为 0–4294967295。请求上限 40 MiB，单张参考图片上限 24 MiB、2400 万像素。

当前不支持此入口的 Vibe 编码、SMEA、ControlNet、Max Enhance、自动放大、流式响应或账号订阅模拟；启用不支持的参数会在扣费前返回 400。需要报价、资产 ID 或 SSE 恢复时，可使用下方工作台扩展接口。

支持自定义 NovelAI 地址的客户端可更换地址与 Key 后接入。SillyTavern 当前 release 源码将图片、订阅和放大地址写死在官方域名，原版不能只更换 Key；需客户端提供自定义地址支持。本服务不冒充官网订阅。

## 可选：工作台扩展报价

```bash
curl --fail-with-body 'https://noveadream.com/v1/nai/estimate' \
  -H "Authorization: Bearer $NOVEA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "nai-v4.5",
  "model_variant": "nai-diffusion-4-5-full",
  "prompt": "a quiet garden, watercolor, soft lighting",
  "negative_prompt": "lowres, blurry",
  "width": 1024,
  "height": 1024,
  "steps": 28,
  "count": 1
}'
```

仅扩展接口使用 model: nai-v4.5 与 model_variant。保存返回的 data.quote_id，修改参数后重新报价。官方格式入口不需要这一步。

## 提交任务

```bash
curl --fail-with-body 'https://noveadream.com/v1/nai/generations' \
  -H "Authorization: Bearer $NOVEA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "nai-v4.5",
  "model_variant": "nai-diffusion-4-5-full",
  "prompt": "a quiet garden, watercolor, soft lighting",
  "negative_prompt": "lowres, blurry",
  "width": 1024,
  "height": 1024,
  "steps": 28,
  "count": 1,
  "quote_id": "QUOTE_ID",
  "client_request_id": "YOUR_UNIQUE_REQUEST_ID"
}'
```

替换 QUOTE_ID 与 YOUR_UNIQUE_REQUEST_ID。重试同一次请求时复用 client_request_id，新的创作使用新的 ID。

---

# 酒馆



## 填写连接信息

以下设置适用于支持自定义 NovelAI 接口地址的酒馆扩展。酒馆内置 NovelAI 生图使用官方固定地址，不能仅替换 API Key 接入本站。

[创建 API Key](https://noveadream.com/ai/api?section=keys)

| 设置项 | 填写内容 |
| --- | --- |
| 接口格式 | NovelAI |
| 基础地址 | https://noveadream.com |
| 完整生图地址 | https://noveadream.com/ai/generate-image |
| API Key | 填写 NoveaDream API Key。 |
| 模型（NAI5） | nai-diffusion-5-full |
| 模型（NAI4.5） | nai-diffusion-4-5-full |

扩展要求基础地址时填写网站根地址；要求完整请求地址时填写 /ai/generate-image 地址。Key 输入框通常填写原文，HTTP 请求头使用 Authorization: Bearer YOUR_API_KEY。

## 模型参数

| 设置项 | 示例 |
| --- | --- |
| 宽度 × 高度 | 832 × 1216 |
| 步数 | 23 |
| 采样器 | k_euler_ancestral |
| CFG / scale | 5 |
| 种子 | 42 |
| 角色位置 | 自动（use_coords: false） |
| SMEA / SMEA DYN | 关闭 |

[NovelAI 接入与参数范围](https://noveadream.com/developers/zh/nai/)

## 常见问题

| 现象 | 检查 |
| --- | --- |
| 401 | 检查 API Key 是否完整、有效。 |
| 403 | 检查 Key 的模型权限及账号状态。 |
| 400 | 按返回字段检查种子、尺寸或不支持的参数。 |
| 404 / 返回网页 | 确认最终请求为 POST /ai/generate-image，避免重复拼接路径。 |
| 超时 / 网络中断 | 先到网站生成记录确认结果，再决定是否重新提交。 |

---

# 角色、参考与精细控制

主提示词描述整体画面，角色提示词分别控制人物。

## 独立角色提示词

```json
{
  "prompt": "watercolor, a quiet garden, afternoon light",
  "auto_character_positions": true,
  "characters": [
    {
      "prompt": "adult painter, blue coat, holding a sketchbook",
      "negative_prompt": "blurry"
    },
    {
      "prompt": "adult gardener, straw hat, holding flowers",
      "negative_prompt": ""
    }
  ]
}
```

示例使用自动角色位置。V4.5 最多 6 个角色，V5 最多 32 个；角色描述与全局画风分开填写。

## 上传图片

```bash
curl --fail-with-body https://noveadream.com/v1/nai/assets \
  -H "Authorization: Bearer $NOVEA_API_KEY" \
  -F "file=@reference.png"
```

后续请求使用返回的 data.id，素材属于上传账号。原图、遮罩与参考图应分别保存对应的资产 ID。

## 绘图参数

| 字段 | 取值 |
| --- | --- |
| steps | 1–50 |
| count | 1–4 |
| seed | 0–4294967295 |
| guidance | 0–10 |
| source_strength | (0, 1] |
| source_noise | 0–1 |

精确参考与 Vibe 不在同一请求内混用。各版本支持的参考方式、透明背景和增强能力不同，提交前查询 capabilities。

---

# 流式预览与恢复

接收生成预览；断线后继续查询同一个任务。

## 开始流式生成

```bash
curl -N https://noveadream.com/v1/nai/generations/stream \
  -H "Authorization: Bearer $NOVEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json
```

request.json 使用报价后的完整生成参数，包括 quote_id 与 client_request_id。此端点使用 SSE；处理 preview、queued、done、error 和 keepalive 事件。

## 恢复已有任务

```bash
curl -N https://noveadream.com/v1/nai/generations/456/events \
  -H "Authorization: Bearer $NOVEA_API_KEY"
```

```bash
curl --fail-with-body 'https://noveadream.com/v1/nai/generations/456' \
  -H "Authorization: Bearer $NOVEA_API_KEY"
```

将 456 替换为任务 ID。断开连接后仍可用同一 ID 查询结果。

---

# 对话与文本

使用站内 API Key 接入文本模型。

## 模型与协议

| 模型 | 接口 |
| --- | --- |
| gpt-6-sol / gpt-6-astra / gpt-5.6-sol | /v1/responses; /v1/chat/completions; /v1/responses/compact |
| deepseek-v4.1-flash | /v1/chat/completions |

## 对话示例

```bash
curl --fail-with-body 'https://noveadream.com/v1/chat/completions' \
  -H "Authorization: Bearer $NOVEA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "gpt-6-sol",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "stream": false
}'
```

## 读取回复

非流式回复读取 choices[0].message.content；开启 stream 后按 SSE 处理增量。具体参数需按所选模型与接口协议填写。

---

# 鉴权与访问权限

文档公开阅读。实际 API 调用使用你自己的站内密钥。

## Bearer 鉴权

```http
Authorization: Bearer YOUR_API_KEY
```

在自己的服务端保管 Key。不要将其写进公开网页、示例截图、仓库或日志。API Key 管理、钱包与个人任务仍需登录。

## 模型权限

```bash
curl --fail-with-body 'https://noveadream.com/v1/models' \
  -H "Authorization: Bearer $NOVEA_API_KEY"
```

目录介绍的是平台提供的能力，实际调用还要通过 Key 的模型限制、账户权限、余额和会员条件。文档公开不会改变这些检查。

## 正确使用接口地址

| 类型 | 路径 |
| --- | --- |
| Images | /v1/images/generations |
| Video | /v1/videos |
| NovelAI | /v1/nai/estimate → /v1/nai/generations |

API 以本站返回字段为准。不同服务商即便模型同名，也可能使用不同协议，不能直接替换域名后假定完全兼容。

---

# 计费与结果保存

先确认适用费用，再发起请求。妥善处理重试与生成结果。

## 费用以什么为准

不同模型按图片规格、时长、Token 或点数计费。账号适用价格查看模型目录；NAI 每次使用 estimate 返回的报价确认付款方式、费用与权益扣减。所有费用实际以 USD 结算。

[查看模型计费](https://noveadream.com/developers/zh/pricing/)

## NAI 费用与会员

基础费不一定等于最终费用。尺寸、步数、参考素材和会员权益都会影响最终报价。网页端 V5 仍需会员；API 非会员可以使用钱包付费。

## 避免重复生成

图片和视频重试复用 Idempotency-Key；NAI 重试复用 client_request_id。保存任务 ID，再恢复查询。超时或断线不能直接视为失败退款。

## 及时保存结果

生成成功后下载到自己的存储。不要把临时链接当作永久地址，也不要在下载第三方链接时附带本站 Authorization。

---

# 错误与重试

先判断请求是否已经提交，再决定修正参数、等待或重试。

## 常见情况

| 情况 | 建议处理 |
| --- | --- |
| 401 | 检查 Key 是否填写正确、有效且未过期。 |
| 403 / model_not_found | 检查模型权限和会员条件，不要反复生成。 |
| 429 | 按服务端提示退避，降低并发。 |
| generation_pending | 任务仍可能执行，保留原幂等键。 |
| 报价失效 | 重新报价，使用新 quote_id 提交。 |
| 流式连接中断 | 按任务 ID 查询或重新连接事件流。 |

## 保留诊断信息

记录请求时间、接口、HTTP 状态、错误代码和任务 ID，提交问题时先去掉 API Key 与私人素材。不要只记录「生成失败」。

---

# 让 AI 帮你接入

给编程助手可直接读取的文档与请求示例。

## 可下载的文档

https://noveadream.com/developers/zh/llms.txt
https://noveadream.com/developers/zh/llms-full.txt
https://noveadream.com/developers/zh/examples.json

HTML、Markdown 与全文索引由同一份内容生成。接口字段仅描述本文档覆盖的功能；账号权限仍以实际 API 返回为准。

## 复制给编程助手

```text
Read https://noveadream.com/developers/en/llms-full.txt first.
Use https://noveadream.com and my site API key from an environment variable.
Images: POST /v1/images/generations.
Video: POST /v1/videos, then GET /v1/videos/{id}.
NAI: POST /ai/generate-image with input, model, action, parameters. No quote required. Accept: application/json returns Base64 images.
Save task IDs. Reuse the original idempotency key on network retries.
Do not log credentials or invent unsupported endpoints.
```