DocsICP FilingConsole
官方文档
首页

Image outpainting API reference

更新时间：
复制 MD 格式
产品详情
我的收藏

This topic describes the input and output parameters for the image outpainting model. Image outpainting supports multiple expansion methods, such as expanding by aspect ratio, expanding by scale, or adding pixels to the top, bottom, left, or right. You can also combine these methods with a rotation angle.

Related guide: Image outpainting

Important

This document applies only to the China (Beijing) region. Use an API key from this region.

Important

Alibaba Cloud Model Studio has released a workspace-specific domain for the China (Beijing) region: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from https://dashscope.aliyuncs.com to the new domain.

{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

Model overview

Model name

Unit price

Rate limit (shared between Alibaba Cloud accounts and RAM users)

Free quota(View)

QPS limit for task submission API

Number of concurrent tasks

image-out-painting

CNY 0.18/image

2

5

500 images

Prerequisites

Obtain an API key and export the API key as an environment variable. If you use an SDK to make calls, install the DashScope SDK.

HTTP call

To reduce wait times and prevent request timeouts, this service is asynchronous. You must make two requests:

  • Step 1: Create a task to obtain a task ID: Send a request to create an outpainting task. The response returns a task ID.

  • Step 2: Query the result based on the task ID: Use the task ID from the previous step to query the result generated by the model.

Step 1: Create a task to obtain a task ID

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/out-painting

Replace {WorkspaceId} with your actual workspace ID.

Request headers

Rotate image

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location --request POST 'https://{WorkspaceId}.cn-beijing.maas.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
    }
}'

Expand image by scale

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location --request POST 'https://{WorkspaceId}.cn-beijing.maas.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
    }
}'

Expand image in a specified direction

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location --request POST 'https://{WorkspaceId}.cn-beijing.maas.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
    }
}'

Expand image by aspect ratio

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location --request POST 'https://{WorkspaceId}.cn-beijing.maas.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 (Required)

The content type of the request. Must be application/json.

Authorization string (Required)

Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

X-DashScope-Async string (Required)

Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.

Important

If this request header is missing, the error "current user api does not support synchronous calls" is returned.

Request body

model string (Required)

The model name. For example: image-out-painting.

input object (Required)

The basic information of the input image, such as the image URL.

Property

image_url string (Required)

The URL or base64-encoded data of the image.

The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.

Image limits:

  • Image format: JPG, JPEG, PNG, HEIF, or WEBP.

  • Image size: no more than 10 MB.

  • Image resolution: must not be lower than 512 × 512 pixels or higher than 4096 × 4096 pixels.

  • The length of each side must be between 512 and 4096 pixels.

parameters object (Required)

The processing parameters for the output image, such as the counter-clockwise rotation angle, aspect ratio, expansion scale, and pixel padding for the four sides.

Properties

angle integer (Optional)

The counter-clockwise rotation angle in degrees. Default value: 0. Value range: [0, 359].

For more information, see Parameter usage.

output_ratio string (Optional)

The aspect ratio of the output image. Valid values: `""`, `"1:1"`, `"3:4"`, `"4:3"`, `"9:16"`, and `"16:9"`. The default value is `""`, which indicates that the aspect ratio of the output image is not set.

For more information, see Parameter usage.

x_scale float (Optional)

Centers the image and expands it horizontally by the specified scale.

Default value: 1.0. Value range: [1.0, 3.0].

You can use this parameter with the `y_scale` parameter. For more information, see Parameter usage.

Example

For example, if the input image resolution is 1000 × 1000 (width × height) and `x_scale` is set to 2.0, the expanded image resolution is 2000 × 1000 (width × height). The height remains unchanged, and 500 pixels are added to the left and right sides.

y_scale float (Optional)

Centers the image and expands it vertically by the specified scale.

Default value: 1.0. Value range: [1.0, 3.0].

You can use this parameter with the `x_scale` parameter. For more information, see Parameter usage.

Example

For example, if the input image resolution is 1000 × 1000 (width × height) and `y_scale` is set to 2.0, the expanded image resolution is 1000 × 2000 (width × height). The width remains unchanged, and 500 pixels are added to the top and bottom.

top_offset integer (Optional)

Adds pixels to the top of the image.

Default value: 0. Value limit: top_offset + bottom_offset < 3 × input image height.

You can use this parameter with the `bottom_offset`, `left_offset`, and `right_offset` parameters. For more information, see Parameter usage.

Example

