生图与图像编辑接口
使用 OpenAI 兼容协议生成图片、编辑参考图，并以 URL 或 Base64 返回结果。
本页介绍文本生图和参考图编辑接口。生图接口使用 OpenAI 兼容的 JSON 请求和响应格式；图像编辑支持 multipart/form-data 和 application/json。生成或编辑结果可以返回临时 URL 或 Base64 字符串，具体能力取决于目标模型。
接口地址
POST /v1/images/generations火山方舟 OpenAI 兼容入口也支持：
POST /api/v3/images/generations请求头
Authorization: Bearer <APIQIK_API_KEY>
Content-Type: application/json请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 是 | 图片描述，不能为空。 |
model | string | 否 | 建议显式指定目录中的图像模型；未提供时网关回退到内置默认值，该默认模型可能不在当前目录中。 |
n | integer | 否 | 生成数量。未提供时按 1 处理；具体范围由目标模型和供应商限制。 |
size | string | 否 | 输出尺寸。可用尺寸由目标模型决定，例如 1024x1024、1792x1024 或 1024x1792。 |
quality | string | 否 | 质量参数，取值由目标模型决定，例如 standard、hd 或 low、medium、high。 |
style | string | 否 | 风格参数，取值由目标模型决定，例如 vivid 或 natural。 |
output_format | string | 否 | png、jpeg 或 webp，需目标模型支持。 |
response_format | string | 否 | url 或 b64_json，默认 url；部分模型不支持该参数。 |
image | string 或 string[] | 否 | 图生图参考图，支持单个值或数组。具体模型可能支持 HTTP(S) URL、Base64 或 data URL；最多 16 张，是否支持图生图取决于目标模型。 |
negative_prompt | string | 否 | 反向提示词，需目标模型支持。 |
prompt_extend | boolean | 否 | 提示词扩展开关，需目标模型支持。 |
watermark | boolean | 否 | 生成结果加水印开关，需目标模型支持。 |
stream | boolean | 否 | 请求渐进式图像事件，需目标模型支持。带 Idempotency-Key 时不能使用流式模式。 |
layer_decomposition | boolean | 否 | 图层拆分意图，是否生效取决于目标供应商。 |
user | string | 否 | 终端用户标识。 |
网关会校验 output_format、response_format 和参考图的基本形态。data URL 参考图只接受 JPEG、PNG 或 WebP，单张解码后不超过 10 MiB；具体模型的出站限制可能更严格。
模型选择
模型目录中 capabilities 含 image 的条目即可用于本接口。文生图、图生图、图片编辑、图层拆分等具体能力由目标模型决定，应以控制台的模型详情为准，本文档不列举固定清单。
调用 GET /v1/public/models?availableOnly=true 可查看当前可用的图像模型。
请求示例
curl "${BASE_URL}/v1/images/generations" \
-H "Authorization: Bearer ${APIQIK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "<image-model-id>",
"prompt": "一座雨夜中的未来城市，电影感构图",
"size": "1024x1024",
"quality": "standard",
"response_format": "url"
}'响应示例
{
"created": 1789987200,
"data": [
{
"url": "https://example.com/generated-image.png",
"revised_prompt": "一座雨夜中的未来城市，电影感构图"
}
]
}data[] 可能包含以下字段：
| 字段 | 说明 |
|---|---|
url | 生成图片的临时访问地址。客户端应尽快下载或持久化。 |
b64_json | Base64 编码的图片内容；请求 response_format: "b64_json" 时使用。 |
revised_prompt | 模型修改或扩展后的提示词。 |
部分图像模型还会返回 usage，其中包含 input_tokens、output_tokens 和 total_tokens。
错误处理
400：缺少必填参数、参数类型或取值无效、模型不支持请求参数。401：API Key 缺失或无效。403：API Key 没有图像接口权限。413：请求体或上传文件超过入口限制。429：上传并发或请求频率受限。500、502或503：网关或上游图像服务异常。
客户端应根据 HTTP 状态码和结构化错误字段处理失败，并保留响应中的 X-Request-Id。
图像编辑
POST /v1/images/edits
图像编辑支持参考图编辑、遮罩编辑和多图输入。当前没有 /api/v3/images/edits 别名。请求使用 Authorization: Bearer <APIQIK_API_KEY> 鉴权；Content-Type 支持 multipart/form-data 和 application/json。
multipart/form-data
multipart 请求使用以下字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
image[] 或 image | file | 是 | 输入图片。image[] 支持最多 16 张；使用 image 时是否支持多图由目标模型决定。 |
prompt | string | 是 | 编辑描述，不能为空。 |
mask | file | 否 | 遮罩图片，具体遮罩语义由目标模型决定。 |
model | string | 否 | 建议显式指定目录中的图像模型；未提供时网关回退到内置默认值，该默认模型可能不在当前目录中。 |
n | integer | 否 | 生成数量，传入时必须大于等于 1。 |
size | string | 否 | 输出尺寸，由目标模型决定。 |
quality | string | 否 | 输出质量，由目标模型决定。 |
output_format | string | 否 | png、jpeg 或 webp，需目标模型支持。 |
background | string | 否 | 背景参数，例如 transparent、opaque 或 auto，需目标模型支持。 |
moderation | string | 否 | 内容审核级别，例如 low 或 auto，需目标模型支持。 |
response_format | string | 否 | url 或 b64_json；部分模型不支持该参数。 |
user | string | 否 | 终端用户标识。 |
单张输入图片和遮罩文件的上限由目标模型决定：部分模型为 4 MiB，部分为 50 MiB。单次最多接收 16 张输入图片，其他限制由对应适配器继续校验。
application/json
JSON 编辑请求支持以下字段：
{
"model": "<image-model-id>",
"image": ["data:image/png;base64,<BASE64_DATA>"],
"mask": "data:image/png;base64,<BASE64_MASK>",
"prompt": "移除背景并保留主体",
"size": "1024x1024",
"quality": "medium",
"output_format": "png",
"background": "transparent",
"response_format": "b64_json"
}image 可以是单个 Base64/data URL 字符串或字符串数组；mask 为单个 Base64/data URL 字符串。JSON 请求不支持让网关代下载 HTTP(S) 图片 URL。JSON 入口允许不传 image 或 prompt，但是否能作为无参考图生成请求执行取决于目标适配器；multipart 入口要求两者都提供。
图像编辑响应使用与图像生成相同的基本结构：created、data[]，以及部分模型可能返回的 usage。两个入口均要求 API Key 具备 images 或兼容的 chat scope。