图片生成 API

OpenAI 兼容的图片生成端点，支持 gpt-image-2 等图片模型。

请求

POST /v1/images/generations

请求头

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

也可以使用 x-api-key 头（Anthropic SDK 风格）：

x-api-key: pk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

请求体

参数	类型	必填	说明
`model`	string	✅	模型名称，如 `gpt-image-2`
`prompt`	string	✅	图片描述，最长 32000 字符
`n`	integer	❌	生成数量，默认 1，上限由模型配置决定
`size`	string	❌	图片尺寸，见下方支持列表
`quality`	string	❌	质量等级，如 `auto`、`high`、`medium`、`low`
`background`	string	❌	背景设置，如 `auto`、`transparent`、`opaque`
`output_format`	string	❌	输出格式，如 `png`、`jpeg`、`webp`
`response_format`	string	❌	返回格式，固定为 `b64_json`。传 `url` 也会返回 base64 数据（不暴露外部地址）
`aspect_ratio`	string	❌	画面比例，如 `1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`。设置后生成的图片会按指定比例输出

支持的尺寸

Picklyone 不限制尺寸——只要图片模型支持,这里就能用。

格式约束(Picklyone 侧的轻量校验):

必须是字符串,长度不超过 16 字符
必须是 auto 或 WIDTHxHEIGHT 格式(纯数字,小写 x 分隔,如 1024x1024、2048x2048)
以下会被 400 invalid_request 拒绝:文字关键字(big、large)、带空格(1024 x 1024)、非字符串(数字、对象)、超长

实测已验证可用(gpt-image-2,2026-04-25):

尺寸	类型	说明
`auto`	自动	模型自行决定输出尺寸
`1024x1024`	方形	gpt-image-1 / DALL-E 系列原生
`1024x1536`、`1536x1024`	3:2	gpt-image-1 原生(竖版 / 横版)
`1024x1792`、`1792x1024`	7:4	DALL-E 3 风格(竖幅 / 宽幅)
`1280x1280`	方形(非标)	支持,实测出图正常
`2048x2048`	方形(高分辨率)	支持,出图约 3 MB,延迟约 90 秒
`256x256`、`512x512`	小尺寸	DALL-E 2 兼容

超出模型支持能力的尺寸(如 4096x4096):请求会返回 502 upstream_error,已预扣的费用会自动退回,不会扣钱。

请求示例

{
  "model": "gpt-image-2",
  "prompt": "一只戴着魔法帽的橘猫，坐在月光下的屋顶上，水彩风格",
  "n": 1,
  "size": "1024x1024",
  "quality": "auto"
}

响应

{
  "created": 1776864985,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}

data 数组中每个对象包含：

字段	说明
`b64_json`	Base64 编码的图片数据（始终返回，不会暴露任何外部 URL）
`revised_prompt`	模型优化后的提示词（如果有）

计费方式

图片模型采用按次计费，不按 token 收费：

每张图片固定价格，见定价页
预扣费按请求的 n 冻结，结算按实际返回的图片数量收取
如果实际返回的图片数量少于请求数量，差额会自动退回

Python 示例

from openai import OpenAI
import base64

client = OpenAI(
    api_key="pk_live_xxxxxxxxxxxxxxxx",
    base_url="https://api.picklyone.com/v1",
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="一只戴着魔法帽的橘猫，坐在月光下的屋顶上，水彩风格",
    n=1,
    size="1024x1024",
)

# 保存图片
image_data = base64.b64decode(result.data[0].b64_json)
with open("cat.png", "wb") as f:
    f.write(image_data)

cURL 示例

curl https://api.picklyone.com/v1/images/generations \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a cute cat wearing a wizard hat on a rooftop under moonlight, watercolor style",
    "n": 1,
    "size": "1024x1024"
  }'

Node.js 示例

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: "pk_live_xxxxxxxxxxxxxxxx",
  baseURL: "https://api.picklyone.com/v1",
});

const result = await client.images.generate({
  model: "gpt-image-2",
  prompt: "a cute cat wearing a wizard hat",
  n: 1,
  size: "1024x1024",
});

// 保存图片
const imageData = Buffer.from(result.data[0].b64_json, "base64");
fs.writeFileSync("cat.png", imageData);

错误码

HTTP 状态码	code	说明
400	`invalid_request`	参数校验失败（无效的 n、size、prompt 等）
400	`content_policy_violation`	提示词触发内容审查（已自动退还预扣费）
400	`no_image_generated`	返回 0 张图但非审查原因——prompt 过于抽象或模型拒绝（已退预扣）
401	`invalid_api_key`	API Key 无效或缺失
402	`insufficient_balance`	余额不足
403	`MODEL_ACCESS_DENIED`	无权访问该模型
404	`model_not_found`	模型不存在或未上架
429	`rate_limit_exceeded`	请求频率超限
502	`upstream_error`	服务异常

注意事项

图片生成通常需要 30-90 秒，请设置足够长的超时时间
返回的 Base64 图片数据较大（单张 1-5 MB），注意客户端内存
当前 gpt-image-2 单次请求最多生成 1 张图片
非图片模型（如 GPT-4o、Claude）请使用 /v1/chat/completions 或 /v1/messages 端点