HTTP API
图片生成
提交图片任务、轮询结果并读取图片模型目录。
提交任务
POST /api/v1/images/generations请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型目录中的图片模型 ID。 |
prompt | string | 是 | 要画的内容。 |
negativePrompt | string | 否 | 要避开的内容。 |
ratio | string | 否 | 画面比例，默认 Auto。例如 1:1、16:9、9:16、4:3、3:4。 |
quality | string | 否 | standard 或 high。 |
resolutionTier | string | 否 | 1k 或 2k；仅部分模型支持。 |
steps | number | string | 否 | 推理步数，或预设值 low、standard、high。 |
referenceImages | array | 否 | 参考图，每项为 { "base64": "..." }。 |
参考图规则：
- 只支持 Base64（接受
data:image/png;base64,前缀）；不支持 URL。 - 解码后单张最大 10MB。
- 数量上限因模型而异；请从模型列表读取
referenceImageLimit。 - 如果所选模型不支持参考图，服务器会改用支持参考图的兜底模型。响应中的
settings.model是实际运行的模型。
示例
curl -X POST https://imagifly.net/api/v1/images/generations \
-H "Authorization: Bearer $IMAGIFLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "Minimalist poster of a mountain at dawn, warm gradient sky",
"ratio": "16:9",
"quality": "high"
}'响应 202 Accepted
{
"ok": true,
"generation": {
"id": "gen_2f1c9a...",
"status": "generating",
"cost": 12,
"size": "1536x864",
"imageCount": 1
},
"settings": {
"model": "gpt-image-2",
"ratio": "16:9",
"resolutionTier": null,
"steps": null
}
}| 字段 | 说明 |
|---|---|
generation.id | 用于轮询的任务 ID。 |
generation.cost | 本任务扣除的积分。 |
generation.size | 实际选定的输出尺寸。 |
generation.imageCount | 图片数量，恒为 1。 |
settings | 实际生效的归一化参数。 |
轮询任务
GET /api/v1/images/generations/{id}{
"ok": true,
"generation": {
"id": "gen_2f1c9a...",
"status": "success",
"error": null,
"durationMs": 18420,
"imageUrls": ["https://imagedelivery.net/.../public"]
}
}| 字段 | 说明 |
|---|---|
status | generating、success 或 failed。 |
error | 失败原因；成功时为 null。 |
durationMs | 任务耗时，单位毫秒。 |
imageUrls | 成功时是图片 URL；否则为空数组。 |
任务不存在，或属于其他账号，会返回 404 GENERATION_NOT_FOUND。
模型目录
GET /api/v1/images/models{
"ok": true,
"models": [
{
"id": "gpt-image-2",
"label": "GPT Image 2",
"credits": 12,
"resolutionTiers": ["1k", "2k"],
"resolutionQuality": "high",
"defaultResolutionTier": "1k",
"supportsSteps": false,
"referenceImageLimit": 4
}
]
}以响应内容为准：模型更新时，价格、档位和限制都会随之变化。credits 是基础价格；分辨率、质量和步数等选项会改变最终费用。
说明
ratio接受Auto以及模型支持的比例；不支持的值会以400 INVALID_IMAGE_REQUEST拒绝。- 提示词内容还会由模型提供方审核。被提供方拒绝的提示词会产生一个失败任务，并在
error里说明原因，而不会在提交时返回 HTTP 错误。 - 想重试就提交新任务；没有重试接口。