HomeDocsConsolePricing

Vocal Separation

Description

This API submits a video vocal-separation task. According to the source document, the algorithm runs asynchronously after a successful submission. You can retrieve the result through the task query API or receive it through the callback URL supplied with the request.

Version

1.0

Media Requirements

The source document lists JPG and PNG as supported image formats. However, its request example uses a MOV video URL and sets media_data_type to MP4. The source document does not specify file-size, resolution, or video-duration limits.

API URL

    Production host: https://openapi.meitu.com
    Task submission endpoint: https://openapi.meitu.com/api/v1/sdk/sync/push
    Task name (task): /v1/ai_audio_spliter/481965
    Task type (task_type): formula

Method

POST

Content-Type: application/json

Authentication

Open Platform API Signature

Request Parameters

RequiredParameterTypeDescription
YesparamsstringAlgorithm parameters as a JSON string
Yesinit_imagesobject[]Input media list
YestaskstringFixed value: /v1/ai_audio_spliter/481965
Yestask_typestringFixed value: formula
Nosync_timeoutintSynchronous timeout in seconds; default: 30

The legacy request table in the source document also lists an optional task_id. It is described as a unique custom task ID that can be used to query task status. The unified gateway does not allow this field at the top level, so it is not included in the request example below.

init_images item fields:

RequiredParameterTypeDescription
YesurlstringMedia URL; the source example uses a MOV video URL
YesprofileobjectMedia profile

profile fields:

RequiredParameterTypeDescription
Yesmedia_profilesobjectMedia attributes
YesversionstringFixed value: v1

media_profiles fields:

RequiredParameterTypeDescription
Yesmedia_data_typestringThe source example uses MP4 for a media URL

params is a JSON string. After decoding, it has the following structure:

RequiredFieldTypeDescription
Norsp_media_typestringDefault: url; jpg means base64 output
YesparameterobjectAlgorithm-specific parameters

parameter fields:

RequiredFieldTypeDescription
Yestask_typestringFixed value: spliter

Request Example

{
  "task": "/v1/ai_audio_spliter/481965",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://tos-vesdk-wink-sh.meitudata.com/mtlab_video/68daacf4a6bb1r0zqrmdip600.mov",
      "profile": {
        "media_profiles": {
          "media_data_type": "MP4"
        },
        "version": "v1"
      }
    }
  ],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"task_type\":\"spliter\"}}",
  "sync_timeout": 30
}

Response Fields

Generated results are cleaned up periodically. Download and save them promptly.
FieldTypeDescription
request_idstringRequest identifier
trace_idstringTrace identifier
codeintBusiness status code; 0 means the request was accepted
error_codeintError code; 0 on success
messagestringBusiness message
tipsanyAdditional information; may be null
dataobjectTask status and algorithm result

data fields:

FieldTypeDescription
statusint-1: task not found; 0: created; 1: running; 2: failed; 9: timed out and requires the query API; 10: succeeded
resultobjectAlgorithm result
progressnumberTask progress
predict_elapsedintEstimated processing time in milliseconds
create_timeint64Creation timestamp in milliseconds
task_idstringTask ID
custom_task_idstringClient-supplied custom task ID
trace_idstringTrace identifier inside data
client_infostringClient information
init_imagesobject[]/nullEcho of input media

result fields:

FieldTypeDescription
idint/stringTask ID; the source table declares an int, while the response example uses a string
urlsstring[]Result URL list in the success response
parametersobjectTask result information in the source field table
dataint/objectThe source table declares an int, while the failure response uses an error-detail object
msglong/stringThe source table declares a long, while the failure response uses an error-message string
msg_idstringDescribed as a system-generated task ID in the source table and used as a message ID in the failure response

parameters fields:

FieldTypeDescription
codeint0 indicates a normal result; any other value indicates an error
idstringUnique string identifying each request, also called job_id
namestringUser-supplied request parameter
created_timestringTime when task execution was created
updated_timestringTime when task execution finished
msgstringTask execution message
latencyfloatAPI latency
split_listlistSeparated file URLs; names beginning with vocals_ contain vocals, while names beginning with no_vocals_ contain accompaniment
loudnorm_resultdictMaps loudness values to audio URLs; returned when a unified loudness value is supplied

Fields of result.data in the failure example:

