Omni Image Set

Description

Regenerates images from an input image and structured editing instructions. The prompt can specify text to add, content to preserve or modify, and content to avoid, supporting revisions of product presentation images and similar visuals.

Version

1.0

Image Requirements

JPG and PNG are supported. Provide images by URL or as Base64-encoded data. The examples use one source image.

Request URL

- Production host: `https://openapi.meitu.com`
- Task submission endpoint: `https://openapi.meitu.com/api/v1/sdk/sync/push`
- Task name (`task`): `/v1/Encompassing_Image/495717`
- Task type (`task_type`): `formula`

HTTP Method

POST

Content-Type: application/json

Authentication

Sign requests with an Access Key (AK) and Secret Key (SK). See API Request Signing.

Request Parameters

RequiredParameterTypeDescription
YesparamsstringAlgorithm parameters serialized as a JSON string. See the structure below.
Yesinit_imagesobject[]Input image list.
YestaskstringFixed value: /v1/Encompassing_Image/495717.
Yestask_typestringFixed value: formula.
Nosync_timeoutintSynchronous wait timeout in seconds. Default: 30. Query the task when data.status = 9.

init_images Item

RequiredParameterTypeDescription
YesurlstringImage URL or Base64-encoded data. Do not Base64-encode a URL.
YesprofileobjectImage properties.

profile

RequiredParameterTypeDescription
Yesmedia_profilesobjectMedia transmission information.
YesversionstringFixed value: v1.
Nomedia_extraobjectAdditional image parameters. Use {} when no additional settings are needed.

media_profiles

RequiredParameterTypeDescription
Yesmedia_data_typestringurl for an image URL; jpg for Base64-encoded data.

params

Build the following parameter object, then serialize it as a string for the request's params field.

RequiredParameterTypeDescription
YesparameterobjectCore algorithm parameters.
NoextraobjectAdditional algorithm request information. Use {} when no additional settings are needed.

parameter

RequiredParameterTypeDescription
YespromptobjectStructured editing instructions, described below. Keep it as an object within parameter after decoding params.
NoheightnumberOutput image height in pixels. If omitted, it is parsed from prompt.
NowidthnumberOutput image width in pixels. If omitted, it is parsed from prompt.
Norsp_media_typestringOutput transmission type: url for an image URL or jpg for Base64-encoded image data. Default: url.
NoseednumberRandom seed. Default: 42. Set to -1 to use a random seed.

prompt

The following fields illustrate the structured prompt format. Keep the property names exactly as shown, including the Chinese keys. Translate or edit the string values to describe the required image changes.

PropertyTypeDescription
image_ratiostringOutput aspect ratio. The example uses 1:1.
文字新增stringText to add, including font, placement, and layout requirements.
画面不变内容stringSubjects, structures, and layout elements to preserve.
画面修改内容stringShapes, lighting, textures, or other elements to modify.
画面禁止内容stringContent that must not be generated or changed.

Request Example

This example edits a phone-case presentation image and returns a URL. Replace the example image URL.

params is a string that decodes to an object containing parameter and extra; parameter.prompt remains an object.

{
  "task": "/v1/Encompassing_Image/495717",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://example.com/input.png",
      "profile": {
        "media_profiles": {
          "media_data_type": "url"
        },
        "media_extra": {},
        "version": "v1"
      }
    }
  ],
  "params": "{\"parameter\":{\"prompt\":{\"image_ratio\":\"1:1\",\"文字新增\":\"Add the text 'Multiple materials available | Blue-light model resists yellowing' in a modern bold sans-serif font in the upper-left negative space. Add 'Fast refunds | Ready to ship | Factory direct' in a light sans-serif font along the lower edge.\",\"画面不变内容\":\"Preserve the structures of both phone cases, the certificate layout, the original anti-yellowing comparison, and the certificate background structure.\",\"画面修改内容\":\"Replace square UI bubbles with rounded ones. Enhance the new phone case's transparency and lighting to emphasize its difference in texture from the old case.\",\"画面禁止内容\":\"Do not change the colors of the two phone cases or the comparison layout. Do not make the new phone case appear yellowed. Do not cover the phone cases or certificates with text. Do not add cheap-looking color blocks.\"},\"seed\":-1,\"rsp_media_type\":\"url\"},\"extra\":{}}",
  "sync_timeout": 30
}

