# HamuBox API

Base URL: https://api.hamubox.com
NovelAI native client Base URL: https://api.hamubox.com/v1/novelai (append the official /ai/... or /user/... path).
Scope: the documented default-group image models, Seedance EP / Doubao, Wan 3 EP, Midjourney / Niji image and video tasks, and NovelAI asynchronous/native image endpoints. NovelAI login, stories, text and voice endpoints are outside this API.

Source: https://api.hamubox.com/docs/authentication/

# 鉴权与模型可用性

## 请求头

```http
Authorization: Bearer sk-your-api-key
Content-Type: application/json
```

使用本站 API Key，不是网站登录密码、Cookie 或模型供应商的 Key。查询任务同样需要鉴权，推荐始终使用提交时的 Key。

## 分组怎么选择

分组在创建 API Key 时选择。通常不需要在 JSON 请求体添加 `group`。更换分组时使用该分组的 Key。

分组决定可用模型和适用价格。本站内部的模型路由与账户调度不属于客户端请求参数，客户端只需传文档中的公开模型 ID。

同名模型不等于所有分组都拥有完全相同的能力。例如，本版 `nano-banana-pro` 章节描述 `default` 分组的 1K / 2K 规格，不能据此推断其他分组也相同。

## 查询模型清单

```bash
curl 'https://api.hamubox.com/v1/models' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"
```

响应是包含 `data` 数组的对象，模型名称位于 `data[].id`。清单会随 Key 的权限、可用线路与模型上下架变化。

这不是完整的模型参数 Schema。不要从名称猜测参考素材数量、分辨率和费用；使用对应的模型章节。也不要依赖 `owned_by` 等描述性字段做业务路由。

## 常见鉴权问题

| 现象 | 检查方向 |
| --- | --- |
| HTTP 401 | Key 是否完整、有效、过期；是否误填登录令牌 |
| 模型不在清单 | Key 分组、模型权限、模型是否已下架 |
| HTTP 403 | 当前操作或模型访问权限 |
| HTTP 429 | 降低请求频率；检查模型与账户限流 |
| 查询返回 404 | 任务 ID、图片 / 视频查询路径、访问账户是否一致 |

Key 失效时应暂停轮询并让操作者处理鉴权问题，不要自动退出整个网站或不断重试鉴权失败请求。


---

Source: https://api.hamubox.com/docs/billing/

# 计费与结算

## 各模型怎么收费

| 模型 | 计费方式 | 影响金额的主要输入 |
| --- | --- | --- |
| Seedance EP / Doubao | 视频 token | 分辨率、比例、输出时长、是否及多少参考视频 |
| Wan 3 EP | 按秒 | 分辨率档位 ×（输出秒数 + 参考视频秒数） |
| Seedream 5 Pro EP | 按次，附参数倍率 | 1K / 2K、超过第一张的参考图数量 |
| GPT Image 2（default） | 按次 | 当前 Key 适用的模型单价 |
| Nano Banana 2 / Pro（default） | 按次 | 当前 Key 适用的模型单价 |

同系列名称、相同请求路径不意味着计费单位相同。不要把「每百万视频 token」当作「每秒」，也不要将视频 token 等同于文本提示词 token。

## 价格从哪里获取

