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
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | params | string | Algorithm parameters serialized as a JSON string. See the structure below. |
| Yes | init_images | object[] | Input image list. |
| Yes | task | string | Fixed value: /v1/Encompassing_Image/495717. |
| Yes | task_type | string | Fixed value: formula. |
| No | sync_timeout | int | Synchronous wait timeout in seconds. Default: 30. Query the task when data.status = 9. |
init_images Item
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | url | string | Image URL or Base64-encoded data. Do not Base64-encode a URL. |
| Yes | profile | object | Image properties. |
profile
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | media_profiles | object | Media transmission information. |
| Yes | version | string | Fixed value: v1. |
| No | media_extra | object | Additional image parameters. Use {} when no additional settings are needed. |
media_profiles
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | media_data_type | string | url 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.
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | parameter | object | Core algorithm parameters. |
| No | extra | object | Additional algorithm request information. Use {} when no additional settings are needed. |
parameter
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | prompt | object | Structured editing instructions, described below. Keep it as an object within parameter after decoding params. |
| No | height | number | Output image height in pixels. If omitted, it is parsed from prompt. |
| No | width | number | Output image width in pixels. If omitted, it is parsed from prompt. |
| No | rsp_media_type | string | Output transmission type: url for an image URL or jpg for Base64-encoded image data. Default: url. |
| No | seed | number | Random 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.
| Property | Type | Description |
|---|---|---|
| image_ratio | string | Output aspect ratio. The example uses 1:1. |
| 文字新增 | string | Text to add, including font, placement, and layout requirements. |
| 画面不变内容 | string | Subjects, structures, and layout elements to preserve. |
| 画面修改内容 | string | Shapes, lighting, textures, or other elements to modify. |
| 画面禁止内容 | string | Content 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.
| Field | Type | Description |
|---|---|---|
| request_id | string | Request identifier. |
| trace_id | string | Trace identifier. |
| code | int | Business status code: 0 for normal processing, nonzero for an error. |
| error_code | int | Error code; matches code in the examples. |
| message | string | Response or error message. |
| data | object | Task state and results. |
| tips | null | Additional hints; null in this failure example and may be omitted. |
data
| Field | Type | Description |
|---|---|---|
| status | int | Status: -1 not found; 0 created; 1 running; 2 failed; 9 timeout (synchronous wait expired), continue with the Task Query API; 10 succeeded. |
| result | object | Result wrapper; may contain only id before completion. |
| task_id | string | Gateway task ID. Pass it as task_id when querying. |
| progress | number | Task progress. |
| predict_elapsed | number | Estimated processing duration. |
| create_time | number | Task creation time. |
| custom_task_id | string | Custom task identifier. |
| trace_id | string | Task trace identifier. |
| client_info | string | Additional client information. |
| init_images | array/null | Input image information; null in the examples. |
result
| Field | Type | Description |
|---|---|---|
| id | string | Gateway task ID corresponding to data.task_id. |
| code | int | Algorithm status code. |
| data | object | Original algorithm response, described below. |
| msg | string | Algorithm response message. |
| msg_id | string | Algorithm request identifier; not a replacement for the gateway task_id. |
result.data
| Field | Type | Description |
|---|---|---|
| error_code | int | Error code. 0 indicates success. |
| error_msg | string | Processing result or error description. |
| msg_id | string | Unique algorithm request identifier. This identifier and the algorithm result are deleted after 24 hours; gateway queries use data.task_id. |
| media_info_list | object[] | Processed images. |
| parameter | object/null | Output transmission type and algorithm version; may be null on failure. |
| duration | object | Detailed processing timings. |
| extra | object | Additional information. The example includes algo_msg. |
| callback_msg | string | Callback-related information. May be an empty string. |
result.data.media_info_list Item
| Field | Type | Description |
|---|---|---|
| media_data | string | Result image URL or Base64-encoded data. |
| media_extra | object/null | Additional image information. May be null. |
| media_profiles | object | Output image transmission information. |
| media_profiles.media_data_type | string | url for a URL or jpg for Base64-encoded data. |
result.data.parameter
| Field | Type | Description |
|---|---|---|
| rsp_media_type | string | Output transmission type: url or jpg. |
| version | string | Algorithm version. The response example uses 1.0.0. |
result.data.duration
| Field | Type | Description |
|---|---|---|
| created_timestamp | int | Timestamp when the algorithm received the request, in seconds. |
| pull_timestamp | int | Timestamp when the task left the queue, in seconds. |
| waiting_time | int | Time spent waiting in the queue, in milliseconds. |
| alg_process_time | int | Algorithm processing time, including download time, in milliseconds. |
| upload_time | int | Upload time, in milliseconds. |
| repost_time | int | Asynchronous 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();
}
}
}