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

RequiredParameterTypeDescription
YestaskstringFixed value: /v1/Pic_Filter/477479.
Yestask_typestringFixed value: formula.
Yesinit_imagesobject[]Input resources containing the source image and filter package. Identify each resource with ref_name.
YesparamsstringA JSON-encoded string containing the algorithm parameters described below.
Nosync_timeoutintSynchronous 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

RequiredParameterTypeDescription
YesurlstringSource image URL, Base64-encoded source image, or filter package URL. Its role is identified by ref_name.
YesprofileobjectResource transmission information and reference name.

profile

RequiredParameterTypeDescription
Nomedia_extraobjectAdditional media parameters.
Yesmedia_profilesobjectResource transmission type and reference name.
NoversionstringThe examples use v1.

media_profiles

RequiredParameterTypeDescription
Yesmedia_data_typestringurl: provide the source image or filter package by URL. jpg: provide the source image as Base64-encoded data.
Yesref_namestringUse 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.

RequiredParameterTypeDescription
YesparameterobjectImage filter parameters.

parameter

RequiredParameterTypeDescription
Yesmaterial_idstringFilter material ID from the list below. It must correspond to the provided package.
Yesresource_urlstringPackage reference name, which must match the package input's ref_name. The examples use resource. This is not the ZIP URL.
Nofilter_alphaintFilter strength in [0, 100]. If omitted, the default configured in the package is used.
Norandom_idxintIndex of a sub-material within the package, starting at 0. The upper limit depends on the package configuration.
Norsp_media_typestringOutput transmission type: url for image URLs or jpg for Base64-encoded image data. Default: url.
Norsp_long_side_maxintMaximum output long-side length in pixels, limiting the larger of the image width and height.
Norsp_jpg_qualityintJPEG 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.

FieldTypeDescription
error_codeintError code. 0 indicates normal request processing; a nonzero value indicates failure. Also check data.status to determine whether the task has completed.
messagestringResponse message or error information.
dataobject/nullTask information. May be null if the request fails.

data

FieldTypeDescription
statusintTask status: -1 not found; 0 created; 1 processing; 2 failed; 9 result query required; 10 succeeded.
resultobjectTask ID and processing result.
progressnumberTask progress, for example 0.1, 0.85, or 1.

result

FieldTypeDescription
idstringTask ID. Pass this value as task_id when querying the result.
urlsstring[]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 CodeError MessageDescription
20001PROCESS_ERRORProcessing 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.

Namematerial_idMaterial Package URL
CreamET007450Download ZIP
Classic DET0061997Download ZIP
CS5ET0062088Download ZIP
FeiyanET0062014Download ZIP
Peel-Apart FilmET1111130Download ZIP
Family DinnerET1111125Download ZIP
OtaruET005043Download ZIP
Wedding BanquetET0062161Download ZIP
CatET0061984Download ZIP
LoulanET0061971Download ZIP

For additional filter materials, contact customer service through the Meitu AI Open Platform.