> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Midjourney API 概览

>  - Midjourney 文生图（Imagine）/ 垫图 / 二次操作 / 图生视频接口总览
- 异步任务模式：提交后返回 task_id，轮询查询结果
- 新版路由自动注入 model=midjourney，支持原生 MJ 参数、body 结构化参数与 metadata 

<Note>
  **Base URL：** `https://gccai.heqingsong.uk`

  **鉴权：** `Authorization: Bearer <token>`

  新版 `/v1/midjourney/...` 路由会自动注入 `model=midjourney`，请求体不需要传 `model`。
</Note>

## 快速开始

```bash theme={null}
# 1. 提交绘图
curl -X POST https://gccai.heqingsong.uk/v1/midjourney/generations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a cute cat, watercolor style --ar 16:9"}'

# 2. 查询结果（推荐轮询统一任务接口直到 status=completed）
curl https://gccai.heqingsong.uk/v1/tasks/task_01JWXXXX \
  -H "Authorization: Bearer <token>"

# 3. 放大第1张图
curl -X POST https://gccai.heqingsong.uk/v1/midjourney/generations/upscale \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "task_01JWXXXX", "index": 1}'
```

## 接口总览

每个功能的完整字段、示例、注意事项见对应子页面。

| 功能         | 路径                                                               | 文档                                 |
| ---------- | ---------------------------------------------------------------- | ---------------------------------- |
| 文生图（默认入口）  | `POST /v1/midjourney/generations`                                | [Imagine](./imagine)               |
| 文生图（显式入口）  | `POST /v1/midjourney/generations/imagine`                        | [Imagine](./imagine)               |
| 多图融合       | `POST /v1/midjourney/generations/blend`                          | [Blend](./blend)                   |
| 图生文（识图）    | `POST /v1/midjourney/generations/describe`                       | [Describe](./describe)             |
| 图片编辑       | `POST /v1/midjourney/generations/edits`                          | [Edits](./edits)                   |
| 放大选图       | `POST /v1/midjourney/generations/upscale`                        | [Upscale](./upscale)               |
| 生成变体       | `POST /v1/midjourney/generations/variation`                      | [Variation](./variation)           |
| 大幅变体       | `POST /v1/midjourney/generations/high-variation`                 | [High Variation](./high-variation) |
| 微调变体       | `POST /v1/midjourney/generations/low-variation`                  | [Low Variation](./low-variation)   |
| 重新生成       | `POST /v1/midjourney/generations/reroll`                         | [Reroll](./reroll)                 |
| 缩放扩展       | `POST /v1/midjourney/generations/zoom`                           | [Zoom](./zoom)                     |
| 平移扩展       | `POST /v1/midjourney/generations/pan`                            | [Pan](./pan)                       |
| 局部重绘       | `POST /v1/midjourney/generations/inpaint`                        | [Inpaint](./inpaint)               |
| Modal 补充参数 | `POST /v1/midjourney/generations/modal`                          | [Modal](./modal)                   |
| 图生视频       | `POST /v1/midjourney/generations/video`                          | [Video](./video)                   |
| 重塑（强 / 弱）  | `POST /v1/midjourney/generations/remix-strong` · `/remix-subtle` | [Remix](./remix)                   |
| 任务查询       | `GET /v1/tasks/{task_id}` · `/v1/midjourney/{task_id}`           | [任务查询](./query)                    |

参考：[最佳实践](./best-practices)（轮询 / 重试 / 排错） · [完整工作流示例](./workflow)（端到端 curl + 客户端封装）

## 完整使用流程

```mermaid theme={null}
flowchart TB
  A["① POST /generations<br/>提交 Imagine"] --> B["② GET /v1/tasks/{task_id}<br/>轮询至 completed"]
  B --> C["③ 如需按钮<br/>GET /v1/midjourney/{task_id}"]
  C --> D1["/upscale"]
  C --> D2["/variation"]
  C --> D3["/reroll"]
  C --> D4["/zoom"]
  C --> D5["/inpaint<br/>(进入 MODAL)"]
  D5 --> M["/modal<br/>提交遮罩 + prompt"]
```

## 错误处理

### 错误响应格式

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "prompt is required"
  }
}
```

### 常见错误

| HTTP 状态码 | type                    | 说明               |
| -------- | ----------------------- | ---------------- |
| 400      | `invalid_request_error` | 参数错误（缺少必填、格式错误等） |
| 401      | `authentication_error`  | API Key 无效       |
| 402      | `payment_required`      | 余额不足             |
| 404      | `not_found`             | 任务不存在            |
| 429      | `rate_limit_error`      | 请求频率超限           |
| 500      | `internal_error`        | 服务器内部错误          |

### 任务失败

`fail_reason` 常见值：

* `Banned prompt detected` — 提示词含违禁内容
* `Task timeout` — 任务超时（超过 30 分钟未完成），已自动退款
* `No available upstream` — 服务暂不可用，请稍后重试

## 计费说明

MJ 新版统一模型名是 `midjourney`，通过 action、version、speed 生成计费 key。匹配顺序通常为：

```text theme={null}
midjourney@<action>-<version>-<speed>
-> midjourney@<action>-<version>
-> midjourney@<action>-<speed>
-> midjourney@<action>
-> midjourney
```

| 操作             | 计费名称                                          | 说明                     |
| -------------- | --------------------------------------------- | ---------------------- |
| Imagine        | `midjourney@imagine[-version][-speed]`        | 文生图 / 垫图               |
| Blend          | `midjourney@blend[-speed]`                    | 多图融合                   |
| Describe       | `midjourney@describe[-speed]`                 | 图生文                    |
| Edits          | `midjourney@edits[-speed]`                    | 图片编辑                   |
| Upscale        | `midjourney@upscale[-version][-speed]`        | 放大                     |
| Variation      | `midjourney@variation[-version][-speed]`      | 变体                     |
| High Variation | `midjourney@high_variation[-version][-speed]` | 强变体                    |
| Low Variation  | `midjourney@low_variation[-version][-speed]`  | 弱变体                    |
| Reroll         | `midjourney@reroll[-version][-speed]`         | 重新生成                   |
| Zoom           | `midjourney@zoom[-version][-speed]`           | 缩放扩图                   |
| Pan            | `midjourney@pan[-version][-speed]`            | 平移扩图                   |
| Inpaint        | `midjourney@inpaint[-version][-speed]`        | 局部重绘入口                 |
| Modal          | `midjourney@modal[-speed]`                    | 局部重绘补参                 |
| Video          | `midjourney@video` / `midjourney@video-720p`  | 图生视频，实扣 × `batch_size` |
| Remix Strong   | `midjourney@remix_strong[-speed]`             | 强重塑（仅 v8.1 / v8.2）     |
| Remix Subtle   | `midjourney@remix_subtle[-speed]`             | 弱重塑（仅 v8.1 / v8.2）     |

说明：

* `speed=relax` 或未传 `speed` 时，不追加 speed 后缀；`fast` / `turbo` 会追加对应后缀。
* 主版本归一化为 `v8.2`、`v8.1`、`v7`、`v6.1`、`v5.2`、`v5.1`。
* `niji=true + version=7/6` 归一化为 `niji7` / `niji6`。

> 具体价格以控制台模型定价页为准。任务失败会自动全额退款。