Response Fields

Generated results are cleaned up periodically. Download and save them promptly.

code = 0 indicates normal request processing; also check data.status to determine whether the task has completed. On success, read output images from data.result.data.media_info_list.

FieldTypeDescription
request_idstringRequest identifier.
trace_idstringTrace identifier.
codeintBusiness status code: 0 for normal processing, nonzero for an error.
error_codeintError code; matches code in the examples.
messagestringResponse or error message.
dataobjectTask state and results.
tipsnullAdditional hints; null in this failure example and may be omitted.

data

FieldTypeDescription
statusintStatus: -1 not found; 0 created; 1 running; 2 failed; 9 timeout (synchronous wait expired), continue with the Task Query API; 10 succeeded.
resultobjectResult wrapper; may contain only id before completion.
task_idstringGateway task ID. Pass it as task_id when querying.
progressnumberTask progress.
predict_elapsednumberEstimated processing duration.
create_timenumberTask creation time.
custom_task_idstringCustom task identifier.
trace_idstringTask trace identifier.
client_infostringAdditional client information.
init_imagesarray/nullInput image information; null in the examples.

result

FieldTypeDescription
idstringGateway task ID corresponding to data.task_id.
codeintAlgorithm status code.
dataobjectOriginal algorithm response, described below.
msgstringAlgorithm response message.
msg_idstringAlgorithm request identifier; not a replacement for the gateway task_id.

result.data

FieldTypeDescription
error_codeintError code. 0 indicates success.
error_msgstringProcessing result or error description.
msg_idstringUnique algorithm request identifier. This identifier and the algorithm result are deleted after 24 hours; gateway queries use data.task_id.
media_info_listobject[]Processed images.
parameterobject/nullOutput transmission type and algorithm version; may be null on failure.
durationobjectDetailed processing timings.
extraobjectAdditional information. The example includes algo_msg.
callback_msgstringCallback-related information. May be an empty string.

result.data.media_info_list Item

FieldTypeDescription
media_datastringResult image URL or Base64-encoded data.
media_extraobject/nullAdditional image information. May be null.
media_profilesobjectOutput image transmission information.
media_profiles.media_data_typestringurl for a URL or jpg for Base64-encoded data.

result.data.parameter

FieldTypeDescription
rsp_media_typestringOutput transmission type: url or jpg.
versionstringAlgorithm version. The response example uses 1.0.0.

result.data.duration

FieldTypeDescription
created_timestampintTimestamp when the algorithm received the request, in seconds.
pull_timestampintTimestamp when the task left the queue, in seconds.
waiting_timeintTime spent waiting in the queue, in milliseconds.
alg_process_timeintAlgorithm processing time, including download time, in milliseconds.
upload_timeintUpload time, in milliseconds.
repost_timeintAsynchronous callback time, in milliseconds.

data.status = 9 means the synchronous wait has expired, not that the algorithm has failed. Save data.task_id and use the Task Query API. Do not substitute the algorithm msg_id for the gateway task ID. The algorithm identifier and results are retained for only 24 hours; retrieve and save results promptly.

Response Examples

Successful Response

Response Status: 200

Content-Type: application/json; charset=utf-8

{
  "request_id": "example-request-id",
  "trace_id": "example-trace-id",
  "code": 0,
  "error_code": 0,
  "message": "success",
  "data": {
    "status": 10,
    "result": {
      "id": "example-task-id",
      "code": 0,
      "data": {
        "callback_msg": "",
        "duration": {
          "alg_process_time": 18828,
          "created_timestamp": 1770117759,
          "pull_timestamp": 1770118674,
          "repost_time": 22,
          "upload_time": 105,
          "waiting_time": 914880
        },
        "error_code": 0,
        "error_msg": "success",
        "extra": {
          "algo_msg": {}
        },
        "media_info_list": [
          {
            "media_data": "https://example.com/result.jpeg",
            "media_extra": null,
            "media_profiles": {
              "media_data_type": "url"
            }
          }
        ],
        "msg_id": "example-message-id",
        "parameter": {
          "rsp_media_type": "url",
          "version": "1.0.0"
        }
      },
      "msg": "success",
      "msg_id": "example-message-id"
    },
    "progress": 1,
    "predict_elapsed": 10000,
    "create_time": 1770117759000,
    "task_id": "example-task-id",
    "custom_task_id": "",
    "trace_id": "example-trace-id",
    "client_info": "",
    "init_images": null
  }
}

