# 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)。示例中的图片地址是占位地址，实际参考任务需要可访问的图片。