Image Filters
Description
Apply a selected filter to an image and adjust filter opacity, beauty opacity, and blur intensity. Select the filter using its material ID.
Version
1.0
Image Requirements
JPG and PNG are supported. Do not Base64-encode image URLs.
Request URL
Task submission endpoint:
https://openapi.meitu.com/api/v1/sdk/sync/pushTask name (task): /v1/Image_Filter/496525
Task type (task_type): formula
HTTP Method
POST
Content-Type: application/json
Authentication
Use an AK/SK pair with access to this capability and sign requests using the signing SDK. See API Request Signing.
Request Parameters
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | task | string | Fixed value: /v1/Image_Filter/496525. |
| Yes | task_type | string | formula. |
| Yes | init_images | object[] | Input images. |
| Yes | params | string | JSON-serialized algorithm parameter object. |
| No | sync_timeout | integer | Synchronous waiting period in seconds. Default: 30. |
init_images Element
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | url | string | Image URL or Base64 data, matching the media type. |
| Yes | profile | object | Image properties. |
profile
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | version | string | Gateway media configuration version. Fixed value: v1. |
| Yes | media_profiles | object | Image transfer properties. |
| No | media_extra | object | Additional image information. Omit when not needed. |
media_profiles
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | media_data_type | string | jpg: Base64 data, the original algorithm default; url: image URL. Explicitly set url for URL input. |
params
The decoded object contains:
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | parameter | object | Filter parameters. |
| No | extra | object | Additional processing information. Omit when not needed. |
parameter
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | filterType | string | Filter material ID from the table below, such as Fa0145JwLfwjjbch. |
| No | filterAlpha | integer | Filter opacity. Default: 70. The source does not specify a range. |
| No | beautyAlpha | integer | Beauty opacity. Default: 0. The source does not specify a range. |
| No | virtualType | integer | Blur intensity. Default: 0; range: 0–100. Higher values produce stronger blur. |
| No | version | string | Algorithm version. Default: 1.0. Distinct from profile.version. |
| No | rsp_media_type | string | The source request example uses url, while its parameter table lists base64, referring to URL and Base64 output respectively. Actual support remains subject to integration verification. |
The source labels filterType as an integer with default 0, but its request example and material table use string IDs. This document sends a string material ID. Explicitly select an ID below instead of relying on the undocumented meaning of the source's default.
The source parameter table, request example, and response example use base64, url, and jpg respectively without a consistent explanation. Requests here follow its url example, while the response example preserves its Base64 structure. They are not a tested request-response pair.
Filter Materials
| Material ID | Filter Name |
|---|---|
| Fa0145JwLfwjjbch | Colored Pencil |
| Fa0415o4g8OfwAw8 | Hana |
| Fa0436P7QKK0zKRL | Central Park |
| Fa0108HAz4MlDLVx | Yogurt |
| Fa0535samdIjz0Wq | Lan Kwai Fong |
| Fa0727hdRPZAndOR | Pink Lens |
Request Example
Replace the image URL. The example uses the Colored Pencil filter.
{
"task": "/v1/Image_Filter/496525",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"filterType\":\"Fa0145JwLfwjjbch\",\"filterAlpha\":70,\"beautyAlpha\":0,\"virtualType\":0,\"version\":\"1.0\",\"rsp_media_type\":\"url\"}}",
"sync_timeout": 30
}Decoded params object:
{
"parameter": {
"filterType": "Fa0145JwLfwjjbch",
"filterAlpha": 70,
"beautyAlpha": 0,
"virtualType": 0,
"version": "1.0",
"rsp_media_type": "url"
}
}Response Fields
The response follows the unified gateway format. The original algorithm result is under data.result.data. These structures have not been verified through a live API call.
| Field | Type | Description |
|---|---|---|
| code | integer | Gateway business status code. 0 does not mean the task is complete. |
| message | string | Response message. |
| data.status | integer | -1: not found; 0: created; 1: running; 2: failed; 9: synchronous wait timed out; 10: succeeded. |
| data.task_id | string | Gateway task ID for queries. Do not use the algorithm msg_id. |
| data.progress | number | Task progress. |
| data.result | object | Algorithm result envelope. |
| data.result.id | string | Task ID. |
| data.result.code | integer | Algorithm status code. |
| data.result.data | object | Original algorithm response. |
result.data
| Field | Type | Description |
|---|---|---|
| media_info_list | object[] | Processed images. |
| media_info_list[].media_data | string | Result image data; the source success example contains Base64 data. |
| media_info_list[].media_profiles.media_data_type | string | jpg in the source success example, indicating Base64 data. |
| parameter | object | Returned parameters. |
| parameter.rsp_media_type | string | Result media type; documented as jpg in the source field table but absent from its success example. |
Response Examples
These illustrative responses combine the unified gateway template with the original algorithm response. They are not live results. The request uses url, while the source response uses Base64; they do not represent the same call. Result data and task IDs are placeholders.
Success Example
{
"code": 0,
"message": "success",
"data": {
"status": 10,
"task_id": "example-task-id",
"result": {
"id": "example-task-id",
"code": 0,
"data": {
"media_info_list": [
{
"media_data": "BASE64_IMAGE_DATA",
"media_profiles": {
"media_data_type": "jpg"
}
}
],
"parameter": {}
}
},
"progress": 1
}
}Query Required Example
data.status = 9 means synchronous waiting timed out, not that the task failed. Use data.task_id with Task Query instead of resubmitting.
{
"code": 0,
"message": "success",
"data": {
"status": 9,
"task_id": "example-task-id",
"result": {
"id": "example-task-id"
},
"progress": 0
}
}Error Example
This example illustrates an HTTP 400 processing failure. It does not imply that every error uses this HTTP status and error code.
{
"code": 20001,
"error_code": 20001,
"message": "ALGO_MODEL_CRASH",
"data": {
"status": 2,
"task_id": "example-task-id",
"result": {
"id": "example-task-id",
"code": 20001,
"msg": "ALGO_MODEL_CRASH",
"data": {
"ErrorCode": 20001,
"ErrorMsg": "process error",
"Data": null
}
}
}
}Common Error Codes
The source lists 20001 / PROCESS_ERROR for a processing error. See API Error Codes for other errors.
SDK Examples
Each example embeds the complete request body and requires no separate JSON file. Set up the SDK for your language and replace the AK, SK, and image URL. Each example submits once and prints the response.
Python
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": {
"filterType": "Fa0145JwLfwjjbch",
"filterAlpha": 70,
"beautyAlpha": 0,
"virtualType": 0,
"version": "1.0",
"rsp_media_type": "url"
}
}
payload = {
"task": "/v1/Image_Filter/496525",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"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
package main
import (
"fmt"
"io"
"net/http"
"time"
"github.com/mtlab/api/signer"
)
func main() {
body := `{
"task": "/v1/Image_Filter/496525",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"filterType\":\"Fa0145JwLfwjjbch\",\"filterAlpha\":70,\"beautyAlpha\":0,\"virtualType\":0,\"version\":\"1.0\",\"rsp_media_type\":\"url\"}}",
"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
<?php
require_once __DIR__ . '/signer.php';
$innerParams = json_encode([
'parameter' => [
'filterType' => 'Fa0145JwLfwjjbch',
'filterAlpha' => 70,
'beautyAlpha' => 0,
'virtualType' => 0,
'version' => '1.0',
'rsp_media_type' => 'url'
]
], JSON_UNESCAPED_SLASHES);
$body = json_encode([
'task' => '/v1/Image_Filter/496525',
'task_type' => 'formula',
'init_images' => [
[
'url' => 'https://example.com/input.jpg',
'profile' => [
'media_profiles' => [
'media_data_type' => 'url'
],
'version' => 'v1'
]
]
],
'params' => $innerParams,
'sync_timeout' => 30
], 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
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/Image_Filter/496525\",\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" +
" },\n" +
" \"version\": \"v1\"\n" +
" }\n" +
" }\n" +
" ],\n" +
" \"params\": \"{\\\"parameter\\\":{\\\"filterType\\\":\\\"Fa0145JwLfwjjbch\\\",\\\"filterAlpha\\\":70,\\\"beautyAlpha\\\":0,\\\"virtualType\\\":0,\\\"version\\\":\\\"1.0\\\",\\\"rsp_media_type\\\":\\\"url\\\"}}\",\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();
}
}
}