图片生成 API

使用当前 Essevin To C 密钥可用的 GPT Image 与 Gemini 图片模型生成或编辑图片。

Essevin 为当前密钥已经开放的图片模型提供统一的 OpenAI Images 兼容请求结构。请先查询完整模型 ID，不要假设完整模型目录里的每一种图片模型都可用。

项目	填写值
Base URL	`https://api.essevin.com/v1`
图片生成	`POST /v1/images/generations`
图片编辑	返回模型能力包含编辑时使用 `POST /v1/images/edits`
异步状态	收到 `202 Accepted` 后使用 `GET /v1/images/tasks?task_id=...`
鉴权	`Authorization: Bearer <对应套餐密钥>`

1. 查询已开放的图片模型

curl https://api.essevin.com/v1/models \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY"

从返回结果中选择带图片能力的完整 ID。代表型号包括 gpt-image-2、gemini-2.5-flash-image 和 gemini-3-pro-image；实际开放范围由密钥分组决定。

2. 生成一张图片

curl https://api.essevin.com/v1/images/generations \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "白色桌面上的陶瓷杯，干净的商品摄影",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url"
  }'

响应里的图片 URL 只在有限时间内有效。需要长期保留时，请及时下载到项目现有存储。

参考图与图片编辑

不同模型的图片能力不完全相同。先检查 GET /v1/models，再只使用所选路由支持的字段：

输入方式	用途
在 generation JSON 中传 `image` URL 或 Data URL	模型支持时进行图生图或参考图生成
`/v1/images/edits` multipart 请求	模型支持时复用已有 OpenAI 编辑代码
`prompt`	描述要修改的内容，以及必须保持不变的细节

用 multipart 编辑本地图片

curl https://api.essevin.com/v1/images/edits \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=把杯子移到右侧，并保持标签文字不变" \
  -F "[email protected]" \
  -F "size=1536x1024" \
  -F "quality=medium" \
  -F "output_format=png"

Gemini 图片兼容行为

Gemini 图片模型继续使用相同的 OpenAI Images 客户端协议，但模型能力不一定与 GPT Image 完全一致。

能力	行为
请求	调用 `/v1/images/generations`；Essevin 会按所选 Gemini 模型适配请求。
响应	从标准 OpenAI Images JSON 的 `data[].b64_json` 或 `data[].url` 读取结果。
编辑	支持编辑的模型可通过 `/v1/images/edits` 接收一张或多张参考图；Gemini 不支持硬区域 `mask`。
尺寸	网关会在生成前按所选模型校验 `size`。
可选字段	`quality`、`background`、`output_format`、`input_fidelity` 与 `n` 是否生效取决于模型。
流式	Gemini 图片请求保持同步，不要发送 `stream: true`。
异步	部分模型支持 `Prefer: respond-async`；请按 HTTP 状态区分 `202 task_id` 与同步结果。

所选图片模型属于 Gemini 套餐分组时，请使用 ESSEVIN_GEMINI_API_KEY。包括后缀在内的完整模型 ID 必须与 GET /v1/models 返回值完全一致。

常用请求字段

字段	是否必填	说明
`model`	是	当前密钥返回的完整 GPT Image 或 Gemini 图片模型 ID
`prompt`	是	图片内容、构图、风格、文字或编辑要求
`size`	否	`auto` 或 `宽x高`；支持范围取决于模型
`quality`	否	模型支持时可用 `low`、`medium`、`high` 或 `auto`
`n`	否	生成张数；部分模型只支持 `1`
`background`	否	模型支持时可用 `opaque` 或 `transparent`
`output_format`	否	模型支持时可用 `png`、`jpeg` 或 `webp`
`image` / `mask`	编辑时使用	可传一张或多张参考图；`mask` 取决于模型，Gemini 不支持

不支持的尺寸或字段应在生成前返回校验错误。遇到 400 时，请对照所选模型能力修改请求，不要盲目重试。

响应模式

同步响应

不传 Prefer: respond-async 时，请求会等待生成完成并返回标准 OpenAI Images JSON。部分模型返回 base64，部分模型返回临时 URL。

{
  "created": 1780000000,
  "data": [{
    "b64_json": "iVBORw0KGgoAAA...",
    "revised_prompt": "..."
  }],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1056,
    "total_tokens": 1074
  }
}

非 Gemini 图片模型只有在明确支持时才可使用 stream: true 获取 Images SSE；最后一个 data: 事件包含 Images JSON，随后是 [DONE]。官方 SDK 与 Gemini 图片请求应保持默认同步模式。

异步任务响应

对于支持异步的模型，发送 Prefer: respond-async。202 Accepted 响应会包含 task_id 与 status_url；轮询到 completed 或 failed。模型也可能直接同步返回，因此必须按实际 HTTP 状态分支处理。

# 提交请求，并检查 HTTP 状态与 task_id。
curl -i https://api.essevin.com/v1/images/generations \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "夜晚的电影感未来城市",
    "size": "2048x2048"
  }'

# 只有第一步返回 202 和 task_id 后才轮询。
curl "https://api.essevin.com/v1/images/tasks?task_id=your-task-id" \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY"

第一次验证保持最小成本

只生成一张最低可用分辨率的测试图。不要记录 API 密钥、完整 Data URL、私有原图或完整 base64 输出。

商品素材发布前，请逐张检查标签、Logo、包装文字、商品比例以及画面中的人物细节。

本页目录