For example, if the input image resolution is 1000 × 1000 (width × height) and `top_offset` is set to 500, the expanded image resolution is 1000 × 1500 (width × height). The width remains unchanged, and 500 pixels are added only to the top of the image.

bottom_offset integer (Optional)

Adds pixels to the bottom of the image.

Default value: 0. Value limit: top_offset + bottom_offset < 3 × input image height.

You can use this parameter with the `top_offset`, `left_offset`, and `right_offset` parameters. For more information, see Parameter usage.

Example

For example, if the input image resolution is 1000 × 1000 (width × height) and `bottom_offset` is set to 500, the expanded image resolution is 1000 × 1500 (width × height). The width remains unchanged, and 500 pixels are added only to the bottom of the image.

left_offset integer (Optional)

Adds pixels to the left of the image.

Default value: 0. Value limit: left_offset + right_offset < 3 × input image width.

You can use this parameter with the `top_offset`, `bottom_offset`, and `right_offset` parameters. For more information, see Parameter usage.

Example

For example, if the input image resolution is 1000 × 1000 (width × height) and `left_offset` is set to 500, the expanded image resolution is 1500 × 1000 (width × height). The height remains unchanged, and 500 pixels are added only to the left of the image.

right_offset integer (Optional)

Adds pixels to the right of the image.

Default value: 0. Value limit: left_offset + right_offset < 3 × input image width.

You can use this parameter with the `top_offset`, `bottom_offset`, and `left_offset` parameters. For more information, see Parameter usage.

Example

For example, if the input image resolution is 1000 × 1000 (width × height) and `right_offset` is set to 500, the expanded image resolution is 1500 × 1000 (width × height). The height remains unchanged, and 500 pixels are added only to the right of the image.

best_quality boolean (Optional)

Specifies whether to enable the best quality mode for the image. The default value is `false`, which reduces the waiting time for image generation.

If you require more image details, set this parameter to `true`. This significantly increases the time required.

limit_image_size boolean (Optional)

Specifies whether to limit the file size of the image generated by the model. The default value is `true`. If the side length of the input image is less than or equal to 10,000 pixels, the output image file size is less than 5 MB.

The aspect ratio of the output image must be within the range of 1:4 to 4:1.

You must set this parameter to `true`. The image generated by the model must pass through a security filter before it can be output. Images that are larger than 10 MB are not supported.

add_watermark boolean (Optional)

Specifies whether to add a Generated by AI watermark. The default value is `true`, which adds a watermark to the lower-left corner of the output image.

Response

Successful response

Save the task_id to query the task status and result.

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

Error response

Task creation failed. See Error codes.

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

output object

The task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The status of the task.

Enumeration values

  • PENDING

  • RUNNING

  • SUCCEEDED

  • FAILED

  • CANCELED

  • UNKNOWN: The task does not exist or its status is unknown.

request_id string

Unique request identifier for tracing and troubleshooting.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

Step 2: Query the result based on the task ID

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Replace {WorkspaceId} with your actual workspace ID.

Request headers

Query task result

Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task_id.

If you use a model in the Singapore region, replace base_url with https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx, where {WorkspaceId} is your actual workspace ID.
curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Authorization string (Required)

Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

URL path parameters

task_id string (Required)

The ID of the task.

Response

Task successful

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

Task running

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

Task failed

