图像生成

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

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

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

运行示例前准备

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

python -m pip install requests

如果你的系统使用 python3，安装和运行时都使用 python3。Windows 也可以对应使用 py -m pip install requests 与 py example.py。使用虚拟环境时，先激活环境。在 API 密钥页创建密钥，从当前 Key 可用的模型列表复制支持图像生成的模型 ID，然后在运行脚本的终端设置变量。下面的大写值是占位符，需要替换。

macOS / Linux
Windows PowerShell

export APIONE_API_KEY="YOUR_APIONE_API_KEY"
export APIONE_IMAGE_MODEL="YOUR_IMAGE_MODEL"

$env:APIONE_API_KEY = "YOUR_APIONE_API_KEY"
$env:APIONE_IMAGE_MODEL = "YOUR_IMAGE_MODEL"

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

查询模型和参数

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

curl https://api.apione.ai/v1/models/YOUR_IMAGE_MODEL/params \
  -H "Authorization: Bearer YOUR_APIONE_API_KEY"

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

最小请求

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

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

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

Python 示例

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 无需额外依赖。

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。代码只提交一次创建请求，不自动重试，解码后将结果保存在当前目录。

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"))

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

{
  "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 数自行认定费用。该例没有异步任务查询步骤：结果直接随生成响应返回。视频的任务查询见视频接口。

参数返回为空时

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

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

下一步：图像编辑、媒体参数与计费、请求跟踪、超时与重试。

地址与鉴权

模型接口

输出与进阶用法

图像 API

视频 API

运行示例前准备

查询模型和参数

最小请求

常见问题

请求字段怎么确认

Python 示例

Node.js 示例

处理生成结果

上线前测试用例

计费与重试

完整实战：生成并保存 PNG

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

参数返回为空时