Image Filters
Description
Applies a selected filter to an input image. Adjust the filter strength with filter_alpha. Provide both the source image and the filter package, identify the material with material_id, and use resource_url to reference the package in the input list.
Image Requirements
- Source image formats: JPG, JPEG, PNG, BMP, and HEIF.
- Source image file size: up to 30 MB.
- Inputs: one source image and one filter package.
- Provide the filter package by URL using a ZIP link from the material list below.
Request URL
- Endpoint:
https://openapi.meitu.com/api/v1/sdk/sync/push - Task name (
task):/v1/Pic_Filter/477479 - Task type (
task_type):formula
HTTP Method
POST
Content-Type: application/json
Authentication
Sign requests using your Access Key (AK) and Secret Key (SK). See API Request Signing.
Request Parameters
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | task | string | Fixed value: /v1/Pic_Filter/477479. |
| Yes | task_type | string | Fixed value: formula. |
| Yes | init_images | object[] | Input resources containing the source image and filter package. Identify each resource with ref_name. |
| Yes | params | string | A JSON-encoded string containing the algorithm parameters described below. |
| No | sync_timeout | int | Synchronous wait time in seconds. Default: 30. Set to -1 to return without waiting. If data.status = 9, use the Task Status API to retrieve the result. |
init_images Item
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | url | string | Source image URL, Base64-encoded source image, or filter package URL. Its role is identified by ref_name. |
| Yes | profile | object | Resource transmission information and reference name. |
profile
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | media_extra | object | Additional media parameters. |
| Yes | media_profiles | object | Resource transmission type and reference name. |
| No | version | string | The examples use v1. |
media_profiles
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | media_data_type | string | url: provide the source image or filter package by URL. jpg: provide the source image as Base64-encoded data. |
| Yes | ref_name | string | Use origin for the source image. The package reference name is configurable; the examples use resource. It must match parameter.resource_url. |
params
Construct the following parameter object, then encode it as a JSON string for the params field in the request body.
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | parameter | object | Image filter parameters. |
parameter
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | material_id | string | Filter material ID from the list below. It must correspond to the provided package. |
| Yes | resource_url | string | Package reference name, which must match the package input's ref_name. The examples use resource. This is not the ZIP URL. |
| No | filter_alpha | int | Filter strength in [0, 100]. If omitted, the default configured in the package is used. |
| No | random_idx | int | Index of a sub-material within the package, starting at 0. The upper limit depends on the package configuration. |
| No | rsp_media_type | string | Output transmission type: url for image URLs or jpg for Base64-encoded image data. Default: url. |
| No | rsp_long_side_max | int | Maximum output long-side length in pixels, limiting the larger of the image width and height. |
| No | rsp_jpg_quality | int | JPEG output quality factor. Default: 100. Adjust according to image quality and processing time requirements, for example to 99. |
Algorithm parameters such as resource_url, material_id, and filter_alpha belong to the parameter object inside the params string.
Place the actual package download URL in the corresponding init_images item's url field. For example, if that item's ref_name is resource, set parameter.resource_url to resource as well.
Request Example
This example uses the Cream filter with material ID ET007450, sets the filter strength to 100, and returns the result as a URL. Replace https://example.com/input.jpg with an accessible source image URL.
{
"task": "/v1/Pic_Filter/477479",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url",
"ref_name": "origin"
},
"version": "v1"
}
},
{
"url": "https://my-material.zone1.meitudata.com/b3c0fd6d58e6a03.zip",
"profile": {
"media_profiles": {
"media_data_type": "url",
"ref_name": "resource"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"rsp_media_type\":\"url\",\"material_id\":\"ET007450\",\"resource_url\":\"resource\",\"filter_alpha\":100}}",
"sync_timeout": 30
}To change filters, update both parameter.material_id and the package input's url using values from the same material-list row. If you change the package's ref_name, also update parameter.resource_url.
Response Fields
The following descriptions and examples use URL output. After the task succeeds, retrieve the output image from data.result.urls.
| Field | Type | Description |
|---|---|---|
| error_code | int | Error code. 0 indicates normal request processing; a nonzero value indicates failure. Also check data.status to determine whether the task has completed. |
| message | string | Response message or error information. |
| data | object/null | Task information. May be null if the request fails. |
data
| Field | Type | Description |
|---|---|---|
| status | int | Task status: -1 not found; 0 created; 1 processing; 2 failed; 9 result query required; 10 succeeded. |
| result | object | Task ID and processing result. |
| progress | number | Task progress, for example 0.1, 0.85, or 1. |
result
| Field | Type | Description |
|---|---|---|
| id | string | Task ID. Pass this value as task_id when querying the result. |
| urls | string[] | Result image URLs available after the task succeeds. |
When data.status = 9, use data.result.id to call the Task Status API. Send a signed GET request to https://openapi.meitu.com/api/v1/sdk/status?task_id=<TASK_ID>.
Query status 0 or 1 means the task is not yet complete; 10 means success; 2 means failure. Query and save results promptly. Tasks expire after 24 hours, and historical task queries are not supported.
Response Examples
Successful Response
{
"error_code": 0,
"message": "success",
"data": {
"status": 10,
"result": {
"id": "t_mt1a3i5n7bdb4183fe-8f91-4b1c-ae95-402b6f48613b",
"urls": [
"https://example.com/result.png"
]
},
"progress": 1
}
}Query-Required Response
Pass the returned data.result.id as the task_id parameter to the Task Status API.
{
"error_code": 0,
"message": "success",
"data": {
"status": 9,
"result": {
"id": "t_mt1a3i5n7bdb4183fe-8f91-4b1c-ae95-402b6f48613b"
},
"progress": 0
}
}Failed Response
{
"error_code": 20001,
"message": "PROCESS_ERROR",
"data": null
}Error Codes
| Error Code | Error Message | Description |
|---|---|---|
| 20001 | PROCESS_ERROR | Processing error. |
For other errors, see API Error Codes.
SDK Examples
The following examples use the Cream filter with material_id = ET007450 and filter_alpha = 100. Replace the AK, SK, and input image URL before running the code.
The examples print the API response. If data.status = 9, query the task result as described above. To use another filter, update both the material ID and its package URL.
Python
Set up the SDK as described in the Python Signing SDK documentation.
import json
import requests
from sign_sdk import sign
def api_call_example():
key = "your_access_key"
secret = "your_secret_key"
url = "https://openapi.meitu.com/api/v1/sdk/sync/push"
headers = {
"Content-Type": "application/json",
sign.HeaderHost: "openapi.meitu.com",
}
inner_params = {
"parameter": {
"rsp_media_type": "url",
"material_id": "ET007450",
"resource_url": "resource",
"filter_alpha": 100
}
}
payload = {
"task": "/v1/Pic_Filter/477479",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url",
"ref_name": "origin"
},
"version": "v1"
}
},
{
"url": "https://my-material.zone1.meitudata.com/b3c0fd6d58e6a03.zip",
"profile": {
"media_profiles": {
"media_data_type": "url",
"ref_name": "resource"
},
"version": "v1"
}
}
],
"params": json.dumps(inner_params, ensure_ascii=False),
"sync_timeout": 30
}
body = json.dumps(payload, ensure_ascii=False)
signer = sign.Signer(key, secret)
signed_request = signer.sign(url, "POST", headers, body)
with requests.Session() as session:
response = session.send(signed_request, timeout=60)
print("Status:", response.status_code)
print("Response:", response.text)
if __name__ == "__main__":
api_call_example()Go
Set up the SDK as described in the Go Signing SDK documentation.
package main
import (
"fmt"
"io"
"net/http"
"time"
"github.com/mtlab/api/signer"
)
func main() {
key := "your_access_key"
secret := "your_secret_key"
signObj := signer.NewSigner(key, secret)
url := "https://openapi.meitu.com/api/v1/sdk/sync/push"
headers := make(http.Header)
headers.Set(signer.HeaderHost, "openapi.meitu.com")
headers.Set("Content-Type", "application/json")
body := `{
"task": "/v1/Pic_Filter/477479",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url",
"ref_name": "origin"
},
"version": "v1"
}
},
{
"url": "https://my-material.zone1.meitudata.com/b3c0fd6d58e6a03.zip",
"profile": {
"media_profiles": {
"media_data_type": "url",
"ref_name": "resource"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"rsp_media_type\":\"url\",\"material_id\":\"ET007450\",\"resource_url\":\"resource\",\"filter_alpha\":100}}",
"sync_timeout": 30
}`
req, err := signObj.Sign(url, http.MethodPost, headers, body)
if err != nil {
fmt.Println("Failed to sign request:", err)
return
}
client := &http.Client{Timeout: 60 * time.Second}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Failed to send request:", err)
return
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
fmt.Println("Failed to read response:", err)
return
}
fmt.Println("Status:", resp.StatusCode)
fmt.Println("Response:", string(responseBody))
}PHP
Set up the SDK as described in the PHP Signing SDK documentation.
<?php
require_once __DIR__ . '/signer.php';
$key = 'your_access_key';
$secret = 'your_secret_key';
$url = 'https://openapi.meitu.com/api/v1/sdk/sync/push';
$headers = [
'Content-Type' => 'application/json',
'Host' => 'openapi.meitu.com',
];
$innerParams = json_encode([
'parameter' => [
'rsp_media_type' => 'url',
'material_id' => 'ET007450',
'resource_url' => 'resource',
'filter_alpha' => 100,
],
], JSON_UNESCAPED_SLASHES);
$body = json_encode([
'task' => '/v1/Pic_Filter/477479',
'task_type' => 'formula',
'init_images' => [
[
'url' => 'https://example.com/input.jpg',
'profile' => [
'media_profiles' => [
'media_data_type' => 'url',
'ref_name' => 'origin',
],
'version' => 'v1',
],
],
[
'url' => 'https://my-material.zone1.meitudata.com/b3c0fd6d58e6a03.zip',
'profile' => [
'media_profiles' => [
'media_data_type' => 'url',
'ref_name' => 'resource',
],
'version' => 'v1',
],
],
],
'params' => $innerParams,
'sync_timeout' => 30,
], JSON_UNESCAPED_SLASHES);
$signer = new Signer($key, $secret);
$curl = $signer->sign($url, 'POST', $headers, $body);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_TIMEOUT, 60);
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
Set up the SDK as described in the Java Signing SDK documentation.
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 {
Signer signer = new Signer("your_access_key", "your_secret_key");
String url = "https://openapi.meitu.com/api/v1/sdk/sync/push";
String method = "POST";
Map<String, String> headers = new HashMap<>();
headers.put("Content-Type", "application/json");
headers.put(Signer.HeaderHost, "openapi.meitu.com");
String body = "{\n"
+ " \"task\": \"/v1/Pic_Filter/477479\",\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"
+ " \"ref_name\": \"origin\"\n"
+ " },\n"
+ " \"version\": \"v1\"\n"
+ " }\n"
+ " },\n"
+ " {\n"
+ " \"url\": \"https://my-material.zone1.meitudata.com/b3c0fd6d58e6a03.zip\",\n"
+ " \"profile\": {\n"
+ " \"media_profiles\": {\n"
+ " \"media_data_type\": \"url\",\n"
+ " \"ref_name\": \"resource\"\n"
+ " },\n"
+ " \"version\": \"v1\"\n"
+ " }\n"
+ " }\n"
+ " ],\n"
+ " \"params\": \"{\\\"parameter\\\":{\\\"rsp_media_type\\\":\\\"url\\\",\\\"material_id\\\":\\\"ET007450\\\",\\\"resource_url\\\":\\\"resource\\\",\\\"filter_alpha\\\":100}}\",\n"
+ " \"sync_timeout\": 30\n"
+ "}";
Map<String, String> signedHeaders = signer.sign(url, method, headers, body);
HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
try {
connection.setRequestMethod(method);
connection.setConnectTimeout(10000);
connection.setReadTimeout(60000);
connection.setInstanceFollowRedirects(false);
for (Map.Entry<String, String> entry : signedHeaders.entrySet()) {
connection.setRequestProperty(entry.getKey(), entry.getValue());
}
connection.setDoOutput(true);
try (OutputStream output = connection.getOutputStream()) {
output.write(body.getBytes(StandardCharsets.UTF_8));
}
int status = connection.getResponseCode();
System.out.println("Status: " + status);
InputStream stream = status >= 400
? connection.getErrorStream()
: connection.getInputStream();
if (stream != null) {
try (InputStream input = stream;
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: "
+ new String(output.toByteArray(), StandardCharsets.UTF_8));
}
}
} finally {
connection.disconnect();
}
}
}Filter Material List
Set parameter.material_id to the listed ID, and place the package URL in the package resource's url field within init_images. Preview images illustrate the effect; they are not filter package URLs.
| Name | material_id | Material Package URL |
|---|---|---|
| Cream | ET007450 | Download ZIP |
| Classic D | ET0061997 | Download ZIP |
| CS5 | ET0062088 | Download ZIP |
| Feiyan | ET0062014 | Download ZIP |
| Peel-Apart Film | ET1111130 | Download ZIP |
| Family Dinner | ET1111125 | Download ZIP |
| Otaru | ET005043 | Download ZIP |
| Wedding Banquet | ET0062161 | Download ZIP |
| Cat | ET0061984 | Download ZIP |
| Loulan | ET0061971 | Download ZIP |
For additional filter materials, contact customer service through the Meitu AI Open Platform.