Response Requiring a Query

Pass data.task_id to the Task Query API.

Response Status: 200

Content-Type: application/json; charset=utf-8

{
  "request_id": "example-request-id",
  "trace_id": "example-trace-id",
  "code": 0,
  "error_code": 0,
  "message": "success",
  "data": {
    "status": 9,
    "result": {
      "id": "example-task-id"
    },
    "progress": 0,
    "predict_elapsed": 10000,
    "create_time": 1770117759000,
    "task_id": "example-task-id",
    "custom_task_id": "",
    "trace_id": "example-trace-id",
    "client_info": "",
    "init_images": null
  }
}

Failed Response

The following illustrates an algorithm execution error. Other failures may return different codes and messages; see the actual response and error code documentation.

Response Status: 400

Content-Type: application/json; charset=utf-8

{
  "request_id": "example-request-id",
  "trace_id": "example-trace-id",
  "code": 20001,
  "error_code": 20001,
  "message": "ALGO_MODEL_CRASH",
  "data": {
    "status": 2,
    "result": {
      "id": "example-task-id",
      "code": 20001,
      "data": {
        "duration": {
          "alg_process_time": 0,
          "created_timestamp": 1770117759,
          "pull_timestamp": 1770117759,
          "repost_time": 0,
          "upload_time": 0,
          "waiting_time": 0
        },
        "error_code": 20001,
        "error_msg": "ALGO_MODEL_CRASH",
        "extra": {},
        "media_info_list": [],
        "msg_id": "example-message-id",
        "parameter": null
      },
      "msg": "ALGO_MODEL_CRASH",
      "msg_id": "example-message-id"
    },
    "progress": 1,
    "predict_elapsed": 10000,
    "create_time": 1770117759000,
    "task_id": "example-task-id",
    "custom_task_id": "",
    "trace_id": "example-trace-id",
    "client_info": "",
    "init_images": null
  },
  "tips": null
}

Common Error Codes and Messages

See API Error Codes.

SDK Examples

The examples construct the complete request body in code; no additional JSON file is needed. Include the signing SDK following the relevant guide, replace AK/SK and the image URL, and adjust the prompt as needed. Keep params as a JSON string.

Each example signs and submits the request. If data.status = 9, retrieve the result as described in the task query instructions above.

Python

Install or include the SDK following the Python Signing SDK Guide.

import json

import requests
from sign_sdk import sign

def main():
    key = "YOUR_ACCESS_KEY"
    secret = "YOUR_SECRET_KEY"
    url = "https://openapi.meitu.com/api/v1/sdk/sync/push"
    inner_params = {
        "parameter": {
            "prompt": {
                "image_ratio": "1:1",
                "文字新增": "Add the text 'Multiple materials available | Blue-light model resists yellowing' in a modern bold sans-serif font in the upper-left negative space. Add 'Fast refunds | Ready to ship | Factory direct' in a light sans-serif font along the lower edge.",
                "画面不变内容": "Preserve the structures of both phone cases, the certificate layout, the original anti-yellowing comparison, and the certificate background structure.",
                "画面修改内容": "Replace square UI bubbles with rounded ones. Enhance the new phone case's transparency and lighting to emphasize its difference in texture from the old case.",
                "画面禁止内容": "Do not change the colors of the two phone cases or the comparison layout. Do not make the new phone case appear yellowed. Do not cover the phone cases or certificates with text. Do not add cheap-looking color blocks."
            },
            "seed": -1,
            "rsp_media_type": "url"
        },
        "extra": {}
    }
    payload = {
        "task": "/v1/Encompassing_Image/495717",
        "task_type": "formula",
        "init_images": [
            {
                "url": "https://example.com/input.png",
                "profile": {
                    "media_profiles": {
                        "media_data_type": "url"
                    },
                    "media_extra": {},
                    "version": "v1"
                }
            }
        ],
        "params": json.dumps(inner_params, ensure_ascii=True),
        "sync_timeout": 30
    }
    body = json.dumps(payload, ensure_ascii=True)
    headers = {
        "Content-Type": "application/json",
        sign.HeaderHost: "openapi.meitu.com",
    }
    signer = sign.Signer(key, secret)
    signed_request = signer.sign(url, "POST", headers, body)
    with requests.Session() as session:
        response = session.send(
            signed_request, timeout=(10, 60), verify=True, allow_redirects=False
        )
        print("Status:", response.status_code)
        print("Response:", response.text)