{
    "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

The task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The status of the task.

Enumeration values

  • PENDING

  • RUNNING

  • SUCCEEDED

  • FAILED

  • CANCELED

  • UNKNOWN: The task does not exist or its status is unknown.

task_metrics object

Statistics for the task result.

Properties

TOTAL integer

The total number of tasks.

SUCCEEDED integer

The number of successful tasks.

FAILED integer

The number of failed tasks.

submit_time string

The time the task was submitted.

end_time string

The time the task was completed.

output_image_url string

The URL of the output image.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

usage object

The image statistics information.

Property

image_count integer

Number of images successfully generated. Billing: Cost = Number of images × Unit price.

request_id string

Unique request identifier for tracing and troubleshooting.

Image processing parameter usage

The image processing parameters include two parameter types: rotation and expansion. The expansion parameters are divided into three independent categories based on their functions.

Parameter type

Priority

Parameter

Rotation parameter

Rotate first, then expand

angle

Expansion parameters

Expansion priority 1: Expand by aspect ratio

output_ratio

Expansion priority 2: Expand by scale

x_scale, y_scale

Expansion priority 3: Expand by adding pixels in a specified direction

left_offset, right_offset, top_offset, bottom_offset

Parameter setting recommendations

  1. To expand only by aspect ratio: Set output_ratio to an aspect ratio, such as "4:3" or "16:9".

  2. To expand only by scale: Set the x_scale parameter, the y_scale parameter, or both. At least one parameter must have a value greater than 1.0.

  3. To expand by adding pixels in a specific direction: Set one or more of the left_offset, right_offset, top_offset, or bottom_offset parameters to a value greater than 0.

  4. To rotate the image only: Set the angle parameter to a value in the range of 1 to 359, excluding 90, 180, and 270.

  5. To rotate and then expand the image: You can set the angle parameter to a value in the range of [1, 359]. You must also use this parameter with one of the following three groups of expansion parameters. If you set multiple groups of expansion parameters, they take effect according to parameter priority.

    1. output_ratio: Cannot be empty.

    2. x_scale, y_scale: At least one of the values must be greater than 1.0.

    3. top_offset, bottom_offset, left_offset, right_offset: The value of at least one parameter must be greater than 0.

    Note: When you rotate and expand an image, the model first rotates the image by the specified angle and then performs the expansion operation on the rotated image. The actual expansion effect is determined by the model output.

Parameter priority

  • If angle > 0 and expansion parameters are also set, the processing order is: First rotate, then expand.

  • If angle = 0 or if the image is rotated, the expansion parameters are applied in the following priority order:

    • Priority 1: Expand by aspect ratio (output_ratio)

      If `output_ratio` is not empty, the image is generated based on this aspect ratio, and all other expansion parameters are ignored.

    • Priority 2: Expand by scale (x_scale, y_scale)

      If `output_ratio` is not set and at least one of `x_scale` or `y_scale` is greater than 1, the image is expanded by the specified scale. In this case, the pixel offset parameters are ignored.

    • Priority 3: Expand by adding pixels in a specified direction (left_offset, right_offset, top_offset, bottom_offset)

      If `output_ratio`, `x_scale`, and `y_scale` are not set, and at least one of `left_offset`, `right_offset`, `top_offset`, or `bottom_offset` is greater than 0, the image is expanded by adding pixels in the specified direction.

Parameter combination examples

Configuration combination

Actual effective mode

output_ratio="4:3", x_scale=2.0

Expand by 4:3 aspect ratio (only output_ratio takes effect)

x_scale=2.0, left_offset=100

Expand by scale (only x_scale takes effect)

angle=90, x_scale=2.0

Rotate 90° counter-clockwise, then expand the width of the rotated image to 2.0 times its original size (both angle and x_scale take effect)

angle=90, output_ratio="4:3", x_scale=2.0, left_offset=100

Rotate 90° counter-clockwise, then expand the rotated image to a 4:3 aspect ratio (only angle and output_ratio take effect)

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

This API also has specific status codes, which are described in the following table.

HTTP status code

API error code (code)

API error message (message)

Description

400

InvalidParameter.JsonPhrase

input json error

Input JSON error.

400

InvalidParameter.FileDownload

oss download error

Failed to download the input image.

400

InvalidParameter.ImageFormat

read image error

Failed to read the image.

400

InvalidParameter.ImageContent

The image content does not comply with green network verification

The image content is not compliant.

400

InvalidParameter

the parameters must conform to the specification: xxx

The input parameter value is out of range.

400

InvalidParameter.DataInspection

The image size is not supported for the data inspection.

The output image size exceeds the limit (larger than 10 MB).

500

InternalError.Algo

algorithm process error

Algorithm error.

500

InternalError.FileUpload

oss upload error

File upload failed.

FAQ

Q: The create task API call returns a successful response, but no image URL is returned. Why?

A: For image model processing, you must make two HTTP requests to retrieve the result: first, create a task, and then query the result based on the task ID. The create task API call only submits the task and does not return the image result. You must call the GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} operation to obtain the URL of the image generated by the model.

Q: After I set the output_ratio, why doesn't the model automatically calculate the scale for the other dimension based on x_scale or y_scale?

A: The image outpainting API supports three expansion methods: by aspect ratio, by scale, and by adding pixels in a specific direction. The parameters for these methods are independent. To prevent conflicts, the system uses the following priority order: output_ratio > x_scale / y_scale > *offset.

When you set `output_ratio` to a non-empty value, the system expands the image only based on that aspect ratio and ignores all other expansion parameters. Therefore, if you set both `output_ratio` and `x_scale`, only `output_ratio` takes effect. The `x_scale` parameter is ignored, and `y_scale` is not automatically inferred or calculated based on `x_scale`.

Previous：Portrait style repaintNext：Virtual Model