Images API 图片生成

功能概览

本页用于说明 Images API 图片生成 的核心能力、调用入口和接入要点，帮助开发者快速判断适用场景并完成集成。

适用场景

• 产品原型验证：快速接入模型能力，验证内容生成、理解或编辑流程。
• 生产业务接入：用于批量任务、自动化工作流和多模型组合调用。
• 能力迁移适配：适合从原有模型或 SDK 平滑切换到爱虾AI统一接口。

接入建议

• 优先确认模型名称、请求路径和响应字段，再接入具体业务流程。
• 对异步任务、媒体生成和长耗时请求，建议在业务侧加入重试与状态轮询。
• 上线前建议准备日志追踪、错误处理和内容安全校验，便于稳定运行。

本文介绍 OpenAI Images API 风格的图片生成接口。

本文适用于以下图片模型：jiuma-5.4-image-2、jiuma-6-image-2.5-flare、jiuma-6-image-2.5-sunburst、gk-imagine-image、jiuma-image-2（支持4K）。示例使用 jiuma-5.4-image-2。

以下尺寸、画质和图片输入限制以 jiuma-5.4-image-2 为准；其它模型的参数支持范围可能不同。

接口总览

POST /v1/images/generations
POST /v1/images/edits
GET /v1/images/tasks/{task_id}

POST /v1/images/generations

用于文生图。需要上传参考图、图片编辑或图生图时，使用 /v1/images/edits。

部分明显涉及黄色、赌博、违法交易等高风险提示词，可能会直接返回 content_policy_violation。

文生图

curl "/v1/images/generations" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jiuma-5.4-image-2",
    "prompt": "一只橘猫坐在窗边晒太阳，柔和光线，写实风格",
    "size": "1024x1024",
    "n": 1,
    "quality": "high"
  }'

流式最终结果

stream: true 是本项目网关的最终结果 SSE 功能，只返回最终结果和 [DONE]，不返回中间图片。

curl -N "/v1/images/generations" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jiuma-5.4-image-2",
    "prompt": "一只橘猫坐在窗边晒太阳，柔和光线，写实风格",
    "size": "1024x1024",
    "n": 1,
    "stream": true
  }'

响应格式

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "..."
    }
  ]
}

参数支持状态

支持尺寸

常见官方规格：

auto
1024x1024
1536x1024
1024x1536
1792x1024
1024x1792

自定义尺寸必须使用 WIDTHxHEIGHT 格式，宽、高均为 16 的倍数，任一边不超过 3840，长边与短边之比不超过 3:1，总像素数在 655,360 到 8,294,400 之间。超过 3,686,400 总像素的尺寸属于实验性支持。

POST /v1/images/edits

用于图片编辑、图生图或参考图生成。OpenAI 官方风格请求建议使用 multipart/form-data 上传图片。

部分明显涉及黄色、赌博、违法交易等高风险提示词，可能会直接返回 content_policy_violation。

JSON 图片 URL 和 JSON data URL 属于本项目网关扩展能力，已单独整理到 Images API 网关扩展请求格式。如果请求经过 LiteLLM 或其它 OpenAI 兼容中转层，建议优先使用本文的 multipart 请求方式。

jiuma-5.4-image-2 单次最多输入 14 张图片。单张 multipart 上传图片最大 50MB。

multipart 上传单图

curl "/v1/images/edits" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -F "model=jiuma-5.4-image-2" \
  -F "image[]=@source.png" \
  -F "prompt=参考这张图片，生成一张相同主体但换成雪山背景的图片" \
  -F "size=1024x1024" \
  -F "n=1" \
  -F "quality=high" 

multipart 上传多图

curl "/v1/images/edits" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -F "model=jiuma-5.4-image-2" \
  -F "image[]=@subject.png" \
  -F "image[]=@style.png" \
  -F "prompt=保留第一张图的主体，参考第二张图的色彩和质感生成新图" \
  -F "size=1024x1024" 

参数支持状态

图片输入限制

支持的图片引用：

https://example.com/image.png
http://example.com/image.jpg

multipart 上传支持的后缀和 MIME：

.jpg  image/jpeg
.jpeg image/jpeg
.png  image/png
.webp image/webp

常见错误

异步图片生成

在 generations 或 edits 请求中传入 async: true，接口会立即返回任务 ID，图片由后台任务处理。异步请求不支持 stream: true。

异步模式同样适用于：jiuma-5.4-image-2、jiuma-6-image-2.5-flare、jiuma-6-image-2.5-sunburst、gk-imagine-image。

提交异步任务

curl "/v1/images/generations" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-demo-001" \
  -d '{
    "model": "jiuma-5.4-image-2",
    "prompt": "一只橘猫坐在窗边晒太阳，柔和光线，写实风格",
    "size": "1024x1024",
    "n": 1,
    "async": true
  }'

提交成功返回 HTTP 202：

{
  "task_id": "img_task_7ed82c6454482a26808c3170a36",
  "status": "queued"
}

Idempotency-Key 可选。建议客户端为每次业务请求设置唯一值，网络重试时可避免重复创建任务。

查询任务

curl "/v1/images/tasks/img_task_7ed82c6454482a26808c3170a36" \
  -H "Authorization: Bearer <API_TOKEN>"

处理中：

{
  "task_id": "img_task_7ed82c6454482a26808c3170a36",
  "status": "running"
}

成功：

{
    "task_id": "img_task_xxxxxx",
    "status": "succeeded",
    "created": 1789185796,
    "data": [
        {
            "b64_json": "iVBORw0KGgoA...AABJRU5ErkJggg==",
            "revised_prompt": null,
            "url": null
        }
    ],
    "usage": {
        "total_tokens": 1568,
        "input_tokens": 20,
        "input_tokens_details": {
            "image_tokens": 0,
            "text_tokens": 20
        },
        "output_tokens": 1548,
        "output_tokens_details": null
    }
}

失败：

{
  "task_id": "img_task_7ed82c6454482a26808c3170a36",
  "status": "failed",
  "error": {
    "code": "image_generation_failed",
    "message": "图片生成失败"
  }
}

任务状态包括：queued（排队中）、running（处理中）、succeeded（成功）、failed（失败）、cancelled（已取消）和 reconciling（上游结果确认中）。任务结果默认保留 7 天，客户端应在成功后及时保存图片地址或内容。

异步参数

异步任务查询只允许任务创建用户访问。任务不存在、已过期或不属于当前用户时返回 404。