# Seedream 5.0

seedream-5.0 支持文生图和参考图生成，提供 1K、2K 两档分辨率。

Seedream 5.0 走 OpenAI 兼容图片接口，可文生图，也可传入参考图继续生成。模型 ID 固定为 `seedream-5.0`。

```http
POST /v1/images/generations
```

耗时较长、批量并发或需要可靠轮询时，也可以使用异步任务：

```http
POST /v1/images/generations/jobs
```

> **不要使用 `POST /v1/images/edits`。参考图请放在生成接口的 `image` 或 `images` 字段中。**

## 接入信息

| 项目 | 内容 |
|---|---|
| API 模型 ID | `seedream-5.0` |
| 接口 | `POST https://kaienapi.com/v1/images/generations` |
| 鉴权 | `Authorization: Bearer <YOUR_API_KEY>` |
| 返回图片 | 读取 `data[].url` 预览或下载 |

调用前先用 `/v1/models` 确认当前 API Key 能看到 `seedream-5.0`。

## 价格

按张计费。一次请求只生成一张图。1K 与 2K 价格不同：

| 分辨率 | 价格 |
|---|---|
| 1K | 0.22 / 张 |
| 2K | 0.30 / 张 |

以控制台模型广场当前价格为准。

## 画面规格

**分辨率 `resolution`**：`1k` 或 `2k`，默认 `1k`。参数值使用小写 `k`。本模型不提供 4K 档位，请不要传 `4k`。

**比例 `size`**：默认 `auto`，由模型根据提示词或参考图判断；固定版式请明确填写比例。本模型的 `size` 填写画面比例，例如 `16:9`，不要写成 `1024x1024`。

可选比例：

`auto`、`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`5:4`、`4:5`、`16:9`、`9:16`、`2:1`、`1:2`、`3:1`、`1:3`、`21:9`、`9:21`

**参考图**：建议不超过 4 张；`images` 最多 10 项。只接受公网可直接下载的图片 URL。

**生成张数 `n`**：只允许 `1`，或不传（默认 `1`）。一次请求只生成一张图；需要多张请多次调用。

## 请求参数

所有参数均放在 JSON 顶层。

| 参数 | 必填 | 说明 |
|---|---|---|
| `model` | 是 | 固定填写 `seedream-5.0` |
| `prompt` | 是 | 至少 1 个字符。描述主体、场景、构图、风格、光线或画面文字；使用参考图时说明要保留和修改的内容 |
| `resolution` | 否 | `1k` 或 `2k`，默认 `1k` |
| `size` | 否 | 上方列出的比例之一，默认 `auto` |
| `image` | 否 | 单张参考图：公网可访问的图片 URL |
| `images` | 否 | 多张参考图：1～10 项公网图片 URL 数组，顺序保留 |
| `n` | 否 | 只允许 `1`，或不传。一次请求只生成一张图 |

单张参考图用 `image`，多张参考图用 `images`，同一次请求选用其中一种。

## 文生图 · 1K

```bash
curl --fail-with-body --silent --show-error \
  --request POST 'https://kaienapi.com/v1/images/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "seedream-5.0",
    "prompt": "电影感产品图：柔和自然光，主体清晰，背景简洁。",
    "resolution": "1k",
    "size": "auto",
    "n": 1
  }'
```

## 单张参考图 · 2K

```bash
curl --fail-with-body --silent --show-error \
  --request POST 'https://kaienapi.com/v1/images/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "seedream-5.0",
    "prompt": "保留参考图中的产品外形，改为干净的商业摄影风格，使用柔和自然光。",
    "resolution": "2k",
    "size": "4:3",
    "image": "https://example.com/reference.jpg",
    "n": 1
  }'
```

## 多张参考图

```bash
curl --fail-with-body --silent --show-error \
  --request POST 'https://kaienapi.com/v1/images/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "seedream-5.0",
    "prompt": "保留第一张图中的产品主体，参考第二张图的背景与光线，制作横版展示图。",
    "resolution": "2k",
    "size": "16:9",
    "images": [
      "https://example.com/product.jpg",
      "https://example.com/style.jpg"
    ],
    "n": 1
  }'
```

## 异步任务

客户端超时较短或需要并发提交时，改用任务接口：

```bash
curl https://kaienapi.com/v1/images/generations/jobs \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0",
    "prompt": "电影感产品图：柔和自然光，主体清晰，背景简洁。",
    "resolution": "1k",
    "size": "1:1",
    "n": 1
  }'
```

创建后保存任务 ID，再轮询：

```bash
curl https://kaienapi.com/v1/images/generations/jobs/<JOB_ID> \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

`queued` / `running` 时继续等待；`succeeded` 后读取 `data`；`failed` 时读取 `error.message`。不要在超时后自动重新创建同一任务。

## 成功响应

```json
{
  "created": 1784300000,
  "data": [
    {
      "url": "https://example.com/result.png"
    }
  ]
}
```

读取 `data[0].url`。一次请求只返回一张图。生成完成后请及时下载到自己的存储；结果 URL 不保证长期有效。

```bash
IMAGE_URL="$(jq -er '.data[0].url' response.json)"
curl --fail --location --output generated-image.png "$IMAGE_URL"
```

## 请求失败时

先看 HTTP 状态码，再读 `error.message`。核对 API Key 是否能访问 `seedream-5.0`，以及 `resolution`、`size` 和参考图地址是否正确。向客服反馈时请提供状态码、完整错误 JSON，以及响应头中的 `X-Oneapi-Request-Id`。