AI Image Expansion V2
Description
Use AI outpainting to generate content beyond the image borders based on the original image. Expand uniformly, specify a ratio or pixel count for each side, or expand automatically to a target aspect ratio.
Version
1.0
Image Requirements
JPG and PNG are supported.
Request URL
Production environment: https://openapi.meitu.com
Task submission endpoint: https://openapi.meitu.com/api/v1/sdk/sync/push
Task name (task): /v1/AI_Image_Expansion_v2/497076
Task type (task_type): formulaHTTP Method
POST
Content-Type: application/json
Authentication
Use Open Platform API Signing.
Request Parameters
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | params | string | Algorithm parameters encoded as a JSON string. |
| Yes | init_images | object[] | Input image list. Submit one item. |
| Yes | task | string | /v1/AI_Image_Expansion_v2/497076 |
| Yes | task_type | string | formula |
| No | sync_timeout | integer | Set to -1 to submit without waiting for the result. |
init_images
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | url | string | Input image URL. |
| — | profile | object | Image media properties. |
profile
| Required | Parameter | Type | Description |
|---|---|---|---|
| — | media_profiles | object | Media type settings. |
| — | version | string | Example value: v1. |
media_profiles
| Required | Parameter | Type | Description |
|---|---|---|---|
| — | media_data_type | string | Use url for an image URL. |
params
The decoded params JSON contains the parameter object.
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | parameter | object | Image expansion settings. |
parameter
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | expand_ratio | number | Uniform expansion ratio in [0, 1]. Default: 0.5. A value of 0.1 expands both dimensions to 120% of their original sizes; 0.5 expands both to 200%. |
| No | free_expand_ratio | object | Expansion ratio for each side. Each value must be in [0, 1]. |
| No | free_expand_pixel | object | Number of pixels to add on each side. Each value must be a non-negative integer. |
| No | mode | integer | Omit to use manual expansion parameters. Use 1 to expand automatically according to ratio, or 2 to expand to 1:1 without specifying ratio. |
| Conditional | ratio | string | Required when mode=1. Accepted values: arbitrary, 1:1, 3:4, 4:3, 9:16, and 16:9. |
| No | generate_num | integer | Number of images to generate. Default: 1; maximum: 20. |
| No | seed | integer | Random seed in [-1, 65535]. Default: 0. Use a fixed seed for reproducibility or -1 for a random seed. |
| No | extra_prompt | string | Additional guidance for the generated content. Use English and separate multiple prompts with commas. |
| No | high_quality_encode | boolean | Encode the result with less compression. Default: false. Enabling this can improve encoding quality and increase latency without changing the generated content. |
| No | rsp_media_type | string | Use url for result image URLs or jpg for Base64 image data. |
For manual expansion, pass at most one of expand_ratio, free_expand_ratio, and free_expand_pixel. For per-side expansion, supply all four fields: top, bottom, left, and right. Use 0 for any side that should remain unchanged. Ratios for the top and bottom are relative to the original height; ratios for the left and right are relative to the original width. For example, top: 0.1 adds 10% of the original height above the image.
Request Example
This example adds 25% of the original dimension on each side.
{
"task": "/v1/AI_Image_Expansion_v2/497076",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"rsp_media_type\":\"url\",\"free_expand_ratio\":{\"top\":0.25,\"bottom\":0.25,\"left\":0.25,\"right\":0.25},\"seed\":42,\"extra_prompt\":\"Extend the background and keep its color consistent.\"}}",
"sync_timeout": -1
}Response Fields
| Field | Type | Description |
|---|---|---|
error_code | integer | Error code. 0 indicates success. |
message | string | Processing message. |
data.status | integer | Task status. |
data.result.id | string | Task ID used to query the task. |
data.result.urls | string[] | Result image URLs returned on success. |
data.progress | number | Task progress. 1 indicates completion. |
Response Examples
Successful Response
Response Status: 200
Content-Type: application/json; charset=utf-8
{
"error_code": 0,
"message": "success",
"data": {
"status": 10,
"result": {
"id": "example-task-id",
"urls": [
"https://example.com/result.jpeg"
]
},
"progress": 1
}
}When to Query the Task
If data.status = 9, the synchronous wait timed out. This does not mean the task failed. Use data.result.id as the task ID in the Task Query API.
In the query response, 0 or 1 means the task is not complete, 10 means it succeeded, and 2 means it failed.
Failed Response
Response Status: 400
Content-Type: application/json; charset=utf-8
Common Error Codes
See API Error Codes.
SDK Examples
Before submitting a request, fill in your access key, secret key, and image URL.
Python
import requests
from sign_sdk import sign
url = "https://openapi.meitu.com/api/v1/sdk/sync/push"
body = r'''{
"task": "/v1/AI_Image_Expansion_v2/497076",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"rsp_media_type\":\"url\",\"free_expand_ratio\":{\"top\":0.25,\"bottom\":0.25,\"left\":0.25,\"right\":0.25},\"seed\":42,\"extra_prompt\":\"Extend the background and keep its color consistent.\"}}",
"sync_timeout": -1
}'''
headers = {"Content-Type": "application/json", sign.HeaderHost: "openapi.meitu.com"}
signer = sign.Signer("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY")
request = signer.sign(url, "POST", headers, body)
with requests.Session() as session:
response = session.send(request, timeout=(10, 60), allow_redirects=False)
print(response.status_code, response.text)Go
package main
import (
"fmt"
"io"
"log"
"net/http"
"time"
"github.com/mtlab/api/signer"
)
func main() {
url := "https://openapi.meitu.com/api/v1/sdk/sync/push"
body := `{
"task": "/v1/AI_Image_Expansion_v2/497076",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"rsp_media_type\":\"url\",\"free_expand_ratio\":{\"top\":0.25,\"bottom\":0.25,\"left\":0.25,\"right\":0.25},\"seed\":42,\"extra_prompt\":\"Extend the background and keep its color consistent.\"}}",
"sync_timeout": -1
}`
headers := make(http.Header)
headers.Set(signer.HeaderHost, "openapi.meitu.com")
headers.Set("Content-Type", "application/json")
s := signer.NewSigner("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY")
req, err := s.Sign(url, http.MethodPost, headers, body)
if err != nil {
log.Fatal(err)
}
client := &http.Client{
Timeout: 60 * time.Second,
CheckRedirect: func(*http.Request, []*http.Request) error {
return http.ErrUseLastResponse
},
}
res, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
result, err := io.ReadAll(res.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(res.StatusCode, string(result))
}PHP
<?php
require_once __DIR__ . '/signer.php';
$url = 'https://openapi.meitu.com/api/v1/sdk/sync/push';
$body = <<<'JSON'
{
"task": "/v1/AI_Image_Expansion_v2/497076",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"rsp_media_type\":\"url\",\"free_expand_ratio\":{\"top\":0.25,\"bottom\":0.25,\"left\":0.25,\"right\":0.25},\"seed\":42,\"extra_prompt\":\"Extend the background and keep its color consistent.\"}}",
"sync_timeout": -1
}
JSON;
$headers = ['Host' => 'openapi.meitu.com', 'Content-Type' => 'application/json'];
$signer = new Signer('YOUR_ACCESS_KEY', 'YOUR_SECRET_KEY');
$curl = $signer->sign($url, 'POST', $headers, $body);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => false,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 60,
]);
$result = curl_exec($curl);
if ($result === false) {
$error = curl_error($curl);
curl_close($curl);
throw new RuntimeException($error);
}
echo curl_getinfo($curl, CURLINFO_HTTP_CODE), PHP_EOL, $result, PHP_EOL;
curl_close($curl);Java
package com.meitu.openai.common;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
public class Main {
public static void main(String[] args) throws Exception {
String url = "https://openapi.meitu.com/api/v1/sdk/sync/push";
String body = "{\n" +
" \"task\": \"/v1/AI_Image_Expansion_v2/497076\",\n" +
" \"task_type\": \"formula\",\n" +
" \"init_images\": [\n" +
" {\n" +
" \"url\": \"https://example.com/input.jpg\",\n" +
" \"profile\": {\n" +
" \"media_profiles\": {\n" +
" \"media_data_type\": \"url\"\n" +
" },\n" +
" \"version\": \"v1\"\n" +
" }\n" +
" }\n" +
" ],\n" +
" \"params\": \"{\\\"parameter\\\":{\\\"rsp_media_type\\\":\\\"url\\\",\\\"free_expand_ratio\\\":{\\\"top\\\":0.25,\\\"bottom\\\":0.25,\\\"left\\\":0.25,\\\"right\\\":0.25},\\\"seed\\\":42,\\\"extra_prompt\\\":\\\"Extend the background and keep its color consistent.\\\"}}\",\n" +
" \"sync_timeout\": -1\n" +
"}";
Map<String, String> headers = new HashMap<>();
headers.put("Content-Type", "application/json");
headers.put(Signer.HeaderHost, "openapi.meitu.com");
Signer signer = new Signer("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY");
Map<String, String> signed = signer.sign(url, "POST", headers, body);
HttpURLConnection connection = (HttpURLConnection) URI.create(url).toURL().openConnection();
try {
connection.setRequestMethod("POST");
connection.setConnectTimeout(10000);
connection.setReadTimeout(60000);
connection.setInstanceFollowRedirects(false);
signed.forEach(connection::setRequestProperty);
connection.setDoOutput(true);
try (OutputStream out = connection.getOutputStream()) {
out.write(body.getBytes(StandardCharsets.UTF_8));
}
int status = connection.getResponseCode();
try (InputStream in = status >= 400 ? connection.getErrorStream() : connection.getInputStream()) {
String result = in == null ? "" : new String(in.readAllBytes(), StandardCharsets.UTF_8);
System.out.println(status + " " + result);
}
} finally {
connection.disconnect();
}
}
}