智能扩图API

免费体验

AI 基于原图内容智能生成扩展区域，扩大画布并补全背景与场景细节。支持画布模式和四边模式，适用于商品图、人像照片、设计素材等扩图场景。支持异步、同步两种调用方式。

接口返回的链接有效期为 1 小时，请及时下载存储。

鉴权

每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。

X-API-KEY: YOUR_API_KEY

创建智能扩图任务

POST /api/tasks/visual/advanced-image-expand

请求参数

image_url string 可选

原图下载地址。必须与 image_file 二选一；支持 HTTP 协议和 OSS 协议，最长 512 个字符，下载超时为 10 秒。如果同时传入 image_file 与 image_url，优先使用 image_file。

二选一必填

image_file file 可选

原图文件（二进制）。必须与 image_url 二选一；仅支持 JPG、JPEG、PNG，最大 5MB，分辨率 64x64 至 4096x4096，优先级高于 image_url。

图片上传要求请参看使用规范与限制#7。

mask_url string 可选

mask 图 URL。选填，传入后即为画布模式；支持 HTTP 协议和 OSS 协议，最长 512 个字符，下载超时为 10 秒。如果同时传入 mask_file 与 mask_url，优先使用 mask_file。

二选一可选

mask_file file 可选

mask 图文件（二进制）。选填，传入后即为画布模式，优先级高于 mask_url。

mask 与 image 的尺寸需保持一致，请参看使用规范与限制#5。

return_type integer 可选

结果返回方式。1 表示返回图片下载地址（默认）；2 表示将图片作为 Base64 字符串返回。

top number 可选

向上扩展比例。默认值 0.1，取值范围 (0, 1]。

bottom number 可选

向下扩展比例。默认值 0.1，取值范围 (0, 1]。

left number 可选

向左扩展比例。默认值 0.1，取值范围 (0, 1]。

right number 可选

向右扩展比例。默认值 0.1，取值范围 (0, 1]。

strength number 可选

原图相似度。建议取值范围 [0.1, 1.0]；值越小越接近原图，值越大越接近文本控制；设为 0 时，结果与原图基本保持一致。

scale number 可选

文本描述的影响程度。默认值 7.0，取值范围 [1, 20]。

steps integer 可选

采样步数。默认值 30；数值越大，图像可能更精细，但耗时也会显著增加。

seed integer 可选

随机种子。默认值 -1；-1 表示使用随机种子。当随机种子为相同正整数且其他参数一致时，生成结果大概率一致。

prompt string 可选

提示词。用于生成图像的提示词，支持中英文输入；建议内容简洁准确，控制在 100 个中文字或英文单词以内；该字段会经过审核。

sync integer 可选

是否同步返回结果。0 表示异步先返回 task_id，再通过查询接口轮询结果；1 表示同步直接返回结果。整体轮询时长建议不超过 180 秒，轮询间隔推荐 1 秒。

返回参数

status number

HTTP 响应状态码。200 表示 HTTP 请求成功，并不代表扩图成功，详见状态码说明。

message string

接口返回消息。任务失败时可参考此字段或联系客服。

data.task_id string

异步智能扩图任务 ID。创建任务成功后返回，用于后续查询智能扩图结果。

status number

HTTP 响应状态码。200 表示 HTTP 请求成功，并不代表扩图成功，详见状态码说明。

message string

接口返回消息。任务失败时可参考此字段或联系客服。

data.task_id string

智能扩图任务 ID。

data.created_at string

任务创建时间戳。

data.processed_at string

任务开始处理时间戳。

data.completed_at string

任务完成时间戳。

data.download_time number

图片下载耗时。

data.image string

结果图 URL 或 Base64 数据，链接有效期为 1 小时。

data.image1 string

部分响应中使用的备用结果字段。

data.image_1 string

部分响应中返回的第一张结果图。

data.image_2 string

部分响应中返回的第二张结果图。

data.image_3 string

部分响应中返回的第三张结果图。

data.image_4 string

部分响应中返回的第四张结果图。

data.return_type number

结果返回方式。

data.progress number

任务处理进度，取值范围 0 到 100。

data.state number

任务状态码。1 表示完成，大于 1 表示处理中，小于 0 表示失败，详见状态码说明。

data.state_detail string

任务状态详情。

data.time_elapsed string

总耗时。

查询智能扩图结果

异步请求建议每 1 秒 轮询一次结果，本接口最大轮询时长为 180 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。

GET /api/tasks/visual/advanced-image-expand/{task_id}

路径参数

task_id string 必填

智能扩图任务 ID。创建异步任务后返回，用于查询任务处理结果。

返回参数

status number

HTTP 响应状态码。200 表示 HTTP 请求成功，并不代表扩图成功，详见状态码说明。

message string

接口返回消息。任务失败时可参考此字段或联系客服。

data.task_id string

智能扩图任务 ID。

data.created_at string

任务创建时间戳。

data.processed_at string

任务开始处理时间戳。

data.completed_at string

任务完成时间戳。

data.download_time number

图片下载耗时。

data.image string

结果图 URL 或 Base64 数据，链接有效期为 1 小时。

data.image1 string

部分响应中使用的备用结果字段。

data.image_1 string

部分异步响应中返回的第一张结果图。

data.image_2 string

部分异步响应中返回的第二张结果图。

data.image_3 string

部分异步响应中返回的第三张结果图。

data.image_4 string

部分异步响应中返回的第四张结果图。

data.return_type number

结果返回方式。

data.progress number

任务处理进度，取值范围 0 到 100。

data.state number

任务状态码。1 表示完成，大于 1 表示处理中，小于 0 表示失败，详见状态码说明。

data.state_detail string

任务状态详情。

data.time_elapsed string

总耗时。

使用规范与限制

接口返回的结果图片链接有效期为 1 小时，请及时下载并存储。
HTTP status 为 200 表示 HTTP 请求成功，并非扩图成功，任务结果请结合 data.state 判断，详见状态码说明。
使用 URL 作为参数传递时，请遵守 URL 编码规范，避免参数解析混乱。
传入 mask 参数时为画布模式；不传 mask 参数时，可通过 top、bottom、left、right 控制四边扩展比例。
mask 图片需要与 image 图片尺寸一致。
画布模式下，红框内的图片就是 image 图片，包括原图和需要扩展的区域。

画布模式示意图
上传图片需符合以下格式、分辨率和大小限制。

格式分辨率大小

jpg, jpeg, png 最小 64x64，最大 4096x4096 最大5MB

格式	分辨率	大小
jpg, jpeg, png	最小 64x64，最大 4096x4096	最大5MB

响应

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": "1634884056", // 仅在异步轮询结果中存在。
    "processed_at": "1634884056", // 仅在异步轮询结果中存在。
    "completed_at": "1634884056", // 仅在异步轮询结果中存在。
    "download_time": 1200, // 仅在异步轮询结果中存在。
    "image": "https://wxtechsz.oss-cn-shenzhen.aliyuncs.com/tasks/output/advanced-image-expand/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // 仅在异步轮询结果中存在。
    "image1": "https://wxtechsz.oss-cn-shenzhen.aliyuncs.com/tasks/output/advanced-image-expand/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // 仅在异步轮询结果中存在。
    "return_type": 1, // 仅在异步轮询结果中存在。
    "progress": 100, // 仅在异步轮询结果中存在。
    "state": 1, // 仅在异步轮询结果中存在。
    "state_detail": "success", // 仅在异步轮询结果中存在。
    "time_elapsed": "4.23s" // 仅在异步轮询结果中存在。
  }
}