---
description: "Midjourney 异步图片生成、放大与变体接口，按模型按次计费。"
---

# Midjourney API

Midjourney 通过异步任务接口提供图片生成、图片放大和图片变体。每个任务都会返回图片地址，任务完成后可以继续对其中一张图片进行放大或生成变体，并按模型配置的“按次价格”单独计费。

## 基本信息

- Base URL：`https://oneapi.zaiwenai.com/v1`
- 鉴权：`Authorization: Bearer $YOUR_API_KEY`
- 模型：`midjourney`
- 任务记录保留：30 天
- 图片地址有效期：约 7 天，以响应中的 `expires_at` 和 `asset_expires_at` 为准
- 返回形式：图片 URL

## 生成图片

### 端点

```http
POST /midjourney/generations
```

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `model` | string | 是 | 固定为 `midjourney` |
| `prompt` | string | 是 | 提示词，1-1000 个字符 |
| `aspect_ratio` | string | 否 | `1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`，默认 `1:1` |
| `mode` | string | 否 | `fast` 或 `relax`，默认 `fast` |
| `seed` | integer | 否 | 0 到 4294967295 |
| `stylize` | integer | 否 | 0 到 1000 |
| `chaos` | integer | 否 | 0 到 100 |
| `weird` | integer | 否 | 0 到 3000 |
| `reference_images` | array | 否 | 最多 4 张参考图；目前只支持公网 URL |

### 不带参考图的请求

```bash
curl https://oneapi.zaiwenai.com/v1/midjourney/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney",
    "prompt": "a blue ceramic cup on a white table, product photography",
    "aspect_ratio": "1:1",
    "mode": "fast"
  }'
```

### 参考图

参考图目前只支持公网 URL，服务必须能够访问该地址。

```bash
curl https://oneapi.zaiwenai.com/v1/midjourney/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney",
    "prompt": "preserve the reference style, a blue ceramic cup on a white table",
    "reference_images": [
      {
        "url": "https://example.com/reference.jpg"
      }
    ]
  }'
```

参考图限制：

- 最多 4 张
- 只支持 `http` 或 `https` 图片 URL
- URL 必须可以从服务端访问
- 不支持直接上传文件，只支持图片 URL

### 创建任务响应：`202`

```json
{
  "id": "mj_3d30e775c1314f5c92e6cd60421bfa41",
  "object": "midjourney.task",
  "model": "midjourney",
  "operation": "imagine",
  "status": "pending",
  "progress": 0,
  "created_at": 1786611625,
  "asset_expires_at": null,
  "assets_expired": false
}
```

创建成功只代表任务已进入队列，不代表图片已经生成。请使用任务查询接口轮询。

## 查询任务

### 端点

```http
GET /midjourney/tasks/{task_id}
```

### 处理中响应：`202`

```json
{
  "id": "mj_3d30e775c1314f5c92e6cd60421bfa41",
  "object": "midjourney.task",
  "model": "midjourney",
  "operation": "imagine",
  "status": "running",
  "progress": 50,
  "created_at": 1786611625,
  "asset_expires_at": null,
  "assets_expired": false
}
```

### 成功响应：`200`

