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/push

Task 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

RequiredParameterTypeDescription
YestaskstringFixed value: /v1/Image_Filter/496525.
Yestask_typestringformula.
Yesinit_imagesobject[]Input images.
YesparamsstringJSON-serialized algorithm parameter object.
Nosync_timeoutintegerSynchronous waiting period in seconds. Default: 30.

init_images Element

RequiredParameterTypeDescription
YesurlstringImage URL or Base64 data, matching the media type.
YesprofileobjectImage properties.

profile

RequiredParameterTypeDescription
YesversionstringGateway media configuration version. Fixed value: v1.
Yesmedia_profilesobjectImage transfer properties.
Nomedia_extraobjectAdditional image information. Omit when not needed.

media_profiles

RequiredParameterTypeDescription
Nomedia_data_typestringjpg: Base64 data, the original algorithm default; url: image URL. Explicitly set url for URL input.

params

The decoded object contains:

RequiredParameterTypeDescription
YesparameterobjectFilter parameters.
NoextraobjectAdditional processing information. Omit when not needed.

parameter

RequiredParameterTypeDescription
NofilterTypestringFilter material ID from the table below, such as Fa0145JwLfwjjbch.
NofilterAlphaintegerFilter opacity. Default: 70. The source does not specify a range.
NobeautyAlphaintegerBeauty opacity. Default: 0. The source does not specify a range.
NovirtualTypeintegerBlur intensity. Default: 0; range: 0–100. Higher values produce stronger blur.
NoversionstringAlgorithm version. Default: 1.0. Distinct from profile.version.
Norsp_media_typestringThe 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 IDFilter Name
Fa0145JwLfwjjbchColored Pencil
Fa0415o4g8OfwAw8Hana
Fa0436P7QKK0zKRLCentral Park
Fa0108HAz4MlDLVxYogurt
Fa0535samdIjz0WqLan Kwai Fong
Fa0727hdRPZAndORPink 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.

FieldTypeDescription
codeintegerGateway business status code. 0 does not mean the task is complete.
messagestringResponse message.
data.statusinteger-1: not found; 0: created; 1: running; 2: failed; 9: synchronous wait timed out; 10: succeeded.
data.task_idstringGateway task ID for queries. Do not use the algorithm msg_id.
data.progressnumberTask progress.
data.resultobjectAlgorithm result envelope.
data.result.idstringTask ID.
data.result.codeintegerAlgorithm status code.
data.result.dataobjectOriginal algorithm response.

result.data

FieldTypeDescription
media_info_listobject[]Processed images.
media_info_list[].media_datastringResult image data; the source success example contains Base64 data.
media_info_list[].media_profiles.media_data_typestringjpg in the source success example, indicating Base64 data.
parameterobjectReturned parameters.
parameter.rsp_media_typestringResult 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

Python Signing SDK

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

Go Signing SDK

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 Signing SDK

<?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

Java Signing SDK

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