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

# Muse Image Ext 图片生成

> 支持文生图和最多 9 张参考图生图，每次返回 1 张 WebP 图片。

> [!NOTE]
>
> 本接口采用异步处理。提交后保存任务 ID，通过 `GET /v1/tasks/{task_id}` 查询状态和结果。默认提交响应的任务 ID 位于 `data[0].task_id`。

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: <unique-operation-key>' \
  --data '{
    "model": "muse-image-ext",
    "prompt": "一只红色陶瓷杯放在白色桌面上，柔和棚拍灯光，产品摄影，无文字",
    "aspect_ratio": "1:1",
    "n": 1
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Accept": "application/json",
        "Idempotency-Key": "<unique-operation-key>"
    },
    json={
        "model": "muse-image-ext",
        "prompt": "一只红色陶瓷杯放在白色桌面上，柔和棚拍灯光，产品摄影，无文字",
        "aspect_ratio": "1:1",
        "n": 1
    }
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
    Accept: "application/json",
    "Idempotency-Key": "<unique-operation-key>"
  },
  body: JSON.stringify({
    "model": "muse-image-ext",
    "prompt": "一只红色陶瓷杯放在白色桌面上，柔和棚拍灯光，产品摄影，无文字",
    "aspect_ratio": "1:1",
    "n": 1
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}
```

## 请求头

**Authorization** `string` *required*

使用 APIMart API Key，格式为 `Bearer <token>`。提交和查询任务均需鉴权，使用同一用户身份。

**Idempotency-Key** `string`

强烈建议传入。每次独立生成使用一个新键（1–191 个可见 ASCII 字符，推荐 UUID），将示例中的 `<unique-operation-key>` 替换为实际值。提交超时或网络断开后重试，必须保持相同端点、请求体、响应版本及幂等键；获得任务 ID 后只查询任务。

## 请求参数

**model** `string` *required*

固定为 `muse-image-ext`。

**prompt** `string` *required*

生成内容的文本描述，支持中文和英文，去除首尾空白后不能为空。带参考图时也必填。

**image\_urls** `string[]`

参考图片列表，最多 9 个非空输入；支持公网 URL、Data URI（如 `data:image/png;base64,...`）或裸 base64。省略或传 `[]` 为纯文字生成。推荐 PNG、JPEG、WebP；远程 URL 必须可由服务器直接访问，不能依赖浏览器登录态。

所有参考图的原始字节合计不得超过 **11 MiB（11,534,336 字节）**，不是每张 11 MiB。base64 编码会额外增加请求体大小。不要传 `blob:` URL、本地文件路径或 `File` 对象。

**aspect\_ratio** `string`

支持下列七种比例。省略时，文生图默认 `1:1`，参考图生图跟随参考图构图；显式指定时按该比例生成。自动选择应省略此字段，不能传 `"auto"`。

`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`

**size** `string`

比例兼容字段，接受上述七种比例或 `auto`，不支持 `1024x1024` 等像素尺寸。仅传 `size: "auto"` 等同未指定比例。推荐只使用 `aspect_ratio`；两者均合法时 `aspect_ratio` 优先，但两个字段分别校验，合法比例不能抵消非法 `size`。

**n** `integer` (default: 1)

每次只生成 1 个结果，只能传数值 `1`。显式传 `0`、负数或大于 `1` 的值会报错。

> [!NOTE]
>
> 图片输出为 WebP URL，尺寸由模型决定，不支持指定像素或 1K / 2K / 4K 档位。不要发送非空 `resolution` 或任何时长字段。

### 其他可选参数

**webhook** `string`

任务通知的后端基础地址。平台去掉末尾斜杠后追加 `/callback`，例如 `https://your-backend.example/muse` 对应 `https://your-backend.example/muse/callback`。只使用轮询时可省略。

**language** `string`

控制 Webhook 错误文案语言，不改变生成内容。支持 `zh`、`en`、`ja`、`ko`、`ru`、`fr`、`de`、`id`、`pt`、`es`，不接受 `zh-CN` 等地区标签。轮询语言需另放在 GET 查询参数中。

## 参考图生成示例

```json theme={null}
{
  "model": "muse-image-ext",
  "prompt": "保留参考图中杯子的外观，将背景改为木质咖啡桌，温暖自然光",
  "image_urls": [
    "https://your-cdn.example/cup.png"
  ],
  "n": 1
}
```

将示例 URL 替换为实际可访问的图片地址。此示例省略比例以跟随参考图构图；如需固定比例，可添加 `aspect_ratio`。多图时在 `image_urls` 中追加输入，总数不超过 9 张。

## 提交响应

默认返回 HTTP `200`，`data` 为数组。`submitted` 仅表示任务已受理，不表示生成完成。保存 `data[0].task_id`，随后查询任务。

> **可选响应版本：2026-07-27**
>
> 发送请求头 `X-APIMart-Response-Version: 2026-07-27` 后，提交响应改为 HTTP `202`，任务 ID 改从 `data.id` 读取，查询地址位于 `data.poll_url`。
>
> ```json theme={null}
> {
>   "code": 202,
>   "request_id": "req_example",
>   "data": {
>     "id": "task_01K...",
>     "object": "generation.task",
>     "type": "image",
>     "status": "pending",
>     "progress": 0,
>     "poll_url": "/v1/tasks/task_01K..."
>   }
> }
> ```
>
> 该版本不改变 GET 查询结构。请勿添加版本头后仍按 `data[0].task_id` 解析提交响应。

## 查询任务与结果

替换为提交返回的完整任务 ID，使用同一用户身份查询。`language` 是可选的错误文案语言参数。完整字段见 [任务查询](https://docs.apimart.ai/cn/api-reference/tasks/status.md)。

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/tasks/<task_id>?language=zh' \
  --header 'Authorization: Bearer <token>'
```

建议每 5 秒查询一次，同一任务避免并发轮询。客户端等待超时或停止轮询不会取消服务端任务；保留任务 ID，稍后继续 GET 查询，不要自动重新提交。

| `data.status` | 处理方式 |
| - | - |
| `pending` / `processing` | 排队或处理中，继续查询。 |
| `completed` | 生成成功，停止轮询并读取结果 URL。 |
| `failed` | 生成失败，停止轮询，读取 `data.error.message`。 |
| `unknown` / … | 状态暂不明确，保留任务 ID 并有限重试查询；不要当作成功或自动重新生成。 |

以 `data.status` 判断是否结束，HTTP `200` 或 `progress: 100` 本身不代表生成成功。处理中出现 `polling_error` 也不等于终态失败。

完成后的查询响应示例（结果地址为占位值）：

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://cdn.example/generated-image.webp"
          ]
        }
      ]
    }
  }
}
```

查询响应的 `data` 是对象，`url` 是字符串数组。第一个结果位于 `data.result.images[0].url[0]`。`expires_at`（如有）是 Unix 秒级过期时间，请及时保存所需文件。`actual_time` 是任务处理耗时，不是视频播放时长。

## 功能限制与错误处理

不支持参考视频、参考音频、遮罩、首尾帧控制、续写或 remix。`quality` 不影响生成；`seed`、`negative_prompt`、`width`、`height`、`response_format`、`output_format` 不属于此模型的生成参数，请省略。`async: false` 不能改为同步生成，`stream` 不提供 SSE 生成流。

| HTTP / `error.code` | 处理建议 |
| - | - |
| `400 / invalid_request_error` | 检查提示词、参考图数量、比例、数量及固定规格参数。 |
| `409 / idempotency_in_progress` | 按 `Retry-After` 等待后，用同一个幂等键重试原请求。 |
| `409 / idempotency_key_reused` | 同一幂等键用于不同请求；修正键的使用，每次独立生成使用新键。 |
| `409 / idempotency_result_indeterminate` | 停止自动重发，保留幂等键和任务信息以便排查。 |
| `429` | 按 `Retry-After` 退避重试。 |

任务失败也可能返回 HTTP `200`，应读取 `data.status` 和 `data.error.message`。提交时遇到网络错误或 `5xx`，任务可能已受理，不能直接用新键重复提交。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.