图像画面扩展 — 创建任务 - 千问云
跳转到主要内容
千问云 home page
开放平台文档
图像外扩

图像画面扩展 — 创建任务

创建图像画面扩展异步任务

POST
/services/aigc/image2image/out-painting
curl --location --request POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/out-painting' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'X-DashScope-Async: enable' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "image-out-painting",
  "input": {
    "image_url": "http://xxx/image.jpg"
  },
  "parameters": {
    "angle": 45,
    "x_scale": 1.5,
    "y_scale": 1.5
  }
}'
{
  "output": {
    "task_status": "PENDING",
    "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
  },
  "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}
请先获取 API Key 并设置为环境变量。
支持旋转图像、等比例扩图、指定方向扩图、指定宽高比扩图。

扩图模式与优先级

参数存在优先级关系：当同时设置多个扩图模式的参数时，仅高优先级的参数生效。旋转参数 angle 不受优先级影响，可与任意扩图模式叠加使用。
功能参数说明
旋转angle先旋转，后扩展。可与下方任意扩图模式同时使用。
扩图优先级 1output_ratio按宽高比扩展画面。
扩图优先级 2x_scale、y_scale按比例扩展画面。
扩图优先级 3left_offset、right_offset、top_offset、bottom_offset在指定方向添加像素扩展画面。

参数设置建议

  • 仅按宽高比扩图：设置 output_ratio 为非空值（如 "4:3"）。
  • 仅按比例扩图：设置 x_scale 和 y_scale，至少一个大于 1.0。
  • 仅在指定方向添加像素扩图：设置 left_offset、right_offset、top_offset、bottom_offset，至少一个大于 0。
  • 仅旋转图像：设置 angle 为 [1, 359] 之间的值。建议避免设置为 90、180、270 度。
  • 先旋转再扩图：设置 angle 的同时，搭配上述任一扩图模式的参数。

参数组合示例

参数设置生效参数说明
output_ratio="4:3", x_scale=2.0output_ratiooutput_ratio 优先级高于 x_scale。
x_scale=2.0, left_offset=100x_scalex_scale 优先级高于 left_offset。
angle=90, x_scale=2.0angle + x_scale旋转与扩图叠加，两者均生效。
angle=90, output_ratio="4:3", x_scale=2.0, left_offset=100angle + output_ratio旋转与最高优先级扩图模式生效。

错误码

HTTP 状态码错误码错误信息说明
400InvalidParameter.JsonPhraseinput json error输入 JSON 格式错误。
400InvalidParameter.FileDownloadoss download error输入图像下载失败，请检查 URL 是否有效。
400InvalidParameter.ImageFormatread image error读取图像失败，请检查图像格式。
400InvalidParameter.ImageContentThe image content does not comply with green network verification图像内容不合规。
400InvalidParameterthe parameters must conform to the specification: xxx输入参数值超出范围。
400InvalidParameter.DataInspectionThe image size is not supported for the data inspection.输出图像尺寸超限（大于 10 MB）。
500InternalError.Algoalgorithm process error算法处理错误。
500InternalError.FileUploadoss upload error文件上传失败。

FAQ

创建任务接口只返回 task_id 和 task_status。请使用查询扩图结果接口，通过 task_id 轮询获取生成结果。
三种扩图方式（宽高比、比例缩放、方向偏移）是互斥的，存在优先级关系。output_ratio 优先级最高，设置后 x_scale/y_scale 和 *_offset 参数不生效。如需按比例扩图，请不要设置 output_ratio。

鉴权

​
string
header
必填

千问云 API Key。详见获取 API Key。

Header 参数

​
enum<string>
默认值"enable"
必填

开启异步处理，必须设为 enable。HTTP 调用仅支持异步方式，不设置此 Header 会返回错误。

可选值：enable

请求体

application/json
​
enum<string>
必填

模型名称。

可选值：image-out-painting
示例:image-out-painting
​
object
必填

输入数据。

​
object
必填

扩图参数。支持四种扩图模式：旋转、宽高比、等比例缩放、指定方向偏移。存在优先级：angle（旋转） → output_ratio（宽高比） → x_scale/y_scale（等比例） → *_offset（方向偏移）。

响应

200-application/json
​
object
​
string

请求唯一标识，用于排查问题。