AI 助理
备案控制台登录注册
文档
输入文档关键字查找
首页大模型服务平台百炼API参考（模型）图像生成图像画面扩展API参考

图像画面扩展API参考

更新时间：2025-04-01 10:08:28
产品详情
我的收藏

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

相关指南：图像画面扩展

模型概览

模型名

免费额度

计费单价

限流（含主账号与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
    }
}'

Content-Type string （必选）

请求内容类型。此参数必须设置为application/json。

Authorization string（必选）

请求身份认证。接口使用百炼API-Key进行身份认证。示例值：Bearer d1xxx2a。

X-DashScope-Async string （必选）

异步处理配置参数。HTTP请求只支持异步，必须设置为enable。

请求体（Request Body）

model string （必选）

模型名称。示例值：image-out-painting。

input object （必选）

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

属性

image_url string （必选）

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

图像限制：

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

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

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

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

parameters object （必选）

图像处理参数。

属性

angle integer （可选）

逆时针旋转角度。默认值为0，取值范围[0, 359]。

angel参数需要与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]。

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

示例

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

y_scale float （可选）

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

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

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

示例

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

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×输入图像宽度。

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

示例

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

right_offset integer （可选）

在图像右侧添加像素。

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

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

示例

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

best_quality boolean （可选）

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

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

limit_image_size boolean （可选）

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

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

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

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

建议设置为true，模型生成的图像需要经过一层绿网安全过滤后才能输出。当前绿网不支持大于10M的图像处理。

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-xxxxxx"
}

output object

任务输出信息。

属性

task_id string

任务ID。

task_status string

任务状态。

枚举值

  • PENDING：任务排队中

  • RUNNING：任务处理中

  • SUSPENDED：任务挂起

  • SUCCEEDED：任务执行成功

  • FAILED：任务执行失败

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

request_id string

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

code string

请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息。

message string

请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息。

根据任务ID查询结果

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

请求头（Headers）

查询任务结果

您需要将86ecf553-d340-4e21-xxxxxxxxx替换为真实的task_id。

curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx

Authorization string（必选）

请求身份认证。接口使用百炼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

任务提交时间。

end_time string

任务完成时间。

output_image_url string

输出图像URL地址。

code string

请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息。

message string

请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息。

usage object

图像统计信息。

属性

image_count integer

模型生成图片的数量。

request_id string

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

错误码

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

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

HTTP状态码

接口错误码（code）

接口错误信息（message）

含义说明

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

输入参数值超出范围

400

InvalidParameter.DataInspection

The image size is not supported for the data inspection.

输出图像尺寸超限（大于10M）

500

InternalError.Algo

algorithm process error

算法错误

500

InternalError.FileUpload

oss upload error

文件上传失败

常见问题

1 创建任务接口响应成功，但没有返回图像URL？

答：在图像模型处理中，HTTP请求需要经过两步才能获取结果：创建任务、根据任务ID查询结果。创建任务接口仅提交任务，不返回图像结果。您需要查询 GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id} 接口获得模型生成的图像URL。

上一篇：人像风格重绘下一篇：虚拟模特
  • 本页导读 （1）
  • 模型概览
  • 前提条件
  • HTTP调用
  • 创建任务
  • 根据任务ID查询结果
  • 错误码
  • 常见问题
AI助理

点击开启售前

在线咨询服务

你好，我是AI助理

可以解答问题、推荐解决方案等