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

RequiredParameterTypeDescription
Yesinit_imagesobject[]Input image list.
YesparamsstringJSON string that decodes directly to an object containing prompt and task_id.
-rsp_media_typestringOutput transmission type. This example uses url; put this field at the top level of the request.
YestaskstringFixed value: /v1/Encompassing_Image/495797.
Yestask_typestringFixed 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

RequiredParameterTypeDescription
YesurlstringInput image URL.
YesprofileobjectImage properties.

profile

RequiredParameterTypeDescription
Nomedia_extraobjectAdditional image information; {} in the example.
Yesmedia_profilesobjectImage transmission information.

media_profiles

RequiredParameterTypeDescription
Yesmedia_data_typestringurl 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.

RequiredParameterTypeDescription
YespromptstringImage-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

The response descriptions and examples below are carried over from the previous version. The actual response structure of /v1/Encompassing_Image/495797 has not yet been verified.

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 = {
        "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();
        }
    }
}