查看[模型广场](https://api.hamubox.com/pricing)中的目标模型与分组。本文列出的基础价用于说明算法，活动价和可用模型可能调整；生产客户端不要把静态文档价格当成唯一账单依据。

用户只需理解所用 Key 的适用价格，不需要配置或传递本站内部路由、成本和倍率规则。

## 预扣与最终费用

提交任务时先检查余额并预扣。某些模型按估算预扣，执行完毕后按照实际用量多退少补；固定按次模型通常预扣额与最终额相同。

Seedance 视频 token 预估还会考虑输入视频时长与预扣缓冲，不能简单以输出秒数推算退款。失败后按任务结算规则退款，客户端不应自行增加或减少账户余额。

## 响应字段

| `usage` 字段 | 含义 |
| --- | --- |
| `estimated_cost_usd` | 预估 / 预扣金额，不是最终账单 |
| `actual_cost_usd` | 结算后的实际美元金额 |
| `billing_mode` | 计费模式，如 `per_request`、`per_second`、`seedance_video_token` |
| `price_unit` | 对应计价单位 |
| `completion_tokens` / `total_tokens` | 对支持 token 用量回报的任务，返回实际用量 |
| `billing_detail` | 补充费用明细；可选，字段随模型变化 |
| `quota` | 平台内部额度单位，不是美元；应用应优先显示美元字段 |

一些字段只在有值时返回，零费用也可能省略 `actual_cost_usd`，不能把字段缺失直接认定为免费。

```json
{
  "usage": {
    "quota": 8000,
    "estimated_cost_usd": 0.016,
    "actual_cost_usd": 0.016,
    "billing_mode": "per_request",
    "price_unit": "request"
  }
}
```

## 避免重复计费

- POST 仅提交一次；拿到 ID 后只做 GET 查询。
- 客户端断网、页面刷新或等待超时，不表示服务端任务取消。
- 一个任务失败后重新生成是新任务，先让用户确认是否重试。
- 需要对账时保留任务 ID、模型、创建时间、终态和 `usage`，不要保存完整 Key。


---

Source: https://api.hamubox.com/docs/errors/

# 错误处理

## 两层错误

**请求层错误**：HTTP 非 2xx，可能在提交前发生。响应可能使用 `error.code` / `error.message`，也可能是兼容格式的顶层 `code` / `message`。不要只支持一种错误外壳。

**任务层错误**：查询请求 HTTP 200，但 `status: "failed"`，错误位于 `error`。这是终态，停止查询，不要因 HTTP 200 而把它当作生成成功。

## 常见情况

| 情况 | 建议处理 |
| --- | --- |
| 400 / 422，参数或素材被拒绝 | 检查 `error.message`、模式、尺寸、格式、时长；修改后再提交 |
| 400，`model_endpoint_not_supported` | 当前模型不支持所用接口；按报错给出的端点和文档修改路径及请求体，不要原样重试。NAI、工作流模型不能直接使用聊天 `messages` 格式；支持聊天生图的线路不受此限制 |
| 401 / 403 | 处理 Key 或权限，停止高频查询 |
| 404，任务不可查询 | 检查任务 ID、媒体类型路径和账户权限 |
| 429 | 降低频率，按 `Retry-After` 等待；不循环重发生成 |
| 查询出现网络错误、502 / 504 | 可以有限退避重试同一个 GET |
| POST 网络超时 | 结果未知，可能已创建任务；先查任务记录，避免重复提交 |
| `status: failed` | 展示任务错误并停止轮询；如需重试，创建新任务 |
| 成功但链接打不开 | 完整保留签名参数，检查时效、跨域与下载网络；及时保存结果 |

供应商错误码未必与用户请求 HTTP 状态一一对应。状态码写在错误文案里时，不要仅凭字符串数字判定是否继续轮询，以公开任务 `status` 为准。

## 容易混淆的参数

- Seedance 首尾帧输出比例跟随输入帧，优先使用 `adaptive`，不要强制指定不匹配比例。
- Seedance 2.5 单视频编辑需要 `duration: -1` 和 `adaptive`，普通参考生成不需要。
- Wan 3 EP 有「输入视频 + 输出 ≤ 30 秒」限制，不能只检查输出。
- 参考音频不是「生成音频」开关，而且不能单独代替图像 / 视频参考。
- 香蕉 default 暂不支持 4K；GPT 的 `quality`、`moderation` 不能直接照搬给香蕉。
- 自定义尺寸传 `resolution: custom` 与 `size`，不要再传另一个冲突比例。
- 大段 Base64、`blob:` 和网页分享链接容易造成上传或下载失败，优先使用直接可访问的 HTTPS 文件。

## 向支持人员提供什么

提供任务 ID、请求时间、模型、所用分组、HTTP 状态、错误码与消息，以及去掉密钥和大段编码后的请求 JSON。不要公开 Key、Authorization、私有图片或含敏感凭证的链接。

本文错误文案仅为说明，不构成固定枚举。需要稳定处理时优先使用 HTTP 状态与 `status` / `error.code`，保留未知错误兜底展示。


---

Source: https://api.hamubox.com/docs/examples/

# 调用示例

## 可下载的请求 JSON

把示例中的 `https://example.com/...` 换成自己的可访问素材 URL。

| 任务 | JSON |
| --- | --- |
| Seedance 文生视频 | [seedance-text.json](https://api.hamubox.com/docs/examples/seedance-text.json) |
| Seedance 首尾帧 | [seedance-frames.json](https://api.hamubox.com/docs/examples/seedance-frames.json) |
| Seedance 仅尾帧 | [seedance-tail.json](https://api.hamubox.com/docs/examples/seedance-tail.json) |
| Seedance 全能参考 | [seedance-reference.json](https://api.hamubox.com/docs/examples/seedance-reference.json) |
| Seedance 2.5 视频编辑 | [seedance-edit.json](https://api.hamubox.com/docs/examples/seedance-edit.json) |
| Wan 3 文生视频 | [wan-text.json](https://api.hamubox.com/docs/examples/wan-text.json) |
| Wan 3 首尾帧 | [wan-frames.json](https://api.hamubox.com/docs/examples/wan-frames.json) |
| Wan 3 参考生成 | [wan-reference.json](https://api.hamubox.com/docs/examples/wan-reference.json) |
| Seedream 生成 / 编辑 | [生成](https://api.hamubox.com/docs/examples/seedream-generate.json) · [编辑](https://api.hamubox.com/docs/examples/seedream-edit.json) |
| GPT Image 2 生成 / 编辑 / 自定义 | [生成](https://api.hamubox.com/docs/examples/gpt-generate.json) · [编辑](https://api.hamubox.com/docs/examples/gpt-edit.json) · [自定义](https://api.hamubox.com/docs/examples/gpt-custom.json) |
| Nano Banana 生成 / 编辑 / 自定义 | [生成](https://api.hamubox.com/docs/examples/banana-generate.json) · [编辑](https://api.hamubox.com/docs/examples/banana-edit.json) · [自定义](https://api.hamubox.com/docs/examples/banana-custom.json) |
| MJ 生成 / 风格与角色参考 / 编辑 | [生成](https://api.hamubox.com/docs/examples/midjourney-image-generate.json) · [参考](https://api.hamubox.com/docs/examples/midjourney-image-reference.json) · [编辑](https://api.hamubox.com/docs/examples/midjourney-image-edit.json) |
| MJ 变体 / 放大 / 图转提示词 | [变体](https://api.hamubox.com/docs/examples/midjourney-image-variation.json) · [放大](https://api.hamubox.com/docs/examples/midjourney-image-upscale.json) · [图转提示词](https://api.hamubox.com/docs/examples/midjourney-image-describe.json) |
| MJ 视频生成 / 延长 | [生成](https://api.hamubox.com/docs/examples/midjourney-video-generate.json) · [延长](https://api.hamubox.com/docs/examples/midjourney-video-extend.json) |
| NovelAI 异步文生图 / 图生图 / 局部重绘 | [文生图](https://api.hamubox.com/docs/examples/novelai-generate.json) · [图生图](https://api.hamubox.com/docs/examples/novelai-img2img.json) · [局部重绘](https://api.hamubox.com/docs/examples/novelai-inpaint.json) |
| NovelAI 异步 Director / 放大 / 氛围编码 | [Director](https://api.hamubox.com/docs/examples/novelai-director.json) · [放大](https://api.hamubox.com/docs/examples/novelai-upscale.json) · [氛围编码](https://api.hamubox.com/docs/examples/novelai-vibe.json) |
| NovelAI 原生文生图 / 图生图 / 局部重绘 | [文生图](https://api.hamubox.com/docs/examples/novelai-native-generate.json) · [图生图](https://api.hamubox.com/docs/examples/novelai-native-img2img.json) · [局部重绘](https://api.hamubox.com/docs/examples/novelai-native-inpaint.json) |
| NovelAI 原生 Director / 放大 / 氛围编码 | [Director](https://api.hamubox.com/docs/examples/novelai-native-director.json) · [放大](https://api.hamubox.com/docs/examples/novelai-native-upscale.json) · [氛围编码](https://api.hamubox.com/docs/examples/novelai-native-vibe.json) |
| NovelAI 原生流式 | [请求 JSON](https://api.hamubox.com/docs/examples/novelai-native-stream.json) · [MessagePack 客户端](https://api.hamubox.com/docs/examples/novelai-stream.py) |

## 用 curl 提交文件

```bash
curl --fail-with-body 'https://api.hamubox.com/v1/video/generations' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @seedance-text.json
```

图片换成 `/v1/image/generations` 与对应 JSON 文件。Windows PowerShell 请使用 `curl.exe`，避免旧版 PowerShell 的同名别名。

NovelAI [异步任务](https://api.hamubox.com/docs/novelai/tasks/)使用 `/v1/novelai/tasks`；[原生接口](https://api.hamubox.com/docs/novelai/native/)按操作选择 `/v1/novelai/ai/...` 路径，原生流式还需要专用解析器。两套示例的外层格式不同，不能互换。

## Python 完整客户端

[下载 client.py](https://api.hamubox.com/docs/examples/client.py)。Python 3.10+，仅使用标准库，支持提交、查询、GET 退避与任务恢复，不会自动重发 POST。

```bash
export HAMUBOX_API_KEY='sk-your-api-key'
python client.py image banana-generate.json
python client.py video seedance-text.json
python client.py novelai novelai-generate.json
python client.py image midjourney-image-generate.json
python client.py video midjourney-video-generate.json
```

程序提交成功后立即输出任务 ID，并保存不含 Key 的 `task_….json`。等待超时或下次运行时：

```bash
python client.py video --task-id task_your_existing_id --max-wait 1800
```

`--max-wait` 是客户端本次最长等待秒数，不改变服务器任务状态。把示例集成到业务时，建议用数据库保存任务 ID、媒体类型和终态，而不是仅依赖本地文件。

## 下载结果

成功后，视频优先遍历 `outputs[].url`，没有时兼容 `metadata.url`；图片遍历 `outputs[].url`。MJ 图转提示词读取 `descriptions[]`，无需下载图片。NovelAI 取 `result.images[].url`（氛围编码取 `result.encoded_vibe`）。下载不要携带本站 Authorization：

```bash
curl --fail --location --output result.mp4 '替换为完整视频结果URL'
```

签名 URL 必须保留查询参数。客户端展示时使用真实媒体尺寸，避免把所有结果硬编码为正方形或 16:9。


---

Source: https://api.hamubox.com/docs/image/

# 异步图片接口

## 提交

```http
POST /v1/image/generations
Authorization: Bearer sk-your-api-key
Content-Type: application/json
```

路径为单数 `image`。无论有没有参考图，都调用同一个异步端点。

本页通用参数表针对 Seedream、GPT Image 2 和 Nano Banana。Midjourney / Niji 复用同一接口，但使用独立参数契约，见 [Midjourney 章节](https://api.hamubox.com/docs/models/midjourney/)。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string，必填 | 公开模型 ID |
| `prompt` | string，必填 | 非空提示词或图片编辑指令 |
| `images` | string[] | 可选参考图；非空时自动进入编辑 |
| `image_urls` | string[] | `images` 的兼容别名；两者不要同时使用 |
| `aspect_ratio` | string | 比例，枚举或格式依模型而定 |
| `resolution` | string | 分辨率档位，依模型而定 |
| `size` | string | 仅支持自定义尺寸的模型使用，如 `1536x1024` |
| `output_format` | string | 输出格式，依模型而定 |

Seedream、GPT Image 2 和 Nano Banana 每个任务生成一张。GPT Image 2 和 Nano Banana 的 `n` 必须为 `1`；Seedream 不提供批量 `n` 参数。MJ 的 `n=1` 表示一组任务，可能返回多张，必须遍历 `outputs`。

## 参数不要跨模型照搬

| 模型 | 参考图上限 | 分辨率 | 自定义尺寸 | 专属选项 |
| --- | ---: | --- | --- | --- |
| Seedream 5 Pro EP | 10 | 1K / 2K | 不支持 | 无 `quality` / `moderation` |
| GPT Image 2（default） | 16 | auto / 1K / 2K / 4K | 支持 | `quality`、`moderation` |
| Nano Banana 2 / Pro（default） | 14 | 1K / 2K | 支持 | 不使用 GPT 的质量枚举 |

带参考图不需要为模型 ID 添加 `-edit` 后缀。没有参考图是文生图，有参考图是编辑。

```json title="seedream-generate.json"
{
  "model": "dola-seedream-5-0-pro-ep",
  "prompt": "A quiet futuristic city after rain, cinematic lighting, no text.",
  "aspect_ratio": "16:9",
  "resolution": "2k",
  "output_format": "png"
}
```

## 查询

```http
GET /v1/image/generations/{task_id}
Authorization: Bearer sk-your-api-key
```

响应为 `image.generation.task`，状态与视频相同。成功结果位于 `outputs[].url`，不返回同步图片接口的 `data[].b64_json`。

`operation: "generate"` 或 `"edit"` 反映实际操作。不要在任务尚未 `completed` 时仅根据输出字段存在就停止查询。

## 模型章节

- [Seedream 5 Pro](https://api.hamubox.com/docs/models/seedream/)
- [GPT Image 2](https://api.hamubox.com/docs/models/gpt-image-2/)
- [Nano Banana 2 / Pro](https://api.hamubox.com/docs/models/banana/)
- [Midjourney / Niji](https://api.hamubox.com/docs/models/midjourney/)：多结果、风格参考、变体、放大和图转提示词。


---

Source: https://api.hamubox.com/docs/

# 图片与视频 API

使用一个 API Key，通过「提交任务 → 查询状态 → 下载结果」接入图片和视频生成。无需为文生图、图片编辑、首尾帧或参考生成切换 API 地址。

**服务地址：`https://api.hamubox.com`**

## 从哪里开始

使用网页创作、学习参考素材或专业模型，请进入[创作学堂](/learn/)。本页以下内容面向 API 接入。

| 目标 | 文档 |
| --- | --- |
| 发起第一个任务 | [快速开始](https://api.hamubox.com/docs/quickstart/) |
| 生成视频、首尾帧、图片 / 视频 / 音频参考 | [视频接口](https://api.hamubox.com/docs/video/) |
| 生成图片、使用参考图编辑 | [图片接口](https://api.hamubox.com/docs/image/) |
| NovelAI 专业绘图与生成过程 | [NovelAI 接入概览](https://api.hamubox.com/docs/novelai/overview/) · [客户端接入](https://api.hamubox.com/docs/novelai/clients/) · [流式协议](https://api.hamubox.com/docs/novelai/streaming/) |
| Midjourney / Niji 生图、多结果与后续操作 | [MJ 快速开始](https://api.hamubox.com/docs/midjourney/quickstart/) · [参数参考](https://api.hamubox.com/docs/models/midjourney/) · [常见问题](https://api.hamubox.com/docs/midjourney/faq/) |
| 交给 AI 编程助手接入 | [LLM 接入资料](https://api.hamubox.com/docs/llm/) |
| 查询费用与错误 | [计费与结算](https://api.hamubox.com/docs/billing/) · [错误处理](https://api.hamubox.com/docs/errors/) |

## 本版覆盖模型

| 系列 | 公开模型 ID | 接入说明 |
| --- | --- | --- |
| Seedance 2.0 / Fast / Mini / 2.5 | `dreamina-seedance-…-ep`、`doubao-seedance-…` | [Seedance](https://api.hamubox.com/docs/models/seedance/) |
| Wan 3 | `wan3.0-video-ep` | [Wan 3](https://api.hamubox.com/docs/models/wan3/) |
| Seedream 5 Pro | `dola-seedream-5-0-pro-ep` | [Seedream](https://api.hamubox.com/docs/models/seedream/) |
| GPT Image 2 | `gpt-image-2` | [GPT Image 2](https://api.hamubox.com/docs/models/gpt-image-2/) |
| Nano Banana 2 / Pro | `nano-banana-2`、`nano-banana-pro` | [Nano Banana](https://api.hamubox.com/docs/models/banana/) |
| Midjourney / Niji / MJ 视频 | `midjourney-v…`、`niji-v…`、`midjourney-video` | [生成、变体、放大与视频延长](https://api.hamubox.com/docs/models/midjourney/) |
| NovelAI V5 / V4.5 / V4 / V3 | `nai-diffusion-…` | [模型与绘图参数](https://api.hamubox.com/docs/novelai/models/) |

图片模型章节以 `default` 分组的接口能力为准。同名模型在其他分组的参数可能不同，请不要混用其他服务的请求示例。使用当前 Key 调用 `GET /v1/models` 确认模型可用；价格见[模型广场](https://api.hamubox.com/pricing)。

NovelAI 使用独立的 `/v1/novelai/tasks` 和流式入口，不通过下面的通用图片接口提交。

## 四个核心接口

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/v1/video/generations` | 创建视频任务 |
| GET | `/v1/video/generations/{task_id}` | 查询视频状态、错误和结果 |
| POST | `/v1/image/generations` | 创建图片任务，包括图片编辑 |
| GET | `/v1/image/generations/{task_id}` | 查询图片状态、错误和结果 |

:::note[注意路径]
异步图片接口中的 `image` 是单数。不要替换为同步接口 `/v1/images/generations`，也不要把查询视频的路径用于图片任务。
:::

## 可下载资料

- [OpenAPI JSON](https://api.hamubox.com/docs/openapi.json)：包含本版公开的异步接口与 NovelAI 流式入口，不包含后台管理接口。
- [llms.txt](https://api.hamubox.com/docs/llms.txt)：章节索引。
- [llms-full.txt](https://api.hamubox.com/docs/llms-full.txt)：完整纯文本 Markdown 文档，可直接提供给 LLM。
- [调用示例](https://api.hamubox.com/docs/examples/)：Python 完整提交与轮询，以及 curl 请求。

本文档不涉及 BYOK 与 RunningHub 工作流接入；这些能力后续单独补充。


---

Source: https://api.hamubox.com/docs/llm/

# LLM 接入资料

## 直接提供这些地址

- [章节索引 llms.txt](https://api.hamubox.com/docs/llms.txt)
- [完整文档 llms-full.txt](https://api.hamubox.com/docs/llms-full.txt)
- [公开 OpenAPI JSON](https://api.hamubox.com/docs/openapi.json)
- [请求示例 JSON](https://api.hamubox.com/docs/examples/)

每个章节还有原始 Markdown，路径为 `/docs/markdown/{章节}.md`，例如 [Seedance Markdown](https://api.hamubox.com/docs/markdown/models/seedance.md)。这些文件由当前文档源自动导出，不是另一套手动维护内容。

NovelAI 有独立目录。按接入方式提供[概览](https://api.hamubox.com/docs/markdown/novelai/overview.md)、[通用参数](https://api.hamubox.com/docs/markdown/novelai/models.md)、[原生协议](https://api.hamubox.com/docs/markdown/novelai/native.md)、[异步任务](https://api.hamubox.com/docs/markdown/novelai/tasks.md)、[流式与恢复](https://api.hamubox.com/docs/markdown/novelai/streaming.md)及[客户端配置](https://api.hamubox.com/docs/markdown/novelai/clients.md)。同一操作只选择一种提交方式，不同时调用原生和异步端点。

Midjourney / Niji 按需求读取[快速开始](https://api.hamubox.com/docs/markdown/midjourney/quickstart.md)、[完整参数](https://api.hamubox.com/docs/markdown/models/midjourney.md)、[参考图与风格](https://api.hamubox.com/docs/markdown/midjourney/references.md)、[变体与放大](https://api.hamubox.com/docs/markdown/midjourney/actions.md)、[视频](https://api.hamubox.com/docs/markdown/midjourney/video.md)与[常见问题](https://api.hamubox.com/docs/markdown/midjourney/faq.md)。字段约束集中在完整参数页，其它章节解释使用流程，不是另一套接口。公开参数契约不等于所有操作都已配置可用价格。

## 给编程助手的要求

```text
请接入 HamuBox 的异步图片 / 视频 API。
先阅读 https://api.hamubox.com/docs/llms-full.txt
再对照 https://api.hamubox.com/docs/openapi.json

Base URL: https://api.hamubox.com
使用用户配置的本站 API Key，放在 Authorization: Bearer 中。
视频 POST /v1/video/generations，GET /v1/video/generations/{task_id}。
图片 POST /v1/image/generations，GET /v1/image/generations/{task_id}。
NovelAI 单独 POST /v1/novelai/tasks（202），GET /v1/novelai/tasks/{task_id}。
提交后立即保存 id 和媒体类型，每隔 5 秒查询。
completed / failed 表示生成结束，HTTP 200 不代表任务成功。
视频和图片都遍历 outputs[].url；视频 metadata.url 只是第一条兼容结果，不代表全部输出。
Midjourney 图片 n:1 表示一组，视频 n 表示条数。不要把全部图片结果重新逐张乘价。
Midjourney describe 读取 descriptions[]，允许没有图片输出的成功任务。
MJ 后续操作仅使用响应 actions 中的 operation、output_index 和本站 parent_task_id，不能用上游 ID 或界面排序后的下标。
MJ 如返回保存状态，图片读取 result_transfer_status，视频读取 metadata.result_transfer_status。
需要本站转存 URL 时可继续查询至 stored；设置等待期限，保存 failed 不等于生成 failed，也不能因此再次 POST。
NovelAI 图片读取 result.images[].url，氛围编码读取 result.encoded_vibe。
NovelAI 原生流式 /v1/novelai/ai/generate-image-stream 是长度帧 MessagePack，不是 SSE 或 ZIP。
已有官方协议客户端将 Base URL 设为 https://api.hamubox.com/v1/novelai，再追加 /ai/generate-image、/ai/augment-image、/ai/upscale（ZIP），以及 /ai/encode-vibe（二进制）。
拼接原生路径时必须保留 /v1/novelai 前缀；账户查询同样为 /v1/novelai/user/data 等，返回本站虚拟显示单位，不是上游真实余额。
需要 SSE 时，提交 NovelAI 任务 stream:true 后 GET /v1/novelai/tasks/{task_id}/events。
流式 image/final 事件可先于存储和结算送达，完成状态仍以任务查询为准。
刷新页面后按已保存的 ID 恢复查询，不重复 POST。
除对应章节明确说明外，不要自行假定支持 webhook、取消、批量端点或 Idempotency-Key。
参数以对应分组的公开模型章节为准，不照搬供应商 SDK 的字段。
Key 不写入源码和日志，下载第三方结果时不携带本站 Authorization。
```

## 范围与边界

本版 OpenAPI 覆盖常用公开模型的异步图片、视频、NovelAI 任务和原生绘图接口，以及模型清单。NovelAI 登录、支付、故事、文本与语音不在兼容范围内。BYOK、工作流、后台管理、账户调度、内部成本及模型级价格覆盖均不属于本次公开接入合同。

OpenAPI 用于字段结构与示例，跨字段的媒体约束仍需结合模型章节。例如参考视频真实时长、图像透明通道、任务意图等不能仅凭 JSON Schema 完成校验。


---

Source: https://api.hamubox.com/docs/midjourney/actions/

# Midjourney API 变体与放大

Midjourney 的变体、放大和扩图是基于原任务的新操作。不要复制图片界面的按钮名称或上游 `customId`；以本站任务响应的 `actions` 为准。

## 从结果选择操作

1. 查询已完成的图片任务，遍历 `outputs` 展示所有图片。
2. 找到对应图片可用的 `actions`，保留其中的 `operation` 和 `output_index`。
3. 将它们与本站 `parent_task_id`、原图片 `model` 一起估价，再提交到 `/v1/image/generations`。
4. 保存新的任务 ID，查询新结果。原任务不会被替换。

```json title="midjourney-image-variation.json"
{
  "model": "midjourney-v7",
  "operation": "variation",
  "parent_task_id": "task_example",
  "output_index": 0
}
```

`output_index` 从 0 开始；它不是筛选、排序后的界面下标。`output_1` 对应原始下标 0。父任务必须属于当前用户且已经完成，不能填写上游任务 ID 或其他用户的任务。

## 变体、放大与提取的区别

| 操作 | 意义 |
| --- | --- |
| `variation` / `vary_subtle` / `vary_strong` | 创建变体或不同程度的重绘 |
| `upscale_subtle` / `upscale_creative` | 提交保守或创意放大任务 |
| `zoom_1_5` / `zoom_2` / `pan_*` | 向外或向指定方向扩展画面 |
| `select` | 获取已有单图，不是重新生成或高清放大 |
| `reroll` | 使用原设置重新生成 |

不是每个模型、阶段或图片都提供上述操作。有单张结果 URL 时不必再次调用 `select`。需要放大时，先确认实际返回了对应放大动作。

```json title="midjourney-image-upscale.json"
{
  "model": "midjourney-v7",
  "operation": "upscale_subtle",
  "parent_task_id": "task_selected_image",
  "output_index": 0,
  "speed": "fast"
}
```

普通后续操作继承原提示词、种子及参考设置，不应重新发送 `images`、`seed`、`stylize` 等生成参数。`custom_zoom` 和 `region` 的例外字段与限制见[完整操作契约](https://api.hamubox.com/docs/models/midjourney/#多结果与后续操作)；列出契约不代表完整编辑器已经开放。

## 图片转提示词

`operation: "describe"` 接收一张图片，成功后读取 `descriptions[]`。它输出多个候选文字描述，不是生成四张图片，也不保证候选数永远为四。

从中选择一个描述生成图片，需要另外发起 `generate` 并独立计费。客户端应支持 `completed` 且没有 `outputs` 的图转提示词任务。

## 费用与重试

变体、放大和扩图分别估价、提交，不应视作原任务的免费重试。对每个操作发送相同参数到 `/v1/image/generations/estimate`，不要用普通生图基础价代替操作报价。

提交超时后先核对已有任务；拿到任务 ID 后只查询该任务，不通过再次 POST 修复超时或下载失败。具体错误处理见[常见问题](https://api.hamubox.com/docs/midjourney/faq/)。


---

Source: https://api.hamubox.com/docs/midjourney/faq/

# Midjourney 与 Niji API 常见问题

## 需要自己购买 Midjourney 订阅吗

不需要。通过本站公开接口使用 HamuBox API Key，按本站任务价格计费，不填写 Discord Token 或 MJ 官网 Cookie。本站提供第三方接入服务，不是 Midjourney 官方 API，也不等同于购买官网订阅。

## 为什么 n 为 1 却返回四张图

图片 `n: 1` 表示一组生成任务，而不是一张图片。通常会返回四张，但不同模式可能不同，应遍历 `outputs`，不能写死数量或重复按张数乘价。视频的 `n` 则表示输出条数。详见[费用说明](https://api.hamubox.com/docs/models/midjourney/#估价扣费与失败处理)。

## Fast 和 Relax 怎么收费

速度、模型和生成模式一起决定报价。Fast/Relax 是速度档位，Standard/Draft/HD 是生成模式；Draft 不等于 Relax，HD 也不是一个单独的速度。

将完整请求发到对应 `/estimate` 端点，读取美元金额 `estimated_cost_usd`，不把内部 `quota` 当成美元。本站不承诺自动将 Fast 切成 Relax；不要依靠自动降档控制费用。

## 可以使用 OpenAI 或旧版 MJ 客户端吗

本站 MJ 走统一异步 `/v1/image/generations` 和 `/v1/video/generations`，不使用聊天接口、同步 `/v1/images/generations` 或旧版 `/mj/submit/*`。客户端必须能适配提交、任务查询、多结果和后续动作，不能保证只改地址即可使用。

## 可以直接粘贴带参数的 MJ 提示词吗

图片提示词支持文档列出的原生尾随参数。其优先级高于对应 JSON 创作参数，但不会改变模型权限、批量和费用上限。视频仍使用结构化参数。不支持的参数会报错，不代表官网全部功能都能直接透传。支持列表与示例统一见[原生提示词格式](https://api.hamubox.com/docs/models/midjourney/#原生提示词格式)。

## 为什么有的图片没有变体或放大按钮

动作取决于模型、任务阶段与具体结果。客户端只展示 `actions` 返回的操作；后续请求使用其中的原始 `output_index`，不能按页面排序重新编号。`select` 仅提取已有单图，不会重新高清放大。详见[变体与放大](https://api.hamubox.com/docs/midjourney/actions/)。

## 图转提示词成功但没有图片正常吗

正常。`describe` 返回 `descriptions[]` 候选文字，不生成新图。客户端不要把没有 `outputs` 的描述任务直接判为失败；用某条描述生图需要新建独立任务。

## 生成完成后为什么下载失败

生成完成与保存完成是两个阶段。结果可能先提供官方 CDN URL，随后转存为本站 URL；浏览器能打开 CDN 不代表服务器脚本一定能下载。

图片可选字段 `result_transfer_status`、视频可选字段 `metadata.result_transfer_status` 表示保存进度：`queued` 排队、`pending` 保存中、`stored` 已保存、`failed` 保存失败。需要本站地址时可在等待期限内继续查询至 `stored`。保存失败不等于生成失败，后台补偿也不保证最终成功；超出等待期限应保留已有结果并排查，不能无限轮询或自动重跑付费生成。

历史任务可能没有保存状态字段，仍按其返回结果处理。不要向第三方 CDN 发送本站 Authorization，也不要把第一次返回的 URL 当作永远不会变化的结果标识；使用稳定输出 ID。

## HTTP 409 是否表示生成失败

不一定。提交时如果估价超过 `max_cost_usd`，会拒绝并返回 409，需要重新确认价格，而不是自动提高费用上限。其它错误也应结合 `error.message` 判断；HTTP 200 只能说明查询成功，最终生成状态仍看 `status`。

## 模型可见是否代表所有官网功能都能用

不是。`/v1/models` 只表示当前 Key 的模型权限。操作还要满足版本能力、参考限制、父任务动作与实际报价。完整官网编辑器、平台情绪版管理等不能由模型可见性推断；未配置价格的操作不可提交。以[参数契约](https://api.hamubox.com/docs/models/midjourney/)及实际估价为准。

相关资料：[快速开始](https://api.hamubox.com/docs/midjourney/quickstart/) · [参考图与风格](https://api.hamubox.com/docs/midjourney/references/) · [视频 API](https://api.hamubox.com/docs/midjourney/video/) · [OpenAPI](https://api.hamubox.com/docs/openapi.json)。


---

Source: https://api.hamubox.com/docs/midjourney/quickstart/

# Midjourney API 快速开始

HamuBox 的 Midjourney API 和 Niji API 使用异步任务：先提交一次请求，保存任务 ID，再查询结果。使用本站 API Key，不需要提供自己的 Midjourney 订阅、Discord Token 或官网登录凭据。本站是第三方接入服务，不是 Midjourney 官方 API。

## 地址与鉴权

```text
Base URL: https://api.hamubox.com
Authorization: Bearer <本站 API Key>
```

先用 `GET /v1/models` 确认 Key 可用的 `midjourney-v…`、`niji-v…` 模型。模型列表不代表其全部操作已经开放；Fast/Relax、Standard/Draft/HD 等档位还需要单独估价。

图片提交使用单数的 `/v1/image/generations`，不是 `/v1/images/generations`、`/v1/chat/completions` 或旧版 `/mj/submit/imagine`。仅支持这些其它协议的客户端需要适配，不能只改 Base URL。

## 先估价，再提交一次

```json title="midjourney-image-generate.json"
{
  "model": "midjourney-v7",
  "prompt": "A quiet greenhouse at sunrise, soft watercolor illustration",
  "speed": "fast",
  "generation_mode": "standard",
  "aspect_ratio": "3:2",
  "stylize": 100,
  "seed": 0,
  "raw": false,
  "n": 1
}
```

下载[请求 JSON](https://api.hamubox.com/docs/examples/midjourney-image-generate.json)。使用同一个请求分别估价和提交：

```sh
curl --fail-with-body https://api.hamubox.com/v1/image/generations/estimate \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @midjourney-image-generate.json
```

估价返回 `estimated_cost_usd`，单位为美元。确认费用后，将 URL 改为 `/v1/image/generations` 提交一次。可在 JSON 中加入 `max_cost_usd` 限制接受的最高费用；估价本身不锁价。

图片的 `n: 1` 表示一组任务，不是只返回一张图。Fast/Relax 控制速度档位，Standard/Draft/HD 控制生成模式，两者不是同一个开关。模型差异与全部字段见[参数参考](https://api.hamubox.com/docs/models/midjourney/#基础参数)。

## 查询全部结果

保存提交返回的本站 `id`，之后每隔约 5 秒查询：

```sh
curl --fail-with-body https://api.hamubox.com/v1/image/generations/task_example \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"
```

- `queued` / `in_progress`：继续等待，不要重复提交。
- `completed`：生成完成，遍历 `outputs[].url`，不要只读取第一张或写死四张。
- `failed`：读取 `error.message` 与 `usage`，先判断原因，不自动重发付费请求。

结果可以包含稳定的 `outputs[].id` 和可用操作 `actions`。需要变体或放大时，使用返回的操作和下标创建下一项任务，见[后续操作](https://api.hamubox.com/docs/midjourney/actions/)。`describe` 的成功结果是 `descriptions[]`，可以没有图片输出。

若响应包含 `result_transfer_status`，它表示保存进度，与生成状态分开。需要本站转存地址时，可以在等待期限内继续查询至 `stored`；图片可能先返回官方 CDN 地址，随后更新为本站地址。不要因为下载受限或保存失败就重新生成。详细规则见[结果下载问题](https://api.hamubox.com/docs/midjourney/faq/#生成完成后为什么下载失败)。

## 按需求继续接入

| 需求 | 章节 |
| --- | --- |
| 普通参考图、风格码、角色参考 | [参考图与风格](https://api.hamubox.com/docs/midjourney/references/) |
| 变体、放大、扩图、图片转提示词 | [结果与后续操作](https://api.hamubox.com/docs/midjourney/actions/) |
| 图片生成视频、视频延长 | [视频 API](https://api.hamubox.com/docs/midjourney/video/) |
| 原生尾随参数、优先级和限制 | [原生提示词格式](https://api.hamubox.com/docs/models/midjourney/#原生提示词格式) |
| 费用、四张图、客户端兼容与报错 | [常见问题](https://api.hamubox.com/docs/midjourney/faq/) |

给 AI 编程助手提供[本页 Markdown](https://api.hamubox.com/docs/markdown/midjourney/quickstart.md)、[完整参数 Markdown](https://api.hamubox.com/docs/markdown/models/midjourney.md)与 [OpenAPI](https://api.hamubox.com/docs/openapi.json)。示例中的图片地址是占位地址，实际参考任务需要可访问的图片。


---

Source: https://api.hamubox.com/docs/midjourney/references/

# Midjourney API 参考图与风格码

Midjourney 的普通参考图、风格参考和角色参考用途不同，不应把所有图片都放到同一个字段。参考图只参与引导，不保证精确复制原图、构图或角色细节。

## 选择参考方式

| 目标 | 请求字段 | 需要注意 |
| --- | --- | --- |
| 参考图片内容、构图或整体感觉 | `images` | 生成时是图片参考，不会自动切换成编辑 |
| 参考画风、质感与配色 | `style_references` / `style_codes` | 图片 URL 与数字风格码不同；权重用 `style_weight` |
| 角色参考 | `character_references` | 仅 V6、V6.1、Niji V6，权重用 `character_weight` |
| Omni Reference | `omni_reference` | 仅 V7 Standard；还需当前服务已开放对应档位 |
| 使用公开个性化或情绪版代码 | `profile_codes` | 依赖代码分享权限与模型兼容性，不等同于数字风格码 |

各字段的数量、权重、版本与组合限制统一见[参考参数表](https://api.hamubox.com/docs/models/midjourney/#参考图风格与角色)。不要把 V6 的角色参考配置直接用于 V8 或 Niji V7。

## 提供图片与代码

图片字段填写上游可下载的 HTTP(S) URL，不使用浏览器 `blob:`、本地路径或图片 Base64。需要上传时，先调用[素材上传接口](https://api.hamubox.com/docs/references/#上传素材)，再把返回的 URL 放入参考字段。

结构化 `style_codes` 只填写数字风格码，不加 `--sref` 前缀；`profile_codes` 填写明确的公开代码，不加 `--p`。风格码不是模型 ID，也不是情绪版名称。

通过提示词尾部提供参数时，遵循[原生格式与优先级](https://api.hamubox.com/docs/models/midjourney/#原生提示词格式)。不要同时在多个位置放置不同的参考图或代码，除非明确希望尾随参数覆盖 JSON。

## 引用人物不等于直接编辑

`generate` 加参考图会创建新画面；“保持底图，只修改衣服”等编辑需求属于另一种操作。参数契约列出了 `edit` 等字段，但不能据此假定当前线路支持完整官网编辑器。只有对应模型、操作和价格都可用时才应提交。

V7 Standard 可以同时传 `omni_reference`、`omni_weight` 和 `profile_codes`。Fast / Relax 沿用对应的 Omni 报价；个性化不另加价。工作台选择“全能参考”后，可在“情绪版 / 个性化代码”中填写公开代码，画布使用同样的设置。

公开个性化代码同样不代表可以访问他人的私有情绪版。平台情绪版的创建和管理不属于本公共 API 的开放范围。组合能力不包括 Niji、Draft、HD，也暂不接受 `style_weight` 或 `style_version`。

继续阅读：[完整参数](https://api.hamubox.com/docs/models/midjourney/) · [估价与提交](https://api.hamubox.com/docs/midjourney/quickstart/) · [常见问题](https://api.hamubox.com/docs/midjourney/faq/)。


---

Source: https://api.hamubox.com/docs/midjourney/video/

# Midjourney 视频 API 接入

Midjourney 视频模型为 `midjourney-video`，使用 `/v1/video/generations` 创建任务，使用 `/v1/video/generations/{task_id}` 查询。虽然端点与其他视频模型相同，参数并不通用。

## 从图片生成视频

```json title="midjourney-video-generate.json"
{
  "model": "midjourney-video",
  "images": [
    "https://example.com/start.png"
  ],
  "prompt": "The camera slowly moves forward through the greenhouse",
  "resolution": "480p",
  "speed": "fast",
  "motion": "low",
  "n": 2
}
```

`images` 的第一张为首帧，可选第二张为尾帧；至少提供一张图片，不能只传提示词。`prompt` 用于描述运动。循环视频可用 `loop`，但不能同时提供尾帧。

先向 `/v1/video/generations/estimate` 发送相同 JSON，确认该规格已开放和完整任务的 `estimated_cost_usd`，再提交。示例图片需替换成真实可访问的素材。

## 分辨率、速度与时长

| 项目 | 请求方式 |
| --- | --- |
| SD / HD | `resolution: "480p"` / `"720p"` |
| 速度 | 显式指定 `speed`；HD 必须 Fast，SD Relax 还需要当前服务及报价支持 |
| 运动强度 | `motion: "low"` 或 `"high"` |
| 一次输出数量 | `n: 1`、`2` 或 `4`，表示视频条数 |
| 初次时长 | 约 5 秒，实际编码时长可能略有差异 |

不接受用 `duration` 或 `seconds` 指定任意时长，也不使用 `first_frame_url`、`reference_video_urls`、`aspect_ratio` 等其它视频模型字段。详细限制见[视频参数参考](https://api.hamubox.com/docs/models/midjourney/#视频生成与延长)。

## 读取所有视频

生成完成后遍历 `outputs[].url`。`metadata.url` 仅兼容提供第一条视频，不能用于判断结果只有一条。视频 `n` 和 MJ 图片按组提交的 `n: 1` 含义不同；估价已包含当前请求的批量，不要再乘一次数量。

若提供 `metadata.result_transfer_status`，它是保存状态。官方 CDN 地址可能在转存后更新为本站地址，需要长期地址的客户端按[下载规则](https://api.hamubox.com/docs/midjourney/faq/#生成完成后为什么下载失败)等待保存；不重新生成。

## 延长已有视频

延长只适用于本站已完成的 MJ 视频任务，不是上传任意视频后续写。使用 `operation: "extend"`、本站 `parent_task_id`、原始 `output_index`，并保持与父任务相同的分辨率；不再传 `images` 或开启 `loop`。

每次延长约 4 秒，最多 4 次；每次都会创建新任务，再次延长使用最新的任务 ID。可用次数与父任务信息仍需服务端验证。**延长需要独立定价和能力支持，不能因为模型可见就直接提交**；应先估价，不可估价则尚不可用。

完整请求见[视频延长示例](https://api.hamubox.com/docs/models/midjourney/#视频生成与延长)。


---

Source: https://api.hamubox.com/docs/models/banana/

# Nano Banana 2 / 2.1 / Pro

公开模型 ID：**`nano-banana-2`**、**`nano-banana-pro`**。二者使用相同的 [异步图片接口](https://api.hamubox.com/docs/image/) 与参数格式。

本章适用于 `default` 分组。请直接使用上述模型名，不需要改成 Gemini 名称，也不需要添加 `-edit` 后缀。以下尺寸表适用于 `nano-banana-2` / `nano-banana-pro`；`nano-banana-2.1` 的独立参数见本章末尾。

## 参数

| 字段 | 支持值 |
| --- | --- |
| `images` | 最多 14 张，非空自动进入图片编辑 |
| `n` | 固定 `1` |
| `resolution` | `1k`（默认）、`2k`、`custom` |
| `aspect_ratio` | 常用比例或合法的 `宽:高`，比例范围 1:3–3:1 |
| `size` | 自定义像素 `宽x高`，例如 `1536x1024` |
| `output_format` | `png`（默认）、`jpeg`、`webp` |

**不支持 4K。** 不使用 GPT 的 `quality: "high"`、`moderation`，也不要同时传相互矛盾的质量和分辨率。

## 文生图

```json title="banana-generate.json"
{
  "model": "nano-banana-pro",
  "prompt": "A red ceramic teapot on a white table, soft daylight, no text.",
  "aspect_ratio": "3:2",
  "resolution": "2k",
  "output_format": "png",
  "n": 1
}
```

换成 `nano-banana-2` 即使用另一个模型，其他字段相同。

## 常用比例与尺寸

| 比例 | 1K 像素 | 2K 像素 |
| --- | --- | --- |
| 1:1 | 1024×1024 | 2048×2048 |
| 2:3 | 848×1264 | 1696×2528 |
| 3:2 | 1264×848 | 2528×1696 |
| 3:4 | 896×1200 | 1792×2400 |
| 4:3 | 1200×896 | 2400×1792 |
| 4:5 | 928×1152 | 1856×2304 |
| 5:4 | 1152×928 | 2304×1856 |
| 9:16 | 768×1376 | 1536×2752 |
| 16:9 | 1376×768 | 2752×1536 |
| 21:9 | 1584×672 | 3168×1344 |

这些是请求尺寸，比例会因像素对齐产生小幅偏差；客户端展示应读取真实返回图片的宽高，不要强制拉伸结果。

## 自定义尺寸

```json title="banana-custom.json"
{
  "model": "nano-banana-pro",
  "prompt": "A peaceful garden, wide composition.",
  "resolution": "custom",
  "size": "1536x1024",
  "output_format": "png",
  "n": 1
}
```

- 宽、高都是 16 的倍数。
- 单边 256–3168px。
- 长边 / 短边不超过 3。
- 总像素不超过 4300000。

自定义时不传 `aspect_ratio`。不要用自定义字段绕过 4K 限制。

## 参考图编辑

```json title="banana-edit.json"
{
  "model": "nano-banana-2",
  "prompt": "Change the teapot color to blue, keep the composition unchanged.",
  "images": [
    "https://example.com/reference.png"
  ],
  "resolution": "1k",
  "output_format": "png",
  "n": 1
}
```

有参考图时省略 `aspect_ratio` 和 `size`，可跟随首张参考图比例并结合分辨率档位。香蕉不接受 `size: "auto"`，这一点与 GPT Image 2 不同。

## 计费与已验证范围

当前基础价为每次 **$0.016**，最终适用价以模型广场和 Key 为准。每个任务一张图，多任务分别计费。

`nano-banana-pro` 已通过本站异步接口验证 2K 文生图与 1K 参考图编辑，结果可正常下载。供应商能力变化时以本站公开限制为准，不把其他网站同名模型的 4K 支持视作本线路能力。

## Nano Banana 2.1

公开模型 ID 为 `nano-banana-2.1`，同样使用本站异步图片接口，不需要客户端处理 Gemini 原生协议。

| 字段 | 支持值 |
| --- | --- |
| `resolution` | `1K`（默认）、`2K`、`4K` |
| `aspect_ratio` | `1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`、`5:4`、`4:5`、`21:9`、`8:1`、`4:1`、`1:4`、`1:8` |
| `images` | 最多 14 张参考图 |
| `n` | 固定 `1` |

省略 `aspect_ratio` 或使用 `auto` 时由模型自动决定比例，不保证跟随首张图。需要固定比例时请显式指定。不要传自定义像素 `size`、GPT 的 `quality` 或输出格式参数。

基础价为 **$0.016/次**，最终适用价以模型广场和 Key 为准。已通过本站异步接口实测 `1:1` 文生图：1K 返回 1024×1024、2K 返回 2048×2048、4K 返回 4096×4096。其他比例与参考图编辑尚未逐项进行付费验证；输出像素不代表对上游内部生成或放大方式的保证。


---

Source: https://api.hamubox.com/docs/models/gpt-image-2/

# GPT Image 2

模型 ID：**`gpt-image-2`**。本章适用于 `default` 分组，使用 [异步图片接口](https://api.hamubox.com/docs/image/)。

## 参数

| 字段 | 支持值 |
| --- | --- |
| `images` | 最多 16 张，非空自动进入图片编辑 |
| `n` | 固定 `1` |
| `resolution` | `auto`、`1k`、`2k`、`4k`、`custom` |
| `aspect_ratio` | `宽:高`；比例范围 1:3–3:1 |
| `size` | `auto` 或 `宽x高`，例如 `1536x1024` |
| `quality` | `auto`（默认）、`low`、`medium`、`high` |
| `moderation` | `auto`（默认）、`low`；不保证所有内容都可生成 |
| `output_format` | `png`（默认）、`jpeg`、`webp` |

## 比例加分辨率

```json title="gpt-generate.json"
{
  "model": "gpt-image-2",
  "prompt": "A red teapot on a white table, clean product photograph.",
  "aspect_ratio": "3:2",
  "resolution": "2k",
  "quality": "auto",
  "moderation": "auto",
  "output_format": "png",
  "n": 1
}
```

网关将比例和档位转换为具体像素尺寸。1K、2K、4K 是目标像素规模而非任意比例下固定长边；最终尺寸按模型约束取整，4K 最大约 829 万像素。

## 自定义尺寸

```json title="gpt-custom.json"
{
  "model": "gpt-image-2",
  "prompt": "A peaceful garden, wide composition.",
  "resolution": "custom",
  "size": "1536x1024",
  "quality": "auto",
  "output_format": "png",
  "n": 1
}
```

自定义时不要再传 `aspect_ratio`；`size` 才是实际像素尺寸。尺寸约束：

- 宽、高都是 16 的倍数。
- 最长边不超过 3840px。
- 长边 / 短边不超过 3。
- 总像素在 655360–8294400 之间。

`1920x1080` 的高度不是 16 的倍数，不能直接当作本接口的有效自定义尺寸。使用预设比例档位，或选择满足约束的尺寸。

## 自动尺寸与参考图编辑

```json title="gpt-edit.json"
{
  "model": "gpt-image-2",
  "prompt": "Change the teapot color to blue. Keep the composition unchanged.",
  "images": [
    "https://example.com/reference.png"
  ],
  "size": "auto",
  "quality": "high",
  "output_format": "png",
  "n": 1
}
```

`size: "auto"` 或 `resolution: "auto"` 让模型自行决定尺寸，不保证它严格复制原图像素。要求固定构图比例时，读取参考图宽高后传 `aspect_ratio` 加明确分辨率，或使用合法 `size`。

## 计费

本章 default 线路按请求计费，不按文本 token 计费。当前基础单价以模型广场为准，`quality` 不代表本站必定按官方 token 规则收费。提交与成功响应通过 `usage` 给出预估和实际金额。

## GPT Image 2.5 专线

`gpt-image-2.5-flare-dedicated` 和 `gpt-image-2.5-sunburst-dedicated` 是独立专线模型，
同样通过异步图片接口调用。`dedicated` 表示专线，不能与 `-official` 官渠的尺寸规则混用。

- 支持文生图、最多 16 张参考图编辑，以及 `auto / low / medium / high / xhigh / max` 质量选项。
- `n` 可省略或填写 `1`，不支持一次请求多张；平台转发时自动省略上游不接受的 `n`。
- 支持下表固定尺寸，不支持 `size: "auto"` 或任意宽高。可传 `resolution` 加 `aspect_ratio`，也可直接传表中的 `size`。
- 游乐场和画布的“跟随首张参考图”会匹配最接近的受支持比例，不保证与原图像素完全相同。
- `-official` 官渠模型仍支持受约束的自定义尺寸和 `auto`，本次没有取消这些能力。

| 比例 | 1K | 2K | 4K |
| --- | --- | --- | --- |
| 3:1 | 1536x512 | 3072x1024 | 3840x1280 |
| 21:9 | 1344x576 | 2688x1152 | 3840x1648 |
| 16:9 | 1280x720 | 2048x1152 | 3840x2160 |
| 3:2 | 1152x768 | 2304x1536 | 3520x2352 |
| 4:3 | 1024x768 | 2048x1536 | 3312x2480 |
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 3:4 | 768x1024 | 1536x2048 | 2480x3312 |
| 2:3 | 768x1152 | 1536x2304 | 2352x3520 |
| 9:16 | 720x1280 | 1152x2048 | 2160x3840 |
| 1:3 | 512x1536 | 1024x3072 | 1280x3840 |

1K、2K、4K 为档位名称；部分尺寸经过上游取整，请使用表值。
当前 default 基础售价为 $0.03/张，实际价格和用户优惠以模型广场及估价为准。


---

Source: https://api.hamubox.com/docs/models/midjourney/

# Midjourney 与 Niji API 参数参考

Midjourney 使用本站统一异步接口，不需要提供 Midjourney 账号或执行服务的密钥。所有请求使用 `Authorization: Bearer sk-your-api-key`；JSON 请求同时设置 `Content-Type: application/json`。

本页集中维护字段与协议约束。首次接入可从[快速开始](https://api.hamubox.com/docs/midjourney/quickstart/)阅读；按场景查找[参考图与风格码](https://api.hamubox.com/docs/midjourney/references/)、[变体与放大](https://api.hamubox.com/docs/midjourney/actions/)、[视频生成](https://api.hamubox.com/docs/midjourney/video/)和[常见问题](https://api.hamubox.com/docs/midjourney/faq/)。

:::note[参数支持不等于已开放生成]
可用模型以当前 Key 的 `/v1/models` 为准，操作与档位以实时估价及返回的 `actions` 为准。本页保留完整参数契约，不承诺所有版本、编辑器操作或视频延长都已配置可用价格；不能估价的操作不要提交。本站是第三方接入服务，不是 Midjourney 官方 API。
:::

## 接口与模型

| 用途 | 方法与路径 |
| --- | --- |
| 图片提交 | `POST /v1/image/generations` |
| 图片估价 | `POST /v1/image/generations/estimate` |
| 图片查询 | `GET /v1/image/generations/{task_id}` |
| 视频提交 | `POST /v1/video/generations` |
| 视频估价 | `POST /v1/video/generations/estimate` |
| 视频查询 | `GET /v1/video/generations/{task_id}` |

图片提交包含生成、参考、编辑及后续操作；视频提交包含生成与延长。估价使用相同请求体，不创建生成任务。

图片模型 ID：`midjourney-v6`、`midjourney-v6.1`、`midjourney-v7`、`midjourney-v8.1`、`midjourney-v8.2`、`niji-v6`、`niji-v7`。视频模型 ID：`midjourney-video`。

使用当前 Key 调用 `GET /v1/models` 确认模型权限。某个模型可用不代表它的每个操作、速度和批量档位都已开放；请先估价确认。未配置的档位会拒绝提交，不会自动改成另一种收费模式。这里不使用旧版 `/mj/submit/*` 协议，也不使用同步 `/v1/images/generations`。

## 第一次生成

```json title="midjourney-image-generate.json"
{
  "model": "midjourney-v7",
  "prompt": "A quiet greenhouse at sunrise, soft watercolor illustration",
  "speed": "fast",
  "generation_mode": "standard",
  "aspect_ratio": "3:2",
  "stylize": 100,
  "seed": 0,
  "raw": false,
  "n": 1
}
```

下载[该请求 JSON](https://api.hamubox.com/docs/examples/midjourney-image-generate.json)，将下面命令中的 Key 替换为自己的：

```sh
curl https://api.hamubox.com/v1/image/generations \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @midjourney-image-generate.json
```

保存响应的 `id`，之后每隔约 5 秒查询一次，直至 `status` 为 `completed` 或 `failed`。`queued` / `in_progress` 不是失败，也不要反复 POST。HTTP 200 本身不代表图片已生成。

生成完成后，结果可能先返回 Midjourney 官方 CDN 地址，后台继续转存。
图片响应的 `result_transfer_status`（视频位于 `metadata` 中）表示保存进度；
需要本站长期地址时，可以继续查询至 `stored`。结果编号保持不变，URL 可能更新，
已保存的文件优先返回本站地址。`failed` 的保存状态不等于生成失败。
官方 CDN 可能对服务器下载触发访问验证；遇到这种情况请稍后查询本站地址，
不要重复提交生成请求，以免产生第二次费用。

:::caution[已有客户端的结果下载]
`completed` 不保证文件已经转存到本站。如果客户端只允许本站文件域名，或者服务器无法下载官方 CDN，请继续按保存状态查询，不要仅收到 `completed` 就固定保存第一次返回的 URL。保存状态为 `queued`（排队）、`pending`（保存中）、`stored`（已保存）或 `failed`（保存失败）。保存失败可能在后台补偿后恢复，但不保证最终成功；客户端应设置等待期限并保留已有结果，不要无限轮询。历史任务可能没有此字段，仍按原有结果处理。
:::

```sh
curl https://api.hamubox.com/v1/image/generations/task_example \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"
```

### 基础参数

| 字段 | 说明 |
| --- | --- |
| `model` | 上表中的图片模型 ID |
| `operation` | 默认 `generate`；其它操作见下文 |
| `prompt` | 生成提示词，最多 4000 字符（包含原生尾随参数）。`generate`、`edit`、`retexture`、`region`、`custom_zoom` 必填 |
| `images` | 普通参考图 URL 数组，最多 4 张；在 `generate` 中是参考，不会自动切换为 `edit` |
| `aspect_ratio` | `1:1`（默认）、`2:3`、`3:2`、`3:4`、`4:3`、`9:16`、`16:9` |
| `speed` | `fast` 或 `relax`。建议明确指定；后续操作省略时优先继承原任务速度 |
| `generation_mode` | `standard`（默认）、`draft`、`hd`，不是速度设置 |
| `stylize` | 整数 0–1000，风格化强度 |
| `chaos` | 整数 0–100，结果差异程度 |
| `seed` | 整数 0–4294967295；`0` 有效 |
| `raw` | 布尔值；启用后减少模型默认审美修饰，并非无审核模式 |
| `negative_prompt` | 排除的内容，等价于 `--no`；最多 4000 字符，不包含其它参数、花括号或控制字符 |
| `image_weight` | 普通参考图权重，0–3；Niji V7 为 0–2，需要同时提供 `images` |
| `tile` | 布尔值，生成可平铺图案 |
| `weird` | 0–3000 的整数，增加非典型审美；不适用于 Niji |
| `n` | 图片任务只能是 `1`，表示一次任务／一组结果，不是仅生成一张图片 |
| `max_cost_usd` | 可选费用上限，0–10000 美元；估价超出上限时拒绝提交 |

`draft` 可用于 V7 / V8.1 / V8.2，`hd` 可用于 V8.1 / V8.2，均只用于 `generate`。Draft 是草稿生成模式，HD 是高清生成模式；它们与 Fast／Relax 分别控制生成方式与队列速度，价格也分别计算。这里不支持 `turbo`。

`negative_prompt`、`image_weight`、`tile` 和 `weird` 首版仅支持 `generate`。后续变体等继承父任务设置，不重新传这些字段。

:::caution[不要混用其它模型参数]
MJ 图片不接受 `size`、`resolution`、`quality`、`image_urls` 等其它图片协议字段。可使用本页的结构化参数或下方列出的原生尾随参数；不支持 `{...}` 排列生成、重复任务和未配置价格的质量／Turbo 档位。
:::

### 原生提示词格式

支持把常见的 MJ 参数放在提示词末尾，仍提交到 **`/v1/image/generations`**，不是另一个同步接口。描述放前面，参数放后面，参数名区分大小写。

```json title="midjourney-image-native.json"
{
  "model": "midjourney-v7",
  "prompt": "A quiet greenhouse at sunrise --v 7 --ar 16:9 --s 150 --chaos 0 --seed 42 --raw --no text, watermark --fast",
  "aspect_ratio": "1:1",
  "speed": "relax",
  "n": 1
}
```

此例实际使用 **16:9、Fast**，而不是 JSON 中的 1:1、Relax。估价和提交都会先解析相同的尾随参数，再按生效的规格计费。

| 原生写法 | 对应结构化字段 |
| --- | --- |
| `--ar` / `--aspect` | `aspect_ratio` |
| `--s` / `--stylize`，`--c` / `--chaos`，`--seed` | `stylize`、`chaos`、`seed` |
| `--raw` / `--style raw` | `raw: true` |
| `--no`，`--iw`，`--tile`，`--w` / `--weird` | `negative_prompt`、`image_weight`、`tile: true`、`weird` |
| `--sref`，`--sw`，`--sv` | 风格参考图／数字风格码、风格权重和版本 |
| `--cref`，`--cw` | 角色参考图和权重 |
| `--oref`，`--ow` | Omni Reference 和权重 |
| `--p` / `--profile` | `profile_codes`，需提供明确的共享代码 |
| `--draft`，`--hd`，`--sd` | `generation_mode`；`--sd` 对应 `standard` |
| `--fast`，`--relax` | `speed` |
| `--zoom` | `zoom`，仅用于 `custom_zoom` |
| `--v` / `--version`，`--niji` | 只核对版本，必须与 `model` 一致，不会替换已选择的模型 |

- 优先级：**尾随参数 > 对应 JSON 创作参数 > 默认值**。同一普通参数重复时以最后一次为准；同时出现 Fast／Relax，或多个不同的生成模式，会明确报错。
- 参考素材可放在文本开头，例如 `https://example.com/a.png https://example.com/b.png a garden --ar 16:9`。这些 URL 会替换 JSON 的 `images`，仍受参考图数量和下载校验限制。
- `--sref` 会整体替换 `style_references` 和 `style_codes`，支持同一参数下用空格分隔图片 URL 与数字风格码；`--cref`、`--oref`、`--p` 也替换各自对应的参考内容。平台工作台同时带有情绪版选择时，明确的 `--p` 优先。
- 参数覆盖不会改变模型权限、`n: 1`、父任务归属或 `max_cost_usd`。例如 `model: "midjourney-v7"` 搭配 `--v 8.2` 会拒绝；不会按 V7 的价格调用 V8.2。
- 不支持的参数会返回明确的 HTTP 400，而不是悄悄忽略。`--q` / `--quality`、`--turbo`、`--r` / `--repeat`、排列生成、视频命令仍不能使用。其它字段和模型限制仍按本页规定验证；复制官网参数不代表所有官网能力都已开放。
- 空提示词与超过 4000 字符会分别说明原因；只有参数、没有必填的正文描述，也会报错。普通单词或 URL 内的 `--` 不会被当成参数。

原始提示词保留在任务记录中，生成使用解析后的内容。视频接口仍只接受下方列出的结构化参数，不使用此图片解析规则。

### 参考图、风格与角色

参考素材必须是无需登录即可读取的公网 HTTPS 图片 URL，支持 PNG、JPEG、WebP，单张不超过 10 MB。不要求使用平台图床，但链接及其重定向不能指向内网地址，也不能携带登录凭据或使用非标准端口。不支持 `blob:`、本地路径或图片 Data URL。可先使用[素材上传接口](https://api.hamubox.com/docs/references/)取得 URL；`mask` 是下文单独说明的例外。

```json title="midjourney-image-reference.json"
{
  "model": "midjourney-v7",
  "prompt": "A traveler standing in a sunlit greenhouse",
  "speed": "fast",
  "style_references": [
    "https://example.com/style.png"
  ],
  "style_weight": 100,
  "omni_reference": "https://example.com/character.png",
  "omni_weight": 100
}
```

| 字段 | 范围与适用条件 |
| --- | --- |
| `style_references` | 最多 4 张风格参考图 URL |
| `style_codes` | 最多 4 个不重复的纯数字字符串，每个 1–20 位，不包含 `--sref` 前缀；与 `style_references` 合计不超过 4 项 |
| `style_weight` | 0–1000 的整数，必须同时提供风格图片或风格码 |
| `style_version` | 可选。V6 / V6.1：1–4；V7 图片风格参考：1–6，含风格码时仅 4 或 6；其它模型省略 |
| `character_references` | 最多 4 张；仅 V6 / V6.1 / Niji V6 |
| `character_weight` | 0–100 的整数，需搭配角色参考图 |
| `omni_reference` | 单张参考图 URL，仅 V7 的 `standard` 模式 |
| `omni_weight` | 1–1000 的整数，需搭配 Omni Reference |
| `profile_codes` | 最多 4 个不重复的公开个性化／情绪版代码，每个 2–32 位英文字母或数字；不包含 `--p` 前缀 |

风格、角色和 Omni 参数只用于 `generate` 或适用的 `edit`。V8 不接受 `character_references` / `omni_reference`，需要结合图片修改时使用 `edit`。

Omni 的 Fast 和 Relax 分别计价，不沿用普通生图的报价。若返回 `model_price_error`，表示平台尚未配置该操作和速度的有效价格，生成未提交、未扣款；请联系管理员，不要重复提交或改成普通生图来绕过报价。

`profile_codes` 仅用于 Midjourney 的 `generate`，不用于 Niji；支持与 V7 Standard 的 `omni_reference`、`omni_weight` 组合。组合请求沿用对应速度的 Omni 报价，不额外加收个性化费用，不能同时传 `style_weight` 或 `style_version`。不要传 `default`、`global`、`random`，也不要把数字风格码当作个性化代码。代码是否可用仍取决于分享权限与模型兼容性。平台情绪版创建和管理不属于本公共 API 的开放范围。

### 多结果与后续操作

成功任务的 `outputs` 是全部可见结果，不只是第一张。常规图片生成通常返回 4 张，某些模式可能更多或更少，客户端必须遍历数组，不能写死数量。下方是字段节选，不代表固定输出数量：

```json
{
  "id": "task_example",
  "object": "image.generation.task",
  "model": "midjourney-v7",
  "operation": "generate",
  "status": "completed",
  "outputs": [
    { "id": "output_1", "object": "image.generation.output", "url": "https://example.com/result-1.png", "mime_type": "image/png" },
    { "id": "output_2", "object": "image.generation.output", "url": "https://example.com/result-2.png", "mime_type": "image/png" }
  ],
  "actions": [
    { "operation": "variation", "output_index": 0 },
    { "operation": "variation", "output_index": 1 }
  ]
}
```

后续操作仍 POST 图片端点，但传入本站的 `parent_task_id` 和 `actions` 提供的 `operation`、`output_index`。父任务必须属于当前用户且已完成；`model` 必须与父图片任务一致。不要传上游任务 ID 或按钮 `customId`。

```json title="midjourney-image-variation.json"
{
  "model": "midjourney-v7",
  "operation": "variation",
  "parent_task_id": "task_example",
  "output_index": 0
}
```

`output_index` 从 **0** 开始；请直接使用对应动作的值，不要使用图片界面筛选或排序后的下标。`output_1` 对应原始下标 0，`output_2` 对应 1。后续操作返回新的任务 ID，需要另行查询。

| `operation` | 用途 |
| --- | --- |
| `variation` / `vary_subtle` / `vary_strong` | 变体／轻微重绘／较强重绘 |
| `reroll` | 按原始设置重新生成 |
| `upscale_subtle` / `upscale_creative` | 保守放大／创意放大 |
| `zoom_1_5` / `zoom_2` | 向外扩展画面 |
| `pan_left` / `pan_right` / `pan_up` / `pan_down` | 向对应方向扩图 |
| `custom_zoom` | 自定义扩图，另传 `prompt` 和 `zoom`（1–2），可传 `aspect_ratio` |
| `region` | 局部重绘，另传 `prompt` 和 PNG Data URL `mask` |
| `select` | 提取已有单图，不等同于付费重新放大；已取得单图 URL 时无需再次调用 |

**只展示并提交 `actions` 实际返回的操作。** 不同模型、结果阶段和图片可用动作不同；例如某些放大或局部重绘需要先取得单图，不能假设所有四宫格都支持。

```json title="midjourney-image-upscale.json"
{
  "model": "midjourney-v7",
  "operation": "upscale_subtle",
  "parent_task_id": "task_selected_image",
  "output_index": 0,
  "speed": "fast"
}
```

除 `region` / `custom_zoom` 外，后续操作不重新传 `prompt` 或 `aspect_ratio`；也不要传 `images`、`seed`、`raw`、`chaos`、`stylize` 或参考控制参数，这些继承原任务。`mask` 必须是有效 PNG，Data URL 总长度不超过 8 MiB，宽高分别为 1–8192 像素；只允许用于 `region`。

### 编辑、融合与图转提示词

| `operation` | 模型与参数 |
| --- | --- |
| `edit` | V8.1 / V8.2，1–4 张 `images` 和非空 `prompt` |
| `retexture` | V6.1，1 张 `images` 和非空 `prompt` |
| `blend` | 2–4 张 `images`，正方形比例，不传提示词或风格化参数 |
| `describe` | 1 张 `images`，不传提示词或其它生成控制参数 |

```json title="midjourney-image-edit.json"
{
  "model": "midjourney-v8.2",
  "operation": "edit",
  "prompt": "Change the greenhouse into a winter garden, preserve the traveler",
  "images": [
    "https://example.com/source.png"
  ],
  "speed": "fast"
}
```

```json title="midjourney-image-describe.json"
{
  "model": "midjourney-v7",
  "operation": "describe",
  "images": [
    "https://example.com/source.png"
  ]
}
```

`describe` 完成后读取顶层 `descriptions` 字符串数组，通常有多个候选提示词；**不会因此生成四张图片**，也不保证永远有四条描述。客户端应支持没有 `outputs` 的成功任务。选择一条描述再次生成时，另行提交 `generate`，按新任务计费。

## 视频生成与延长

MJ 视频使用 `midjourney-video`，至少需要一张首帧图，不支持仅提示词的纯文生视频。

```json title="midjourney-video-generate.json"
{
  "model": "midjourney-video",
  "images": [
    "https://example.com/start.png"
  ],
  "prompt": "The camera slowly moves forward through the greenhouse",
  "resolution": "480p",
  "speed": "fast",
  "motion": "low",
  "n": 2
}
```

| 字段 | 说明 |
| --- | --- |
| `operation` | `generate`（默认）或 `extend` |
| `images` | 生成时 1–2 张 URL，顺序为首帧、可选尾帧 |
| `prompt` | 可选运动描述，最多 4000 字符，不允许原生参数或排列语法 |
| `resolution` | `480p`（默认，SD）或 `720p`（HD） |
| `speed` | `fast` / `relax`；720p 必须 Fast。480p Relax 也需要当前线路和价格支持 |
| `motion` | `low`（默认）或 `high` |
| `n` | 1（默认）、2 或 4，表示本次视频输出条数；与图片的 `n` 含义不同 |
| `raw` | 可选布尔值 |
| `loop` | 可选布尔值，循环视频；不能同时提供尾帧 |
| `max_cost_usd` | 可选本次任务费用上限 |

初次视频约 5 秒，每次延长约 4 秒，最多延长 4 次。实际编码时长可能略有差异。不接受 `duration`、`seconds`、`aspect_ratio`、`first_frame_url` 或 `reference_video_urls`，不能通过这些字段指定任意时长或上传外部视频进行延长。

查询成功后遍历 `outputs[].url` 获取全部视频；`metadata.url` 兼容提供第一条结果，不代表只有一条。

```json title="midjourney-video-extend.json"
{
  "model": "midjourney-video",
  "operation": "extend",
  "parent_task_id": "task_video_example",
  "output_index": 0,
  "prompt": "Continue the gentle camera movement",
  "resolution": "480p",
  "speed": "fast",
  "n": 1
}
```

延长使用本平台已完成的视频父任务和原始结果下标（0–3），不要传 `images`，也不要开启 `loop`。`resolution` 必须与父任务一致，建议显式填写。每次延长都会创建新任务；再次延长时使用最新任务 ID。达到延长次数上限或父任务缺少必要信息时会拒绝请求。

## 估价、扣费与失败处理

向对应 `/estimate` 端点发送与实际提交完全相同的 JSON（包括速度、模式、批量和父任务），返回顶层 `estimated_cost_usd`（美元）和 `quota`（内部额度单位）。估价不创建任务、不发起生成；不是锁价承诺。

```sh
curl https://api.hamubox.com/v1/image/generations/estimate \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @midjourney-image-generate.json
```

提交时可将接受的最高金额填入 `max_cost_usd`。超出会返回 HTTP 409；需要重新确认价格，不要自动提高限额。正式价格以[模型广场](/pricing)及当前 Key 的实时估价为准，不应把示例中的结果数量当成额外的计费乘数。

- 图片生成按组估价，后续变体、放大等是独立操作；视频批量按完整请求估价，不要再自行重复乘 `n`。
- 模型广场中的 MJ 单位为“次”，表示一次任务。图片的一组通常包含多张结果，并非每张都按页面基础价收费；视频也不是按秒计费，具体金额以规格、批量和操作的估价为准。
- 无法估价的操作或档位不要提交。费用、权限、原任务可用动作都会在提交时重新验证。
- 任务失败读取 `error.message`，费用读取 `usage`；结算与退款说明见[计费文档](https://api.hamubox.com/docs/billing/)。
- 没有结果 URL 时先检查 `status`，不要立即重发。已经生成但正在保存结果的任务应继续查询，不能通过重新生成来修复保存问题。
- 提交断网或超时不代表上游没收到。已获得任务 ID 时只查询该任务；尚未获得 ID 时先核对任务记录，避免重复收费。

可下载本页的[纯文本版本](https://api.hamubox.com/docs/markdown/models/midjourney.md)，或使用包含相同示例的 [OpenAPI](https://api.hamubox.com/docs/openapi.json)。


---

Source: https://api.hamubox.com/docs/models/seedance/

# Seedance 系列

使用 [异步视频接口](https://api.hamubox.com/docs/video/)。本章覆盖 EP 系列与对应 Doubao 模型，客户端不需要填写内部线路名。

## 模型与输出规格

| 模型 ID | 建议生成时长 | 分辨率 |
| --- | --- | --- |
| `dreamina-seedance-2-0-ep` | 4–15 秒 | `480p` / `720p` / `1080p` / `4k` |
| `dreamina-seedance-2-0-fast-ep` | 4–15 秒 | `480p` / `720p` |
| `dreamina-seedance-2-0-mini-ep` | 4–15 秒 | `480p` / `720p` |
| `dreamina-seedance-2-5-ep` | 4–30 秒 | `480p` / `720p` / **`1080p`** |
| `doubao-seedance-2-0-260128` | 4–15 秒 | `480p` / `720p` / `1080p` / `4k` |
| `doubao-seedance-2-0-fast-260128` | 4–15 秒 | `480p` / `720p` |
| `doubao-seedance-2-0-mini-260615` | 4–15 秒 | `480p` / `720p` |
| `doubao-seedance-2-5-260628` | 4–30 秒 | `480p` / `720p` / `1080p` |

按范围内的整数传 `duration`，不局限于 5 / 10 / 15 秒。官转 2.5 还支持 `duration: -1`，表示由模型决定输出时长；此值不是单独的编辑模式。不同分组可用模型以 `/v1/models` 为准。

支持的比例：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`、`adaptive`。建议总是明确填写 `resolution` 和 `duration`，不要依赖不同线路的默认分辨率。

## 文生视频

省略 `mode` 和参考素材。

```json title="seedance-text.json"
{
  "model": "dreamina-seedance-2-0-ep",
  "prompt": "A slow aerial shot over a green valley at sunrise, natural light, steady camera.",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true,
  "watermark": false
}
```

`audio` 控制是否生成音轨；`watermark` 控制水印。本章 EP 系列不承诺 `seed` 可复现结果，请勿依赖种子固定。

## 首帧、尾帧、首尾帧

使用 `mode: "first_last_frame"`，至少提供一个显式帧字段：

- 只有 `first_frame_url`：首帧生成。
- 只有 `last_frame_url`：尾帧生成，不要把尾帧放进 `image_urls[0]`。
- 两者都有：首尾帧生成。

```json title="seedance-frames.json"
{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "The character turns slowly toward the camera. Keep the face and outfit consistent.",
  "mode": "first_last_frame",
  "first_frame_url": "https://example.com/first.png",
  "last_frame_url": "https://example.com/last.png",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "adaptive",
  "audio": true
}
```

**输出比例跟随输入帧**。建议 `aspect_ratio: "adaptive"`；不要期待通过固定比例把输入帧变成另一个比例。需要特定比例时先裁剪素材。

只传尾帧：

```json title="seedance-tail.json"
{
  "model": "dreamina-seedance-2-0-fast-ep",
  "prompt": "The camera slowly approaches the final composition.",
  "mode": "first_last_frame",
  "last_frame_url": "https://example.com/last.png",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "adaptive"
}
```

首尾帧模式不要混入 `reference_video_urls`、`reference_audio_urls`。旧的位置数组写法仍可兼容首帧 / 首尾帧，但新接入使用显式帧字段，避免用途混淆。

## 全能参考

使用 `mode: "multi_ref"`。图片是形象 / 风格参考，视频可提供动作与镜头，音频提供声音参考。至少提供一张图片或一段视频，再按需附加音频，避免仅音频请求。

```json title="seedance-reference.json"
{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "Keep the character from image 1, follow the movement in video 1 and the mood of audio 1.",
  "mode": "multi_ref",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "reference_video_urls": [
    "https://example.com/motion.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/music.mp3"
  ],
  "metadata": {
    "reference_video_seconds": 8.4,
    "reference_audio_seconds": 6
  },
  "duration": 10,
  "resolution": "720p",
  "aspect_ratio": "9:16",
  "audio": true
}
```

参考视频和音频的实际时长由服务端检测，调用方不必填写。`metadata.reference_video_seconds` 和 `metadata.reference_audio_seconds` 保留兼容，校验和费用预估以服务端检测值为准。

## 参考限制

| 系列 | 图片 | 视频 | 音频 | 时间边界 |
| --- | ---: | ---: | ---: | --- |
| 2.0 / Fast / Mini | 最多 9 张 | 最多 3 段 | 最多 3 段 | 标称单段 2–15 秒，视频与音频分别累计不超过 15 秒 |
| 2.5 | 最多 30 张 | 最多 10 段 | 最多 10 段 | 标称单段 2–30 秒，视频与音频分别累计不超过 30 秒 |

本站为编码时间误差保留边界余量：最小 1.8 秒，2.0 的最大 / 累计校验边界 15.2 秒，2.5 为 30.2 秒。**余量不是建议的目标长度**，也不改变生成时长上限；尽量按标称范围准备素材。

图片建议采用 JPEG / PNG 等常用格式。官转 Seedance 2.5（包括对应 EP、经济版和 face-library 线路）的参考图、首帧、尾帧均要求：宽和高各为 **300–6000px**，宽高比在 **0.4–2.5** 之间，单文件不超过 **30MB**。

游乐场上传时提前检查，服务端也会在预扣费和提交上游前读取实际图片进行校验；外链、Base64 和历史参数复用同样适用，客户端填写宽高不能绕过检查。不符合要求返回 HTTP 400、`invalid_reference_media`，说明图片序号、实际尺寸和限制，不会自动缩放。例如 `reference_images[2] has dimensions 290x382: shortest side must be at least 300px` 表示第三张图片过小。无法下载或识别图片时也会明确拒绝，请更换素材后重新提交。

`asset://` 是上游登记素材的标识，不作为图片网址下载；仍沿用素材登记与状态检查。其他渠道以模型能力接口公布的限制为准，不将某个模型或登记流程的边界套用到全部线路。

## Seedance 2.5 参考、编辑与延长

这三种意图都使用 `mode: "multi_ref"`。可选的顶层字段 `omni_reference_task_type` 用于提前校验参数；省略时为 `auto`。它不会强制改变模型对提示词的理解，请让提示词与指定意图一致。

| `omni_reference_task_type` | 含义 | 参考视频 | `aspect_ratio` | `duration` |
| --- | --- | --- | --- | --- |
| `auto`（默认） | 根据提示词和素材识别意图 | 按实际需求 | 推荐 `adaptive` | 推荐 `-1`，也可填 4–30 的整数，但须符合实际意图 |
| `reference` | 参考素材生成新视频 | 可选 | 支持固定比例或 `adaptive` | 4–30 的整数或 `-1` |
| `edit` | 修改已有视频 | 至少一段，每段 4–30 秒 | 必须 `adaptive` | 必须 `-1`，跟随被编辑的视频 |
| `extend` | 延长已有视频 | 至少一段，每段 2–30 秒 | 必须 `adaptive` | 4–30 的整数或 `-1` |

**编辑和延长也可同时提供图片、其他参考视频和音频**，仍受上表的数量和累计时长限制。多段视频时，模型根据提示词选择编辑或延长的对象。音频不能作为唯一参考素材。

不打算区分子任务时，建议 `auto + adaptive + -1`，并将参考视频准备为 4–30 秒，以同时满足编辑意图的下限。`-1` 不保证某个固定秒数，也不要把它套用到 2.0、Venice 或其他未声明支持的线路。

### 编辑已有视频

明确描述保留什么、修改什么。输出宽高比和时长跟随模型选中的原视频：

```json title="seedance-edit.json"
{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "Edit the video: replace the background with a snowy city, preserve the camera movement.",
  "mode": "multi_ref",
  "omni_reference_task_type": "edit",
  "image_urls": [
    "https://example.com/background.png"
  ],
  "reference_video_urls": [
    "https://example.com/input.mp4"
  ],
  "metadata": {
    "reference_video_seconds": 8.4
  },
  "duration": -1,
  "resolution": "720p",
  "aspect_ratio": "adaptive"
}
```

### 延长已有视频

明确描述在原视频后继续发生的动作。输出比例跟随输入视频，`duration` 是请求的输出视频时长，不是自行假定的拼接后总长度：

```json title="seedance-extend.json"
{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "Extend the video: continue the camera movement as the character walks toward the snowy city.",
  "mode": "multi_ref",
  "omni_reference_task_type": "extend",
  "reference_video_urls": [
    "https://example.com/input.mp4"
  ],
  "metadata": {
    "reference_video_seconds": 8.4
  },
  "duration": 10,
  "resolution": "720p",
  "aspect_ratio": "adaptive"
}
```

### 参数检查与错误处理

- 显式指定 `edit` / `extend` 时，本站先检查是否有视频、是否使用 `adaptive`，以及编辑时是否传入 `-1`。
- 服务端检测每个音视频文件的时长，分别累计后检查上限；填写 `metadata` 不能替代文件检查。每个文件的尺寸、格式仍须满足供应商要求。
- 省略子任务类型或使用 `auto` 时，模型识别的实际意图与固定比例/时长不兼容，可返回 `InvalidParameter.TaskTypeConstraint`。
- 指定的子任务类型与提示词表达的意图冲突，可返回 `InvalidParameter.TaskTypeMismatch`。请修改提示词或类型后由调用方决定是否重新提交。

字段定义和任务类型边界依据[官方创建视频任务文档](https://docs.volcengine.com/docs/82379/1520757?lang=zh)及[Seedance 2.5 参数约束](https://docs.volcengine.com/docs/82379/2607688?lang=zh#2.5_param_constraints)。本站统一接口使用 `aspect_ratio`，会转为上游的 `ratio`。

## Seedance 2.5 草稿与高清生成

已验证的 Doubao 2.5 和标准 EP 2.5 线路可先生成 `480p` 草稿，再用同一草稿生成 `1080p` 正式视频。是否开放以模型能力中的 `contract.draft` 为准；不要将此能力套用到经济版、特价版或其他未声明支持的线路。

### 第一步：生成草稿

通过 `POST /v1/video/generations` 提交 JSON，在正常生成参数上增加顶层 `draft: true`，且 `resolution` 必须为 `480p`。仍支持该模型允许的首尾帧和全能参考参数。

```json title="seedance-draft.json"
{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "A red cube slowly rotates on a table, fixed camera.",
  "duration": 4,
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "draft": true,
  "audio": false,
  "watermark": false
}
```

用返回的本站 `task_...` ID 查询 `GET /v1/video/generations/{task_id}`。成功后，响应 `metadata` 提供 `draft`、`draft_can_finalize`、`draft_expires_at`（Unix 秒）。只有 `draft_can_finalize: true` 且未过期的草稿才可继续生成；不要使用上游任务 ID 或视频 URL 替代。

### 第二步：估价并确认生成 1080p

向 `POST /v1/video/generations/estimate` 提交以下参数，读取 `estimated_cost_usd`。估价不发起生成、不扣费；随后向 `POST /v1/video/generations` 提交同一份参数，并可将报价放入 `max_cost_usd`。

```json title="seedance-draft-final.json"
{
  "model": "doubao-seedance-2-5-260628",
  "draft_task_id": "task_replace_with_your_completed_draft_id",
  "resolution": "1080p",
  "watermark": false
}
```

- 必须是本人已成功的草稿，`model` 与草稿一致，`resolution` 必须为 `1080p`。
- 正式生成继承草稿设置。不要再次传提示词、模式、时长、比例、种子、声音、参考素材或 `metadata`，即使取值未变也应省略；`draft` 省略或为 `false`。
- 服务端锁定草稿原线路和原账号，不切换至普通高清备用线路。原账号被停用、权限变化或草稿过期会明确报错，不自动重新生成草稿。
- `max_cost_usd` 限制本次预扣报价。价格上涨时返回 HTTP 409、`approval_price_changed`，请重新估价并确认。它不是最终实际用量的硬性封顶。
- 草稿和正式视频是两个任务，**分别预扣、分别结算，不是补差价**。原草稿不再计作额外参考视频；原请求已有的参考视频费用仍按对应规则计算。
- 可用期以返回的 `draft_expires_at` 为准。草稿过期不删除已生成的视频，只是不再允许继续生成高清版本。部分正式视频采用 HEVC 编码，播放器需支持对应格式。

草稿及升级请求仅接受 JSON，不接受 multipart。视频游乐场和无限画布均提供草稿开关：游乐场在结果区操作；画布选中已完成的草稿视频后，可重新估价并确认高清生成。高清结果在画布中新增独立节点，保留原草稿。

## 计费

按视频 token 计费。不同分辨率、是否有参考视频，对应不同的每百万 token 单价。图片 / 音频参考不应被当作视频输入时长。

提交时按估算预扣，任务完成后按实际用量结算。实际输出尺寸、时长和参考视频都会影响费用；不能用文字 token 估算器计算视频 token。详细单价与当前 Key 的适用价格见[模型广场](https://api.hamubox.com/pricing)，响应字段见[计费与结算](https://api.hamubox.com/docs/billing/)。

官转 2.5 使用自动时长时，按 30 秒输出估算预扣；显式编辑且已知参考视频总时长时，按该时长保守估算。最终仍以实际用量结算，多余预扣退回。


---

Source: https://api.hamubox.com/docs/models/seedream/

# Seedream 5 Pro

模型 ID：**`dola-seedream-5-0-pro-ep`**。使用 [异步图片接口](https://api.hamubox.com/docs/image/)。

## 参数

| 字段 | 支持值 |
| --- | --- |
| `images` | 0–10 张参考图；0 张文生图，非空为编辑 |
| `resolution` | `1k`（默认）、`2k` |
| `aspect_ratio` | 见下方；文生图默认 `1:1`，编辑时可省略 |
| `output_format` | `jpeg`（默认）、`png` |

常用比例：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`9:16`、`16:9`、`21:9`。以上比例均可选择 `1k` 或 `2k`。

默认关闭生成水印，文生图和图片编辑均适用，客户端无需额外传参。这不会去除参考图中已有的水印。

不提供自定义 `size`、`width` / `height`、4K、`quality`、`moderation` 或多张 `n` 选项。不要把这些字段当作已支持参数传入。

## 文生图

```json title="seedream-generate.json"
{
  "model": "dola-seedream-5-0-pro-ep",
  "prompt": "A quiet futuristic city after rain, cinematic lighting, no text.",
  "aspect_ratio": "16:9",
  "resolution": "2k",
  "output_format": "png"
}
```

## 图片编辑

```json title="seedream-edit.json"
{
  "model": "dola-seedream-5-0-pro-ep",
  "prompt": "Keep the composition and character, change the background to a snowy train station.",
  "images": [
    "https://example.com/reference.png"
  ],
  "resolution": "1k",
  "output_format": "png"
}
```

`images` 的顺序用于多图指代。编辑时省略 `aspect_ratio` 为自动，由模型决定输出比例，不保证与第一张参考图一致；需要固定比例时使用支持的比例值。界面的“自动”会省略该字段，API 不要传字符串 `auto`。

## 计费特点

按请求计费，但分辨率和多参考图会影响单次金额：

```text
请求倍率 = 分辨率倍率 + max(参考图数量 - 1, 0) / 15
分辨率倍率：1K = 1，2K = 2
```

第一张参考图不增加多图附加费，第二张起每张增加基础价的 `1/15`。例如 2K、3 张参考图，请求倍率为 `2 + 2/15`，不是把所有附加费再乘一次 2。

基础单价和当前优惠见[模型广场](https://api.hamubox.com/pricing)。最终金额读取 `usage.actual_cost_usd`。


---

Source: https://api.hamubox.com/docs/models/wan3/

# Wan 3 EP

使用 [异步视频接口](https://api.hamubox.com/docs/video/)。本章描述 `wan3.0-video-ep`，不要与其他分组中的 `wan-3-0` 系列混淆。

## 输出与基础单价

| 模型 ID | 分辨率 | 基础单价（美元 / 计费秒） |
| --- | --- | ---: |
| `wan3.0-video-ep` | `480p` | 0.05 |
| `wan3.0-video-ep` | `720p` | 0.10 |
| `wan3.0-video-ep` | `1080p` | 0.20 |

实际优惠价以[模型广场](https://api.hamubox.com/pricing)及 Key 分组为准，表格不是固定成交价承诺。

- 输出 `duration` 支持 **2–30 的任意整数**，例如 7 秒、12 秒。
- 比例：`adaptive`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。
- `audio`：是否生成声音。
- `prompt_extend`：是否优化 / 扩展提示词；建议明确传 `false` 或 `true`。
- `seed`：可选，范围 `0`–`2147483647`；省略表示随机，不使用 `-1`。

## 文生视频

```json title="wan-text.json"
{
  "model": "wan3.0-video-ep",
  "prompt": "A paper boat drifting across a quiet lake, cinematic lighting.",
  "mode": "text",
  "duration": 7,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true,
  "prompt_extend": false
}
```

## 首尾帧

```json title="wan-frames.json"
{
  "model": "wan3.0-video-ep",
  "prompt": "A smooth transition from the first image to the final image.",
  "mode": "first_last_frame",
  "first_frame_url": "https://example.com/first.png",
  "last_frame_url": "https://example.com/last.png",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "audio": true
}
```

至少提供首帧或尾帧之一；仅一帧时保留对应字段即可。不要同时传入参考视频或参考音频。

## 全能参考

```json title="wan-reference.json"
{
  "model": "wan3.0-video-ep",
  "prompt": "Animate the character in image 1, following the camera motion in video 1.",
  "mode": "multi_ref",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "reference_video_urls": [
    "https://example.com/motion.mp4"
  ],
  "duration": 12,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "audio": true,
  "prompt_extend": false
}
```

最多 10 张图片、5 段视频、5 段音频。音频参考至少搭配一张图片或一段视频，不支持仅音频。

## 参考限制

| 媒体 | 规格 |
| --- | --- |
| 图片 | JPEG / JPG、PNG、BMP、WebP；单边 240–8000px；最长边 / 最短边 ≤ 8；每张 ≤ 20MB |
| 视频 | MP4 / MOV；单边 240–4096px；最长边 / 最短边 ≤ 8；帧率 ≥ 16fps；每段 ≤ 100MB |
| 音频 | MP3 / WAV；每段 ≤ 15MB |

PNG 可以上传，但不要使用透明通道作为预期有效输入，必要时先合成不透明背景。

视频与音频：**每段 1–15 秒，同类分别累计 ≤ 15 秒**。Wan EP 没有沿用 Seedance 的 0.2 秒余量。

含参考视频时还有一条独立约束：

```text
参考视频总时长 + 输出时长 ≤ 30 秒
```

例如参考视频合计 12.5 秒，输出 17 秒可以；输出 18 秒不可以。服务端会读取真实媒体信息，不以客户端填写的时长代替。

## 怎么计费

```text
计费秒数 = 输出时长 + 参考视频总时长
基础金额 = 当前分辨率单价 × 计费秒数
```

没有参考视频时只计算输出时长。参考音频不增加计费秒数。

例如标准版 720p，8 秒参考视频、12 秒输出：基础金额为 `0.10 × (8 + 12) = $2.00`，再按当前 Key 适用价格结算。不要因为输出只有 12 秒而漏算输入视频费用。

## 获取结果

查询 `GET /v1/video/generations/{task_id}`，终态成功时读取 `metadata.url`。任务生成结束后还可能需要处理结果文件，这段时间仍请按 `status` 继续等待，而不是重新提交。


---

Source: https://api.hamubox.com/docs/novelai/clients/

# 客户端接入

客户端必须允许修改服务地址与 API Key，且不能强制要求先登录 NovelAI 官网。使用官方 NovelAI 格式时按下方配置；只支持 OpenAI 图片格式时，可使用 [OpenAI Images 兼容入口](https://api.hamubox.com/docs/novelai/openai-images/)。不能修改地址或强制要求 `pst-` 前缀的客户端，不能保证只改地址就能接入。

## 通用配置

| 客户端设置 | 填写内容 |
| --- | --- |
| NovelAI API / 图片服务 Base URL | `https://api.hamubox.com/v1/novelai` |
| API Key / Bearer Token | 本站 API Key |
| 生成张数 | 1 |
| 模型 | `GET /v1/models` 返回的可用 NovelAI 模型 |
| 流式生成 | 客户端支持官方 MessagePack 且选择 V4 或更新模型时可启用 |

若客户端分别配置账户服务和图片服务地址，两处都填写上述 Base URL。最终生成请求应为 `/v1/novelai/ai/generate-image` 或 `/v1/novelai/ai/generate-image-stream`；不能丢掉前缀，也不能重复追加 `/v1/novelai`。

本站不代理官网登录、文本或语音等非绘图能力。不要把本站 Key 发送到 NovelAI 官网或第三方结果下载地址。

## 先确认配置，再生成

这些检查不发起图片生成：

1. 使用本站 Key 调用 `GET https://api.hamubox.com/v1/models`，确认有目标 NovelAI 模型。
2. 调用 `GET https://api.hamubox.com/v1/novelai/user/data`，确认鉴权与账户显示兼容。
3. 按[原生报价格式](https://api.hamubox.com/docs/novelai/native/#账户与报价)调用 `/v1/novelai/ai/generate-image/request-price`，确认当前模型与参数能估价。
4. 检查客户端生成地址、请求格式与单图设置，然后由使用者决定是否提交一次实际生成。

账户接口通过，不等于该客户端的每项功能都兼容。完整接入还应核对 ZIP 解包、流式帧解析、图生图 / 遮罩上传、缓存失效补传、模型切换和断线后任务查询。

## 当前验证范围

本站接口已有请求规范化、模型映射、计费边界和示例合同测试。文档提供[异步 Python 示例](https://api.hamubox.com/docs/examples/client.py)与[原生 MessagePack 示例](https://api.hamubox.com/docs/examples/novelai-stream.py)作为接入参考。

下面的第三方客户端核对基于指定版本源码和本站协议回归，不代表全部功能已经完成实际付费生成验收。智绘姬 3.1.5 曾在客户端临时兼容补丁下完成单张 V5 Full 出图；本站兼容层更新后的原版插件仍需实际客户端验收。

| 客户端 | 源码核对版本 | 配置与边界 |
| --- | --- | --- |
| 智绘姬 st-chatu8 | 3.1.5，`b688a65` | NovelAI → 浏览器 → 其他站点；Base URL 使用 `/v1/novelai`，支持 Bearer 与 ZIP。同步请求固定携带的 `parameters.stream: "msgpack"` 由本站兼容处理，仍返回 ZIP。关闭插件自己的云端排队；超时后先到任务日志核对，不要直接重发。 |
| 柏宝绘 ST-BaiBai-Image | 0.3.2，`1187528` | 新增 NovelAI 第三方接入点，Base URL 使用 `/v1/novelai`。兼容同步 `msgpack` 提示、空参考数组及其 `/ai/user/subscription` 连接检查路径。V5 请关闭 Vibe；首次测试关闭自动生成 tag、自动生成图片，并发设为 1。插件网络重试未发送幂等键，超时后不要继续反复生成。 |
| NovelAI Image Direct | 1.1.1 | 图像与账户地址均使用 `/v1/novelai`；V5 界面和完整生成仍需客户端实测。 |
| Quick Image Gen | 3.5.0 | 选择 OpenAI 图片代理、Base URL 使用 `/v1`、模型使用本站 NAI ID，每次一张。其另一个 NAI JSON 代理模式不能直接接收原生 ZIP。 |
| Aaalice NAI Launcher | 源码 `c648ee6` | 第三方 API 登录，主 API 与图片 API 均使用 `/v1/novelai`；发行版是否包含这些设置需核对。 |
| SillyTavern 内置生图扩展 | 1.18.0 | 内置 NovelAI 和 OpenAI 生图分支使用固定官方地址。仅改聊天反代地址不会改变图片请求，需使用支持自定义图片地址的扩展。 |

浏览器直连使用 Bearer Token，请不要设置 `credentials: 'include'`。本站跨域预检明确允许 `Authorization`、`Content-Type`、`Idempotency-Key`，并公开任务 ID 与恢复相关响应头。自建客户端应保存生成意图的幂等标识，见[幂等提交](https://api.hamubox.com/docs/novelai/tasks/#幂等提交)。

## 常见兼容差异

- **同步请求中带有 `msgpack`**：本站只在 `/ai/generate-image` 和 `/ai/generate-image/request-price` 忽略值恰为字符串 `"msgpack"` 的 `parameters.stream`；同步生成仍返回 ZIP，报价仍返回 JSON。其他无效值不会被静默忽略；异步 `/tasks`、`/estimate` 的显式流式冲突校验不变。
- **未开启参考却发送 `[]`**：空 Vibe / 精准参考数组按未使用该能力处理，与省略字段或 `null` 一样。实际非空参考仍受模型能力限制，错误类型不能替代数组。
- **V4/V4.5 的 Vibe 返回 `invalid_input_asset`**：`parameters.reference_image_multiple` 和 `parameters.reference_image` 要填 Vibe 编码，不能直接填 JPEG、PNG 等原图的 Base64。先调用 `/v1/novelai/ai/encode-vibe`，将返回的编码二进制转为 Base64 后再生成。本站在预扣费前检查可识别的图片内容，返回 HTTP 400 和具体字段位置；已登记的编码文件 URL 同样检查实际内容，V3 仍可直接使用原图。此检查不保证所有未知二进制都是有效编码。
- **显示 Anlas 但数值与官网不同**：这里是本站余额的兼容显示单位，含义见[账户与报价](https://api.hamubox.com/docs/novelai/native/#账户与报价)。
- **缓存失效**：收到 `INVALID_CACHE_KEYS` 后补传对应素材；不要直接丢掉参考图重试。
- **流式结果打不开**：MessagePack 是有长度前缀的二进制事件流，不能作为 ZIP / PNG 保存，见[帧格式](https://api.hamubox.com/docs/novelai/streaming/#messagepack-帧格式)。
- **连接超时**：先查询 `X-NovelAI-Task-Id` 指向的任务；不要自动再提交一笔生成。
- **V5 的旧参考功能不可用**：V5 不支持氛围参考和精准参考，图生图仍可用；按[模型能力](https://api.hamubox.com/docs/novelai/models/)调整请求。


---

Source: https://api.hamubox.com/docs/novelai/faq/

# NovelAI 常见问题

## 原生和异步接口是否重复

它们提供相同的绘图能力，满足两类接入方式。原生接口兼容已有客户端的路径、官方请求体和 ZIP / 二进制响应；异步接口提供任务 ID、查询、费用与文件链接。选用一套提交方式即可，同一次生成不要同时提交两个入口。

绘图参数统一见[模型与绘图参数](https://api.hamubox.com/docs/novelai/models/)。原生与异步各有完整请求示例，区别主要在路径、外层包装和响应格式。

## 是否能一次生成多张

当前 `parameters.n_samples` 仅支持 `1`，省略时也是 `1`。其它值在生成和预扣前返回 HTTP 400。需要多张时分别提交；服务端不会默默截成单张或自动拆分请求。

## 为什么客户端显示的 Anlas 与官网不同

本站账户兼容字段按 **1000 个显示单位 = 1 美元**表示本站可用额度，客户端可能将其标为 Anlas。它不是平台 NovelAI 账号的真实 Anlas、电量或会员余额。

任务里的 `estimated_anlas` / `actual_anlas` 与美元费用字段也不是同一个单位。上游免费额度不代表本站服务免费；准确估价和结算分别见 `usage.estimated_cost_usd`、`usage.actual_cost_usd`。完整显示规则见[账户与报价](https://api.hamubox.com/docs/novelai/native/#账户与报价)。

## 只有普通提示词为什么也会报参数错误

普通 V5 Full、V5 Curated 和 V4.5 Full 文生图还需要 `v4_prompt`、`v4_negative_prompt`，没有角色也要提供空的 `caption.char_captions: []`。缺少这些结构曾会被上游报成 HTTP 500；现在提交前返回 HTTP 400，并指出缺失字段。节约模式的规则有所不同，详见[必填结构与提交校验](https://api.hamubox.com/docs/novelai/models/#必填结构与提交校验)。

单纯省略 `n_samples` 不是本次 500 的原因：省略按单张估价，原生/异步透传不会自动补写该字段。工作台会提供完整结构，第三方客户端建议使用[完整请求示例](https://api.hamubox.com/docs/novelai/native/#完整请求示例)。400 参数错误应先修正，不应原样重试；其他上游 500 仍可能是不同原因，不能一概归因于参数缺失。

## 是否保留最终图片元数据

PNG 保留上游生成元数据，缺失时补充可再次导入的参数。显式请求 WebP 时保留原文件格式和已有元数据，不承诺为缺失元数据的 WebP 补写。

流式请求未指定 `image_format` 时默认请求 PNG，中间预览通常仍为 JPEG。收到完整成图即可展示；后台随后继续完成归档和结算。最终图入库，中间预览不入库。恢复规则见[流式生成与恢复](https://api.hamubox.com/docs/novelai/streaming/#成图元数据与恢复)。

## 参考素材是否进入资产库

API 素材归当前 Key 所属用户所有；临时上传与长期文件的展示方式不同。

| 保存方式 | 用户资产库 | 任务详情 |
| --- | --- | --- |
| `POST /v1/media/files` 默认临时上传 | 不展示临时文件；用于任务并完成转存后展示长期参考文件 | 转存完成后展示长期文件地址 |
| 上传时显式 `temporary=false` | 图片、视频、音频按普通参考素材展示 | 展示上传后的文件地址 |
| 已有的长期素材，或生成请求中的源图片经规范化保存 | 按普通文件规则展示；遮罩等内部辅助文件不列入资产库 | 展示保存后的文件地址，不展示 Base64 |

临时素材在转存前仍展示临时地址，默认有效期 24 小时，到期不能用于新任务；已接受任务的引用会受保护。删除长期素材后，用户任务详情也不再展示该文件地址。规则和上传示例统一见[参考素材](https://api.hamubox.com/docs/references/#上传素材)。

## 原生参考缓存与临时上传是否同一回事

不是。原生 `cache_secret_key` 是客户端减少重复上传的协议缓存，按用户隔离，通常一小时有效，也可能因容量或服务重启提前失效。临时上传 URL 的有效期由上传响应中的 `expires_at` 决定。

缓存失效要补传素材；临时 URL 过期要重新上传。缓存不会延长源文件的有效期。详细请求字段见[参考素材缓存](https://api.hamubox.com/docs/novelai/native/#参考素材缓存)。

## 为什么收到成图后任务仍在进行

快速交付成图、长期存储和费用结算是不同阶段。收到 `image` / `final` 后可以使用该图片，但稳定文件链接和最终费用以查询任务的 `completed` 状态为准。若之后转存失败，保留已收到的图片并查看任务错误，不要自动重复付费生成。

客户端断开连接不会取消已接受任务。上游在完整成图到达前断流则不保证找回结果；先查已有任务，详见[中断恢复](https://api.hamubox.com/docs/novelai/streaming/#成图元数据与恢复)。


---

Source: https://api.hamubox.com/docs/novelai/models/

# 模型与绘图参数

本章是[原生接口](https://api.hamubox.com/docs/novelai/native/)与[异步任务接口](https://api.hamubox.com/docs/novelai/tasks/)共用的参数说明。原生接口直接发送操作请求，异步接口将同一个操作请求放入 `payload`。先调用 `GET /v1/models` 确认当前本站 Key 可用的模型。

## 模型与功能

| 模型系列 | 普通模型 ID | 角色提示词 | 氛围参考 | 精准参考 | 生成过程 |
| --- | --- | --- | --- | --- | --- |
| V5 Curated / Full | `nai-diffusion-5-curated` / `nai-diffusion-5-full` | 支持 | 不支持 | 不支持 | 支持 |
| V4.5 Curated / Full | `nai-diffusion-4-5-curated` / `nai-diffusion-4-5-full` | 支持 | 使用编码 | 支持 | 支持 |
| V4 Curated / Full | `nai-diffusion-4-curated-preview` / `nai-diffusion-4-full` | 支持 | 使用编码 | 不支持 | 支持 |
| Anime V3 / Furry V3 | `nai-diffusion-3` / `nai-diffusion-furry-3` | 不支持 | 使用源图 | 不支持 | 不支持 |

以上系列均有文生图、图生图能力。局部重绘的实际模型按下表填写，不能随意拼接后缀。原生请求使用右列的 `model`；异步请求外层使用左列的 `model`，内层 `payload.model` 使用右列。

| 普通模型 / 异步外层 `model` | 局部重绘实际模型 |
| --- | --- |
| `nai-diffusion-5-full` | `nai-diffusion-5-full-inpainting` |
| `nai-diffusion-5-curated` | `nai-diffusion-4-5-curated-inpainting`，当前由 V4.5 Curated 执行 |
| `nai-diffusion-4-5-curated` / `nai-diffusion-4-5-full` | `nai-diffusion-4-5-curated-inpainting` / `nai-diffusion-4-5-full-inpainting` |
| `nai-diffusion-4-curated-preview` / `nai-diffusion-4-full` | `nai-diffusion-4-curated-inpainting` / `nai-diffusion-4-full-inpainting` |
| `nai-diffusion-3` / `nai-diffusion-furry-3` | `nai-diffusion-3-inpainting` / `nai-diffusion-furry-3-inpainting` |

可用性以当前 Key 的模型清单为准。V5 不接受氛围参考、精准参考、Variety+ 或 CFG Delay。角色提示词与图生图不是这两种参考功能，仍然可用。

## V5 Full 节约模式

V5 Full 可选择通常（High）或节约（Medium）。默认仍是通常模式；节约模式使用独立的蒸馏模型，不等同于把普通 V5 的步数减少到 14。

| 模式 | 原生请求 `model` / 异步 `payload.model` |
| --- | --- |
| 节约模式文生图、图生图 | `nai-diffusion-5-full-medium` |
| 节约模式局部重绘 | `nai-diffusion-5-full-medium-inpainting` |

异步请求外层 `model` 与 `payload.model` 均可填写上表对应的 Medium 模型 ID，任务、日志和返回结果会记录实际的 Medium 模型。授权、可用渠道与倍率仍沿用 `nai-diffusion-5-full`，不需要新增 Key 或另选分组。为兼容旧客户端，外层填写 `nai-diffusion-5-full`、内层填写对应 Medium ID 的方式仍然可用；V5 Curated 不支持节约模式。

- 固定 `parameters.steps: 14`、`parameters.sampler: "k_euler_ancestral"`；`cfg_rescale` 省略或为 `0`，不兼容的设置会在提交前拒绝。
- 使用官方固定 Heavy 负向预设，不支持自定义负面提示词或角色负面提示词。工作台会保留原输入，切回通常模式后恢复；需要抑制内容时可在正向提示词使用负权重，如 `-3::hat::`。
- 提示词引导强度、角色正向提示词、透明背景、图生图和局部重绘按 V5 Full 能力使用。流式接口也支持 Medium。
- 平台基础费和 Anlas 单价由站点配置，以报价接口返回的 `base_price_usd`、`anlas_unit_price_usd`、`group_ratio` 和 `estimated_cost_usd` 为准。默认普通生成及辅助操作基础费为 $0.003，V5 通常模式为 $0.01/张，V5 Full 节约模式为 $0.006/张，额外 Anlas 为 $0.004/Anlas，再应用生效倍率。实际结算采用提交时的价格快照，后续改价不影响已提交任务；BYOK 不收平台基础费及平台 Anlas 费用。官方宣称的使用额度节省比例不等于本站售价折扣。
- 当前仅由支持 Medium 的官方账户执行，不会自动替换成通常模型。平台官方可用额度不足时，提交可能被拒绝。

官方说明：[Effort 参数](https://docs.novelai.net/en/image/effort/)、[2026-10-08 公告](https://journal.novelai.net/novelai-diffusion-v5-full-effort-toggle/)。

### 提示词容量

NAI 工作台在提示词下方显示 token 用量和容量条。这是提示词上下文容量，不是计费 token，也不是可调的推理预算。

| 模型 | 提示词容量 |
| --- | --- |
| V5 Full（含节约模式） | 1471 token |
| V5 Curated | 703 token |
| V4 / V4.5 | 512 token |
| V3 | 225 token |

正向、负面提示词分别计算；支持角色的模型将基础提示词与实际提交的角色提示词合计，包含自动质量标签和负向预设。计算在本地浏览器的后台线程执行，不向外部发送提示词。

超出容量时会提示后段内容可能被模型忽略，但工作台不会截断输入，也不会修改 API 请求。容量提示参照官网当前编码器；复杂提示词的最终解释仍以上游模型为准。

## 生成参数

普通生成使用 `action: "generate"`，图生图使用 `"img2img"`，局部重绘使用 `"infill"`。通常模式异步文生图与图生图的外层 `model` 和 `payload.model` 一致；重绘及节约模式按上表填写。

| 操作请求内字段（异步时位于 `payload`） | 用途与边界 |
| --- | --- |
| `input` | 正向提示词 |
| `parameters.width` / `height` | 必填正整数，单位像素；总像素不超过 3,145,728。普通图生图必须为 64 的倍数，如 832×1216、1216×832、1024×1024；Max Enhance、局部重绘使用各自的尺寸规则 |
| `parameters.steps` | 必填，服务端边界为 0–50；通常使用 23 或 28 步，0 并不保证各模型可生成 |
| `parameters.n_samples` | 所有生成及报价入口均暂时只支持 1；省略时按单张估价，原生/异步透传不会自动补写此字段。建议显式传 `1`，需要多张时分别提交单张请求 |
| `parameters.params_version` | V5 使用 4，V4/V4.5/V3 示例采用 3 |
| `parameters.scale` | 提示词引导强度，例如 5；不是缩放图片倍数 |
| `parameters.sampler` / `noise_schedule` | 采样器与噪声计划，例如 `k_euler_ancestral` / `karras`；按模型支持情况传入 |
| `parameters.seed` | 具体的非负整数种子。需要随机时由客户端生成，不要照搬其他模型的 `-1` 约定 |
| `parameters.uc` | 负向提示词 |
| `parameters.image_format` | 流式请求可选 `png` / `webp`；未指定时主站流式默认请求 PNG |
| `parameters.image` / `mask` | 图生图源图、重绘遮罩；重绘需要两者，尺寸应与本次输入画布一致 |
| `parameters.strength` / `noise` | 图生图强度与噪声，通常在 0–1 内；按实际意图明确传值 |
| `parameters.img2img` | 图生图/重绘的 `strength`、`color_correct`；重绘还可传 `inpaintImg2ImgStrength` |

其他官方绘图参数保留在 `parameters` 对象中透传，显式 `0`、`false` 不会因默认值而被省略。透传不等于所有模型都支持同样参数；不要在 V5 请求中保留旧模型独有的参考或加速字段。

### 必填结构与提交校验

**即使没有角色提示词，普通 V5 和 V4.5 Full 文生图也需要结构化提示词。** 只发送 `input`、`uc`、宽高、步数和采样器并不完整。以下文生图行为已于 2026-10-13 至 14 日用官方上游实际生成验证：

| `action: "generate"` 的实际模型 | `v4_prompt` / `v4_negative_prompt` | 对象内部要求 |
| --- | --- | --- |
| V5 Full、V5 Curated、V4.5 Full | 两个对象都必填；分别省略会导致上游 HTTP 500 | 都必须包含对象 `caption` 和数组 `caption.char_captions` |
| V5 Full Medium | 实测允许省略任一完整对象 | 一旦传入对象，仍必须包含 `caption.char_captions`；省略内部数组会导致上游 HTTP 500 |

没有角色时使用 `char_captions: []`，不是 `null`、`{}`，也不要省略。平台在**创建任务、入队和预扣前**检查上述结构，缺失时返回 HTTP 400 与具体字段路径。同步和流式原生入口遵循相同规则，流尚未开始时仍返回 JSON 错误。

**普通图生图 `action: "img2img"` 也执行相同的提示词结构校验**：V5 Full、V5 Curated、V4.5 Full 必须提供两个对象；V5 Full Medium 允许省略完整对象，但传入时仍校验内部结构。此项补充用于防止不完整的图生图请求进入上游后仅返回笼统的 500；上表的逐项实测记录仍仅针对文生图，不表示每个图生图模型都已完成逐字段复测。其它模型、局部重绘以及 `upscaled_enhance: true` 的 Max Enhance 保留原来的提示词校验范围。

普通图生图的 `parameters.width` 和 `parameters.height` 必须是 **64 的正整数倍**。例如 `832×1110` 会在提交前返回 HTTP 400，明确指出 `parameters.height` 和收到的值 `1110`。请先将底图缩放或裁剪为所需合法尺寸，并填写对应宽高；平台不会自动缩放图片或静默修改尺寸。不要只依赖估价成功判断请求是否合法，报价仍允许按计费规则估算非对齐尺寸。Max Enhance、局部重绘、独立放大和 Director 不套用这项普通图生图限制。

V5 Full 最小文生图结构示例（原生请求直接发送；异步请求放入 `payload`）：

```json
{
  "model": "nai-diffusion-5-full",
  "action": "generate",
  "input": "1girl",
  "parameters": {
    "width": 512,
    "height": 512,
    "steps": 28,
    "n_samples": 1,
    "seed": 1,
    "scale": 5,
    "sampler": "k_euler_ancestral",
    "uc": "lowres",
    "v4_prompt": {
      "caption": { "base_caption": "1girl", "char_captions": [] }
    },
    "v4_negative_prompt": {
      "caption": { "base_caption": "lowres", "char_captions": [] }
    }
  }
}
```

这里需要区分三类参数，不能把所有参数缺失都解释为“官方必然返回 500”：

- **平台计费必填**：`width`、`height`、`steps`，用于预估和预扣；缺失会返回字段明确的 HTTP 400，不会提交生成。`model`、`action`、`parameters` 也必须完整，异步入口还要求外层 `model`、`operation`、`payload`。
- **已验证的上游结构要求**：上表中的提示词对象和角色数组。NAI 工作台已自动构造这些结构；直接对接 API 的客户端需要自己提供。OpenAI Images 兼容入口会从 `prompt`、`nai.uc` 构造结构，无需手工填写。
- **不要误判为必填**：普通 V5 Full 文生图实测可省略 `n_samples`；单独省略 `sampler`、`scale`、`seed` 或提示词位置开关也可以生成。省略这些会依赖上游默认行为，建议为可复现性明确传值。只有完整结构化提示词时，才可参考实测结果省略对应的 `input` / `uc`，不建议混用冲突的两份文案。

`params_version`、`noise_schedule`、`image_format` 在本次 V5 Full 非流式最小请求中未填写也能生成。这些结果不代表所有模型、所有模式都具有相同默认值。**估价成功不代表请求结构完整**：报价入口仍允许只传计费所需参数，正式提交前必须补齐生成字段。

### 角色提示词

V4、V4.5、V5 使用 `v4_prompt` 和 `v4_negative_prompt`，V5 的字段名仍为 `v4_prompt`。`caption.base_caption` 应与正向 `input`、负向 `uc` 各自一致。每个角色用 `char_captions` 的一个条目表示，正负向角色顺序对应：

```json
{
  "v4_prompt": {
    "caption": {
      "base_caption": "two characters, standing in a garden",
      "char_captions": [
        { "char_caption": "short blue hair, white jacket", "centers": [{ "x": 0.25, "y": 0.5 }] },
        { "char_caption": "long red hair, black jacket", "centers": [{ "x": 0.75, "y": 0.5 }] }
      ]
    },
    "use_coords": true,
    "use_order": true
  },
  "v4_negative_prompt": {
    "caption": {
      "base_caption": "lowres, blurry",
      "char_captions": [
        { "char_caption": "hat", "centers": [{ "x": 0.25, "y": 0.5 }] },
        { "char_caption": "glasses", "centers": [{ "x": 0.75, "y": 0.5 }] }
      ]
    },
    "use_coords": false,
    "use_order": false
  }
}
```

以上片段放入 `payload.parameters`。坐标为 0–1 的归一化位置；自动位置使用 `use_coords: false`。没有角色时传空 `char_captions` 即可。本站不替客户端自动拼接质量词或负向预设，最终完整提示词由请求决定。

### 素材输入与参考

`image`、`mask`、`director_reference_images[]` 可使用可访问的 HTTP(S) 图片 URL、图片 Data URL 或原始 Base64。不要传 `blob:` URL 或本地文件路径。提交后，服务端整理素材并转换成上游所需格式，日志保留文件引用，不写入整段图片 Base64。

第三方 URL 必须能由服务器直接下载图片，不依赖登录 Cookie、防盗链 Referer 或额外请求头。支持 PNG、JPEG、WebP、GIF、BMP；单份输入不超过 64 MiB，单次请求全部输入不超过 256 MiB，最多 32 份归档素材。外部图片会先下载、校验并归档，再参与生成；每份下载限时 30 秒，并检查重定向及网络访问安全。本站文件 URL 仍须属于当前用户且未删除，不能用外链下载绕过权限。

链接失效、下载失败、非图片或超限时返回 HTTP 400，错误码 `invalid_input_asset`，消息指出对应素材（如 `precise-reference input 1` 表示 `director_reference_images[0]`）。此时不会提交生成任务；若已预扣，将执行退还。第三方站点无法直连时，请先上传素材或改传 Data URL / Base64。文件存储或数据库故障仍返回 HTTP 500，不属于图片参数错误。

- **图生图 / 局部重绘**：使用 [图生图请求](https://api.hamubox.com/docs/examples/novelai-img2img.json) / [重绘请求](https://api.hamubox.com/docs/examples/novelai-inpaint.json)。图生图不能误用 `-inpainting` 模型。
- **V4/V4.5 氛围参考**：先以 `operation: "encode-vibe"` 提交[编码请求](https://api.hamubox.com/docs/examples/novelai-vibe.json)，再将 `result.encoded_vibe` 放入生成请求的 `parameters.reference_image_multiple[]`，以 `reference_strength_multiple[]` 对应设置强度。编码与模型相关，不要跨模型复用。编码是二进制数据的 Base64，并不是一张图片。
- **V3 氛围参考**：`reference_image_multiple[]` 使用源图片输入，推荐预处理成 448×448；同时传对应的 `reference_strength_multiple[]`、`reference_information_extracted_multiple[]`。不调用 `encode-vibe`。
- **V4.5 精准参考**：使用 `director_reference_images[]`，并对应传 `director_reference_descriptions[]`、`director_reference_strength_values[]`、`director_reference_secondary_strength_values[]` 和 `director_reference_information_extracted[]`。各数组按同一素材顺序对应。素材会由服务端预处理为模型需要的尺寸，留档保留原素材。

氛围参考、精准参考的当前任务计费边界各为最多 16 项，具体能否组合仍取决于模型。V5 两者均不支持。异步任务需要提供实际素材数据或文件地址；原生接口另支持 multipart 与按用户隔离的缓存键，见[官方协议兼容](https://api.hamubox.com/docs/novelai/native/#参考素材缓存)。

也可以先使用[素材上传接口](https://api.hamubox.com/docs/references/#上传素材)获得文件 URL，再填入 `parameters.image`、`parameters.mask` 或源图片数组。临时上传与用户资产库的可见范围见[常见问题](https://api.hamubox.com/docs/novelai/faq/#参考素材是否进入资产库)。

## Director、放大与氛围编码

### Enhance 增强

Enhance 属于图生图重采样，不是独立 Upscale。使用 `operation: "generation"`、`payload.action: "img2img"`，通过 `parameters.image`、`strength`、`noise` 和输出宽高控制；它会重新生成细节。

V5 还支持 `parameters.upscaled_enhance: true`（Max Enhance）：请求宽高保留输入尺寸，输出最多放大 2 倍并限制到 3,145,728 像素，按 32 像素对齐。估价按输出尺寸计算，不能用输入小图尺寸判断免费额度。该模式不能与局部重绘混用；最终实际尺寸以结果文件为准。

### 独立图像工具

这些操作不提供中间生成过程。异步入口通过 `operation` 区分，原生入口通过路径区分；请求内容相同，只有外层包装不同。

| 异步 `operation` | 原生路径（接在 `/v1/novelai` 后） | 操作参数 |
| --- | --- | --- |
| `director` | `/ai/augment-image` | `req_type`、`image`、`width`、`height`；工具可能另需 `prompt`、`defry`、`emotion` |
| `upscale` | `/ai/upscale` | `image`、`model`、`declared_blur_sigma`；固定 2 倍，输入不超过 3,145,728 像素。Base64 图片自动读取尺寸；旧参数 `width`、`height`、`scale=2` 仍可传入 |
| `encode-vibe` | `/ai/encode-vibe` | `model`、`image`、可选 `information_extracted`（大于 0 且不超过 1）；异步时 `model` 与外层一致 |

Director 的 `req_type` 支持 `bg-removal`、`declutter`、`declutter-keep-bubbles`、`lineart`、`sketch`、`colorize`、`emotion`。Director 和放大操作的外层 `model` 用于选择可用的 NovelAI 服务，不代表所有工具都由该绘图模型执行。

各操作均有独立的[原生请求示例](https://api.hamubox.com/docs/novelai/native/#完整请求示例)和[异步请求示例](https://api.hamubox.com/docs/novelai/tasks/#其它操作示例)。费用、结果元数据与留档见[常见问题](https://api.hamubox.com/docs/novelai/faq/)。


---

Source: https://api.hamubox.com/docs/novelai/native/

# 官方协议兼容

已有支持 NovelAI 绘图协议的客户端，可以配置以下地址和本站 API Key，继续使用官方请求字段。需要客户端允许自定义服务地址和 Bearer Token。

```text
Base URL: https://api.hamubox.com/v1/novelai
Authorization: Bearer sk-your-hamubox-api-key
```

Base URL 必须包含 `/v1/novelai`，客户端在其后追加官方原生路径，例如 `/ai/generate-image`。有的客户端分别配置 API 服务地址与图片服务地址，两处都填写上述地址。拼接地址时应保留此前缀，不能用站点根路径覆盖它。本站不接受 NovelAI 官网登录密码或 PST 作为本站鉴权，不代理官方登录、支付、故事、文本生成、语音或云端图片库；本章覆盖 V3、V4、V4.5、V5 的绘图协议。可用模型仍受本站 Key、分组与账号权限约束。

## 路径与格式

| 方法 | 本站完整路径 | 成功响应 |
| --- | --- | --- |
| POST | `/v1/novelai/ai/generate-image` | `application/zip`，单张生成图片 |
| POST | `/v1/novelai/ai/generate-image-stream` | `application/msgpack`，长度帧事件；见[流式协议](https://api.hamubox.com/docs/novelai/streaming/) |
| POST | `/v1/novelai/ai/augment-image` | `application/zip`，Director 处理结果 |
| POST | `/v1/novelai/ai/upscale` | `application/zip`，放大结果 |
| POST | `/v1/novelai/ai/encode-vibe` | 原始编码二进制，不是图片、JSON 或 Base64 文本 |
| POST | `/v1/novelai/ai/generate-image/request-price` | `costPerPrompt`、`numPrompts`、`freePrompts` 等报价字段 |
| GET | `/v1/novelai/ai/generate-image/suggest-tags?model=...&prompt=...` | 原始标签建议 JSON |
| GET | `/v1/novelai/user/data` | 兼容的 `subscription`、`priority` 与本站余额说明 |
| GET | `/v1/novelai/user/subscription` | 兼容的订阅字段 |
| GET | `/v1/novelai/user/priority` | 兼容的优先级字段 |

柏宝绘等客户端误加 `/ai` 前缀的 `GET /v1/novelai/ai/user/subscription` 也可用，与正常订阅路径返回相同结构并要求本站 API Key；这不是官方账户路径，也不代表其他 `/ai/user/*` 路径可用。

同步生图与报价入口兼容部分客户端固定发送的 `parameters.stream: "msgpack"`，忽略该传输提示，分别保持 ZIP 和 JSON 响应。真正的流式生成请使用 `/ai/generate-image-stream`。其他无效 `stream` 值仍会拒绝；异步任务接口中的 `stream: false` 与 `parameters.stream: "msgpack"` 仍视为冲突。

`generate-image` 和 `generate-image-stream` 提交前都会执行[生成结构校验](https://api.hamubox.com/docs/novelai/models/#必填结构与提交校验)。普通 V5 / V4.5 Full 文生图不能只传 `input`：还需要两个结构化提示词对象，没有角色时 `caption.char_captions` 填 `[]`。`request-price` 仍可只传计费所需参数，报价成功不代表生成字段完整。此区别也适用于酒馆插件等第三方客户端；不需要为了报价虚构提示词。

## 完整请求示例

原生生成请求**不加** `operation`、`payload` 包装。下载[原生文生图 JSON](https://api.hamubox.com/docs/examples/novelai-native-generate.json)后直接发送：

```json title="novelai-native-generate.json"
{
  "model": "nai-diffusion-5-curated",
  "input": "a blue ceramic cup on a wooden table, soft daylight, illustration",
  "action": "generate",
  "parameters": {
    "params_version": 4,
    "width": 832,
    "height": 1216,
    "steps": 23,
    "scale": 5,
    "sampler": "k_euler_ancestral",
    "noise_schedule": "karras",
    "seed": 42,
    "n_samples": 1,
    "image_format": "png",
    "uc": "lowres, blurry",
    "v4_prompt": {
      "caption": {
        "base_caption": "a blue ceramic cup on a wooden table, soft daylight, illustration",
        "char_captions": []
      },
      "use_coords": false,
      "use_order": true
    },
    "v4_negative_prompt": {
      "caption": {
        "base_caption": "lowres, blurry",
        "char_captions": []
      },
      "use_coords": false,
      "use_order": false
    }
  }
}
```

```bash
curl --fail-with-body 'https://api.hamubox.com/v1/novelai/ai/generate-image' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @novelai-native-generate.json \
  --dump-header result-headers.txt --output result.zip
```

以下下载均为完整原生请求体。素材示例中的 `https://example.com/...` 需替换为实际文件直链，不能直接用于生成。

| 操作 | 请求路径 | 请求 JSON | 成功内容 |
| --- | --- | --- | --- |
| 图生图 | `/v1/novelai/ai/generate-image` | [novelai-native-img2img.json](https://api.hamubox.com/docs/examples/novelai-native-img2img.json) | ZIP |
| 局部重绘 | `/v1/novelai/ai/generate-image` | [novelai-native-inpaint.json](https://api.hamubox.com/docs/examples/novelai-native-inpaint.json) | ZIP |
| Director 提取线稿 | `/v1/novelai/ai/augment-image` | [novelai-native-director.json](https://api.hamubox.com/docs/examples/novelai-native-director.json) | ZIP |
| 放大 | `/v1/novelai/ai/upscale` | [novelai-native-upscale.json](https://api.hamubox.com/docs/examples/novelai-native-upscale.json) | ZIP |
| 氛围编码 | `/v1/novelai/ai/encode-vibe` | [novelai-native-vibe.json](https://api.hamubox.com/docs/examples/novelai-native-vibe.json) | 编码二进制 |

例如放大请求：

```bash
curl --fail-with-body 'https://api.hamubox.com/v1/novelai/ai/upscale' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @novelai-native-upscale.json \
  --dump-header result-headers.txt --output result.zip
```

图生图、局部重绘、角色提示词等按共用的[绘图参数](https://api.hamubox.com/docs/novelai/models/)填写。原生局部重绘的 `model` 填写实际 inpainting 模型；V5 Curated 对应 `nai-diffusion-4-5-curated-inpainting`。

Director/Upscale 官方请求不要求模型；本站从当前 Key 已开放的 NAI 模型中选择路由，也支持额外提供 `model` 明确指定，下载示例采用后一种方式。JSON 与官方 `multipart/form-data` 均可用：`request` 为 JSON 或 JSON Blob，素材字段引用其余二进制 part 的名称，见[完整 multipart 示例](https://api.hamubox.com/docs/novelai/streaming/#multipart-素材)。显式 `0`、`false`、专业参数与未知绘图参数不会因兼容转换而丢失。

## 生成张数与费用

本站暂时仅支持每次生成一张图片，原生普通接口、流式接口、报价接口及异步任务入口均相同。`parameters.n_samples` 可以省略（默认 1），填写时必须为 `1`。其他张数会在发起生成和预扣前返回 HTTP 400，不会自动截成一张，也不会拆成多个请求。

需要多张图片时，由客户端分别发起单张请求；每次请求独立排队、计费并记录任务 ID。这样可以避免一次批量生成引入额外 Anlas 费用，但高分辨率、步数和参考功能等仍可能产生费用。

普通响应仍使用官方 ZIP 格式，流式成品帧保留 `samp_ix` 字段。基础费用按单张收取，Anlas 按实际消耗结算；使用相同的用户余额、NAI 点数、Key 限额和分组倍率。

## 参考素材缓存

支持 `image_cache_secret_key`、`mask_cache_secret_key`、`reference_image_cache_secret_key`，以及 `reference_image_multiple_cached[]`、`director_reference_images_cached[]` 中的 `cache_secret_key`。

Vibe 和精准参考的普通 / 缓存数组为 `[]`、`null` 或省略时，表示没有参考图；非空数组仍校验模型能力。V5 目前不支持这两类参考，不能通过填写零计数来绕过限制。

首次请求同时带素材数据和缓存键。素材进入本站文件服务后，只缓存其文件地址，缓存按本站用户隔离、有效期一小时，容量不足或服务重启也可能提前失效。后续可只提交缓存键，本站恢复素材后再交给本次调度的账号，不依赖上一次使用的上游账号。

缓存失效时，生成尚未提交，响应为 HTTP 400：

```json
{
  "statusCode": 400,
  "message": "INVALID_CACHE_KEYS",
  "error": "INVALID_CACHE_KEYS",
  "details": {"invalidKeys": ["the-client-cache-key"]}
}
```

客户端补传这些键对应的原始素材即可。缓存键不写入任务参数或日志，也不会转发给上游。

## 账户与报价

`/v1/novelai/user/data`、`/v1/novelai/user/subscription` 返回的是**本站虚拟兼容账户**。`tier: 3` 用于让客户端显示绘图功能，不代表赠送官方会员、免费生成或展示平台上游账号。不会返回平台账号的真实 Anlas、V5 电量或会员到期时间。

`trainingStepsLeft.purchasedTrainingSteps` 按 **1000 个兼容显示单位 = 1 美元**换算本站可用余额和已启用的 NAI 点数，并受当前 Key 额度上限约束。某些客户端会把此字段标为 Anlas；它不是官方 Anlas。订阅等特殊资金来源的实际可用额，以本站预扣检查为准。

报价请求保留官方形状：

```json
{
  "tier": "OPUS",
  "request": {
    "input": "a blue ceramic cup",
    "model": "nai-diffusion-5-curated",
    "action": "generate",
    "parameters": {"width": 832, "height": 1216, "steps": 23, "n_samples": 1}
  }
}
```

响应的 `costPerPrompt` 使用同一套兼容显示单位，包含本站基础费用和实际倍率；向上取整后的显示值可能略高于实际预估。`numPrompts` 为 1，`freePrompts` 为 0；调用方传入的 `tier` 不改变售价。扩展字段 `hamubox.estimatedCostUSD` 提供准确的美元预估，最终费用见任务的 `usage.actual_cost_usd`。

## 留档与中断恢复

原生生成仍创建任务日志并保存参考素材和结果，资产库与任务详情的展示规则见[常见问题](https://api.hamubox.com/docs/novelai/faq/#参考素材是否进入资产库)。返回头 `X-NovelAI-Task-Id` 可用于 [GET 任务接口](https://api.hamubox.com/docs/novelai/tasks/#查询与恢复)查询结果和结算，客户端只能查询自己所属用户的任务。

成图校验后优先交付客户端，后台继续转存和结算。临时快速交付缓存最多保留十分钟；结果超过 32 MiB 或缓存不可用时，等待持久化后交付。PNG 元数据会保留或补齐，显式 WebP 保留原始格式。

客户端断线不会取消已提交任务。同步连接最长等待十分钟；超时并不证明任务失败，必须先查已有任务。不要自动重发 POST，以免重复生成和计费。原生错误使用 `statusCode`、`message`、字符串 `error`；流式开始后的错误使用流内 `error` 事件。

例如缺少负向提示词对象时，提交前返回 HTTP 400，不预扣、不创建生成任务；`message` 与 `error` 保持相同字符串，便于原生客户端展示：

```json
{
  "statusCode": 400,
  "message": "invalid NovelAI generation parameters: parameters.v4_negative_prompt is required; provide caption.char_captions: [] when there are no characters",
  "error": "invalid NovelAI generation parameters: parameters.v4_negative_prompt is required; provide caption.char_captions: [] when there are no characters"
}
```


---

Source: https://api.hamubox.com/docs/novelai/openai-images/

# OpenAI Images 兼容

适合只能发送 OpenAI Images 格式的图片客户端。Base URL 为 `https://api.hamubox.com/v1`，生成端点为 `POST /v1/images/generations`。使用本站 API Key，并从 `/v1/models` 选择已开放的 NAI 模型。

## 请求

```json
{
  "model": "nai-diffusion-5-full",
  "prompt": "a blue ceramic cup, soft daylight, illustration",
  "size": "832x1216",
  "n": 1,
  "response_format": "url",
  "nai": {
    "uc": "lowres, blurry",
    "steps": 28,
    "scale": 5,
    "seed": 42,
    "sampler": "k_euler_ancestral"
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `model` | 必填，NAI 文生图模型 ID；如 `nai-diffusion-5-full`、`nai-diffusion-4-5-full`。 |
| `prompt` | 必填，完整主提示词；同时写入角色格式中的主提示词。 |
| `size` | `宽x高`，两边为 64 的倍数，总像素不超过 3,145,728。省略或 `auto` 时使用 `nai.width` / `nai.height`，未指定边默认 1024。这里的 `auto` 不表示智能推断比例。 |
| `n` | 省略或 1。其它值在生成和预扣前拒绝。 |
| `response_format` | `url`（默认）或 `b64_json`。 |
| `nai` | 官方 `parameters` 对象。可设置 `uc`、`steps`、`scale`、`sampler`、`noise_schedule`、`seed` 及角色参数等；显式的 0 和 false 保留。 |

默认 28 步、CFG 5、`k_euler_ancestral`、`karras`、PNG。未指定 Seed 时在任务首次接受时生成随机 Seed；网络重试复用任务，不重新随机。`size` 与 `nai.width` / `nai.height` 同时指定时必须一致。`nai.n_samples` 也只能为 1。

角色提示词可放在 `nai.v4_prompt.caption.char_captions` 与 `nai.v4_negative_prompt.caption.char_captions`，格式见[角色参数](https://api.hamubox.com/docs/novelai/models/)。`prompt` 和 `nai.uc` 决定对应的主提示词，角色内容保留。

这里仅提供文生图兼容，不映射 OpenAI 的 `quality`、`style` 等参数。图生图、遮罩、官方 multipart 缓存和生成过程流请使用[原生接口](https://api.hamubox.com/docs/novelai/native/)或[任务接口](https://api.hamubox.com/docs/novelai/tasks/)。V5 的氛围与精准参考限制仍然生效。

## 返回与恢复

```json
{
  "created": 1790000000,
  "data": [{ "url": "https://img.hamubox.com/file/novelai-task-result/image/example.png" }]
}
```

选择 `b64_json` 时每项改为 `{"b64_json":"..."}`，内容是原图片字节的 Base64，保留 PNG 提示词元数据；不会把 Data URL 放进 `url` 字段。响应在结果保存完成后返回，使用与 NAI 工作台相同的任务、预扣、结算和资产保存流程。

同步等待最多 10 分钟；客户端断开不会取消后台任务。保存 `X-NovelAI-Task-Id`，通过 `GET /v1/novelai/tasks/{task_id}` 恢复。推荐每次用户生成都提供新的 `Idempotency-Key`，网络重试保留同一个值和请求，详见[幂等提交](https://api.hamubox.com/docs/novelai/tasks/#幂等提交)。下载结果 URL 时不要携带本站 Key。


---

Source: https://api.hamubox.com/docs/novelai/overview/

# NovelAI 接入概览

NovelAI 提供专业绘图参数、角色提示词、图生图、局部重绘和图片工具，使用独立的 `/v1/novelai` 接口。它不通过通用的 `/v1/image/generations` 提交。

## 选择接入方式

| 场景 | 使用方式 | 从这里开始 |
| --- | --- | --- |
| 已有支持 NovelAI 的第三方客户端 | 替换服务地址和 Key，保留官方请求字段与 ZIP / 二进制响应 | [客户端接入](https://api.hamubox.com/docs/novelai/clients/) |
| 自行开发应用，需要任务 ID、轮询与稳定结果链接 | 提交异步任务，再查询状态与结算 | [异步任务接口](https://api.hamubox.com/docs/novelai/tasks/) |
| 需要边生成边预览，尽早收到完整成图 | 异步任务加 SSE，或官方格式 MessagePack 流 | [流式生成与恢复](https://api.hamubox.com/docs/novelai/streaming/) |

两套协议使用同一套模型、计费与结果留存。绘图参数集中在[模型与绘图参数](https://api.hamubox.com/docs/novelai/models/)维护；各协议章节提供各自完整的请求示例。

## 地址与鉴权

第三方原生客户端配置：

```text
Base URL: https://api.hamubox.com/v1/novelai
API Key: 本站创建的 API Key
```

客户端在 Base URL 后追加官方路径。例如 `/ai/generate-image` 的最终地址是：

```text
https://api.hamubox.com/v1/novelai/ai/generate-image
```

所有请求携带 `Authorization: Bearer <本站 API Key>`。不要填写 NovelAI 官网密码或 `pst-…` 密钥。异步接入直接使用本章给出的完整路径，不要重复拼接 `/v1/novelai`。

先确认当前 Key 可用的模型：

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

## 接入范围

支持 V3、V4、V4.5、V5 的绘图操作与已列出的原生路径，包括生成、Director Tools、放大、氛围编码、标签建议、报价和客户端账户显示兼容。不同模型的功能不完全相同，以[能力表](https://api.hamubox.com/docs/novelai/models/#模型与功能)和当前 Key 的模型清单为准。

不代理 NovelAI 登录、支付、故事、文本生成、语音或云端图片库。账户接口返回本站的兼容显示信息，不返回平台上游账号的余额、电量或会员信息。

每次生成暂时只支持一张；`n_samples` 省略或填 `1`。需要多张时分别提交，详情见[生成张数](https://api.hamubox.com/docs/novelai/native/#生成张数与费用)。

## 接入前需要处理的边界

- 素材可用文件 URL、受支持的 Base64 / Data URL 或原生 multipart；临时上传、有效期与可见范围见[参考素材](https://api.hamubox.com/docs/references/)。
- 提交后立即保存任务 ID；原生请求读取 `X-NovelAI-Task-Id` 响应头。断线后查询同一任务，不自动重复 POST。
- 原生流是长度帧 MessagePack；异步事件是 SSE。两者的解析器不能混用。
- 收到完整成图即可展示，但稳定文件链接和最终费用仍以任务查询为准。

给自动化工具或 LLM 接入时，提供[OpenAPI](https://api.hamubox.com/docs/openapi.json)和[文档索引](https://api.hamubox.com/docs/llms.txt)。常见的单位、缓存和素材保存问题集中在[常见问题](https://api.hamubox.com/docs/novelai/faq/)。


---

Source: https://api.hamubox.com/docs/novelai/streaming/

# 流式生成与恢复

本站提供两种流式接法。新应用建议使用异步任务加 SSE，方便持久化任务 ID 和断线恢复；已有支持官方流式格式的客户端可以使用 `/v1/novelai/ai/generate-image-stream`，客户端 Base URL 填写 `https://api.hamubox.com/v1/novelai`。

两者都使用本站 API Key。仅 V4、V4.5、V5 的生成操作可用，每次请求只生成一张，`parameters.n_samples` 省略或填写 `1`；模型和参数限制见[模型与绘图参数](https://api.hamubox.com/docs/novelai/models/)。V3、Director、放大和氛围编码不提供中间生成过程。

## 异步任务加 SSE

按[异步任务示例](https://api.hamubox.com/docs/novelai/tasks/#提交任务)先 POST `/v1/novelai/tasks`，请求顶层添加 `"stream": true`；立即保存 HTTP 202 返回的 `id`。随后订阅：

```bash
curl --no-buffer --fail-with-body \
  'https://api.hamubox.com/v1/novelai/tasks/task_your_existing_id/events' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Accept: text/event-stream'
```

响应为 `text/event-stream`，事件的 `data` 是 JSON：

| 事件 | `data` 内容 | 客户端处理 |
| --- | --- | --- |
| `state` | 与 GET 任务相同的完整响应 | 更新状态；`completed` / `failed` 停止订阅 |
| `preview` | `step`、`sample`、`image`（图片 Data URL） | 临时预览，不能当成最终结果 |
| `image` | `sample`、`filename`、`image`（完整成图 Data URL） | 可立即清晰显示和下载；继续等待归档/结算状态 |

`step`、`sample` 从 0 开始。以 `:` 开头的注释是心跳。中间帧可能被合并或跳过，不保证每一步都有事件；没有预览也不表示生成失败。只做状态订阅而未在提交时开启 `stream`，不会把普通任务变成流式生成。

浏览器原生 `EventSource` 不能直接设置 Authorization 请求头，建议使用 `fetch` 读取响应流并按 SSE 规则解析。不要把 API Key 放进 URL。支持跨网络 chunk 累积文本，遇到空行才结束一个事件，最终图的 Data URL 可能很长。

## 官方格式入口

POST `/v1/novelai/ai/generate-image-stream` 使用官方生成 JSON，**不包含**异步接口的 `payload`、`operation` 外层包装：

```json title="novelai-native-stream.json"
{
  "input": "a blue ceramic cup on a wooden table, soft daylight, illustration",
  "model": "nai-diffusion-5-curated",
  "action": "generate",
  "parameters": {
    "params_version": 4,
    "width": 832,
    "height": 1216,
    "steps": 23,
    "scale": 5,
    "sampler": "k_euler_ancestral",
    "noise_schedule": "karras",
    "seed": 42,
    "n_samples": 1,
    "stream": "msgpack",
    "image_format": "png",
    "uc": "lowres, blurry",
    "v4_prompt": {
      "caption": {
        "base_caption": "a blue ceramic cup on a wooden table, soft daylight, illustration",
        "char_captions": []
      },
      "use_coords": false,
      "use_order": true
    },
    "v4_negative_prompt": {
      "caption": {
        "base_caption": "lowres, blurry",
        "char_captions": []
      },
      "use_coords": false,
      "use_order": false
    }
  }
}
```

```bash
curl --fail-with-body --no-buffer \
  'https://api.hamubox.com/v1/novelai/ai/generate-image-stream' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @novelai-native-stream.json \
  --dump-header stream-headers.txt --output result.msgpack
```

`result.msgpack` 是带长度帧的事件流，**不是 PNG，也不是 ZIP**。不要直接改名成图片。

服务端在响应头 `X-NovelAI-Task-Id` 中返回本站任务 ID。客户端应在读图片前就保存它，以便查询 `/v1/novelai/tasks/{task_id}`。本站原生入口也会创建任务记录，并使用相同的计费、留档和资产入库流程。

### Multipart 素材

支持 `multipart/form-data`：`request` 字段为 JSON 文本或 JSON Blob，其余字段是图片文件。JSON 中的 `parameters.image` / `mask` 指向对应字段名，例如：

```json title="request.json"
{
  "input": "a blue ceramic cup, watercolor illustration",
  "model": "nai-diffusion-5-curated",
  "action": "img2img",
  "parameters": {
    "params_version": 4,
    "width": 832,
    "height": 1216,
    "steps": 23,
    "scale": 5,
    "sampler": "k_euler_ancestral",
    "noise_schedule": "karras",
    "seed": 42,
    "n_samples": 1,
    "stream": "msgpack",
    "image_format": "png",
    "image": "source_image",
    "strength": 0.6,
    "noise": 0
  }
}
```

```bash
curl --fail-with-body --no-buffer \
  'https://api.hamubox.com/v1/novelai/ai/generate-image-stream' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -F 'request=@request.json;type=application/json' \
  -F 'source_image=@source.png;type=image/png' \
  --dump-header stream-headers.txt --output result.msgpack
```

V4/V4.5 的 `reference_image_multiple_cached[]`、`director_reference_images_cached[]` 支持 `data` 和 `cache_secret_key`。首次带数据，后续可以只带缓存键；缓存按本站用户隔离，失效时按官方格式返回 `INVALID_CACHE_KEYS`，客户端应补传素材。普通数组也支持 multipart 字段引用。不能同时发送同一数组的普通字段和 `_cached` 字段，详见[原生接口](https://api.hamubox.com/docs/novelai/native/#参考素材缓存)。

### MessagePack 帧格式

响应 `Content-Type: application/msgpack`，每一帧为：

```text
4 字节无符号大端长度 N | N 字节 MessagePack map
```

| `event_type` | 字段 | 含义 |
| --- | --- | --- |
| `intermediate` | `image` 二进制、`samp_ix`、`step_ix` | 中间图，通常为 JPEG |
| `final` | `image` 二进制、`samp_ix` | 完整最终图；按实际文件格式解析 |
| `error` | `message` | 流内错误，不能只检查 HTTP 200 |
| `heartbeat` | 可忽略其他字段 | 保持连接 |

`image` 在这个入口中是 MessagePack 的二进制值，**不是 Base64**。只有上述 SSE 的图片字段使用 Data URL。网络 chunk 可能只包含半帧，也可能包含多帧，必须精确累计长度；主站当前单帧上限为 32 MiB。

收到完整 `final` 后即可展示或保存该图片，不需要等连接自然 EOF。尚未收到完整成品帧就遇到 EOF、截断、错误事件，不能把预览当作生成成功。

### Python 示例

[下载 novelai-stream.py](https://api.hamubox.com/docs/examples/novelai-stream.py)，需要 Python 3.10+ 和 `msgpack`：

```bash
python -m pip install msgpack
export HAMUBOX_API_KEY='sk-your-api-key'
python novelai-stream.py novelai-native-stream.json --output result.png
```

此 Python 示例面向 `n_samples: 1`，不自动重试 POST。它先保存不含 Key 的任务 ID 文件，再解析长度帧，将最终图原样写入磁盘。请求 WebP 时使用 `.webp` 文件名。需要稳定结果 URL 与最终费用时，用[异步客户端](https://api.hamubox.com/docs/examples/client.py)继续查询：

```bash
python client.py novelai --task-id task_your_existing_id
```

## 成图、元数据与恢复

未指定 `parameters.image_format` 时，主站流式请求默认向上游请求 PNG；显式 `webp` 不强制转码。已验证 V5 可直接流式返回带生成元数据的 PNG。中间 JPEG 的格式不受最终格式选项约束。

最终图片收齐并校验后，优先通过 `image` / `final` 交付；后台仍会完成存储和结算。快速交付缓存上限为每批结果 32 MiB；超限或缓存不可用时等待持久化后交付。成图中的既有元数据保留，PNG 缺失时补充；实时交付与后续转存使用相同的处理后字节。不要把提前收到图片等同于持久化成功，最终状态和实际费用以任务查询为准，流式响应 Trailer 可能没有尚未完成的结算值。

| 情况 | 恢复方式 |
| --- | --- |
| 浏览器、客户端到本站的连接断开 | 后台任务继续；用保存的任务 ID 查询，也可重新 GET SSE |
| SSE 重连时没有旧预览或成图事件 | 正常查询任务；实时缓存只临时保留，不保证事件历史重放，不支持 `Last-Event-ID` 精确续播 |
| 收到成图但任务仍在进行 | 可以展示和下载，同时等待同一任务的稳定链接与结算 |
| 收到成图后转存失败 | 显示任务错误；保留本地已收到的图片，不要自动重新生成 |
| 本站与上游之间的流在完整成图到达前中断 | 不保证找回成图；当前官方流式协议没有可凭本站任务 ID 再取原图的补查接口 |
| 连接已结束但没有成图 | 先查原任务，不能直接判定需要重发付费请求 |

SSE/原生流单连接最长等待 10 分钟，到时结束连接并不取消后台任务。客户端超时也不取消任务。中间图不做持久化；最终图的临时缓存不可替代文件归档。不要把 Base64 图片、API Key 或完整二进制流写进应用日志。


---

Source: https://api.hamubox.com/docs/novelai/tasks/

# 异步任务接口

自行开发应用时，推荐提交任务后查询结果；需要生成过程时再增加 SSE。鉴权使用本站 API Key，所有请求均携带 Bearer Token。

| 方法 | 路径 | 返回 |
| --- | --- | --- |
| POST | `/v1/novelai/estimate` | 费用预估，不创建生成任务 |
| POST | `/v1/novelai/tasks` | HTTP 202，返回任务 ID |
| GET | `/v1/novelai/tasks/{task_id}` | 状态、错误、文件与结算信息 |
| GET | `/v1/novelai/tasks/{task_id}/events` | SSE 状态、预览和成图事件 |

## 提交任务

请求外层是本站任务格式；`payload` 是对应的官方操作请求。通用的[绘图参数](https://api.hamubox.com/docs/novelai/models/)放在 `payload.parameters`，不要放到外层。

| 字段 | 说明 |
| --- | --- |
| `model` | 必填。当前 Key 可用的 NovelAI 模型 ID |
| `operation` | 必填。`generation`、`director`、`upscale` 或 `encode-vibe` |
| `payload` | 必填。对应操作的完整请求对象 |
| `stream` | 可选布尔值，默认关闭。仅 V4 及更新模型的 `generation` 可用；POST 仍返回 JSON 任务 |

V5 单图示例，开启生成过程。下载[novelai-generate.json](https://api.hamubox.com/docs/examples/novelai-generate.json)后直接发送：

```json title="novelai-generate.json"
{
  "model": "nai-diffusion-5-curated",
  "operation": "generation",
  "stream": true,
  "payload": {
    "input": "a blue ceramic cup on a wooden table, soft daylight, illustration",
    "model": "nai-diffusion-5-curated",
    "action": "generate",
    "parameters": {
      "params_version": 4,
      "width": 832,
      "height": 1216,
      "steps": 23,
      "scale": 5,
      "sampler": "k_euler_ancestral",
      "noise_schedule": "karras",
      "seed": 42,
      "n_samples": 1,
      "image_format": "png",
      "uc": "lowres, blurry",
      "v4_prompt": {
        "caption": {
          "base_caption": "a blue ceramic cup on a wooden table, soft daylight, illustration",
          "char_captions": []
        },
        "use_coords": false,
        "use_order": true
      },
      "v4_negative_prompt": {
        "caption": {
          "base_caption": "lowres, blurry",
          "char_captions": []
        },
        "use_coords": false,
        "use_order": false
      }
    }
  }
}
```

```bash
curl --fail-with-body 'https://api.hamubox.com/v1/novelai/tasks' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @novelai-generate.json
```

HTTP 202 示例，服务端还可能返回 `usage` 等字段：

```json
{
  "id": "task_your_existing_id",
  "object": "novelai.image.task",
  "created_at": 1790000000,
  "updated_at": 1790000000,
  "status": "queued",
  "progress": 0,
  "model": "nai-diffusion-5-curated",
  "operation": "generation"
}
```

开启 `stream` 不会让这个 POST 变成 SSE。保存 `id` 后再[订阅事件](https://api.hamubox.com/docs/novelai/streaming/#异步任务加-sse)。

### 参数错误

可提前识别的错误在入队、预扣前返回 HTTP 400，不创建任务。例如请求已包含正向结构，但漏掉负向结构：

```json
{
  "error": {
    "code": "invalid_request",
    "type": "novelai_error",
    "message": "invalid NovelAI generation parameters: parameters.v4_negative_prompt is required; provide caption.char_captions: [] when there are no characters"
  }
}
```

错误里的 `parameters.*` 指 `payload.parameters.*`。例如 `parameters.v4_prompt.caption.char_captions must be an array` 表示应补上角色数组，没有角色时填写 `[]`；`missing required pricing parameters: parameters.steps` 表示缺少用于计费的步数。

修正字段后再提交，不要原样自动重试 400。模型范围、节约模式例外与完整结构见[必填结构与提交校验](https://api.hamubox.com/docs/novelai/models/#必填结构与提交校验)。已被接受的任务若后续失败，仍通过任务查询返回 `failed`，不要将其与提交前拒绝混淆。

## 查询与恢复

每隔 5 秒查询同一个任务：

```bash
curl --fail-with-body \
  'https://api.hamubox.com/v1/novelai/tasks/task_your_existing_id' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"
```

| `status` | 客户端行为 |
| --- | --- |
| `queued` / `in_progress` | 继续等待；也可以订阅 SSE |
| `completed` | 停止查询；图片读取 `result.images[].url`，氛围编码读取 `result.encoded_vibe` |
| `failed` | 停止查询，展示 `error.message`，保留 `id` 和 `error.code` |
| `unknown` | 不当作成功或失败；保留任务 ID，稍后查询或联系支持 |

图片文件对象包含 `id`、`url`、`filename`、`mime_type`、`size`，可能还包含 `md5`。这与通用图片接口的 `outputs[]` 不同。读取结果 URL 时不要携带本站 Authorization。最终图片进入发起用户的资产库，中间预览不入库。

刷新、断线或切换页面后，继续查询同一个任务。通过原生接口或 OpenAI Images 兼容入口提交时，保存响应头 `X-NovelAI-Task-Id`，也能在这里查询。客户端断开连接不会取消已接受的任务。

排队等待默认最多 10 分钟，管理员可以在 NAI 运营设置中调整。达到等待上限仍未开始的任务返回 `failed` / `queue_timeout`，退回预扣；执行中的任务使用单独的运行超时。

## 幂等提交

提交任务、原生生成及 OpenAI Images 兼容入口均接受可选的 `Idempotency-Key` 请求头。每次用户主动生成时创建一个新值；网络重试保留原值与原请求内容，最多 128 字节。

```bash
curl --fail-with-body 'https://api.hamubox.com/v1/novelai/tasks' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-unique-image-request-001' \
  --data-binary @novelai-generate.json
```

- 相同用户、操作、标识和请求内容：取回原任务或原结果，不再次生成或预扣。分组、模型、素材、提示词及参数变化会视为不同内容。
- 同一标识对应不同内容：HTTP 409，`idempotency_conflict`。
- 首次请求尚在准备中：HTTP 409，`idempotency_in_progress`，按 `Retry-After` 等待后用同一标识重试。若长时间未能确认是否接受，请保留标识与任务 ID 联系支持，不要换标识重复生成。
- 首次请求在任务接受前已失败：HTTP 409，`idempotency_rejected`。先解决原错误，再由用户主动发起新的生成。
- 原任务已失败：仍返回原任务的失败状态；重新生成必须使用新的标识。

不提供此请求头的旧客户端仍按每次 POST 创建任务。不能仅依靠相同提示词去重，因为用户可能确实希望连续生成多张。原生错误继续使用其原有的字符串错误格式。

## 费用预估

同一个完整请求可先发送到估价接口：

```bash
curl --fail-with-body 'https://api.hamubox.com/v1/novelai/estimate' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @novelai-generate.json
```

读取 `usage.estimated_cost_usd` 与 `usage.estimated_anlas`。估价不启动生成，不代表锁定报价。正式任务提交时预扣，终态返回 `usage.actual_cost_usd` 等结算信息；尚未返回的字段不能当作零。Anlas 与本站美元余额是不同单位，免费 Anlas 不表示本站服务免费。

报价接口也兼容只包含计费参数的请求，不要求完整的 `v4_prompt` / `v4_negative_prompt`。**获得报价不代表请求可直接生成**；提交到 `/tasks` 前仍需补齐对应模型的提示词结构。

## 其它操作示例

下列文件都包含完整的 `model`、`operation`、`payload`，可使用上面的提交命令，替换 JSON 文件名即可。需要素材的示例先将 `https://example.com/...` 替换为可访问的真实文件 URL。

| 操作 | 请求 JSON | 成功结果 |
| --- | --- | --- |
| 图生图 | [novelai-img2img.json](https://api.hamubox.com/docs/examples/novelai-img2img.json) | `result.images[]` |
| 局部重绘 | [novelai-inpaint.json](https://api.hamubox.com/docs/examples/novelai-inpaint.json) | `result.images[]` |
| Director 提取线稿 | [novelai-director.json](https://api.hamubox.com/docs/examples/novelai-director.json) | `result.images[]` |
| 放大 | [novelai-upscale.json](https://api.hamubox.com/docs/examples/novelai-upscale.json) | `result.images[]` |
| 氛围编码 | [novelai-vibe.json](https://api.hamubox.com/docs/examples/novelai-vibe.json) | `result.encoded_vibe`，编码二进制的 Base64，不是图片 |

Director、放大与氛围编码不支持 `stream`。模型能力、素材字段、角色提示词和操作边界统一见[模型与绘图参数](https://api.hamubox.com/docs/novelai/models/)。

也可以使用[Python 异步客户端](https://api.hamubox.com/docs/examples/client.py)：

```bash
python client.py novelai novelai-generate.json
python client.py novelai --task-id task_your_existing_id
```


---

Source: https://api.hamubox.com/docs/quickstart/

# 快速开始

## 1. 准备 API Key

在控制台创建有余额、未过期并允许目标模型的 API Key。本文使用 `default` 分组常用模型。

在终端设置变量。下面是 Bash 写法；Windows PowerShell 使用 `$env:HAMUBOX_API_KEY = '你的 API Key'`。

```bash
export HAMUBOX_API_KEY='sk-your-api-key'
```

API Key 是账户消费凭证，不要写入网页源码、Git 仓库或分享给他人。第三方应用应在自己的服务端保管 Key。

## 2. 确认可用模型

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

在响应的 `data[].id` 中查找目标模型。空列表、无权限或模型未出现在列表中时，先检查 Key 与分组，不要反复提交生成任务。

## 3. 提交图片任务

```bash
curl --fail-with-body 'https://api.hamubox.com/v1/image/generations' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "一只红色茶壶放在白色桌面上，自然光，产品摄影，无文字",
    "aspect_ratio": "3:2",
    "resolution": "2k",
    "output_format": "png",
    "n": 1
  }'
```

响应示例：

```json
{
  "id": "task_example",
  "object": "image.generation.task",
  "model": "nano-banana-pro",
  "operation": "generate",
  "status": "queued",
  "progress": 0,
  "created_at": 1788627335
}
```

立刻保存 `id`。HTTP 200 和 `queued` 只表示已接受任务，**不是图片已经生成成功**。

## 4. 查询结果

```bash
curl --fail-with-body 'https://api.hamubox.com/v1/image/generations/task_example' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"
```

每隔 5 秒查询一次。`queued`、`in_progress` 时继续等待；`completed` 或 `failed` 时停止。

```json
{
  "id": "task_example",
  "object": "image.generation.task",
  "model": "nano-banana-pro",
  "operation": "generate",
  "status": "completed",
  "progress": 100,
  "created_at": 1788627335,
  "completed_at": 1788627378,
  "outputs": [
    {"object": "image.generation.output", "url": "https://example.com/result.png", "mime_type": "image/png"}
  ]
}
```

从 `outputs[].url` 读取图片地址并下载到自己的存储。示例中的 `example.com` 是占位地址，不能直接用于真实生成。

## 5. 改为视频任务

提交路径改成 `/v1/video/generations`，请求体使用：

```json title="seedance-text.json"
{
  "model": "dreamina-seedance-2-0-ep",
  "prompt": "A slow aerial shot over a green valley at sunrise, natural light, steady camera.",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true,
  "watermark": false
}
```

查询路径为 `/v1/video/generations/{task_id}`。从成功响应的 **`metadata.url`** 读取视频地址，不是图片的 `outputs[]`。

下一步：[任务生命周期](https://api.hamubox.com/docs/tasks/) · [参考素材](https://api.hamubox.com/docs/references/) · [完整 Python 示例](https://api.hamubox.com/docs/examples/)


---

Source: https://api.hamubox.com/docs/references/

# 参考素材

## 推荐使用可访问的 HTTPS URL

使用不需要额外 Cookie、登录或自定义请求头的文件直链。请确保链接在提交、排队和生成期间持续有效。

不要传本机路径、`file://`、浏览器 `blob:`、内网 IP、网页预览页或网盘分享页面。素材下载受到安全检查，内网地址不会作为普通素材下载。

调用方可以使用自己的文件服务，也可以使用本站的素材上传接口。第三方 API 接入不需要复制操练场的文件服务直传与登记流程。

## 上传素材

推荐使用临时上传接口。使用本站 API Key，以 `multipart/form-data` 上传图片、视频或音频，单文件不超过 512 MiB：

```bash
curl https://api.hamubox.com/v1/media/files \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -F "file=@reference.mp4"
```

响应示例：

```json
{
  "id": 123,
  "file_id": 123,
  "object": "file",
  "url": "https://img.hamubox.com/file/task-assets/temporary/reference/video/example.mp4",
  "media_type": "video",
  "status": "uploaded",
  "expires_at": 1790058088
}
```

返回的 `url` 可放入 `image_urls`、`reference_video_urls`、`reference_audio_urls`、图片接口的 `images` 或首尾帧字段。`file_id` 是本站文件记录 ID，不能当成供应商 `asset://` ID。上传不会提交生成任务，也不等于向供应商素材库登记。

临时文件从上传完成起保留 24 小时，`expires_at` 为 Unix 秒时间戳。到期后不能用于新任务，请重新上传；已经接受的任务会继续受保护，直到所有引用该文件的任务进入成功或失败终态。默认情况下，任务使用过的临时素材会在终态后转为长期参考文件，任务详情也会改为展示转存后的地址；清理等待转存完成。没有用于任务的临时上传到期后直接清理。清理是后台异步操作，不保证链接在到期那一秒立刻失效。

临时上传本身不进入用户资产库；用于任务并转存成功后，展示长期参考文件。需要上传后立即长期保存时，可增加 `-F "temporary=false"`。原有 `/v1/video/material-files/upload` 保持默认长期保存行为，也接受 `-F "temporary=true"` 使用相同的临时规则。浏览器直传文件服务后登记的临时素材和 BYOK 临时素材也遵循相同规则。

### 任务详情与资产库

通过 API 上传或转存的文件属于当前 Key 对应的本站用户。任务详情与资产库按输入来源区分：

| 输入方式 | 任务详情中的素材地址 | 用户资产库 |
| --- | --- | --- |
| 外部 HTTPS URL | 保留调用方提供的原始 URL | 转存成功后展示本站文件，原始外链不单独入库 |
| Base64 / Data URL | 展示转存文件地址，不展示原始编码 | 展示同一份转存文件 |
| 临时上传 URL | 转存前为临时地址，转存成功后为长期文件地址 | 只展示转存后的长期文件 |
| `temporary=false` 长期上传 | 展示上传后的文件地址 | 按普通参考素材展示 |

后台转存是异步操作，失败会重试。请保证外部 URL 在排队和生成期间持续可用；外链失效后，任务详情仍保留原地址，已保存的文件可在资产库查看。部分 BYOK 接口另有保存设置：关闭“保存参考素材”时，不新增用户参考资产，任务仍使用原始外链或临时链接。

从资产库删除素材只影响本站保存的文件，不会删除或更改调用方自己的外部文件。被删除的本站地址在用户任务详情中也不再展示；调用方提供的原始外链不受影响。

音视频上传后，后台会预先检测并缓存时长；正式提交仍会按所选模型检查限制。512 MiB 是此上传接口上限，不代表所有模型都接受该大小的素材。

## 内嵌图片

受支持的图片输入字段可以接收带 MIME 类型的 Data URL，例如 `data:image/png;base64,...`。网关会先将内嵌素材转为文件地址，再进行正常任务处理；图片示例：

```json
{
  "model": "nano-banana-pro",
  "prompt": "保持人物，改成雪景背景",
  "images": ["data:image/png;base64,<替换为完整图片编码>"],
  "resolution": "1k",
  "output_format": "png",
  "n": 1
}
```

这是格式示意，尖括号占位内容不是有效编码。大图片、视频和音频优先使用 URL：Base64 增大请求体，也会增加提交耗时，仍受网关请求大小和模型素材上限约束。不要记录包含完整 Base64 或 Key 的请求日志。

## 字段与用途

| 用途 | 视频接口字段 | 图片接口字段 |
| --- | --- | --- |
| 参考图片 | `image_urls` | `images` |
| 首帧 | `first_frame_url` | 不适用 |
| 尾帧 | `last_frame_url` | 不适用 |
| 参考视频 | `reference_video_urls` | 不适用 |
| 参考音频 | `reference_audio_urls` | 不适用 |

同类数组中的顺序就是素材编号顺序。提示词中引用「图片 1」「视频 1」时，应与对应数组一致。

首尾帧模式明确传 `mode: "first_last_frame"`。只传一张普通 `image_urls` 不足以表达它到底是首帧、尾帧还是全能参考。

## 时长信息

Seedance 2.0 / 2.5、Venice 视频接口以及支持音视频参考的媒体线路，会在校验和预扣前检测文件的实际时长。调用方可以省略总时长字段；旧客户端继续传入也可兼容，例如：

```json
{
  "metadata": {
    "reference_video_seconds": 8.4,
    "reference_audio_seconds": 6.0
  }
}
```

这些值表示对应类型全部文件的总和，不是单段时长，也不是输出时长。服务端会用检测值覆盖调用方填写的值。视频与音频**分别计算上限**。

Wan 3 EP 的参考视频时长由服务端检测，用于检查参考加输出总长度和计算费用；客户端不能通过少填时长减少账单。

首次使用外部素材时，检测需要下载文件，会增加提交耗时。本站文件会复用检测缓存；外部 URL 只有版本信息仍一致时才复用，避免同一 URL 换了文件后继续使用旧时长。无法读取文件或检测时长时，会在调用上游和扣费前返回错误，不会把客户端填写的时长当成真实值。`asset://` 素材须在本站登记过且能找到可访问的原文件。

## 素材质量检查

上传前检查格式、单边像素、比例、文件大小、时长和视频帧率。PNG 不等于透明图片，支持 PNG 的模型不一定支持透明通道；需要时将透明背景合成到不透明底色。

具体上限分别见 [Seedance](https://api.hamubox.com/docs/models/seedance/#参考限制) 与 [Wan 3](https://api.hamubox.com/docs/models/wan3/#参考限制)，两者不能混用。

素材可下载不等于必定通过供应商检查；内容、尺寸或编解码不被接受时，仍可能在任务执行阶段失败。


---

Source: https://api.hamubox.com/docs/tasks/

# 任务生命周期

## 任务状态

| `status` | 含义 | 客户端行为 |
| --- | --- | --- |
| `queued` | 已接受，等待执行 | 继续查询 |
| `in_progress` | 正在生成或处理结果 | 继续查询 |
| `completed` | 成功终态 | 停止查询，读取并下载结果 |
| `failed` | 失败终态 | 停止查询，展示 `error.message` |
| `unknown` | 状态暂未确定 | 保留任务 ID，稍后查询，不重提任务 |

`progress` 只是显示进度，不保证持续增加，也不能作为判断终态的依据。HTTP 200 的查询响应也可能携带 `status: "failed"`。

## 任务 ID 与恢复

提交成功后立即持久化 `id`（视频兼容响应也可能有 `task_id`）、媒体类型、模型与提交时间。后续刷新页面、重开应用，继续 GET 该任务即可，不要重新 POST。

客户端超时不代表服务端取消。用户主动关闭页面也不代表任务停止。当前这套公共接口没有在本文中提供取消接口或 webhook，请按查询模式接入。

## 轮询策略

- 默认每 **5 秒** 查询一次，不要每个渲染周期都发请求。
- 一次查询结束后再安排下一次，避免慢请求叠加。
- 多任务为每个任务保存独立状态；不要让多个组件重复查询同一个 ID。
- 429 尊重 `Retry-After`；网络错误、502/504 可有限退避重试 GET。
- 401/403 暂停并处理权限；404 不等于任务成功，也不要据此重新生成。
- 达到客户端等待上限时保留 ID，提示稍后继续查询，不要自行断言任务失败。

这里的 GET 重试与重新生成是两件事。失败终态只会通过一次新的 POST 创建新任务，新的任务可能再次计费。

## 视频成功响应

```json
{
  "id": "task_example",
  "object": "video",
  "model": "wan3.0-video-ep",
  "status": "completed",
  "progress": 100,
  "created_at": 1788627335,
  "completed_at": 1788627455,
  "metadata": {"url": "https://example.com/result.mp4"}
}
```

优先遍历 `outputs[].url` 获取所有视频（例如 MJ 批量结果）；`metadata.url` 兼容提供第一条，旧任务可能只包含此字段。保留原始响应以便排查兼容性，但不要要求所有可选字段总是出现。

## 图片成功响应

```json
{
  "id": "task_example",
  "object": "image.generation.task",
  "model": "gpt-image-2",
  "operation": "edit",
  "status": "completed",
  "progress": 100,
  "created_at": 1788627335,
  "outputs": [
    {"object": "image.generation.output", "url": "https://example.com/result.png", "mime_type": "image/png"}
  ]
}
```

读取所有 `outputs[].url`。Seedream、GPT Image 2 和 Nano Banana 的 `operation` 为 `generate` 或 `edit`，由参考图片输入决定。MJ 使用显式操作，可能是 `variation`、`upscale_subtle` 等；其 `describe` 成功结果是 `descriptions[]`，可以没有图片输出。后续操作按返回的 `actions` 选择，见 [Midjourney](https://api.hamubox.com/docs/models/midjourney/)。

## 失败响应

```json
{
  "id": "task_example",
  "object": "video",
  "model": "wan3.0-video-ep",
  "status": "failed",
  "progress": 100,
  "created_at": 1788627335,
  "error": {"code": "generation_failed", "message": "The generation request was rejected."}
}
```

错误文案不是稳定枚举，不要按完整文案写死匹配；保留 `code`、`message`、任务 ID 与请求时间。

## 下载与重复提交

结果地址可能是有时效的签名 URL，不承诺永久有效。成功后及时下载；需要长期保存的应用应维护自己的存储副本。不要删除 URL 的查询参数，也不要在下载第三方地址时附带本站 API Key。

当前没有承诺生成接口的幂等键。POST 超时、连接断开时，可能任务已经创建；先查看控制台任务记录，不要无条件重发以免重复计费。


---

Source: https://api.hamubox.com/docs/video/

# 异步视频接口

## 提交

下方通用参数表针对 Seedance 和 Wan。[Midjourney 视频](https://api.hamubox.com/docs/models/midjourney/#视频生成与延长)使用同一端点，但以 `images` 传首尾帧，不支持任意 `duration`，请使用其专属请求格式。

```http
POST /v1/video/generations
Authorization: Bearer sk-your-api-key
Content-Type: application/json
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string，必填 | 公开模型 ID，见模型章节 |
| `prompt` | string，必填 | 非空提示词 |
| `mode` | string | 文生视频、`first_last_frame` 或 `multi_ref`，见下表 |
| `duration` | integer | 输出秒数，建议明确传值；允许范围随模型变化 |
| `resolution` | string | 如 `720p`、`1080p`；建议明确传值 |
| `aspect_ratio` | string | 如 `16:9`、`adaptive`；模型支持范围不同 |
| `audio` | boolean | 是否生成声音；不等于参考音频输入 |
| `first_frame_url` | string | 首帧图片；首尾帧模式使用 |
| `last_frame_url` | string | 尾帧图片；支持仅尾帧的模型可单独提供 |
| `image_urls` | string[] | 全能参考图片 |
| `reference_video_urls` | string[] | 全能参考视频 |
| `reference_audio_urls` | string[] | 全能参考音频 |
| `metadata` | object | 模型明确要求的补充参数，如参考时长 |

`watermark`、`seed`、`prompt_extend` 不属于所有视频模型共有能力，请只按模型章节使用。不要直接复制供应商的 `content`、`input`、`parameters` 嵌套格式代替本站字段。

## 模式选择

| 目标 | 推荐写法 |
| --- | --- |
| 文生视频 | Seedance 省略 `mode` 和所有参考；Wan 3 用 `mode: "text"` |
| 首帧 / 尾帧 / 首尾帧 | `mode: "first_last_frame"`，传对应显式帧字段 |
| 多素材参考 | `mode: "multi_ref"`，使用图片 / 视频 / 音频数组 |
| Seedance 2.5 单视频编辑 | `multi_ref` + 唯一视频 + `duration: -1` + `aspect_ratio: "adaptive"` |

不建议依赖服务端从单张图片推测模式。首尾帧和全能参考是不同用途，即便都只有一张图片也应明确区分。

```json title="wan-text.json"
{
  "model": "wan3.0-video-ep",
  "prompt": "A paper boat drifting across a quiet lake, cinematic lighting.",
  "mode": "text",
  "duration": 7,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true,
  "prompt_extend": false
}
```

## 提交响应

```json
{
  "id": "task_example",
  "object": "video",
  "model": "wan3.0-video-ep",
  "status": "queued",
  "progress": 0,
  "created_at": 1788627335
}
```

有些兼容响应会同时给出 `task_id`。优先使用 `id`，缺少时再取 `task_id`；不要把任何供应商 ID 当作本站查询 ID。

## 查询

```http
GET /v1/video/generations/{task_id}
Authorization: Bearer sk-your-api-key
```

成功时优先遍历 `outputs[].url`；`metadata.url` 兼容提供第一条视频，旧任务也可能只有该字段。失败时读取 `error`。完整字段与恢复逻辑见[任务生命周期](https://api.hamubox.com/docs/tasks/)。费用通常位于 `usage`，部分视频响应也兼容顶层费用字段；新客户端优先使用 `usage`。

## 模型参数

- [Seedance 2.0 / Fast / Mini / 2.5](https://api.hamubox.com/docs/models/seedance/)：EP 与 Doubao，按视频 token 结算。
- [Wan 3 EP](https://api.hamubox.com/docs/models/wan3/)：每秒计费，参考视频计入计费时长。
- [Midjourney 视频](https://api.hamubox.com/docs/models/midjourney/#视频生成与延长)：首尾帧、批量视频和延长。


---