通用图片协议

通过 POST /v1/image 同步生成或编辑图片。不传 images 时为文生图，传入 images 时以其为参考图编辑。请求成功即返回图片地址，无需轮询任务。

接口与鉴权

操作	方法与路径
生成 / 编辑图片	POST /v1/image
可用图片模型	GET /v1/models?output_modalities=image

请求使用 Authorization: Bearer <API_KEY> 认证，请求体为 application/json，响应为直接 JSON。

BASE_URL="https://api.ope.ai"
API_KEY="YOUR_API_KEY"

curl "$BASE_URL/v1/models?output_modalities=image" \
  -H "Authorization: Bearer $API_KEY"

请求参数

字段	类型	必填	说明
model	string	是	可用模型列表中的模型 ID
prompt	string	是	图片描述，也用于编辑时的修改要求
images	object[]	否	参考图，按数组顺序生效；省略即文生图。每项为 {"url": "..."}
n	integer	否	期望输出张数上限；实际张数由模型决定，不保证补齐
size	string	否	输出尺寸，格式为 宽x高，使用小写 x，例如 1024x1024；不支持 2K、4K、auto
output_format	string	否	输出编码，例如 png、jpeg、webp；是否支持取决于所选模型
extra_parameters	object	否	模型扩展参数，见下表

images[].url 支持可公开读取的 HTTP/HTTPS 地址，或 data:image/...;base64,... 形式的 Data URL。不需要的可选参数直接省略，不要用 null 代替省略。

extra_parameters

字段	类型	说明
quality	string	输出质量档位，取值随模型而定
mask	object	编辑遮罩，格式 {"url": "..."}；需同时传 images，作用于第一张参考图
background	string	背景控制，是否支持取决于所选模型

返回方式固定为图片地址，不接受 response_format。

文生图

示例模型 ID 为 qwen-image-2.0，请按模型列表中的实际 ID 替换。

curl "$BASE_URL/v1/image" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "qwen-image-2.0",
    "prompt": "白底陶瓷茶壶的产品照，柔和侧光，细节清晰。",
    "size": "1024x1024"
  }'

参考图编辑

curl "$BASE_URL/v1/image" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "qwen-image-2.0",
    "prompt": "保留产品主体，把背景换成浅灰色摄影棚。",
    "images": [{"url": "https://example.com/input.png"}],
    "size": "1024x1024"
  }'

多图参考

curl "$BASE_URL/v1/image" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "qwen-image-2.0",
    "prompt": "把两张参考图中的家具组合到同一个客厅场景里。",
    "images": [
      {"url": "https://example.com/sofa.png"},
      {"url": "https://example.com/lamp.png"}
    ],
    "n": 2,
    "size": "1536x1024"
  }'

响应

成功返回 HTTP 200：

{
  "created": 1791000000,
  "model": "qwen-image-2.0",
  "data": [
    {
      "index": 0,
      "url": "https://media.example.com/generated/8f3c1d.png",
      "mime_type": "image/png",
      "width": 1024,
      "height": 1024
    }
  ],
  "usage": {
    "input_tokens": 24,
    "output_tokens": 1152,
    "total_tokens": 1176,
    "output_images": 1
  }
}

字段	说明
created	生成完成时间，Unix 秒
model	请求的模型 ID
data[]	输出结果，index 从 0 起连续编号
data[].url	图片地址，生成后 24 小时内有效，请及时下载保存
data[].mime_type、width、height	实际输出的类型与尺寸
data[].error	该项失败时包含 code、type、message
usage	实际用量；模型未返回用量时省略

一次请求可能部分成功：成功项带 url，失败项带 error，不会为未生成的结果补占位项。只有至少一张图片成功时才返回 200。

错误

{"error":{"code":"invalid_request","type":"invalid_request_error","message":"size must be WIDTHxHEIGHT","param":"size"}}

param 指出需要修正的字段。常见 HTTP 状态：400 参数错误，401/403 认证或权限问题，402 额度不足，404 模型不存在，413 请求过大，429 限流，500/503 服务异常或暂不可用，504 请求超时。响应 Header 中的 X-Request-ID 可用于反馈问题。

调用边界

• 同步返回，不提供异步任务、任务查询、流式输出、回调或取消。
• 每次请求执行一次生成；等待结果不需要重复发起请求。
• 图片地址按 24 小时保存，到期后请重新生成；需要长期保留的图片请自行下载。