Skip to Content
API 参考OpenAI 兼容协议Images

Images API

两个端点：生成（文字 → 图）、编辑（图 + 文字 → 图）。响应都是 OpenAI 标准结构 data[0].b64_json。

Gemini 系列图像模型（如 google/gemini-3.1-flash-image-preview）在本端点只能生成不能编辑。需要编辑请走 Gemini 原生协议。

生成图像

POST https://api.hao.ai/v1/images/generations

用 gpt-image-2

gen.py
import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_HAOAI_API_KEY", base_url="https://api.hao.ai/v1")
 
resp = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A simple red apple on a white table",
    size="1024x1024",
    quality="low",
    output_format="png",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

实测输出：

gpt-image-2 生成的红苹果

用 gemini-3.1-flash-image-preview

同一端点也接受 Gemini 图像模型。不要传 n——网关会把 n 错误映射为 numberOfImages 字段并报 400，每次固定生成 1 张。

gen_gemini.py
import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_HAOAI_API_KEY", base_url="https://api.hao.ai/v1")
 
resp = client.images.generate(
    model="google/gemini-3.1-flash-image-preview",
    prompt="A simple red apple on a white table, photorealistic",
    size="1024x1024",
    quality="low",
    output_format="png",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

实测输出：

Gemini 生成的红苹果

参数

参数类型必填说明
modelstring✅openai/gpt-image-2、google/gemini-3.1-flash-image-preview
promptstring✅自然语言描述
qualitystring✅auto / low / medium / high。gpt-image 系列质量不影响价格（见下方计费）
nnumber—1–10，默认 1。Gemini 模型不支持
sizestring—auto（默认 1536x1024）或任意 宽x高，约束见下方「支持的尺寸」
output_formatstring—png / jpeg / webp
backgroundstring—opaque / auto。gpt-image-2 不支持 transparent，传了会报错
streamboolean—默认 false

支持的尺寸（gpt-image-2）

尺寸不是固定档位，任意同时满足以下约束的 宽x高 都可以：

  • 宽、高都是 16 的倍数；
  • 单边 ≤ 3840；
  • 宽高比在 1:3 ~ 3:1 之间；
  • 总像素 655,360 ~ 8,294,400（约 0.64MP ~ 8.3MP）。

常用尺寸：1024x1024、1536x1024、1024x1536、2048x2048、2560x1440；4K 档：3840x2160、2160x3840、2880x2880。

1920x1080 会被拒（1080 不是 16 的倍数），请改用 1920x1088。256x256、512x512 等旧 DALL·E 尺寸低于像素下限，同样不可用。

4K 属实验档：单图可能耗时数分钟（客户端超时建议 ≥600 秒），且上游偶发生成失败——失败不计费。

计费（官方 token 口径 × 1.5 折）

与 OpenAI 官方 API 同构计费：计量单位、token 数量与官方完全一致，单价为官方的 0.15 倍，每一项都可用官方工具复算。

计费项官方单价本平台
图片输出$30/M tokens$4.50/M tokens
文本输入（提示词）$5/M tokens$0.75/M tokens
参考图输入（编辑场景）$8/M tokens$1.20/M tokens（见下）
缓存输入$1.25–$2/M tokens本通道无缓存命中，恒为 0
文本输出—（gpt-image-2 无此项）—
  • 图片输出 token 数由官方计量公式确定（输出尺寸 × 质量档，官方文档 Calculating costs 的计算器可逐张复核）。高质档参考值：1024×1024 = 7,024 tokens ≈ $0.0316/张；1536×1024 = 5,488 ≈ $0.0247；3840×2160 = 13,342 ≈ $0.0600；2880×2880 = 23,719 ≈ $0.1067；
  • 质量统一按高质档计量（低/中/高同价）：上游对任何质量参数实际均按高细节渲染，按高质计量即按实际交付计费；
  • 提示词按官方同款分词器（o200k）计数，与你本地用 tiktoken 数出的结果逐 token 一致；
  • 参考图输入仅在 /v1/images/edits 上传参考图时产生（纯文生图无此项）。官方未公开可复算的参考图 token 计数公式，因此当前路径不对参考图输入单独计量收费；表中 $1.20/M 为对齐官方的折后费率（官方 $8/M × 0.15），仅当上游按官方口径上报该 token 时适用；
  • n 大于 1 时按张数计；生成失败不计费。

实时价格以模型目录 为准。

响应

{
  "created": 1777385517,
  "data": [
    { "b64_json": "<图片 Base64>", "index": 0 }
  ],
  "model": "openai/gpt-image-2",
  "size": "1024x1024",
  "quality": "low",
  "usage": {
    "input_tokens": 8,
    "input_tokens_details": { "text_tokens": 8 },
    "output_tokens": 7024,
    "total_tokens": 7032
  }
}

usage 按官方口径返回：输入 = 提示词的 o200k token 数，输出 = 官方公式按实际输出尺寸（高质档）算出的 token 数——与计费数字完全一致。上例 quality 虽为 low，输出仍按高质档计 7,024（见计费说明）。

图片在 data[0].b64_json，自行 base64 解码后保存。

编辑图像

POST https://api.hao.ai/v1/images/edits

multipart/form-data，需上传图片文件。

此端点仅支持 OpenAI / Azure OpenAI 模型。google/gemini-3.1-flash-image-preview 调用会返回 Image editing is not supported for model——改走 Gemini 原生协议编辑图像。

调用

edit.py
import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_HAOAI_API_KEY", base_url="https://api.hao.ai/v1")
 
with open("apple.png", "rb") as f:
    resp = client.images.edit(
        model="openai/gpt-image-2",
        image=f,
        prompt="把苹果改成绿色，其他保持不变",
        size="auto",
        quality="low",
    )
 
with open("apple_edited.png", "wb") as out:
    out.write(base64.b64decode(resp.data[0].b64_json))

image 字段传本地文件路径（cURL 用 @ 前缀），不是 URL。

实测对比：

原图编辑后
原始红苹果编辑后的绿苹果

参数

参数类型必填说明
modelstring✅推荐 openai/gpt-image-2
imagefile✅PNG / JPEG 文件
promptstring✅编辑指令
qualitystring✅low / medium / high
nnumber—默认 1
sizestring—auto 表示与原图一致

响应

{
  "created": 1777385669,
  "data": [
    { "b64_json": "<编辑后图片 Base64>", "index": 0 }
  ],
  "model": "openai/gpt-image-2",
  "size": "auto",
  "quality": "low",
  "usage": {
    "input_tokens": 10,
    "input_tokens_details": { "text_tokens": 10 },
    "num_input_images": 1,
    "output_tokens": 5488,
    "total_tokens": 5498
  }
}

与生成一致，usage 按官方口径返回。num_input_images 是输入图片张数。注意：参考图输入的 token 不计入（官方未公开可复算的输入图计数公式，详见上方计费说明），因此 input_tokens_details 只含 text_tokens。

支持的模型与价格见 模型目录 。

Models CountMessages