AI 助理
备案控制台
文档
输入文档关键字查找
首页 大模型服务平台百炼 开发参考 模型调用 图像编辑与生成 图像画面扩展API参考

图像画面扩展API参考

更新时间：
产品详情
我的收藏

本文介绍图像画面扩展模型的输入输出参数。图像画面扩展（也称“扩图”），支持对输入图像按宽高比、按比例扩图、在上下左右四个方向自定义增加像素扩图。这两种方式还可以结合旋转角度进行扩图。

相关指南：图像画面扩展

模型概览

模型名

模型简介

免费额度

计费单价

限流（含主账号与RAM子账号）

任务下发接口QPS限制

同时处理中任务数量

image-out-painting

图像画面扩展模型可以对输入图像进行画面延展，可以通过指定输出宽高比、横向及纵向扩展比例、向上下左右各方向扩展像素数三种方式进行扩图，均支持先旋转再扩图，可用于创意娱乐、辅助作图、画面设计等场景。

免费额度：500张

领取方式：开通阿里云百炼大模型服务后，自动发放

有效期：180天

限时免费

2

1

前提条件

您需要已获取API Key并配置API Key到环境变量。如果通过SDK调用，还需要安装DashScope SDK。

HTTP调用

为了减少等待时间并且避免请求超时，服务采用异步方式提供。您需要发起两个请求：

  • 创建任务：首先发送一个请求创建扩图任务，该请求会返回任务ID。

  • 根据任务ID查询结果：使用上一步获得的任务ID，查询模型生成的结果。

创建任务

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/out-painting

请求头（Headers）

旋转图像

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
    }
}'

等比例扩图

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":{
        "x_scale":2,
        "y_scale":2,
        "best_quality":false,
        "limit_image_size":true
    }
}'

指定方向扩图

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": {
        "left_offset": 200,
        "right_offset": 100,
        "best_quality": false,
        "limit_image_size": true
    }
}'

指定宽高比扩图

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-raw '{
    "model": "image-out-painting",
    "input": {
        "image_url": "https://huarong123.oss-cn-hangzhou.aliyuncs.com/image/%E5%9B%BE%E5%83%8F%E7%94%BB%E9%9D%A2%E6%89%A9%E5%B1%95.png"
    },
    "parameters":{
        "angle":0,
        "output_ratio":"4:3",
        "best_quality":false,
        "limit_image_size":true
    }
}'

Authorization string 必选

推荐您使用百炼API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。

X-DashScope-Async string 必选

是否开启异步处理。必须开启异步处理，设置为enable。

Content-Type string 必选

请求内容类型。固定为application/json。

请求体（Request Body）

model string 必选

调用模型。图像画面扩展模型为image-out-painting。

input object 必选

输入图像的基本信息，比如图像URL地址。

属性

imaget_url string 必选

图像URL地址或者图像base64数据。

图像限制：

  • 图像格式：JPG、JPEG、PNG、HEIF、WEBP。

  • 图像大小：不超过10MB。

  • 图像分辨率：不低于512×512像素且不超过4096×4096像素。

  • 图像单边长度范围：[512, 4096]，单位像素。

parameters object 必选

图像处理参数。

属性

angle integer 可选

逆时针旋转角度。默认值为0，取值范围[0, 359]。需要与x_scale、y_scale参数或者top_offset、bottom_offset、left_offset 、right_offset参数搭配使用。

output_ratio string 可选

图像宽高比。可选值有["","1:1", "3:4", "4:3", "9:16", "16:9"]。默认为""，表示不设置输出图像的宽高比。

相较于比例参数或者添加像素数参数，output_ratio参数的优先级最高。如果output_ratio取值不为空字符串，则使用该参数输出图像。

扩展参数优先级

  1. 若output_ratio不为空，使用高宽比参数输出图像。

  2. 若扩展比例（x_scale，y_scale）不全为1，使用扩展比例。

  3. 其他情况使用扩展像素值（parameters.left_offset，parameters.right_offset，parameters.top_offset，parameters.bottom_offset）

x_scale float 可选

图像居中，在水平方向上按比例扩展图像。

默认值为1.0，取值范围[1.0, 3.0]。

示例

例如：输入图像分辨率为1000×1000（宽×高），x_scale=2.0，扩展后的图像分辨率为2000×1000（宽×高）。保持高度不变，左右各添加500个像素。

您可以选择与y_scale参数搭配使用，但不能与top_offset、bottom_offset、left_offset 、right_offset这些参数同时使用。若同时配置，则x_scale、y_scale参数优先生效。

y_scale float 可选

图像居中，在垂直方向上按比例扩展图像。

默认值为1.0，取值范围[1.0, 3.0]。

示例

例如：输入图像分辨率为1000×1000（宽×高），y_scale=2.0，扩展后的图像分辨率为1000×2000（宽×高）。保持宽度不变，上下各添加500个像素。

您可以选择与x_scale参数搭配使用，但不能与top_offset、bottom_offset、left_offset、right_offset这些参数同时使用。若同时配置，则x_scale、y_scale参数优先生效。

top_offset integer 可选

在图像上方添加像素。

默认值为0，取值限制top_offset+bottom_offset < 3×输入图像高度。

示例

例如：输入图像分辨率为1000×1000（宽×高），top_offset=500，扩展后的图像分辨率为1000×1500（宽×高）。保持宽度不变，只在图像上方添加500个像素。

您可以选择与bottom_offset、left_offset 、right_offset参数搭配使用，但不能与x_scale、y_scale这些参数同时使用。若同时配置，则x_scale、y_scale参数优先生效。

bottom_offset integer 可选

在图像下方添加像素。

默认值为0，取值限制top_offset+bottom_offset < 3×输入图像高度。

示例