```json
{
  "id": "mj_3d30e775c1314f5c92e6cd60421bfa41",
  "object": "midjourney.task",
  "model": "midjourney",
  "operation": "imagine",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1786611625,
  "asset_expires_at": 1787216440,
  "assets_expired": false,
  "images": [
    {
      "index": 1,
      "url": "https://images.example.com/midjourney/result-1.jpg",
      "expires_at": 1787216440
    },
    {
      "index": 2,
      "url": "https://images.example.com/midjourney/result-2.jpg",
      "expires_at": 1787216440
    },
    {
      "index": 3,
      "url": "https://images.example.com/midjourney/result-3.jpg",
      "expires_at": 1787216441
    },
    {
      "index": 4,
      "url": "https://images.example.com/midjourney/result-4.jpg",
      "expires_at": 1787216442
    }
  ],
  "available_actions": [
    { "action": "upscale", "index": 1, "label": "U1" },
    { "action": "upscale", "index": 2, "label": "U2" },
    { "action": "upscale", "index": 3, "label": "U3" },
    { "action": "upscale", "index": 4, "label": "U4" },
    { "action": "variation", "index": 1, "label": "V1" },
    { "action": "variation", "index": 2, "label": "V2" },
    { "action": "variation", "index": 3, "label": "V3" },
    { "action": "variation", "index": 4, "label": "V4" }
  ],
  "result_summary": { "image_count": 4 },
  "usage": { "cost": 1.0, "currency": "CNY" }
}
```

`images[].url` 是图片地址。URL 到期后，响应会把 `images` 和 `available_actions` 返回为空数组，并设置 `assets_expired: true`。

## 执行动作

### 端点

```http
POST /midjourney/tasks/{task_id}/actions
```

每个操作都会创建一个新的任务，并独立按次计费。请使用上一个任务返回的图片序号选择目标图片。

### 支持的操作

| action | 是否需要 index | 结果形态 |
|---|---:|---|
| `upscale` | 是，1-4 | 单图 |
| `variation` | 是，1-4 | 生成 4 张变体图片 |

### Upscale 示例

```bash
curl https://oneapi.zaiwenai.com/v1/midjourney/tasks/mj_3d30e775c1314f5c92e6cd60421bfa41/actions \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"upscale","index":1}'
```

### Variation 示例

```json
{
  "action": "variation",
  "index": 1
}
```

成功创建动作任务的响应仍然是 `202`：

```json
{
  "id": "mj_6a21833407d44d3ca3a325444b954fe8",
  "object": "midjourney.task",
  "model": "midjourney",
  "operation": "upscale",
  "status": "pending",
  "progress": 0,
  "created_at": 1786611741,
  "asset_expires_at": null,
  "assets_expired": false,
  "parent_id": "mj_3d30e775c1314f5c92e6cd60421bfa41"
}
```

动作任务完成后的响应结构与普通任务相同，区别是包含 `parent_id`，并且 `operation` 为动作名。

## 链式操作

放大和变体都可以继续操作上一个任务的结果，形成链式流程：

```text
生成图片 -> 变体 V1 -> 放大 U2 -> 变体 V3 -> 放大 U1
```

每一步都会返回新的任务 ID、图片和下一步可用的操作。链式操作没有固定层数限制，但每一步都需要单独计费，并且必须在上一步图片地址有效期内提交。

变体操作每次返回 4 张图片；放大操作返回 1 张图片。后续操作使用当前任务返回的图片序号，不需要理解服务内部的按钮或实现细节。

## 错误响应

错误统一使用以下结构：

```json
{
  "error": {
    "message": "Action is not available",
    "type": "invalid_request_error",
    "param": null,
    "code": "action_not_available"
  }
}
```

常见错误：

| HTTP | code | 说明 |
|---:|---|---|
| 401 | `invalid_api_key` | Key 缺失或无效 |
| 402 | `insufficient_balance` | 余额不足 |
| 409 | `task_not_ready` | 父任务尚未成功或未完成结算 |
| 409 | `action_not_available` | 请求的操作当前不可用 |
| 410 | `action_expired` | OSS 资产或动作上下文已过期 |
| 502 | `upstream_error` | 图片生成服务调用失败 |
| 503 | `upstream_unavailable` | 管理员配置的 Midjourney 渠道不可用 |

## 计费和调用建议

- 生成、放大、变体每个任务独立计费一次
- 例如 `生成 -> V1 -> U1` 会计费 3 次
- 先查询任务到 `succeeded`，再提交下一步操作
- 在 `asset_expires_at` 之前完成链式操作
- 图片 URL 过期后不能继续执行动作