# 图片生成

> 用 Seedream、Nano Banana / Gemini 或 GPT Image 生成和编辑图片：参数、完整请求、统一任务查询与产物下载。

本页的图片型号共用统一媒体任务接口。`model` 原样使用[媒体模型目录](models.md#models-media-images)返回的 `id`，包括含空格的 Nano Banana 名称。GPT Image 也保留直接 Images API，直接返回 Base64 的使用方式见[GPT Image 生成与编辑](gpt-images.md)。

<a id="media-images-h-c80d5192"></a>

## 接口

| 项目 | 内容 |
| --- | --- |
| 方法与地址 | `POST https://platform.sgt.site/media/v1/images/generations` |
| 请求头 | `Authorization: Bearer <虚拟密钥>`、`Content-Type: application/json`；建议加 `Idempotency-Key` |
| 返回 | 任务对象 `media.task`。在 `wait` 秒内完成时 HTTP 200，否则 HTTP 202 |
| 结果位置 | `artifacts[]`，每张图片一项，`kind` 为 `image` |
| 取消 | 图片任务不支持取消 |

图片模型在上游同步出图，平台仍以任务受理。请求里设置 `"wait": 50` 可等待最多 50 秒；没完成时用返回的 `id` 查询[任务](media-tasks.md)即可，等待超时不代表生成失败。

<a id="media-images-h-9541ee3d"></a>

## 请求参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型 ID，例如 `doubao-seedream-5-0-lite-260128`。可选值见[模型列表：图片模型与输入方式](models.md#models-media-images) |
| `prompt` | string | 是 | 画面描述，不能为空，不超过 32000 字节 |
| `n` | integer | 否 | 生成张数，默认 1。Seedream 为 1–15（5 Pro 只能为 1），Nano Banana / Gemini 和 GPT Image 只能为 1 |
| `resolution` | string | 否 | 清晰度档位，例如 `2K`。各模型可选值不同，见下文 |
| `aspect_ratio` | string | 否 | 宽高比，例如 `16:9`。各模型可选值不同，见下文 |
| `size` | string | 否 | Seedream 使用档位或像素尺寸；GPT Image 使用 `auto` 或像素尺寸。规则见各型号参数；不能和 `aspect_ratio` 同时传 |
| `output_format` | string | 否 | 仅 Seedream：`jpeg` 或 `png` |
| `references` | array | 否 | 参考图，每项 `{"role": "reference", "type": "image", "url": "..."}`，写法见[参考图](media-images.md#media-images-references) |
| `provider_options` | object | 否 | Seedream 使用 `volcengine.watermark`；GPT Image 使用 `openai.quality` / `openai.background`，见下文；Nano Banana / Gemini 不接受选项 |
| `metadata` | object | 否 | 你的业务信息，例如 `{"order_id": "A1001"}`，随任务原样返回；不超过 64 KiB |
| `wait` | integer | 否 | 本次请求最多等待的秒数，0–50，默认 0。图片建议填 50 |
| `callback_url` | string | 否 | 接收任务状态通知的 HTTPS 地址，见[任务回调](task-callbacks.md)。通知不替代查询，失败重试不会重新生成图片 |

字段名要完全一致，不要传值为 `null` 的字段，不用的字段直接省略。数值要用 JSON 数字（`"n": 2`），不能写成字符串（`"n": "2"`）。

<a id="media-images-h-b80d0153"></a>

## Seedream 参数怎么填

适用于 `doubao-seedream-5-0-lite-260128`、`doubao-seedream-5-0-260128`、`doubao-seedream-5-0-pro-260628`、`doubao-seedream-4-5-251128`、`doubao-seedream-4-0-250828`。

<a id="media-images-h-833bd8a5"></a>

### 尺寸：三种写法任选其一

| 写法 | 示例 | 效果 |
| --- | --- | --- |
| `resolution` + `aspect_ratio`（推荐） | `"resolution": "2K", "aspect_ratio": "16:9"` | 按下方像素对照表输出，此例为 2560×1440 |
| `size` 写档位 | `"size": "2K"` | 由模型根据提示词自行决定宽高比 |
| `size` 写像素 | `"size": "2560x1440"` | 按指定像素输出，像素总数须在下方范围内 |

三项都不传时，按模型默认档位输出 1:1 方图；5 Pro 则由模型决定宽高比。`size` 和 `aspect_ratio` 不能同时出现。`size` 写档位时，如果同时传 `resolution`，两者必须相同。

| 模型 | `resolution` 可选值（默认） | `size` 像素总数范围 |
| --- | --- | --- |
| Seedream 5 Lite、5.0 | `2K`、`3K`、`4K`（`2K`） | 3686400–16777216，约 1920×1920 至 4096×4096 |
| Seedream 5 Pro | `1K`、`1.5K`、`2K`（`1K`） | 921600–4624220，约 960×960 至 2150×2150 |
| Seedream 4.5 | `2K`、`4K`（`2K`） | 3686400–16777216 |
| Seedream 4.0 | `1K`、`2K`、`4K`（`2K`） | 921600–16777216 |

`aspect_ratio` 可选 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3`、`21:9`。`size` 写像素时宽高比必须在 1:16 到 16:1 之间；像素总数低于下限时，平台按默认档位放大并保持宽高比，高于上限时返回 400。

**各档位的实际输出像素（宽×高）**

| 宽高比 | 1K | 1.5K | 2K | 3K | 4K |
| --- | --- | --- | --- | --- | --- |
| `1:1` | 1024×1024 | 1536×1536 | 2048×2048 | 3072×3072 | 4096×4096 |
| `4:3` | 1152×864 | 1792×1344 | 2304×1728 | 3456×2592 | 4608×3456 |
| `3:4` | 864×1152 | 1344×1792 | 1728×2304 | 2592×3456 | 3456×4608 |
| `16:9` | 1312×736 | 2048×1152 | 2560×1440 | 3840×2160 | 5120×2880 |
| `9:16` | 736×1312 | 1152×2048 | 1440×2560 | 2160×3840 | 2880×5120 |
| `3:2` | 1248×832 | 1872×1248 | 2496×1664 | 3744×2496 | 4992×3328 |
| `2:3` | 832×1248 | 1248×1872 | 1664×2496 | 2496×3744 | 3328×4992 |
| `21:9` | 1568×672 | 2352×1008 | 3024×1296 | 4536×1944 | 6048×2592 |


只能使用当前模型支持的档位列，例如 Seedream 4.5 只能用 2K 和 4K 两列。

<a id="media-images-h-a7f0f82e"></a>

### 一次生成多张（组图）

`n` 大于 1 时，模型会生成一组风格一致、内容相关的图片，例如同一角色的多个场景。规则：

- `n` 加上参考图数量不能超过 15。
- `n` 是上限，模型可能返回少于 `n` 张；按实际返回的张数计费。
- 5 Pro 不支持组图，`n` 只能为 1。

<a id="media-images-references"></a>

### 参考图

用于图生图、局部修改或多图融合。每张参考图是 `references` 中的一项：

```json
{"role": "reference", "type": "image", "url": "https://files.example.com/cup.png"}
```

| 项目 | 规则 |
| --- | --- |
| `role` / `type` | 固定为 `reference` / `image` |
| 数量 | 最多 14 张；5 Pro 最多 10 张 |
| 大小 | 单张不超过 10 MiB |
| 图片来源 | 每项只能填一种：`url`（公网 HTTPS 地址，或 `data:image/png;base64,...` 内联数据）、`file_id`（[上传文件](media-files.md)得到的 `id`）、`asset_id`（已审核通过的素材 ID） |

参考图按 `references` 中的顺序传给模型，提示词里可以用“图 1”“图 2”指代，实际理解效果取决于模型。整个请求体不能超过 4 MiB，图片较大时请先上传再用 `file_id`，不要用内联数据。

<a id="media-images-h-2c5858bd"></a>

### 水印与格式

- `provider_options.volcengine.watermark`：`true` 时由模型添加 AI 生成水印，默认 `false`。
- `output_format`：`jpeg` 或 `png`；不传时使用模型默认格式。

<a id="media-images-h-eeced450"></a>

## GPT Image：统一任务生成与编辑

适用于 `gpt-image-2`、`gpt-image-2.5-sunburst`、`gpt-image-2.5-flare`。无参考图为文生图，有参考图为编辑；两者都提交本页的 `/media/v1/images/generations`，使用 `wait`、幂等键和统一任务查询。

| 字段 | 规则 |
| --- | --- |
| `prompt` | 必填，不能为空，不超过 32000 字节 |
| `n` | 省略时为 1，只接受 1 |
| `size` | 可省略，或用 `auto`、`宽x高`（小写 `x`，如 `1024x1024`、`1152x2048`）；宽高分别为 1–65536 的整数，宽高比为 1:16–16:1；不接受 `1K` 等档位或 `1:1`、`1x1` 等比例简写。此为请求尺寸，实际输出以图片字节为准 |
| `references` | 最多 2 张 `reference` / `image`；仅接受可完整解码的 PNG、JPEG、WebP，每张不超过 10 MiB，宽×高不超过 16000000 像素。来源为公网 HTTPS `url`、图片 Data URL 或平台 `file_id`；不支持 `asset_id` |
| `provider_options.openai.quality` | 可省略，或为 `auto` / `medium`；省略时不补写厂商默认值 |
| `provider_options.openai.background` | 可省略，或为 `opaque`；不支持透明背景 |
| 不支持的字段或选项 | `resolution`、`aspect_ratio`、`output_format`、`response_format`、`stream`、`partial_images`、`mask`、`moderation`、`input_fidelity`、`output_compression` 及未列出的厂商选项在生成前拒绝 |

GPT 统一任务的参考图先按现有文件和引用权限校验，再安全读取并实际解码图片，按原顺序交给编辑接口；损坏图片、超过上述像素上限或 Data URL 中 MIME 与实际字节不符时，不发送生成请求。整个请求体上限为 4 MiB；较大图片先[上传文件](media-files.md)后使用 `file_id`。这些参考图限制不代表输出尺寸限制；实际张数、格式、宽高与用量取自生成结果，不能用请求的 `n`、`size` 或 HTTP 200 代替。

任务响应使用 `artifacts[]`，不返回直接接口的 `data[].b64_json`。平台把 Base64 结果转为可读取的产物；上游返回合法图片链接时也按产物返回，以实际 `url_type` 为准。直接 Images API 的请求和响应保持独立，见[GPT Image 生成与编辑](gpt-images.md)。

GPT 上游响应可正常解析、且平台已确认完整图片时，若 `usage.input_tokens` 或 `usage.output_tokens` 缺失、为 `null`，或整数数值未满足计费校验要求，生成保持 `status=succeeded`，已有产物可以下载，账务为 `billing.status=reserved` 或 `billing.status=reconciling`、`amount=null`，以原任务查询为准。平台保留原预留，不能用缺失值补零结算，也不能重新生成来补用量；继续核对原任务。上游明确返回两个计数均为 0 与缺失不同，但仍不代表免费，实际费用由价格规则与权威账单决定。

若用量字段类型或响应结构异常导致整个响应无法解析，例如 `input_tokens` 返回字符串 `"10"` 或小数 `1.5`，平台可能无法提取和保存其中的图片。此时任务为 `status=reconciling`，`artifacts` 为空，费用预留保留，通常为 `billing.status=reserved`、`amount=null`。继续查询原任务并联系平台核对；不能把空产物当成明确失败、免费或重新生成的依据。

<a id="media-images-h-184d7ee6"></a>

## Gemini 参数怎么填

适用于公开调用名 `Nano Banana`、`Nano Banana 2`、`Nano Banana Pro`、`Nano Banana 2 Lite`，以及仍在你的目录中可见的 `gemini-2.5-flash-image`、`gemini-3.1-flash-image`、`gemini-3-pro-image`、`gemini-3.1-flash-lite-image`。使用目录原样返回的 ID，不能把 Nano Banana 名称改成 Gemini 模板名；已有授权、渠道和价格仍按公开名称匹配。

| 字段 | 规则 |
| --- | --- |
| `prompt` | 必填，不能为空 |
| `n` | 只能为 1；需要多张时提交多个任务 |
| `resolution` | Nano Banana 2 / Pro 为 `1K`、`2K`、`4K`，默认 `1K`；Nano Banana / 2 Lite 只能为 `1K`。对应 Gemini 型号保持相同限制 |
| `aspect_ratio` | `auto`、`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`，默认 `1:1`；`auto` 由模型决定 |
| `references` | 最多 14 张 `reference` / `image`；来源为 `url`（HTTPS 或 `data:image/...;base64,` 内联数据）或 `file_id`，不支持 `asset_id` |
| 不支持的字段 | `size`、`output_format`、`provider_options`；传入返回 400 `unsupported_parameter` |

1K 档位的输出像素：

| 宽高比 | 1:1 | 2:3 | 3:2 | 3:4 | 4:3 | 4:5 | 5:4 | 9:16 | 16:9 | 21:9 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1K 像素 | 1024×1024 | 848×1264 | 1264×848 | 896×1200 | 1200×896 | 928×1152 | 1152×928 | 768×1376 | 1376×768 | 1584×672 |

2K、4K 档位按相同宽高比放大，边长约为 1K 的 2 倍和 4 倍，以实际返回为准。

普通 `Nano Banana`（对应 Gemini 2.5 Flash Image）使用原生 1K 输出，平台不向上游写 `imageConfig.imageSize`；Nano Banana 2 Lite 则按其模板传 `1K`。能力模板只决定这些参数规则，不自动替换公开调用名；上游型号仅由所选渠道的既有模型映射决定。

<a id="media-images-h-17d044b5"></a>

## 完整请求示例

以下示例可直接复制，先按[快速开始](overview.md)设置 `GATEWAY_ORIGIN` 和 `KEY`。每个新的生成请求请换一个新的 `Idempotency-Key`。

按使用场景选择示例。表中只列出支持该用法的型号；当前密钥能否使用，以[模型列表](models.md#models-media-images)的查询结果为准：

| 我要做什么 | 支持的型号 | 示例 |
| --- | --- | --- |
| 只用文字生成 | Seedream、Nano Banana / Gemini、GPT Image 全部型号 | [文生图](#media-images-h-34485225)、[Gemini 文生图](#media-images-h-3e5cf9b1)、[GPT 文生图](#media-images-gpt-generate) |
| 指定像素宽高 | Seedream；GPT Image 接受请求尺寸但不保证实际像素相同 | [指定像素尺寸](#media-images-h-e4d39484)、[GPT 文生图](#media-images-gpt-generate) |
| 一次生成多张风格一致的图 | Seedream，5 Pro 除外（`n` 最多 15） | [一次生成四张组图](#media-images-h-e6fd57d2) |
| 用参考图修改或融合 | Seedream（最多 14 张，5 Pro 最多 10 张）；Nano Banana / Gemini（最多 14 张）；GPT Image（最多 2 张）；后两者不支持 `asset_id` | [用参考图修改图片](#media-images-h-a4a3abb3)、[GPT 单图与双图编辑](#media-images-gpt-edit) |
| 直接读取 GPT Base64 同步响应 | 三款 GPT Image，使用独立的直接 Images API | [GPT Image 生成与编辑](gpt-images.md) |

<a id="media-images-h-34485225"></a>

### 文生图

```bash
curl -s "$GATEWAY_ORIGIN/media/v1/images/generations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-demo-001" \
  -d '{
    "model": "doubao-seedream-5-0-lite-260128",
    "prompt": "白色背景上的蓝色陶瓷杯，柔和自然光，产品摄影",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "metadata": {"order_id": "A1001"},
    "wait": 50
  }'
```

<a id="media-images-h-e4d39484"></a>

### 指定像素尺寸

```json
{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "雨后城市街道的电影感夜景，霓虹灯倒影",
  "size": "2560x1440",
  "wait": 50
}
```

<a id="media-images-h-e6fd57d2"></a>

### 一次生成四张组图

```json
{
  "model": "doubao-seedream-5-0-lite-260128",
  "prompt": "同一只橘猫在春、夏、秋、冬四个季节中的插画，画风统一",
  "n": 4,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "wait": 50
}
```

<a id="media-images-h-a4a3abb3"></a>

### 用参考图修改图片

先上传本地图片取得 `file_id`（也可以直接使用公网 URL，跳过这一步）：

```bash
curl -s "$GATEWAY_ORIGIN/media/v1/files" \
  -H "Authorization: Bearer $KEY" \
  -F purpose=reference \
  -F "file=@cup.png;type=image/png" | jq -r '.id'
```

再在 `references` 中引用。下例同时使用了 URL 和 `file_id` 两种来源：

```json
{
  "model": "doubao-seedream-5-0-lite-260128",
  "prompt": "把图 1 中杯子的颜色换成图 2 的配色，其余保持不变",
  "references": [
    {"role": "reference", "type": "image", "url": "https://files.example.com/cup.png"},
    {"role": "reference", "type": "image", "file_id": "替换为上一步返回的 id"}
  ],
  "resolution": "2K",
  "wait": 50
}
```

<a id="media-images-h-3e5cf9b1"></a>

### Gemini 文生图

Nano Banana 系列使用公开名称。以下 Lite 示例采用 `wait=0`，接收任务后查询原 ID；需要等待时改为 `wait=50`，等待方式不改变生成内容：

```bash
curl --fail-with-body -sS "$GATEWAY_ORIGIN/media/v1/images/generations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nano-lite-demo-001" \
  -d '{"model":"Nano Banana 2 Lite","prompt":"生成一只大象的水彩插画","n":1,"resolution":"1K","wait":0}' \
  -o image-task.json
```

其余三款的完整请求体如下，每次新的生成使用一个新幂等键：

```json
{"model":"Nano Banana","prompt":"极简咖啡店标志，白色背景，无文字","n":1,"resolution":"1K","wait":50}
```

```json
{"model":"Nano Banana 2","prompt":"极简咖啡店标志，白色背景，无文字","n":1,"resolution":"2K","aspect_ratio":"1:1","wait":50}
```

```json
{"model":"Nano Banana Pro","prompt":"把参考图的杯子改为红色，保留光照","n":1,"resolution":"2K","references":[{"role":"reference","type":"image","url":"https://files.example.com/cup.png"}],"wait":50}
```

目录若返回 Gemini 名称，也原样使用，例如：

```json
{
  "model": "gemini-3.1-flash-image",
  "prompt": "极简风格的咖啡店标志，白色背景，无文字",
  "aspect_ratio": "1:1",
  "resolution": "2K",
  "wait": 50
}
```

<a id="media-images-gpt-generate"></a>

### GPT 文生图

```bash
curl --fail-with-body -sS "$GATEWAY_ORIGIN/media/v1/images/generations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gpt-image-demo-001" \
  -d '{"model":"gpt-image-2","prompt":"一只蓝色陶瓷杯，浅灰背景，柔和自然光","n":1,"size":"auto","provider_options":{"openai":{"quality":"auto","background":"opaque"}},"metadata":{"order_id":"A1001"},"wait":0}' \
  -o image-task.json
```

<a id="media-images-gpt-edit"></a>

### GPT 单图与双图编辑

单图示例中的 `file_id` 替换为前面上传接口返回的 ID：

```json
{"model":"gpt-image-2.5-sunburst","prompt":"把杯子改为红色，保留形状、光照和背景","n":1,"size":"1024x1024","references":[{"role":"reference","type":"image","file_id":"替换为上传返回的 id"}],"wait":50}
```

双图按数组顺序引用，用同一接口完成编辑：

```json
{"model":"gpt-image-2.5-flare","prompt":"把图 1 的杯子放到图 2 的桌面，保留杯子外观","n":1,"size":"1152x2048","provider_options":{"openai":{"quality":"medium"}},"references":[{"role":"reference","type":"image","url":"https://files.example.com/cup.png"},{"role":"reference","type":"image","file_id":"替换为桌面图片上传返回的 id"}],"wait":50}
```

把上面任一完整 JSON 请求体保存为 `body.json` 后，使用一个新的幂等键提交。若改用内联参考图，把该项的 `file_id` 或 HTTPS `url` 换成 `"url":"data:image/png;base64,BASE64_INPUT_PNG"`；占位值必须替换为完整图片 Base64，MIME 与实际文件一致，同一项不保留第二种来源。

```bash
curl --fail-with-body -sS "$GATEWAY_ORIGIN/media/v1/images/generations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-custom-001" \
  --data-binary @body.json -o image-task.json
```

查询刚才的任务并取回产物，后续只查询同一 `TASK_ID`：

```bash
TASK_ID=$(jq -er '.id | select(type == "string" and length > 0)' image-task.json)
curl --fail-with-body -sS "$GATEWAY_ORIGIN/media/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $KEY"
```

`wait=50` 到期仍未完成时返回 HTTP 202；继续查询原任务。提交断连且未拿到 ID 时，使用原请求和原 `Idempotency-Key` 重放；同键同生成内容返回同一任务，同键不同生成内容返回 409 `idempotency_conflict`。`metadata` 保持在任务中；不要因为等待超时或交付失败换新键生成。具体规则见[媒体请求约定](media-access.md)。

<a id="media-images-h-3b1f210d"></a>

## 响应

<a id="media-images-h-fd95bdc7"></a>

### 在等待时间内完成（HTTP 200）

下例是 `n: 2` 时的完整响应。ID、链接与金额均为示意：

**完整响应（`n: 2`，Seedream 厂商链接）**

```json
{
  "id": "task_example",
  "object": "media.task",
  "model": "doubao-seedream-5-0-lite-260128",
  "type": "image",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1791763200,
  "started_at": 1791763205,
  "finished_at": 1791763221,
  "artifacts": [
    {
      "index": 0,
      "kind": "image",
      "mime_type": "image/png",
      "state": "available",
      "url": "https://example.com/image-0.png",
      "url_type": "upstream",
      "expires_at": null
    },
    {
      "index": 1,
      "kind": "image",
      "mime_type": "image/png",
      "state": "available",
      "url": "https://example.com/image-1.png",
      "url_type": "upstream",
      "expires_at": null
    }
  ],
  "error": null,
  "billing": {"status": "settled", "currency": "CNY", "amount": "0.600000"},
  "metadata": {"order_id": "A1001"},
  "request_id": "req_example"
}
```

Nano Banana / Gemini 的图片，以及 GPT Image 返回 Base64 时的图片，由平台转存后返回签名链接，`url_type` 为 `signed`，并带到期时间：

```json
{
  "index": 0,
  "kind": "image",
  "mime_type": "image/png",
  "state": "available",
  "url": "https://platform.sgt.site/media/v1/tasks/task_example/artifacts/0?expires=1791849600&sig=example-signature",
  "url_type": "signed",
  "expires_at": 1791849600
}
```

<a id="media-images-h-0e7bb8a4"></a>

### 等待时间内未完成（HTTP 202）

```json
{
  "id": "task_example",
  "object": "media.task",
  "model": "doubao-seedream-5-0-lite-260128",
  "type": "image",
  "status": "queued",
  "progress": 0,
  "created_at": 1791763200,
  "started_at": null,
  "finished_at": null,
  "artifacts": [],
  "error": null,
  "billing": {"status": "reserved", "currency": "CNY", "amount": null},
  "metadata": {"order_id": "A1001"},
  "request_id": "req_example"
}
```

这不是错误。保存 `id`，每 3 秒调用 `GET /media/v1/tasks/{id}`，直到 `status` 为 `succeeded` 或 `failed`。

<a id="media-images-h-eb7a6cab"></a>

### 字段说明

| 字段 | 说明 |
| --- | --- |
| `id` | 任务 ID，形如 `task_` 加 32 位字符。查询、排查都用它 |
| `status` | `queued` 排队、`running` 生成中、`succeeded` 成功、`failed` 失败、`reconciling` 平台核对中（继续查询，不要重新提交） |
| `progress` | 0–100 的进度，成功时为 100 |
| `created_at`、`started_at`、`finished_at` | integer/null，Unix 秒；时间未知或尚未发生为 null，不当成 0 |
| `artifacts[].index` | 产物序号，从 0 开始 |
| `artifacts[].kind` | 图片任务为 `image` |
| `artifacts[].mime_type` | 例如 `image/png`、`image/jpeg` |
| `artifacts[].state` | `available` 可下载；`pending` 准备中，稍后再查；`unavailable` 当前不可读 |
| `artifacts[].url` | 下载地址。下载时不要带 `Authorization` |
| `artifacts[].url_type` | `upstream` 为模型厂商的临时链接（Seedream 约 24 小时内有效）；`signed` 为平台签名链接 |
| `artifacts[].expires_at` | 签名链接的到期时间（Unix 秒）；厂商链接为 `null` |
| `error` | null 或错误对象；`succeeded` 也可能有 `stage=delivery` 的交付错误，包含 `code`、`message`、`stage`、`retryable` |
| `billing.status` | `reserved` 已预留、`settled` 已结算、`released` 未扣费、`refunded` 已退款、`reconciling` 核对中 |
| `billing.amount` | 实际扣费金额（人民币元，字符串）；未结算时为 `null` |
| `metadata` | 提交时传入的业务信息 |
| `request_id` | 平台请求标识，联系平台排查时提供 |

<a id="media-images-h-8894375c"></a>

### 下载图片

遍历全部 `artifacts`，只对 `state=available` 且地址非空的项发起下载；`kind=image` 表示图片，不保证 PNG。Seedream 支持 JPEG/PNG，多个结果分别保存，不能把 JPEG 字节改名成 PNG。明确的 `image/jpeg` 对应 `.jpg`，`image/png` 对应 `.png`；文件头冲突时以实际字节核对，未知时保留 `.bin` 并提示。

把[快速开始的完整 Python 示例](overview.md#overview-h-600de8a7)保存为 `media_client.py`，用已提交任务的 ID 下载全部图片：

```bash
export TASK_ID="替换为图片任务 id"
python media_client.py
```

脚本检查 HTTP 错误、空地址和下载字节数，完成前只写 `.part`，不会把错误正文保存为图片。`succeeded` 但数组为空或某张图不可读时报告并继续查询原任务，不能静默跳过。已下载的图片可先保留；账务待核对时不把流程记为全部完成。

签名过期可以重新查询原任务获取新地址；上游图片过期/清理则不能靠重签恢复。下载失败或客户端不能预览，都不自动重新生成。更多恢复与账务规则见[任务查询与结算](media-tasks.md)。

<a id="media-images-h-5b17a229"></a>

## 常见错误

| 报错信息（`error.message`） | 原因 | 改法 |
| --- | --- | --- |
| size and aspect_ratio cannot be combined | 同时传了 `size` 和 `aspect_ratio` | 只保留一个 |
| <模型 ID> resolution must be one of 2K 4K | 档位不在该模型支持范围内 | 按上方表格选择档位 |
| size and resolution specify conflicting image resolutions | `size` 写了档位，又传了不同的 `resolution` | 删掉其中一个，或改成相同档位 |
| <模型 ID> image dimensions exceed 16777216 pixels | `size` 像素总数超过上限 | 缩小宽高 |
| n must be 1..15 and reference images plus n must not exceed 15 | 张数加参考图超过 15 | 减少 `n` 或参考图 |
| Parameter size is not supported by this model | 给 Gemini 传了 `size` 等不支持的字段 | 删除该字段 |
| n is outside the supported range | Nano Banana / Gemini、GPT Image 或 Seedream 5 Pro 传了 `n` > 1，或其他 Seedream 超过 15 | 改为允许的张数；单张型号需要多张时分别提交新任务 |
| resolution has an unsupported value | 档位拼写不对（如小写 `2k`）或不在可选值内 | 使用大写 `1K`、`2K` 等表中的值 |
| Too many references for role reference | 参考图超过上限 | 减少参考图 |
| Parameter references.asset_id is not supported by this model | 给 Nano Banana / Gemini 或 GPT Image 传了 `asset_id` | 改用 `url` 或 `file_id` |
| Parameter provider_options.openai.X is not supported by this model | 给 GPT Image 传了未支持的厂商选项，例如 `mask` | 仅使用上方列出的 `quality` 和 `background` |
| Media request exceeds 4 MiB | 内联 Base64 图片太大 | 先上传，改用 `file_id` |

任务 `status` 为 `failed` 时，`error.message` 说明原因，常见的是提示词或参考图未通过内容审核。修改后用新的 `Idempotency-Key` 重新提交。完整错误码见[媒体错误处理](media-errors.md)。

需要 Seedream 或 Gemini 的原生请求格式（例如图层拆分、搜索增强）时，见[Seedream 原生接口](native-seedream.md)和[Gemini 原生接口](native-gemini.md)。