例如：输入图像分辨率为1000×1000（宽×高），bottom_offset=500，扩展后的图像分辨率为1000×1500（宽×高）。保持宽度不变，只在图像下方添加500个像素。

您可以选择与top_offset、left_offset 、right_offset参数搭配使用，但不能与x_scale、y_scale这些参数同时使用。若同时配置，则x_scale、y_scale参数优先生效。

left_offset integer 可选

在图像左侧添加像素。

默认值为0，扩展限制left_offset+right_offset < 3×输入图像宽度。

示例

例如：输入图像分辨率为1000×1000（宽×高），left_offset=500，扩展后的图像分辨率为1500×1000（宽×高）。保持高度不变，只在图像左侧添加500个像素。

您可以选择与top_offset、bottom_offset、right_offset参数搭配使用，但不能与x_scale、y_scale这些参数同时使用。若同时配置，则x_scale、y_scale参数优先生效。

right_offset integer 可选

在图像右侧添加像素。

默认值为0，扩展限制left_offset+right_offset < 3×输入图像宽度。

示例

例如：输入图像分辨率为1000×1000（宽×高），right_offset=500，扩展后的图像分辨率为1500×1000（宽×高）。保持高度不变，只在图像右侧添加500个像素。

您可以选择与top_offset、bottom_offset、left_offset参数搭配使用，但不能与x_scale、y_scale这些参数同时使用。若同时配置，则x_scale、y_scale参数优先生效。

best_quality boolean 可选

开启图像最佳质量模式。默认值为false，减少图像生成的等待时间。

如果您需要更多图像细节，可以设置为true，但耗时会成倍增加。

limit_image_size boolean 可选

限制模型生成的图像文件大小。默认值为true，限制为：

  • 当输入图像单边长度<=10000，输出图像文件大小在5MB以下

  • 当输入图像单边长度>10000，输出图像文件大小在10MB以下

您也可以设置为false，不压缩模型生成的图像文件，搭配 best_quality 参数可获得高质量图像。

注意：输出图像的长宽比范围为1:4至4:1。

add_watermark boolean 可选

添加Generated by AI水印。默认值为True，在输出图像左下角处添加水印。

响应

成功响应

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

异常响应

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

output object

任务输出信息。

属性

task_id string

任务id，任务唯一标识。

task_status string

任务状态。

  • PENDING：排队中

  • RUNNING：处理中

  • SUSPENDED：挂起

  • SUCCEEDED：执行成功

  • FAILED：执行失败

  • UNKNOWN：任务不存在或状态未知

code string

接口错误码。接口成功请求不会返回该参数。

message string

接口错误信息。接口成功请求不会返回该参数。

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

根据任务ID查询结果

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

请求头（Headers）

查询任务结果

curl --location --request GET 'https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Authorization string 必选

推荐使用百炼API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。

URL路径参数（Path parameters）

task_id string 必选

任务id。

响应

任务执行成功

{
    "request_id": "b67df059-ca6a-9d51-afcd-9b3c4456b1e2",
    "output": {
        "task_id": "d76ec1e8-ea27-4038-8913-235c88ef0f70",
        "task_status": "SUCCEEDED",
        "submit_time": "2024-05-16 13:50:01.247",
        "scheduled_time": "2024-05-16 13:50:01.354",
        "end_time": "2024-05-16 13:50:27.795",
        "output_image_url": "https://xxxx/xxxx"
    },
    "usage": {
        "image_count": 1
    }
}

任务执行中

{
    "request_id":"e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output":{
        "task_id":"d76ec1e8-ea27-4038-8913-235c88ef0f70",
        "task_status":"RUNNING",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

任务执行失败

{
    "request_id": "dccfdf23-b38e-97a6-a07b-f35118c1ada6",
    "output": {
        "task_id": "4cbabbdf-2c1f-43f4-b983-c2cc47f4c115",
        "task_status": "FAILED",
        "submit_time": "2024-05-16 14:15:14.103",
        "scheduled_time": "2024-05-16 14:15:14.154",
        "end_time": "2024-05-16 14:15:14.694",
        "code": "InvalidParameter.FileDownload",
        "message": "download for input_image error"
    }
}

output object

输出的任务信息。

属性

task_id string

任务id。

task_status string

任务状态。

  • PENDING：排队中

  • RUNNING：处理中

  • SUSPENDED：挂起

  • SUCCEEDED：执行成功

  • FAILED：执行失败

  • UNKNOWN：任务不存在或状态未知

task_metrics object

任务统计信息。

属性

TOTAL integer

总的任务数。

SUCCEEDED integer

任务状态为成功的任务数。

FAILED integer

任务状态为失败的任务数。

submit_time string

任务提交时间。

scheduled_time string

任务执行时间。

end_time string

任务完成时间。

output_image_url string

输出图像URL地址。

code string

接口错误码。接口成功请求不会返回该参数。

message string

接口错误信息。接口成功请求不会返回该参数。

usage object

图像统计信息。

属性

image_count integer

生成图像的数量。

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。

此API还有特定状态码，具体如下所示。

HTTP状态码

接口错误码（code）

接口错误信息（message）

含义说明

400

InvalidParameter.JsonPhrase

input json error

输入json错误

400

InvalidParameter.FileDownload

oss download error

输入图像下载失败

400

InvalidParameter.ImageFormat

read image error

读取图像失败

400

InvalidParameter.ImageContent

The image content does not comply with green network verification

图像内容不合规

400

InvalidParameter

the parameters must conform to the specification: xxx

输入参数值超出范围

500

InternalError.Algo

algorithm process error

算法错误

500

InternalError.FileUpload

oss upload error

文件上传失败

上一篇：鞋靴模特API参考下一篇：人物实例分割API参考
文档推荐