if __name__ == "__main__":
    main()

Go

Install or include the SDK following the Go Signing SDK Guide.

package main

import (
    "fmt"
    "io"
    "net/http"
    "time"

    "github.com/mtlab/api/signer"
)

func main() {
    body := `{
  "task": "/v1/Encompassing_Image/495717",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://example.com/input.png",
      "profile": {
        "media_profiles": {
          "media_data_type": "url"
        },
        "media_extra": {},
        "version": "v1"
      }
    }
  ],
  "params": "{\"parameter\":{\"prompt\":{\"image_ratio\":\"1:1\",\"文字新增\":\"Add the text 'Multiple materials available | Blue-light model resists yellowing' in a modern bold sans-serif font in the upper-left negative space. Add 'Fast refunds | Ready to ship | Factory direct' in a light sans-serif font along the lower edge.\",\"画面不变内容\":\"Preserve the structures of both phone cases, the certificate layout, the original anti-yellowing comparison, and the certificate background structure.\",\"画面修改内容\":\"Replace square UI bubbles with rounded ones. Enhance the new phone case's transparency and lighting to emphasize its difference in texture from the old case.\",\"画面禁止内容\":\"Do not change the colors of the two phone cases or the comparison layout. Do not make the new phone case appear yellowed. Do not cover the phone cases or certificates with text. Do not add cheap-looking color blocks.\"},\"seed\":-1,\"rsp_media_type\":\"url\"},\"extra\":{}}",
  "sync_timeout": 30
}`
    url := "https://openapi.meitu.com/api/v1/sdk/sync/push"
    headers := make(http.Header)
    headers.Set("Content-Type", "application/json")
    headers.Set(signer.HeaderHost, "openapi.meitu.com")
    signObj := signer.NewSigner("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY")
    req, err := signObj.Sign(url, http.MethodPost, headers, body)
    if err != nil {
        fmt.Println("Sign request failed:", err)
        return
    }
    client := &http.Client{
        Timeout: 60 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Send request failed:", err)
        return
    }
    defer resp.Body.Close()
    responseBody, err := io.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Read response failed:", err)
        return
    }
    fmt.Println("Status:", resp.StatusCode)
    fmt.Println("Response:", string(responseBody))
}

PHP

Install or include the SDK following the PHP Signing SDK Guide.

<?php
require_once __DIR__ . '/signer.php';

