# 图像（Image）

# OpenAI 图像格式（Image）

官方文档
- [OpenAI Images](https://platform.openai.com/docs/api-reference/images)

## 📝 简介

给定文本提示和/或输入图片，模型将生成新的图片。OpenAI 提供多种强大的图像生成模型，可以根据自然语言描述创建、编辑和修改图像。目前支持的模型包括：

| 模型 | 描述 |
| --- | --- |
| **DALL·E 系列** | 包括 DALL·E 2 和 DALL·E 3 两个版本，它们在图像质量、创意表现和精确度上都有显著差异 |
| **GPT-Image-1** | OpenAI最新图片模型，支持多图片编辑功能，能够基于多个输入图像创建新的组合图像 |

## 💡 请求示例

### 创建图片 ✅

```bash
# 基础图片生成
curl https://$Burncloud_API_BaseUrl/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "dall-e-3",
    "prompt": "一只可爱的小海獭",
    "n": 1,
    "size": "1024x1024"
  }'

# 高质量图片生成
curl https://$Burncloud_API_BaseUrl/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "dall-e-3",
    "prompt": "一只可爱的小海獭",
    "quality": "hd",
    "style": "vivid",
    "size": "1024x1024"
  }'

# 使用 base64 返回格式
curl https://$Burncloud_API_BaseUrl/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "dall-e-3",
    "prompt": "一只可爱的小海獭",
    "response_format": "b64_json"
  }'
```

**响应示例:**

```json
{
  "created": 1589478378,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛"
    }
  ]
}
```

### 编辑图片 ✅

```bash
# dall-e-2 图片编辑
curl https://$Burncloud_API_BaseUrl/v1/images/edits \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -F image="@otter.png" \
  -F mask="@mask.png" \
  -F prompt="一只戴着贝雷帽的可爱小海獭" \
  -F n=2 \
  -F size="1024x1024"

# gpt-image-1 多图片编辑示例
curl https://$Burncloud_API_BaseUrl/v1/images/edits \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -F "model=gpt-image-1" \
  -F "image[]=@body-lotion.png" \
  -F "image[]=@bath-bomb.png" \
  -F "image[]=@incense-kit.png" \
  -F "image[]=@soap.png" \
  -F "prompt=创建一个包含这四个物品的精美礼品篮" \
  -F "quality=high"
```

**响应示例 (dall-e-2):**

```json
{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}
```

**响应示例 (gpt-image-1):**

```json
{
  "created": 1713833628,
  "data": [
    {
      "b64_json": "..."
    }
  ],
  "usage": {
    "total_tokens": 100,
    "input_tokens": 50,
    "output_tokens": 50,
    "input_tokens_details": {
      "text_tokens": 10,
      "image_tokens": 40
    }
  }
}
```

### 生成图片变体 ✅

```bash
curl https://$Burncloud_API_BaseUrl/v1/images/variations \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -F image="@otter.png" \
  -F n=2 \
  -F size="1024x1024"
```

**响应示例:**

```json
{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}
```

## 📮 请求

### 端点

#### 创建图片
```
POST /v1/images/generations
```

根据文本提示创建图片。

#### 编辑图片
```
POST /v1/images/edits
```

根据一个或多个原始图片和提示创建编辑或扩展的图片。此端点支持 dall-e-2 和 gpt-image-1 模型。

#### 生成变体
```
POST /v1/images/variations
```

创建给定图片的变体。

### 鉴权方法

在请求头中包含以下内容进行 API 密钥认证：

```
Authorization: Bearer $Burncloud_API_KEY
```

其中 `$OPENAI_API_KEY` 是您的 API 密钥。

### 请求体参数

#### 创建图片

##### `prompt`
- 类型：字符串
- 必需：是
- 说明：期望生成图片的文本描述。
  - dall-e-2 最大长度为 1000 字符
  - dall-e-3 最大长度为 4000 字符
- 提示：
  - 使用具体和详细的描述
  - 包含关键的视觉元素
  - 指定期望的艺术风格
  - 描述构图和视角

##### `model`
- 类型：字符串
- 必需：否
- 默认值：dall-e-2
- 说明：用于图像生成的模型。

##### `n`
- 类型：整数或 null
- 必需：否
- 默认值：1
- 说明：要生成的图片数量。必须在 1-10 之间。dall-e-3 仅支持 n=1。

##### `quality`
- 类型：字符串
- 必需：否
- 默认值：standard
- 说明：生成图片的质量。hd 选项会生成更细致和一致的图片。仅 dall-e-3 支持此参数。

##### `response_format`
- 类型：字符串或 null
- 必需：否
- 默认值：url
- 说明：返回生成图片的格式。必须是 url 或 b64_json 之一。URL 在生成后 60 分钟内有效。

##### `size`
- 类型：字符串或 null
- 必需：否
- 默认值：1024x1024
- 说明：生成图片的尺寸。dall-e-2 必须是 256x256、512x512 或 1024x1024 之一。dall-e-3 必须是 1024x1024、1792x1024 或 1024x1792 之一。

##### `style`
- 类型：字符串或 null
- 必需：否
- 默认值：vivid
- 说明：生成图片的风格。必须是 vivid 或 natural 之一。vivid 倾向于生成超现实和戏剧性的图片，natural 倾向于生成更自然、不那么超现实的图片。仅 dall-e-3 支持此参数。

##### `user`
- 类型：字符串
- 必需：否
- 说明：代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。

#### 编辑图片

##### `image`
- 类型：文件或文件数组
- 必需：是
- 说明：要编辑的图片。
  - 对于 dall-e-2：必须是有效的 PNG 文件，小于 4MB，且为正方形。如果未提供 mask，图片必须具有透明度，这将用作蒙版。
  - 对于 gpt-image-1：可以提供多个图片作为数组，每个图片应为 PNG、WEBP 或 JPG 文件，小于 25MB。

##### `prompt`
- 类型：字符串
- 必需：是
- 说明：期望生成图片的文本描述。
  - dall-e-2 最大长度为 1000 字符
  - gpt-image-1 最大长度为 32000 字符

##### `mask`
- 类型：文件
- 必需：否
- 说明：额外的图片，其完全透明区域（如 alpha 为零的区域）指示应该编辑的位置。如果提供了多个图片，mask 将应用于第一张图片。必须是有效的 PNG 文件，小于 4MB，且与 image 具有相同尺寸。

##### `model`
- 类型：字符串
- 必需：否
- 默认值：dall-e-2
- 说明：用于图像生成的模型。支持 dall-e-2 和 gpt-image-1。除非使用了 gpt-image-1 特有的参数，否则默认为 dall-e-2。

##### `quality`
- 类型：字符串或 null
- 必需：否
- 默认值：auto
- 说明：生成图片的质量。
  - gpt-image-1 支持 high、medium 和 low
  - dall-e-2 仅支持 standard
  - 默认为 auto

##### `size`
- 类型：字符串或 null
- 必需：否
- 默认值：1024x1024
- 说明：生成图片的尺寸。
  - gpt-image-1 必须是 1024x1024、1536x1024（横版）、1024x1536（竖版）或 auto（默认）之一
  - dall-e-2 必须是 256x256、512x512 或 1024x1024 之一

其他参数与创建图片接口相同。

#### 生成变体

##### `image`
- 类型：文件
- 必需：是
- 说明：作为变体基础的图片。必须是有效的 PNG 文件，小于 4MB，且为正方形。

其他参数与创建图片接口相同。

## 📥 响应

### 成功响应

所有三个端点都返回包含图片对象列表的响应。

#### `created`
- 类型：整数
- 说明：响应创建的时间戳

#### `data`
- 类型：数组
- 说明：生成的图片对象列表

#### `usage`（仅适用于 gpt-image-1）
- 类型：对象
- 说明：API 调用的令牌使用情况
  - `total_tokens`：使用的总令牌数
  - `input_tokens`：输入使用的令牌数
  - `output_tokens`：输出使用的令牌数
  - `input_tokens_details`：输入令牌的详细信息（文本令牌和图像令牌）

### 图片对象

#### `b64_json`
- 类型：字符串
- 说明：如果 response_format 为 b64_json，则包含生成图片的 base64 编码 JSON

#### `url`
- 类型：字符串
- 说明：如果 response_format 为 url（默认），则包含生成图片的 URL

#### `revised_prompt`
- 类型：字符串
- 说明：如果提示有任何修改，则包含用于生成图片的修改后的提示

示例图片对象:
```json
{
  "url": "https://...",
  "revised_prompt": "一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛"
}
```

## 🌟 最佳实践

### Prompt 编写建议

1. 使用清晰具体的描述
2. 指定重要的视觉细节
3. 描述期望的艺术风格和氛围
4. 注意构图和视角的说明

### 参数选择建议

1. 模型选择
   - dall-e-3：适合需要高质量、精确细节的场景
   - dall-e-2：适合快速原型或简单图像生成

2. 尺寸选择
   - 1024x1024：通用场景的最佳选择
   - 1792x1024/1024x1792：适合横版/竖版场景
   - 较小尺寸：适合缩略图或快速预览

3. 质量和风格
   - quality=hd：用于需要精细细节的图像
   - style=vivid：适合创意和艺术效果
   - style=natural：适合真实场景再现


### gpt-image-2 参数
gpt-image-2 提供了丰富的参数，让你能精细地控制生成效果和成本。

1. 参数	类型	说明	示例/备注
   - model	string	必填。指定使用的模型，目前为 gpt-image-2。	"gpt-image-2"
   - prompt	string	必填。描述你想要生成图像的文本。模型对多语言（尤其是中文）文字渲染能力很强。	"A serene cat..."
   - quality	string	可选。生成质量，直接影响价格和生成速度。	"low" (草稿), "medium" (社交媒体), "high" (印刷品)
   - size	string	可选。输出图像的尺寸。支持多种比例。	"1024x1024" (1:1), "1536x1024" (3:2), "1024x1792" (9:16)
   - n	integer	可选。一次提示词生成的图像数量。范围是 1-8。	1 (默认), 4
   - output_format	string	可选。输出图像的格式。	"png" (支持透明背景), "jpeg", "webp"
   - background	string	可选。设置背景是否为透明。	"auto", "transparent" (需配合 png 格式)


### 常见问题

1. 图片生成失败
   - 检查 prompt 是否符合内容政策
   - 确认文件格式和大小限制
   - 验证 API 密钥权限

2. 结果与预期不符
   - 优化 prompt 描述
   - 调整质量和风格参数
   - 考虑使用图片编辑或变体功能

# Midjourney 图像格式（Midjourney Proxy/Midjourney Proxy Plus）

请你注意
  该接口 **非Midjourney官方的接口**，而是基于作者 **novicezk** 的开源项目 [**midjourney-proxy**](https://github.com/novicezk/midjourney-proxy) 实现的midjourney代理接口。
  该项目分为两个版本，New API 都已经适配：
  - 开源版 [midjourney-proxy](https://github.com/novicezk/midjourney-proxy)
  - 付费版 [midjourney-proxy-plus](https://github.com/litter-coder/midjourney-proxy-plus)
  这里非常感谢作者的贡献，让我们可以方便使用midjourney的强大功能，如果有时间，请给作者一个Star，如果有能力，建议支持作者的付费版本，该版本支持更多功能。

| 功能类别 | 开源版 | 付费版 |
|---------|--------|--------|
| **基础功能** | | |
| Imagine指令及相关动作 | ✓ | ✓ |
| 垫图支持 | ✓ | ✓ |
| Blend(图片混合) | ✓ | ✓ |
| Describe(图生文) | ✓ | ✓ |
| 任务实时进度 | ✓ | ✓ |
| 中文prompt翻译 | ✓ | ✓ |
| prompt敏感词检测 | ✓ | ✓ |
| user-token连接wss | ✓ | ✓ |
| 多账号配置 | ✓ | ✓ |
| **高级功能** | | |
| Shorten(prompt分析) | ✗ | ✓ |
| 焦点移动(Pan) | ✗ | ✓ |
| 图片变焦(Zoom) | ✗ | ✓ |
| 局部重绘(Vary Region) | ✗ | ✓ |
| 关联按钮动作和Remix模式 | ✗ | ✓ |
| 获取图片seed值 | ✗ | ✓ |
| **账号管理** | | |
| 账号池持久化 | ✗ | ✓ |
| 多种存储支持(Redis/MySQL) | ✗ | ✓ |
| 账号信息获取和设置 | ✗ | ✓ |
| 任务取消功能 | ✗ | ✓ |
| 内置管理后台 | ✗ | ✓ |
| **智能特性** | | |
| MJ V6.0支持 | ✗ | ✓ |
| 账号状态自动监控 | ✗ | ✓ |
| 模式自动切换 | ✗ | ✓ |
| niji・journey Bot支持 | ✗ | ✓ |
| InsightFace人脸服务 | ✗ | ✓ |
| **安全性能** | | |
| 动态配置支持 | ✗ | ✓ |
| token掉线问题修复 | ✗ | ✓ |
| 自动验证功能 | ✗ | ✓ |
| 违禁词自动申诉 | ✗ | ✓ |

## 📝 简介

Midjourney是一个强大的图像生成和处理模型，可以根据自然语言描述创建、编辑和修改图像。通过提供不同的接口，可以实现各种图像生成和处理任务。

## 🔄 流程示意图

[![Midjourney.webp](/uploads/images/gallery/2025-08/midjourney.webp)](/uploads/images/gallery/2025-08/midjourney.webp)


### 流程说明

1. **初始任务**
   - Imagine: 文本生成图片
   - Blend: 多图混合
   - Describe: 图片描述
   - Swap Face: 人脸替换

2. **图片处理**
   - U1-U4: 放大操作
   - V1-V4: 变体生成
   - Pan: 图片平移
   - Zoom: 图片缩放

3. **特殊流程**
   - Action + Modal: 需要弹窗确认的操作
   - Action 直接执行: 不需要弹窗的操作

4. **任务管理**
   - 获取任务详情
   - 获取图片 Seed
   - 上传至 Discord

## 💡 请求示例

### 提交Imagine任务 ✅

```bash
curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/imagine' \
--header 'Authorization: Bearer $Burncloud_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "botType": "MID_JOURNEY",
  "prompt": "Cat",
  "base64Array": [],
  "accountFilter": {
    "channelId": "",
    "instanceId": "",
    "modes": [],
    "remark": "",
    "remix": true,
    "remixAutoConsidered": true
  },
  "notifyHook": "",
  "state": ""
}'
```

**响应示例:**

```json
{
  "code": 1,
  "description": "提交成功",
  "properties": {},
  "result": 1320098173412546
}
```

### 提交Blend任务 ✅

```bash
curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/blend' \
--header 'Authorization: Bearer $Burncloud_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "botType": "MID_JOURNEY",
  "base64Array": [
    "data:image/png;base64,xxx1",
    "data:image/png;base64,xxx2"
  ],
  "dimensions": "SQUARE",
  "accountFilter": {
    "channelId": "",
    "instanceId": "",
    "modes": [],
    "remark": "",
    "remix": true,
    "remixAutoConsidered": true
  },
  "notifyHook": "",
  "state": ""
}'
```

**响应示例:**

```json
{
  "code": 1,
  "description": "提交成功",
  "properties": {},
  "result": 1320098173412546
}
```

### 提交Describe任务 ✅

```bash
curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/describe' \
--header 'Authorization: Bearer $Burncloud_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "botType": "MID_JOURNEY",
  "base64": "data:image/png;base64,xxx",
  "accountFilter": {
    "channelId": "",
    "instanceId": "",
    "modes": [],
    "remark": "",
    "remix": true,
    "remixAutoConsidered": true
  },
  "notifyHook": "",
  "state": ""
}'
```

**响应示例:**

```json
{
  "code": 1,
  "description": "提交成功",
  "properties": {},
  "result": 1320098173412546
}
```

### 提交Modal ✅

```bash
curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/modal' \
--header 'Authorization: Bearer $Burncloud_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "maskBase64": "",
  "prompt": "",
  "taskId": "14001934816969359"
}'
```

**响应示例:**

```json
{
  "code": 1,
  "description": "提交成功",
  "properties": {},
  "result": 1320098173412546
}
```

### 提交swap_face任务 ✅

```bash
curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/insight-face/swap' \
--header 'Authorization: Bearer $Burncloud_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "sourceBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAWIB0iIiAdHx8kKDQsJCYxJx8fLT0tMTU3Ojo6Iys/RDnYdriP1wsS81kwU8OVs/R3xu8s6bX7+zYnOH8coSqpmRSBjqerjcBlr2OB/lbAf/2Q==",
  "targetBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAWIB0iIiAdHx8kKDQsJCYxJx8fLT0tMTU3Ojo6Iys/RD849k="
}'
```

**响应示例:**

```json
{
  "code": 0,
  "description": "string",
  "result": "string"
}
```

### 执行Action动作 ✅

```bash
curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/action' \
--header 'Authorization: Bearer $Burncloud_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "chooseSameChannel": true,
  "customId": "MJ::JOB::upsample::1::82c51c9d-bc33-4c07-a471-36c3dcb1a6f0",
  "taskId": "1728781324658687",
  "accountFilter": {
    "channelId": "",
    "instanceId": "",
    "modes": [],
    "remark": "",
    "remix": true,
    "remixAutoConsidered": true
  },
  "notifyHook": "",
  "state": ""
}'
```

**响应示例:**

```json
{
  "code": 1,
  "description": "提交成功",
  "properties": {},
  "result": 1320098173412546
}
```

### 上传文件到discord ✅

```bash
curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/upload-discord-images' \
--header 'Authorization: Bearer $Burncloud_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "base64Array": [],
  "filter": {
    "channelId": "",
    "instanceId": "",
    "remark": ""
  }
}'
```

**响应示例:**

```json
{
  "code": 0,
  "description": "string",
  "result": [
    "string"
  ]
}
```

### 根据ID列表查询任务 ✅

```bash
curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/task/list-by-condition' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $Burncloud_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "ids": []
}'
```

**响应示例:**

```json
[
  {
    "action": "IMAGINE",
    "buttons": [
      {
        "customId": "string",
        "emoji": "string",
        "label": "string",
        "style": 0,
        "type": 0
      }
    ],
    "description": "string",
    "failReason": "string",
    "finishTime": 0,
    "id": "string",
    "imageUrl": "string",
    "progress": "string",
    "prompt": "string",
    "promptEn": "string",
    "properties": {},
    "startTime": 0,
    "state": "string",
    "status": "NOT_START",
    "submitTime": 0
  }
]
```

### 指定ID获取任务 ✅

```bash
curl --location --request GET 'https://$Burncloud_API_BaseUrl/mj/task/{id}/fetch' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $Burncloud_API_KEY' \
--header 'Content-Type: application/json'
```

**响应示例:**

```json
{
  "action": "IMAGINE",
  "buttons": [
    {
      "customId": "string",
      "emoji": "string",
      "label": "string",
      "style": 0,
      "type": 0
    }
  ],
  "description": "string", 
  "failReason": "string",
  "finishTime": 0,
  "id": "string",
  "imageUrl": "string",
  "progress": "string",
  "prompt": "string",
  "promptEn": "string",
  "properties": {},
  "startTime": 0,
  "state": "string",
  "status": "NOT_START",
  "submitTime": 0
}
```

### 获取任务图片的seed ✅

```bash
curl --location --request GET 'https://$Burncloud_API_BaseUrl/mj/task/{id}/image-seed' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $Burncloud_API_KEY' \
--header 'Content-Type: application/json'
```

**响应示例:**

```json
{
  "code": 0,
  "description": "string",
  "result": "string"
}
```

## 📮 请求

### 端点

#### 提交Imagine任务
```
POST /mj/submit/imagine
```

根据文本提示创建图片。

#### 提交Blend任务
```
POST /mj/submit/blend
```

根据多个输入图片融合生成新图片。

#### 提交Describe任务
```
POST /mj/submit/describe
```

根据输入图片生成文字描述。

#### 提交Modal
```
POST /mj/submit/modal
```

提交模态信息,用于调整图片生成细节。

#### 提交swap_face任务 
```
POST /mj/insight-face/swap
```

根据源图片和目标图片进行人脸交换。

#### 执行Action动作
```
POST /mj/submit/action
```

对已生成的图片进行后续操作,如放大、调整等。

#### 上传文件到discord
```  
POST /mj/submit/upload-discord-images
```

将图片上传到discord平台。

#### 根据ID列表查询任务
```
POST /mj/task/list-by-condition
```

根据指定的任务ID列表查询任务详情。

#### 指定ID获取任务
```  
GET /mj/task/{id}/fetch
```

根据任务ID获取任务详情。

#### 获取任务图片的seed  
```
GET /mj/task/{id}/image-seed
```

获取指定任务生成图片的seed值。

### 鉴权方法

在请求头中包含以下内容进行 API 密钥认证：

```
Authorization: Bearer $Burncloud_API_KEY$OPENAI_API_KEY
```

其中 `$OPENAI_API_KEY` 是您的 API 密钥。

### 请求体参数

#### 提交 Imagine 任务

##### `botType`
- 类型：枚举字符串
- 必需：否
- 默认值：MID_JOURNEY
- 可选值：
  - `MID_JOURNEY`: Midjourney 模型
  - `NIJI_JOURNEY`: Niji Journey 模型
- 说明：选择使用的 bot 类型

##### `prompt`
- 类型：字符串
- 必需：是
- 说明：图像生成的文本提示词
- 提示：
  - 使用清晰具体的描述
  - 可以包含艺术风格、构图等细节
  - 支持英文和中文输入

##### `base64Array`
- 类型：字符串数组
- 必需：否
- 说明：垫图的 base64 编码数组
- 格式：每个元素应为完整的 base64 图片字符串，包含 MIME 类型前缀

##### `accountFilter`
- 类型：对象
- 必需：否
- 属性：
  - `channelId`: 频道 ID
  - `instanceId`: 账号实例 ID
  - `modes`: 账号模式数组，可选值：RELAX、FAST、TURBO
  - `remark`: 备注包含的内容
  - `remix`: 账号是否支持 remix
  - `remixAutoConsidered`: remix 自动提交设置

##### `notifyHook`
- 类型：字符串
- 必需：否
- 说明：任务完成后的回调地址，为空时使用全局 notifyHook

##### `state`
- 类型：字符串
- 必需：否
- 说明：自定义状态参数，可用于跟踪请求

#### 提交 Blend 任务

##### `base64Array`
- 类型：字符串数组
- 必需：是
- 说明：要混合的图片 base64 编码数组
- 格式：必须包含 2-5 张图片的 base64 字符串

##### `dimensions`
- 类型：枚举字符串
- 必需：否
- 可选值：
  - `PORTRAIT`: 2:3 比例
  - `SQUARE`: 1:1 比例
  - `LANDSCAPE`: 3:2 比例
- 说明：输出图片的宽高比设置

#### 提交 Describe 任务

##### `base64`
- 类型：字符串
- 必需：是
- 说明：需要描述的图片的 base64 编码
- 格式：完整的 base64 字符串，包含 MIME 类型前缀

#### 提交 Modal 任务

##### `maskBase64`
- 类型：字符串
- 必需：否
- 说明：局部重绘的蒙版图片 base64 编码

##### `prompt`
- 类型：字符串
- 必需：否
- 说明：重绘区域的文本提示词

##### `taskId`
- 类型：字符串
- 必需：是
- 说明：原始任务的 ID

#### 提交 Swap Face 任务

##### `sourceBase64`
- 类型：字符串
- 必需：是
- 说明：人脸源图片的 base64 编码
- 要求：图片必须包含清晰的人脸

##### `targetBase64`
- 类型：字符串
- 必需：是
- 说明：目标图片的 base64 编码
- 要求：图片必须包含要替换的人脸

#### 执行 Action 动作

##### `chooseSameChannel`
- 类型：布尔值
- 必需：否
- 默认值：false
- 说明：是否选择同一频道下的账号

##### `customId`
- 类型：字符串
- 必需：是
- 说明：动作标识符
- 格式：特定格式的字符串，如 "MJ::JOB::upsample::1::xxx"

##### `taskId`
- 类型：字符串
- 必需：是
- 说明：要执行动作的任务 ID

#### 上传文件到 Discord

##### `base64Array`
- 类型：字符串数组
- 必需：是
- 说明：要上传的图片 base64 编码数组

##### `filter`
- 类型：对象
- 必需：否
- 属性：
  - `channelId`: 目标频道 ID
  - `instanceId`: 账号实例 ID
  - `remark`: 备注信息

#### 根据 ID 列表查询任务

##### `ids`
- 类型：字符串数组
- 必需：是
- 说明：要查询的任务 ID 列表

### 通用响应格式

所有接口都返回相似的响应结构：

##### `code`
- 类型：整数
- 说明：状态码

| 状态码 | 说明 |
|--------|------|
| 1 | 提交成功 |
| 22 | 任务排队中 |
| 21 | 参数错误 |
| 23 | 系统错误 |
| 24 | 账号不可用 |
| 25 | 余额不足 |

##### `description`
- 类型：字符串
- 说明：响应描述信息

##### `properties`
- 类型：对象
- 说明：扩展属性

##### `result`
- 类型：字符串或数组
- 说明：返回结果，可能是任务 ID 或其他数据

## 📥 响应

### 成功响应

#### `action`
- 类型：枚举字符串
- 说明：任务类型

| 字符串值 | 说明 |
|--------|------|
| `IMAGINE` | 创建图片 |
| `UPSCALE` | 放大图片 |
| `VARIATION` | 变体生成 |
| `ZOOM` | 缩放图片 |
| `PAN` | 平移图片 |
| `DESCRIBE` | 图片描述 |
| `BLEND` | 图片混合 |
| `SHORTEN` | 缩短提示词 |
| `SWAP_FACE` | 人脸替换 |

#### `buttons`
- 类型：对象数组
- 说明：可执行的操作按钮

| 数组包含属性 | 说明 |
|--------|------|
| `customId` | 动作标识 |
| `emoji` | 按钮图标 |
| `label` | 按钮文本 |
| `style` | 样式(2=Primary, 3=Green) |
| `type` | 系统内部使用的类型 |

#### `description`
- 类型：字符串
- 说明：任务描述信息

#### `failReason`
- 类型：字符串
- 说明：任务失败原因

#### `finishTime`
- 类型：整数
- 说明：任务完成时间戳

#### `id`
- 类型：字符串
- 说明：任务唯一标识符

#### `imageUrl`
- 类型：字符串
- 说明：生成图片的URL

#### `progress`
- 类型：字符串
- 说明：任务进度信息

#### `prompt`
- 类型：字符串
- 说明：原始提示词

#### `promptEn`
- 类型：字符串
- 说明：英文提示词

#### `status`
- 类型：枚举字符串
- 说明：任务状态

| 字符串值 | 说明 |
|--------|------|
| `NOT_START` | 未开始 |
| `SUBMITTED` | 已提交 |
| `MODAL` | 模态操作中 |
| `IN_PROGRESS` | 进行中 |
| `FAILURE` | 失败 |
| `SUCCESS` | 成功 |
| `CANCEL` | 已取消 |

#### `submitTime`
- 类型：整数
- 说明：任务提交时间戳

#### `startTime`
- 类型：整数
- 说明：任务开始执行时间戳

### 错误响应

当请求出现问题时，API 将返回错误响应：

#### HTTP 状态码
- `400 Bad Request`: 请求参数无效
- `401 Unauthorized`: API 密钥无效或未提供
- `403 Forbidden`: 权限不足
- `404 Not Found`: 资源不存在
- `429 Too Many Requests`: 请求频率超限
- `500 Internal Server Error`: 服务器内部错误

#### 错误响应格式
```json
{
  "code": <错误码>,
  "description": "错误描述信息",
  "result": null
}
```

## 💡 最佳实践

### Prompt 编写建议

1. 使用清晰简洁的语言描述期望的图像内容
2. 可以参考Midjourney支持的各种参数来控制图片风格
3. 适当使用否定描述以排除不需要的元素
4. 可以通过图片URL作为参考来指导生成

### 图片生成流程

1. 提交Imagine任务,获得初步图片
2. 必要时通过Blend、Modal等任务进一步优化
3. 执行Action动作进行图片微调
4. 将满意的结果图片上传保存

### 图片格式要求

1. 支持的图片格式：
   
   - JPEG/JPG
   
   - PNG
   
   - GIF (静态)
   
   - WEBP

2. 图片大小限制：
   
   - 文件大小：最大 4MB
   
   - 分辨率：建议 1024x1024 或更高
   
   - 宽高比：支持 1:1、2:3、3:2

### 性能优化建议

1. Base64 编码：
   
   - 使用标准 Base64 编码格式
   
   - 包含正确的 MIME 类型前缀
   
   - 压缩图片以减少数据传输

2. 任务处理：
   
   - 使用 webhook 接收任务完成通知
   
   - 合理设置重试策略
   
   - 建议使用异步处理方式

### 错误处理

   - 实现请求重试机制
   
   - 添加错误日志记录
   
   - 设置合理的超时时间

# gemini-3 图片生成API [含4K]

#### 2K图片 / 4K图片
请求
~~~ 
https://ai.burncloud.com/v1beta/models/gemini-3-pro-image-preview:generateContent?key=sk-xxxxxxxxxxxxxxxxxxx' 
{
    "contents": [
        {
            "role": "user",
            "parts": [
                {
                    "text": "画条狗"
                }
            ]
        }
    ]
    , "generationConfig": {
        "temperature": 1
        ,"maxOutputTokens": 32768
        ,"responseModalities": ["TEXT", "IMAGE"]
        ,"topP": 0.95
        ,"imageConfig": {
            "aspectRatio": "1:1"
            ,"imageSize": "4K"
            ,"imageOutputOptions": {
                "mimeType": "image/png"
            }
            ,"personGeneration": "ALLOW_ALL"
        }
    }
}
~~~

### 参考图生图，改图，还是沿用上面的代码，只是修改以下部分content部分：
~~~
{
    "contents": [
        {
            "role": "user",
            "parts": [
                {
                    "text": "画条狗"
                },
                {
                  "fileData": {
                    "mimeType": "image/jpeg",
                    "fileUri": "https://XXXXXX.com/i/2025/01/06/677bbb1f2411d.webp"
                  }
                }
            ]
        }
    ]
~~~

### 获取图片，请看返回结果，拿图片的base64