{
  "openapi": "3.0.3",
  "info": {
    "title": "Volcano Engine Ark — Seedream Image Generation API",
    "version": "1.0.0",
    "description": "火山方舟（Volcano Engine Ark）Seedream 图片生成接口，本规格以 Doubao Seedream 5.0 Pro（模型 ID：doubao-seedream-5-0-pro-260628）为准。\n\n支持能力：文生图（T2I）、单图/多图生图与交互编辑（I2I，最多 10 张参考图）、图层拆分（1 张底图 + 最多 16 张图层）、透明背景输出。\n\n5.0 Pro 不支持：流式输出、文生组图（sequential_image_generation）、联网搜索。\n\n注意：返回的图片 URL 仅保留 24 小时，需及时下载保存。\n\n鉴权：在请求头携带 Authorization: Bearer <ARK_API_KEY>，API Key 获取：https://console.volcengine.com/ark/region:ark+cn-beijing/apikey",
    "contact": {
      "name": "火山方舟文档",
      "url": "https://docs.volcengine.com/docs/82379/2582774"
    }
  },
  "servers": [
    {
      "url": "https://ark.cn-beijing.volces.com/api/v3",
      "description": "华北2（北京）— 模型调用默认地址"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/images/generations": {
      "post": {
        "operationId": "createImageGeneration",
        "summary": "创建图片生成任务（文生图 / 图生图 / 交互编辑 / 图层拆分）",
        "description": "同步接口：提交后直接返回生成结果。5.0 Pro 单次返回 1 张成品图；图层拆分模式下 data 数组同时返回底图（z_index=0）与全部图层。",
        "tags": ["Images"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateImageGenerationRequest"
              },
              "examples": {
                "textToImage": {
                  "summary": "文生图",
                  "value": {
                    "model": "doubao-seedream-5-0-pro-260628",
                    "prompt": "生成一张赛博朋克风格的城市夜景，霓虹灯光，雨后湿润街道反光，宽高比16:9。",
                    "size": "2K",
                    "output_format": "png",
                    "response_format": "url",
                    "watermark": false
                  }
                },
                "imageEdit": {
                  "summary": "图生图 / 交互编辑",
                  "value": {
                    "model": "doubao-seedream-5-0-pro-260628",
                    "prompt": "将图片中的鹦鹉改为孔雀，保持构图、光影与背景不变。",
                    "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream_50_pro_input2.png",
                    "size": "2K",
                    "output_format": "png",
                    "response_format": "url",
                    "watermark": false
                  }
                },
                "layerDecomposition": {
                  "summary": "图层拆分",
                  "value": {
                    "model": "doubao-seedream-5-0-pro-260628",
                    "image": "https://arkdocs.tos-cn-beijing.volces.com/images/image-generation/layer_auto.png",
                    "size": "2K",
                    "layer_decomposition": true,
                    "watermark": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "生成成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageGenerationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "火山方舟 API Key，请求头格式：Authorization: Bearer <ARK_API_KEY>"
      }
    },
    "responses": {
      "Error": {
        "description": "错误响应",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "CreateImageGenerationRequest": {
        "type": "object",
        "required": ["model"],
        "properties": {
          "model": {
            "type": "string",
            "description": "模型 ID。Seedream 5.0 Pro 固定为 doubao-seedream-5-0-pro-260628；也可传入在方舟控制台创建的推理接入点 ID（ep-xxxx）。",
            "example": "doubao-seedream-5-0-pro-260628"
          },
          "prompt": {
            "type": "string",
            "description": "生图/编辑提示词。文生图与图生图编辑场景必填；图层拆分场景可省略，或用 <bbox>x1 y1 x2 y2</bbox> 坐标语法指定需分离的对象。"
          },
          "image": {
            "description": "参考图。单张可传字符串，多张传数组（最多 10 张）。支持可公网访问的 URL，或 Base64 Data URI，格式为 data:image/<fmt>;base64,<内容>，<fmt> 必须小写。图层拆分场景仅支持 1 张图。支持格式 jpeg/png/webp/bmp/tiff/gif/heic/heif，单张不超过 30MB。",
            "oneOf": [
              {
                "type": "string",
                "description": "单张参考图：URL 或 Base64 Data URI"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 1,
                "maxItems": 10,
                "description": "多张参考图：URL 或 Base64 Data URI 列表"
              }
            ]
          },
          "size": {
            "type": "string",
            "description": "输出尺寸，两种方式不可混用。图片生成场景：分辨率档位 1K / 1.5K / 2K（默认 2K），或显式宽高像素 WxH（总像素约 92 万~462 万，宽高比 1/16~16，如 2048x1024）；图层拆分场景：1K / 1.5K / 2K / auto（默认 auto）。使用档位时在 prompt 中描述宽高比，由模型决定具体像素。",
            "default": "2K",
            "example": "2K"
          },
          "response_format": {
            "type": "string",
            "description": "图像返回方式：url 返回下载链接（默认，链接 24 小时有效）；b64_json 返回 Base64 编码字符串。",
            "enum": ["url", "b64_json"],
            "default": "url"
          },
          "output_format": {
            "type": "string",
            "description": "图像文件格式：png 或 jpeg（5.0 Pro 支持两者）。透明背景模式固定输出 png；图层拆分场景该字段仅控制底图，图层始终为 png。",
            "enum": ["png", "jpeg"],
            "default": "png"
          },
          "background": {
            "type": "string",
            "description": "背景模式：opaque 不透明（默认）；transparent 透明背景（仅限图生图、仅 1 张带透明通道参考图，输出固定 png，与 jpeg 互斥）。",
            "enum": ["opaque", "transparent"],
            "default": "opaque"
          },
          "watermark": {
            "type": "boolean",
            "description": "是否在右下角添加“AI生成”水印。",
            "default": false
          },
          "layer_decomposition": {
            "type": "boolean",
            "description": "是否启用图层拆分（5.0 Pro 专属）。启用后 data 数组返回底图与各图层，图层带 z_index、bounding_box、name、description。",
            "default": false
          }
        }
      },
      "ImageGenerationResponse": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string",
            "description": "实际使用的模型 ID"
          },
          "created": {
            "type": "integer",
            "description": "创建时间，Unix 秒级时间戳",
            "example": 1784696685
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ImageObject"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/ImageUsage"
          }
        },
        "required": ["data"]
      },
      "ImageObject": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "结果图下载链接，24 小时有效（response_format=url 时返回）"
          },
          "b64_json": {
            "type": "string",
            "description": "结果图 Base64 编码（response_format=b64_json 时返回）"
          },
          "size": {
            "type": "string",
            "description": "实际输出像素尺寸 WxH",
            "example": "2048x2048"
          },
          "output_format": {
            "type": "string",
            "example": "png"
          },
          "z_index": {
            "type": "integer",
            "description": "图层叠放顺序：底图固定为 0，图层按 1、2、3… 递增（仅图层拆分模式）"
          },
          "name": {
            "type": "string",
            "description": "图层名称（仅图层拆分模式）"
          },
          "description": {
            "type": "string",
            "description": "图层内容描述（仅图层拆分模式）"
          },
          "bounding_box": {
            "$ref": "#/components/schemas/BoundingBox"
          }
        }
      },
      "BoundingBox": {
        "type": "object",
        "description": "图层边界框（仅图层拆分模式）",
        "properties": {
          "absolute": {
            "$ref": "#/components/schemas/BoxCoords",
            "description": "输出底图坐标系中的绝对像素位置"
          },
          "normalized": {
            "$ref": "#/components/schemas/BoxCoords",
            "description": "输出底图坐标系中的归一化位置（0~1）"
          }
        }
      },
      "BoxCoords": {
        "type": "object",
        "properties": {
          "x": { "type": "number" },
          "y": { "type": "number" },
          "width": { "type": "number" },
          "height": { "type": "number" }
        }
      },
      "ImageUsage": {
        "type": "object",
        "description": "计费用量信息（部分账号返回）",
        "properties": {
          "generated_images": {
            "type": "integer",
            "description": "实际生成图片数量"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "错误码，如 AuthenticationError、RateLimitExceeded、InvalidParameter"
              },
              "message": {
                "type": "string",
                "description": "错误详情"
              },
              "param": {
                "type": "string",
                "nullable": true,
                "description": "触发错误的参数"
              },
              "type": {
                "type": "string",
                "description": "错误类型"
              }
            },
            "required": ["message", "type"]
          }
        }
      }
    }
  }
}