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

# 图像生成

> 通过统一图像端点提交提示词，并按模型参数读取生成结果。

使用 `POST https://api.apione.ai/v1/images/generations` 创建图像。

![APIONE 网页端图片生成页面](https://mintcdn.com/apione/pAFvFGkbmcRZirTZ/images/ui/image-generation.png?fit=max\&auto=format\&n=pAFvFGkbmcRZirTZ\&q=85\&s=30f889fdfea0613466caf9910f0b1090)

网页端图片生成提供模板、提示词、模型、画幅、分辨率和输出格式入口。

![APIONE 模型广场图片模型列表](https://mintcdn.com/apione/Vq80XJbufibzxH8S/images/ui/image-models.png?fit=max\&auto=format\&n=Vq80XJbufibzxH8S\&q=85\&s=eae9bd2f7dca4ec988e562d03c1e78aa)

模型广场的图片分类可以比较图像模型、按张价格、输入输出类型和可用渠道。

## 运行示例前准备

安装 Python 3，并在运行脚本的同一个 Python 环境安装依赖：

```bash theme={null}
python -m pip install requests
```

如果你的系统使用 `python3`，安装和运行时都使用 `python3`。Windows 也可以对应使用 `py -m pip install requests` 与 `py example.py`。使用虚拟环境时，先激活环境。

在 [API 密钥页](https://apione.ai/zh/app/api-keys)创建密钥，从[当前 Key 可用的模型列表](https://apione.ai/docs/models/catalog.md)复制支持图像生成的模型 ID，然后在运行脚本的终端设置变量。下面的大写值是占位符，需要替换。

> [tab] macOS / Linux
>
> ```bash theme={null}
> export APIONE_API_KEY="YOUR_APIONE_API_KEY"
> export APIONE_IMAGE_MODEL="YOUR_IMAGE_MODEL"
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $env:APIONE_API_KEY = "YOUR_APIONE_API_KEY"
> $env:APIONE_IMAGE_MODEL = "YOUR_IMAGE_MODEL"
> ```

变量只对当前终端及其启动的子进程生效。在同一终端运行后面的示例；IDE、容器或新终端需要另行配置。不要把真实密钥提交到代码仓库。

## 查询模型和参数

先查询当前 Key 可用的图像模型，再查询目标模型的参数：

```bash theme={null}
curl https://api.apione.ai/v1/models/YOUR_IMAGE_MODEL/params \
  -H "Authorization: Bearer YOUR_APIONE_API_KEY"
```

尺寸、数量、质量、返回格式和其他扩展字段由模型决定，不应套用其他模型的枚举。

## 最小请求

```bash theme={null}
curl https://api.apione.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_APIONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "白色摄影棚中的透明玻璃花瓶，柔和侧光"
  }'
```

成功响应会包含生成结果或结果引用。具体字段及 URL、Base64 等返回形式以目标模型和当前参数说明为准。

## 常见问题

| 问题 | 检查项 |
| - | - |
| 模型不可用 | 当前 Key 的 `/v1/models` 是否包含该 ID |
| 参数错误 | `/v1/models/{model}/params` 返回的字段和枚举 |
| 内容被拒绝 | 提示词、上传素材及目标模型的内容规则 |
| 结果为空或超时 | 请求 ID、控制台明细和上游状态 |

图像通常按张、按请求或按模型规则计费。最终费用以控制台请求明细为准。

## 请求字段怎么确认

`model` 和 `prompt` 是最小请求中的核心字段。尺寸、数量、质量、风格、背景、种子、负面提示词及返回格式是否可用，由目标模型决定。调用参数接口后，按以下顺序检查：

1. 字段是否存在；
2. 类型是字符串、数字、布尔值还是数组；
3. 可选枚举和默认值；
4. 是否影响单次费用；
5. 是否与其他字段互斥。

> [!WARNING]
>
> 不要把某个模型支持的 `size`、`quality` 或 `n` 直接复制到另一个模型。即使字段同名，允许值也可能不同。

## Python 示例

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

payload = {
    "model": os.environ["APIONE_IMAGE_MODEL"],
    "prompt": "白色摄影棚中的透明玻璃花瓶，柔和侧光",
}

response = requests.post(
    "https://api.apione.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['APIONE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=180,
)
print("status:", response.status_code)
print("request-id:", {name: response.headers[name] for name in ("X-Request-ID", "X-Maxx-Trace-Id", "X-Maxx-Request-ID") if name in response.headers})
response.raise_for_status()
print(response.json())
```

## Node.js 示例

使用 Node.js 18 或更高版本（内置 `fetch`），在配置好上述环境变量的同一终端执行。

将下面的 JavaScript 代码保存为 `example.mjs`。在已设置本页所需环境变量的同一终端运行 `node example.mjs`。使用 Node.js 18 或更高版本，内置 `fetch` 无需额外依赖。

```javascript theme={null}
const response = await fetch("https://api.apione.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APIONE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: process.env.APIONE_IMAGE_MODEL,
    prompt: "白色摄影棚中的透明玻璃花瓶，柔和侧光",
  }),
});

