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

# 图片模型

> 用 OpenAI 兼容的图片接口生成、编辑图片，支持流式返回预览图。

大部分图片模型都可以用 OpenAI 兼容的两个接口调用：文生图 `POST /v1/images/generations`、图片编辑 `POST /v1/images/edits`。直接用 OpenAI 官方 SDK，把 `base_url` 换成 `https://api.ephone.ai/v1` 即可。

不同模型支持的参数不同（尺寸、画质档位、能否透明背景等），以模型详情页为准。需要异步提交、拿到图片链接的场景，见 [任务接口](https://docs.rixapi.com/docs/cn/guides/task.md)。

## 文生图

```python Python theme={null} theme={null}
import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ephone.ai/v1",
    api_key="",  # 替换为你在本站点的 API Key
)

result = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="一只趴在窗台上晒太阳的橘猫，水彩风格",
    size="1024x1024",
    quality="low",
)

with open("cat.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
print(result.usage)
```

```javascript Node.js theme={null} theme={null}
import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.ephone.ai/v1",
  apiKey: "", // 替换为你在本站点的 API Key
});

const result = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "一只趴在窗台上晒太阳的橘猫，水彩风格",
  size: "1024x1024",
  quality: "low",
});

fs.writeFileSync("cat.png", Buffer.from(result.data[0].b64_json, "base64"));
console.log(result.usage);
```

```bash cURL theme={null} theme={null}
curl https://api.ephone.ai/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "一只趴在窗台上晒太阳的橘猫，水彩风格",
    "size": "1024x1024",
    "quality": "low"
  }'
```

返回示例（`b64_json` 已截断）：

```json theme={null} theme={null}
{
  "created": 1793011034,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }],
  "background": "opaque",
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 13,
    "input_tokens_details": { "image_tokens": 0, "text_tokens": 13 },
    "output_tokens": 196,
    "output_tokens_details": { "image_tokens": 196, "text_tokens": 0 },
    "total_tokens": 209
  }
}
```

## 编辑图片

把一张或多张图片连同提示词发给编辑接口，可以改风格、换元素、多图合成；带上遮罩图 `mask` 可以只重绘透明区域。图片用 multipart 表单上传，多张时字段名用 `image[]`（官方 SDK 传列表会自动处理）。

```python Python theme={null} theme={null}
import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ephone.ai/v1",
    api_key="",  # 替换为你在本站点的 API Key
)

result = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=[open("cat.png", "rb")],
    prompt="把猫换成蓝色，其他保持不变",
)

with open("cat-blue.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
```

```bash cURL theme={null} theme={null}
curl https://api.ephone.ai/v1/images/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F model="gpt-image-2.5-sunburst" \
  -F "image[]=@cat.png" \
  -F prompt="把猫换成蓝色，其他保持不变"
```

## 流式返回预览图

gpt-image 系列（`gpt-image-2.5-sunburst`、`gpt-image-2.5-flare`、`gpt-image-2`、`gpt-image-1.5`、`gpt-image-1` 等）支持流式：传 `stream: true`，生成过程中先推送 0\~3 张预览图，最后推送完整图片。适合在界面上先给用户看到画面轮廓，等待感更短。

| 参数 | 说明 |
| :- | :- |
| `stream` | 设为 `true` 开启流式 |
| `partial_images` | 预览图张数，0\~3。设为 0 时只推送最终图。图生成得快时，实际收到的预览图可能比要求的少 |

返回的是 SSE 事件流，每条事件的 `type` 与 `event:` 行一致：

* `image_generation.partial_image`：一张预览图（编辑接口为 `image_edit.partial_image`），`partial_image_index` 从 0 开始
* `image_generation.completed`：最终图（编辑接口为 `image_edit.completed`），带本次的 `usage`
* `error`：推送过程中出错，见下文

```python Python theme={null} theme={null}
import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ephone.ai/v1",
    api_key="",  # 替换为你在本站点的 API Key
)

stream = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="一只趴在窗台上晒太阳的橘猫，水彩风格",
    size="1024x1024",
    quality="low",
    stream=True,
    partial_images=2,
)

for event in stream:
    if event.type == "image_generation.partial_image":
        with open(f"cat-preview-{event.partial_image_index}.png", "wb") as f:
            f.write(base64.b64decode(event.b64_json))
    elif event.type == "image_generation.completed":
        with open("cat.png", "wb") as f:
            f.write(base64.b64decode(event.b64_json))
        print(event.usage)
```

```javascript Node.js theme={null} theme={null}
import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.ephone.ai/v1",
  apiKey: "", // 替换为你在本站点的 API Key
});

const stream = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "一只趴在窗台上晒太阳的橘猫，水彩风格",
  size: "1024x1024",
  quality: "low",
  stream: true,
  partial_images: 2,
});

for await (const event of stream) {
  if (event.type === "image_generation.partial_image") {
    fs.writeFileSync(`cat-preview-${event.partial_image_index}.png`, Buffer.from(event.b64_json, "base64"));
  } else if (event.type === "image_generation.completed") {
    fs.writeFileSync("cat.png", Buffer.from(event.b64_json, "base64"));
    console.log(event.usage);
  }
}
```

```bash cURL theme={null} theme={null}
curl -N https://api.ephone.ai/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "一只趴在窗台上晒太阳的橘猫，水彩风格",
    "size": "1024x1024",
    "quality": "low",
    "stream": true,
    "partial_images": 2
  }'
```

编辑接口用法相同：Python 里给 `client.images.edit(...)` 加上 `stream=True, partial_images=2`，cURL 里加 `-F stream=true -F partial_images=2`，事件名换成 `image_edit.*`。

原始事件流示例（`b64_json` 已截断）：

```text theme={null} theme={null}
event: image_generation.partial_image
data: {"type":"image_generation.partial_image","sequence_number":0,"b64_json":"iVBORw0KGgo...","partial_image_index":0,"created_at":1793010866,"background":"opaque","output_format":"png","quality":"low","size":"1024x1024"}

event: image_generation.completed
data: {"type":"image_generation.completed","sequence_number":1,"b64_json":"iVBORw0KGgo...","created_at":1793010871,"background":"opaque","output_format":"png","quality":"low","size":"1024x1024","usage":{"input_tokens":13,"input_tokens_details":{"image_tokens":0,"text_tokens":13},"output_tokens":273,"output_tokens_details":{"image_tokens":273,"text_tokens":0},"total_tokens":286}}
```

### 计费

* 每张预览图都会额外消耗一些图片输出 token（数量随尺寸和画质变化），已经包含在 `completed` 事件的 `usage` 里，按实际用量扣费，不另外收费。不需要预览图时把 `partial_images` 设为 0。
* 出错没有拿到最终图的请求不扣费。
* 推送途中客户端断开连接时，图片仍会生成完成并照常扣费。

### 出错时

* **开始推送之前出错**（参数错误、余额不足、内容审核不通过等）：和非流式一样返回 HTTP 错误码与 JSON 报错。
* **推送过程中出错**（已经收到预览图之后）：连接上会收到一条 `error` 事件，随后结束，此时 HTTP 状态码已经是 200。官方 SDK 遍历事件时会抛出 `APIError`，请用 `try` 包住整个遍历：

```text theme={null} theme={null}
event: error
data: {"type":"error","error":{"message":"Image generation failed","code":"server_error"}}
```

### 其他说明

* 一次要多张图（`n` 大于 1）时没有预览图：每张最终图各一条 `completed` 事件，`usage` 只在最后一条上，是所有图片的合计。
* 其他模型也可以传 `stream: true`：没有预览图，图片生成完后收到一条 `completed` 事件，代码不用区分模型。
* 流式下图片默认以 base64（`b64_json`）返回；传 `response_format: "url"` 时最终图改为图片链接，预览图仍是 base64。
* 不要预览图时，最终图出来之前连接上可能长时间没有数据，请把客户端的读取超时设为几分钟。

## 常用参数

| 参数 | 说明 |
| :- | :- |
| `model` | 模型名，如 `gpt-image-2.5-sunburst` |
| `prompt` | 提示词 |
| `n` | 生成张数，gpt-image 系列为 1\~10 |
| `size` | 尺寸，如 `1024x1024`、`1536x1024`、`auto` |
| `quality` | 画质，gpt-image 系列为 `low` / `medium` / `high` / `auto`，2.5 系列另有 `xhigh` / `max` |
| `background` | 背景：`auto` / `opaque` / `transparent`（透明需配 `png` 或 `webp`） |
| `output_format` | 输出格式：`png` / `jpeg` / `webp` |
| `output_compression` | 压缩率 0\~100，只对 `jpeg` / `webp` 生效 |
| `moderation` | 内容审核强度：`auto` / `low` |
| `response_format` | `b64_json` 或 `url`。gpt-image 系列默认 `b64_json`，传 `url` 时返回本站存储的图片链接 |
| `stream` / `partial_images` | 流式与预览图张数，见上文 |
| `user` | 你这边的终端用户标识，用于滥用监控，可不传 |

## 注意事项

> [!WARNING]
>
> 1. 使用时需要将 `OPENAI_BASE_URL` 设置为 `https://api.ephone.ai/v1`
> 2. `OPENAI_API_KEY` 应设置为您的 API Key
> 3. 大部分模型已适配 OpenAI 生图接口，个别模型未适配，请参考模型文档
> 4. 图片链接（`response_format: "url"` 或任务接口返回的链接）有有效期，请及时下载保存

## 相关链接

> [card] [OpenAI 图片生成指南](https://developers.openai.com/api/docs/guides/image-generation)
>
> 官方的用法说明，含流式与编辑

> [card] [OpenAI 图片接口参考](https://developers.openai.com/api/reference/resources/images)
>
> 完整参数与事件字段


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