Omni Image Set
Description
Generates an image set from an input product image, a text prompt, and a template identifier. Describe the image-set requirements in prompt and select a template with params.task_id.
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/495797`
- 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.
Credits cannot be used to pay for API calls. Please visit the MV console to activate this API and purchase or manage resource packages.
Request Parameters
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | init_images | object[] | Input image list. |
| Yes | params | string | JSON string that decodes directly to an object containing prompt and task_id. |
| - | rsp_media_type | string | Output transmission type. This example uses url; put this field at the top level of the request. |
| Yes | task | string | Fixed value: /v1/Encompassing_Image/495797. |
| Yes | task_type | string | Fixed value: formula. |
- means the supplied specification does not state whether the field is required; it does not mean the field can be omitted.
init_images Item
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | url | string | Input image URL. |
| Yes | profile | object | Image properties. |
profile
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | media_extra | object | Additional image information; {} in the example. |
| Yes | media_profiles | object | Image transmission information. |
media_profiles
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | media_data_type | string | url in this example, indicating an image supplied by URL. |
params
Construct an object with the fields below, then serialize the entire object as a string. There is no parameter wrapper, and prompt itself is a string.
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | prompt | string | Image-set generation instructions, such as “Generate a set of 4 Amazon product images.” Generate up to 7 images at a time. |
params.task_id is a numeric template identifier, not the gateway task ID returned for querying task results.
Request Example
The example uses the product image-set template (task_id: -1) and a prompt requesting 4 Amazon product images. Replace the image URL and prompt as needed.
{
"init_images": [
{
"profile": {
"media_extra": {},
"media_profiles": {
"media_data_type": "url"
}
},
"url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc4NTM5MTIwMA==/78af5a5d-a5c8-4c9a-53ce-bd9d2e883a56.jpeg"
}
],
"params": "{\"prompt\":\"Generate a set of 4 Amazon product images.\"}",
"rsp_media_type": "url",
"task": "/v1/Encompassing_Image/495797",
"task_type": "formula"
}Response Fields
Generated results are cleaned up periodically. Download and save them promptly.The response descriptions and examples below are carried over from the previous version. The actual response structure of
/v1/Encompassing_Image/495797has not yet been verified.
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 = {
"prompt": "Generate a set of 4 Amazon product images."
}
payload = {
"init_images": [
{
"profile": {
"media_extra": {},
"media_profiles": {
"media_data_type": "url"
}
},
"url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc4NTM5MTIwMA==/78af5a5d-a5c8-4c9a-53ce-bd9d2e883a56.jpeg"
}
],
"params": json.dumps(inner_params, ensure_ascii=True),
"rsp_media_type": "url",
"task": "/v1/Encompassing_Image/495797",
"task_type": "formula"
}
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 := `{
"init_images": [
{
"profile": {
"media_extra": {},
"media_profiles": {
"media_data_type": "url"
}
},
"url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc4NTM5MTIwMA==/78af5a5d-a5c8-4c9a-53ce-bd9d2e883a56.jpeg"
}
],
"params": "{\"prompt\":\"Generate a set of 4 Amazon product images.\"}",
"rsp_media_type": "url",
"task": "/v1/Encompassing_Image/495797",
"task_type": "formula"
}`
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([
'prompt' => 'Generate a set of 4 Amazon product images.'
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$body = json_encode([
'init_images' => [
[
'profile' => [
'media_extra' => (object) [],
'media_profiles' => [
'media_data_type' => 'url'
]
],
'url' => 'https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc4NTM5MTIwMA==/78af5a5d-a5c8-4c9a-53ce-bd9d2e883a56.jpeg'
]
],
'params' => $innerParams,
'rsp_media_type' => 'url',
'task' => '/v1/Encompassing_Image/495797',
'task_type' => 'formula'
], 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" +
" \"init_images\": [\n" +
" {\n" +
" \"profile\": {\n" +
" \"media_extra\": {},\n" +
" \"media_profiles\": {\n" +
" \"media_data_type\": \"url\"\n" +
" }\n" +
" },\n" +
" \"url\": \"https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc4NTM5MTIwMA==/78af5a5d-a5c8-4c9a-53ce-bd9d2e883a56.jpeg\"\n" +
" }\n" +
" ],\n" +
" \"params\": \"{\\\"prompt\\\":\\\"Generate a set of 4 Amazon product images.\\\"}\",\n" +
" \"rsp_media_type\": \"url\",\n" +
" \"task\": \"/v1/Encompassing_Image/495797\",\n" +
" \"task_type\": \"formula\"\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();
}
}
}