console.log("status:", response.status);
console.log("request-id:", Object.fromEntries(["X-Request-ID", "X-Maxx-Trace-Id", "X-Maxx-Request-ID"].map(name => [name, response.headers.get(name)]).filter(([, value]) => value)));
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result);
```

## 处理生成结果

先打印一次完整响应确认结构，再编写固定解析逻辑。返回可能是结果 URL、Base64 或模型定义的对象。若得到临时 URL，应及时下载到自己的存储，并记录文件类型、尺寸、任务时间和请求 ID。

不要仅凭 HTTP 200 判断图片可用。还应验证：

* 结果数组是否为空；
* URL 是否能访问，Base64 是否能解码；
* 实际图片格式和扩展名是否一致；
* 宽高、透明通道和颜色空间是否符合业务要求；
* 内容审核或修订字段是否需要展示给用户。

## 上线前测试用例

| 用例 | 目的 |
| - | - |
| 最短合法提示词 | 验证基本连通与默认参数 |
| 中文与英文提示词 | 验证业务语言表现 |
| 支持范围内的最小/最大尺寸 | 验证边界和费用 |
| 不支持的枚举 | 确认错误信息可读 |
| 超时与断网 | 验证不会无限重复生成 |
| 内容受限输入 | 验证拒绝信息和用户提示 |

## 计费与重试

媒体模型可能按张、按请求或按参数档位计费。先在模型参数和控制台核对价格，再批量运行。网络中断后保留请求 ID；结果未知时不要无限重发同一创建请求。

## 完整实战：生成并保存 PNG

2026 年 11 月 14 日使用 APIONE 当前 Key 可用的 `gpt-image-2` 完成一次最小请求：HTTP 200，返回 `data[0].b64_json`。未指定尺寸和质量；本次实际返回 `size=1254x1254`、`quality=low`、`output_format=png`。这些是单次测试结果，不是固定默认值或所有分组的能力承诺。

先按本页设置 `APIONE_API_KEY` 并安装 `requests`，确认当前 Key 仍有该模型权限。保存为 `generate_image.py`，运行 `python generate_image.py`。代码只提交一次创建请求，不自动重试，解码后将结果保存在当前目录。

```python theme={null}
import base64
import os
from pathlib import Path
import requests

response = requests.post(
    "https://api.apione.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['APIONE_API_KEY']}"},
    json={"model": "gpt-image-2", "prompt":
          "A single blue circle centered on a plain white background, flat icon, no text."},
    timeout=(15, 180),
)
ids = {name: response.headers[name] for name in
       ("X-Request-ID", "X-Maxx-Trace-Id", "X-Maxx-Request-ID")
       if name in response.headers}
print("status:", response.status_code, "request identifiers:", ids)
response.raise_for_status()
result = response.json()
items = result.get("data")
if not isinstance(items, list) or not items:
    raise RuntimeError("No generated image returned")
image = items[0].get("b64_json")
if not image:
    raise RuntimeError("Expected b64_json; inspect this model's actual response")
if result.get("output_format") != "png":
    raise RuntimeError("Output is not PNG; inspect the actual output_format")
content = base64.b64decode(image, validate=True)
if not content.startswith(b"\x89PNG\r\n\x1a\n"):
    raise RuntimeError("Invalid PNG signature")
Path("apione-image.png").write_bytes(content)
print("saved:", Path("apione-image.png").resolve(), "bytes:", len(content))
print("usage:", result.get("usage"))
```

### 本次真实响应（图片数据已省略）

```json theme={null}
{
  "created": 1794638369,
  "background": "opaque",
  "data": [
    {
      "b64_json": "BASE64_IMAGE_DATA_OMITTED",
      "generation_id": "76bcf9e2-ed94-4af7-8a19-8c0ed59ddb18"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "safety_identifier": null,
  "size": "1254x1254",
  "usage": {
    "input_tokens": 23,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 23
    },
    "output_tokens": 229,
    "output_tokens_details": {
      "image_tokens": 229,
      "text_tokens": 0
    },
    "total_tokens": 252
  }
}
```

本次文件已验证为可解码的 1254 × 1254 PNG，大小 1,043,307 字节。用量为 23 输入 Token、229 输出 Token；最终扣费需到同一请求的控制台明细核对，不能用 Token 数自行认定费用。该例没有异步任务查询步骤：结果直接随生成响应返回。视频的任务查询见[视频接口](https://apione.ai/docs/api/videos.md)。

## 参数返回为空时

接口返回 HTTP 200，但 `params` 为 `[]`、`request` 为 `{}` 或 `billingMode` 为空时，仅表示该响应没有声明相应信息，不代表模型不支持、参数可以任意填写或调用免费。`chargeModes` 中的 `usage`、`request`、`second`、`image` 是响应列出的模式名称，不等于该模型同时按四种方式收费。

1. 在 APIONE 模型详情和当前 Key 分组中核对可用协议与价格。
2. 有明确模型参数说明时，以该说明确定尺寸、质量、参考图、蒙版等字段；不要照搬其他模型的枚举。
3. 没有明确参数依据时，先验证本页的最小请求，暂不提交可选字段或批量任务。
4. 携带模型 ID、接口、请求时间和实际请求标识联系支持确认参数，不发送完整 Key。

下一步：[图像编辑](https://apione.ai/docs/api/images-edits.md)、[媒体参数与计费](https://apione.ai/docs/api/media-parameters.md)、[请求跟踪、超时与重试](https://apione.ai/docs/api/request-reliability.md)。


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