参考图生成图像 API 参考

    通过 Gate.AI 图生图接口上传参考图生成或编辑图片。该接口使用 multipart/form-data，同步返回图片 URL 与计费信息，usage.input_tokens 会包含参考图读取计入的 image_tokens。

    字段值
    Base URLhttps://api.gate.ai/openai/v1
    认证Authorization: Bearer <API_KEY>
    格式OpenAI 兼容；使用 multipart/form-data 请求体

    图像接口路径位于 /openai/v1 下；生成结果 data\[\].url 为短时 S3 预签名地址，请尽快下载或转存，落盘对象 TTL 30 天。

    基于参考图生成图像

    POST/images/edits

    通过 multipart/form-data 上传参考图并同步生成或编辑图片，usage.input_tokens 会包含参考图读取计入的 image_tokens。

    请求参数

    名称位置类型必选说明
    Authorizationheaderstring是Gate.AI API Key。格式：Bearer <API_KEY>
    Content-Typeheaderstring是请求体格式：multipart/form-data

    请求体

    名称类型必选说明
    modelstring是图像模型 ID，如 gpt-image-1、qwen-image-2.0-pro、seedream-4.0；缺失返回 400 model is required
    imagefile是参考图文件。gpt-image-1 要求 PNG、小于 4 MB、方形；无 mask 时须带透明通道作蒙版
    maskfile否PNG 蒙版，透明区为编辑区域，尺寸需与 image 一致
    promptstring是编辑描述，最长 1000 字符
    ninteger否生成张数，1–10，默认 1；多图按张计费
    sizestring否输出尺寸。gpt-image-1 支持 256x256、512x512 或 1024x1024，并参与费用预估
    response_formatstring否url 或 b64_json。gpt-image-1 不支持该参数，传入可能被上游拒绝

    示例

    text
    1model=gpt-image-12prompt=Add a yellow border and a small sun in the corner3size=1024x10244image=@./input.png

    返回字段说明

    名称类型说明
    createdinteger生成时间戳（秒）
    dataarray结果数组，长度等于 n
    data\[\].urlstring图片 S3 预签名 URL，短时有效，落盘 30 天
    usageobject用量。OpenAI 系为 token 明细；Qwen 系为 width、height、image_count
    model_extend.coststring实际计费金额（USD），扣款以此为准
    model_extend.line_itemsarray计费分项。token 计费含 input/output/cache；按张计费含 billing_unit、rate_usd_per_image、resolution_tier
    model_extend.providerstring实际上游 provider，如 openai、qwen
    size / quality / output_format / backgroundstring部分模型回显的入参
    modelstring仅 Qwen 系在顶层回显

    返回示例

    json
    1{2  "created": 1781604390,3  "data": [4    {5      "url": "https://ai-gateway-file.s3.ap-northeast-1.amazonaws.com/multimodal/image/2026/06/16/example-edit-0.png?X-Amz-Expires=600&X-Amz-Signature=..."6    }7  ],8  "size": "1024x1024",9  "quality": "low",10  "output_format": "png",11  "usage": {12    "input_tokens": 220,13    "input_tokens_details": {14      "image_tokens": 194,15      "text_tokens": 2616    },17    "output_tokens": 272,18    "total_tokens": 49219  },20  "model_extend": {21    "cost": "0.009804",22    "provider": "openai",23    "total_tokens": "492"24  }25}

    返回结果

    状态码状态码含义说明数据模型
    200OK成功，同步返回图片结果与计费信息。ImageResponse
    400Bad Request请求体错误、JSON 无效，或 model / prompt 缺失。OpenAIErrorResponse
    401UnauthorizedAPI Key 无效或缺失。OpenAIErrorResponse
    402Payment Required余额不足，响应中包含当前余额与预估费用。InsufficientBalanceResponse
    404Not Found模型不存在，或图像端点未启用。OpenAIErrorResponse
    413Payload Too Large请求体过大，默认上限 8 MiB。OpenAIErrorResponse
    429Too Many Requests请求过于频繁，请降低调用频率。OpenAIErrorResponse
    500Internal Server Error服务内部错误。OpenAIErrorResponse
    502Bad Gateway上游图像服务失败。OpenAIErrorResponse