FieldTypeDescription
durationobjectStage durations and timestamps
error_codeintAlgorithm error code
error_msgstringAlgorithm error message
extraobjectAdditional data
media_info_listobject[]Media information list
msg_idstringMessage ID
parameterobject/nullEcho of algorithm parameters

API-specific errors:

ErrorCodeErrorDescription
20001PROCESS_ERRORProcessing error
21101Invalid parameter
26101Failed to obtain the model
25402Model feature extraction failed, for example because no timbre could be extracted from the input audio or the content was invalid
20602Model inference failed, possibly because of invalid input characters or another processing error
22201Failed to generate the result, including failures when uploading to OBS
20301Unknown exception

Response Examples

Success

{
  "request_id": "",
  "trace_id": "",
  "code": 0,
  "error_code": 0,
  "message": "",
  "tips": null,
  "data": {
    "status": 10,
    "result": {
      "id": "50309bd5-a827-4125-bc96-62039c93770b",
      "urls": [
        "https://obs.mtlab.meitu.com/mtopen/rF5GIhp5ReLKgLV91CKj5BO1q2FTLMmc/MTY5Mjg1MzIwMA==/1c39ef92-04f1-40b4-5b7e-8fcfca0c11ea.png"
      ]
    },
    "progress": 1,
    "predict_elapsed": 0,
    "create_time": 0,
    "task_id": "",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

Query Required

Use the query API to retrieve the task result.

Response Status: 200

Content-Type: application/json; charset=utf-8

{
  "request_id": "",
  "trace_id": "",
  "code": 0,
  "error_code": 0,
  "message": "success",
  "tips": null,
  "data": {
    "status": 9,
    "result": {
      "id": "t_mt1a3i5n7b3da6d589-46b5-4f66-a0bb-8dd22f2a172e"
    },
    "progress": 0,
    "predict_elapsed": 10000,
    "create_time": 1759202368761,
    "task_id": "t_mt1a3i5n7b3da6d589-46b5-4f66-a0bb-8dd22f2a172e",
    "custom_task_id": "",
    "trace_id": "9129a3a2-99c4-46ce-8731-0e100e2fbee7",
    "client_info": "",
    "init_images": null
  }
}

Failure

Response Status: 400

Content-Type: application/json; charset=utf-8

{
  "request_id": "",
  "trace_id": "",
  "code": 20001,
  "error_code": 20001,
  "message": "ALGO_MODEL_CRASH",
  "tips": null,
  "data": {
    "status": 2,
    "result": {
      "id": "t_mt1a3i5n7be8d575cc-2ffb-4e0c-85a8-1824110e31b8",
      "code": 20001,
      "data": {
        "duration": {
          "alg_process_time": 0,
          "created_timestamp": 1759201989,
          "pull_timestamp": 1759201989,
          "repost_time": 0,
          "upload_time": 0,
          "waiting_time": 0
        },
        "error_code": 20001,
        "error_msg": "ALGO_MODEL_CRASH",
        "extra": {},
        "media_info_list": [],
        "msg_id": "c1b09cb2-6e05-4d21-55ab-r007b1f21bec",
        "parameter": null
      },
      "msg": "ALGO_MODEL_CRASH",
      "msg_id": "c1b09cb2-6e05-4d21-55ab-r007b1f21bec"
    },
    "progress": 1,
    "predict_elapsed": 10000,
    "create_time": 1759201989444,
    "task_id": "t_mt1a3i5n7be8d575cc-2ffb-4e0c-85a8-1824110e31b8",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

General Error Codes

See API Error Codes.

SDK Examples

Python

import json

import requests
from sign_sdk import sign

def api_call_example():
    key = "your_api_key"
    secret = "your_api_secret"
    url = "https://openapi.meitu.com/api/v1/sdk/sync/push"
    method = "POST"

    headers = {
        "Content-Type": "application/json",
        sign.HeaderHost: "openapi.meitu.com",
    }
    inner_params = {
        "rsp_media_type": "url",
        "parameter": {"task_type": "spliter"},
    }
    payload = {
        "task": "/v1/ai_audio_spliter/481965",
        "task_type": "formula",
        "init_images": [
            {
                "url": "https://tos-vesdk-wink-sh.meitudata.com/mtlab_video/68daacf4a6bb1r0zqrmdip600.mov",
                "profile": {
                    "media_profiles": {"media_data_type": "MP4"},
                    "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, method, headers, body)
    response = requests.Session().send(signed_request)
    print(f"Status: {response.status_code}")
    print(f"Response: {response.text}")

if __name__ == "__main__":
    api_call_example()

Go

package main

import (
	"fmt"
	"io"
	"net/http"

	"github.com/mtlab/api/signer"
)

func main() {
	key := "your_api_key"
	secret := "your_api_secret"
	signObj := signer.NewSigner(key, secret)

	url := "https://openapi.meitu.com/api/v1/sdk/sync/push"
	method := http.MethodPost
	headers := make(http.Header)
	headers.Set(signer.HeaderHost, "openapi.meitu.com")
	headers.Set("Content-Type", "application/json")

	body := `{
  "task": "/v1/ai_audio_spliter/481965",
  "task_type": "formula",
  "init_images": [{
    "url": "https://tos-vesdk-wink-sh.meitudata.com/mtlab_video/68daacf4a6bb1r0zqrmdip600.mov",
    "profile": {
      "media_profiles": {"media_data_type": "MP4"},
      "version": "v1"
    }
  }],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"task_type\":\"spliter\"}}",
  "sync_timeout": 30
}`

	req, err := signObj.Sign(url, method, headers, body)
	if err != nil {
		fmt.Println("Failed to sign request:", err)
		return
	}

	resp, err := http.DefaultClient.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("Read response failed:", err)
		return
	}
	fmt.Println("Response:", resp.StatusCode, string(responseBody))
}

PHP

<?php
require 'signer.php';

$key = 'your_api_key';
$secret = 'your_api_secret';
$signer = new Signer($key, $secret);

$url = 'https://openapi.meitu.com/api/v1/sdk/sync/push';
$method = 'POST';
$headers = ['Content-Type' => 'application/json'];

$innerParams = json_encode([
    'rsp_media_type' => 'url',
    'parameter' => ['task_type' => 'spliter'],
]);

$body = json_encode([
    'task' => '/v1/ai_audio_spliter/481965',
    'task_type' => 'formula',
    'init_images' => [
        [
            'url' => 'https://tos-vesdk-wink-sh.meitudata.com/mtlab_video/68daacf4a6bb1r0zqrmdip600.mov',
            'profile' => [
                'media_profiles' => ['media_data_type' => 'MP4'],
                'version' => 'v1',
            ],
        ],
    ],
    'params' => $innerParams,
    'sync_timeout' => 30,
]);

$curl = $signer->sign($url, $method, $headers, $body);
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ($status === 0) {
    echo 'Error: ' . curl_error($curl);
} else {
    echo "Status: {$status}\n";
    echo "Response: {$response}\n";
}
curl_close($curl);
?>

Java

package com.meitu.openai.common;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
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_api_key", "your_api_secret");
        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/ai_audio_spliter/481965\",\n" +
                "  \"task_type\": \"formula\",\n" +
                "  \"init_images\": [{\n" +
                "    \"url\": \"https://tos-vesdk-wink-sh.meitudata.com/mtlab_video/68daacf4a6bb1r0zqrmdip600.mov\",\n" +
                "    \"profile\": {\n" +
                "      \"media_profiles\": {\"media_data_type\": \"MP4\"},\n" +
                "      \"version\": \"v1\"\n" +
                "    }\n" +
                "  }],\n" +
                "  \"params\": \"{\\\"rsp_media_type\\\":\\\"url\\\",\\\"parameter\\\":{\\\"task_type\\\":\\\"spliter\\\"}}\",\n" +
                "  \"sync_timeout\": 30\n" +
                "}";

        Map<String, String> signedHeaders = signer.sign(url, method, headers, body);
        HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
        connection.setRequestMethod(method);
        for (Map.Entry<String, String> entry : signedHeaders.entrySet()) {
            connection.setRequestProperty(entry.getKey(), entry.getValue());
        }
        connection.setDoOutput(true);
        connection.getOutputStream().write(body.getBytes(StandardCharsets.UTF_8));

        int status = connection.getResponseCode();
        InputStream stream = status >= 400
                ? connection.getErrorStream()
                : connection.getInputStream();
        try (BufferedReader reader = new BufferedReader(new InputStreamReader(stream))) {
            StringBuilder response = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) {
                response.append(line);
            }
            System.out.println("Response: " + status + " " + response);
        }
    }
}