$innerParams = json_encode([
    'parameter' => [
        'prompt' => [
            'image_ratio' => '1:1',
            '文字新增' => 'Add the text \'Multiple materials available | Blue-light model resists yellowing\' in a modern bold sans-serif font in the upper-left negative space. Add \'Fast refunds | Ready to ship | Factory direct\' in a light sans-serif font along the lower edge.',
            '画面不变内容' => 'Preserve the structures of both phone cases, the certificate layout, the original anti-yellowing comparison, and the certificate background structure.',
            '画面修改内容' => 'Replace square UI bubbles with rounded ones. Enhance the new phone case\'s transparency and lighting to emphasize its difference in texture from the old case.',
            '画面禁止内容' => 'Do not change the colors of the two phone cases or the comparison layout. Do not make the new phone case appear yellowed. Do not cover the phone cases or certificates with text. Do not add cheap-looking color blocks.'
        ],
        'seed' => -1,
        'rsp_media_type' => 'url'
    ],
    'extra' => (object) []
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$body = json_encode([
    'task' => '/v1/Encompassing_Image/495717',
    'task_type' => 'formula',
    'init_images' => [
        [
            'url' => 'https://example.com/input.png',
            'profile' => [
                'media_profiles' => [
                    'media_data_type' => 'url'
                ],
                'media_extra' => (object) [],
                'version' => 'v1'
            ]
        ]
    ],
    'params' => $innerParams,
    'sync_timeout' => 30
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$url = 'https://openapi.meitu.com/api/v1/sdk/sync/push';
$headers = [
    'Content-Type' => 'application/json',
    'Host' => 'openapi.meitu.com',
];
$signer = new Signer('YOUR_ACCESS_KEY', 'YOUR_SECRET_KEY');
$curl = $signer->sign($url, 'POST', $headers, $body);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($curl, CURLOPT_TIMEOUT, 60);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
$response = curl_exec($curl);
if ($response === false) {
    echo 'Error: ' . curl_error($curl) . PHP_EOL;
} else {
    echo 'Status: ' . curl_getinfo($curl, CURLINFO_HTTP_CODE) . PHP_EOL;
    echo 'Response: ' . $response . PHP_EOL;
}
curl_close($curl);

Java

Install or include the SDK following the Java Signing SDK Guide.

import com.meitu.openai.common.Signer;

import java.io.ByteArrayOutputStream;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
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 body =
                "{\n" +
                "  \"task\": \"/v1/Encompassing_Image/495717\",\n" +
                "  \"task_type\": \"formula\",\n" +
                "  \"init_images\": [\n" +
                "    {\n" +
                "      \"url\": \"https://example.com/input.png\",\n" +
                "      \"profile\": {\n" +
                "        \"media_profiles\": {\n" +
                "          \"media_data_type\": \"url\"\n" +
                "        },\n" +
                "        \"media_extra\": {},\n" +
                "        \"version\": \"v1\"\n" +
                "      }\n" +
                "    }\n" +
                "  ],\n" +
                "  \"params\": \"{\\\"parameter\\\":{\\\"prompt\\\":{\\\"image_ratio\\\":\\\"1:1\\\",\\\"文字新增\\\":\\\"Add the text 'Multiple materials available | Blue-light model resists yellowing' in a modern bold sans-serif font in the upper-left negative space. Add 'Fast refunds | Ready to ship | Factory direct' in a light sans-serif font along the lower edge.\\\",\\\"画面不变内容\\\":\\\"Preserve the structures of both phone cases, the certificate layout, the original anti-yellowing comparison, and the certificate background structure.\\\",\\\"画面修改内容\\\":\\\"Replace square UI bubbles with rounded ones. Enhance the new phone case's transparency and lighting to emphasize its difference in texture from the old case.\\\",\\\"画面禁止内容\\\":\\\"Do not change the colors of the two phone cases or the comparison layout. Do not make the new phone case appear yellowed. Do not cover the phone cases or certificates with text. Do not add cheap-looking color blocks.\\\"},\\\"seed\\\":-1,\\\"rsp_media_type\\\":\\\"url\\\"},\\\"extra\\\":{}}\",\n" +
                "  \"sync_timeout\": 30\n" +
                "}";
        String url = "https://openapi.meitu.com/api/v1/sdk/sync/push";
        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> signedHeaders = signer.sign(url, "POST", headers, body);

        HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
        try {
            connection.setRequestMethod("POST");
            connection.setConnectTimeout(10000);
            connection.setReadTimeout(60000);
            connection.setInstanceFollowRedirects(false);
            connection.setDoOutput(true);
            for (Map.Entry<String, String> entry : signedHeaders.entrySet()) {
                connection.setRequestProperty(entry.getKey(), entry.getValue());
            }
            byte[] bodyBytes = body.getBytes(StandardCharsets.UTF_8);
            connection.setFixedLengthStreamingMode(bodyBytes.length);
            try (OutputStream output = connection.getOutputStream()) {
                output.write(bodyBytes);
            }
            int status = connection.getResponseCode();
            System.out.println("Status: " + status);
            InputStream responseStream = status >= 400
                    ? connection.getErrorStream() : connection.getInputStream();
            if (responseStream != null) {
                try (InputStream input = responseStream;
                     ByteArrayOutputStream output = new ByteArrayOutputStream()) {
                    byte[] buffer = new byte[4096];
                    int length;
                    while ((length = input.read(buffer)) != -1) {
                        output.write(buffer, 0, length);
                    }
                    System.out.println("Response: " + output.toString("UTF-8"));
                }
            }
        } finally {
            connection.disconnect();
        }
    }
}