{ "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 ,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 " } }, "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": "生图/编辑提示词。文生图与图生图编辑场景必填;图层拆分场景可省略,或用 x1 y1 x2 y2 坐标语法指定需分离的对象。" }, "image": { "description": "参考图。单张可传字符串,多张传数组(最多 10 张)。支持可公网访问的 URL,或 Base64 Data URI,格式为 data:image/;base64,<内容>, 必须小写。图层拆分场景仅支持 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"] } } } } } }