Description

This API provides both voice cloning and voice design capabilities, generating speech in a target voice from a small audio sample or a text instruction (Text-to-Speech).

Voice cloning: Clones a voice from a user-provided WAV audio sample, then synthesizes the specified text in the cloned voice.
Voice design: Requires no audio input. Describe the desired voice characteristics with instruct to create a new voice and synthesize speech directly.

params.parameter.task_type supports vocal_transformer, synth_once, and voice_design, covering four input modes.

Version

1.0

Media Requirements

The input medium for this API is audio. Voice cloning mode (vocal_transformer without instruct, or synth_once) requires an audio sample URL; WAV format is recommended. Voice design mode (vocal_transformer with instruct, or voice_design) does not require an audio sample. The request and SDK examples in this document use synth_once, which requires an audio sample.

API URL

    Production environment: https://openapi.meitu.com
    Task submission endpoint: https://openapi.meitu.com/api/v1/sdk/sync/push
    Task name (task): /v1/ai_audio_qwen_tts/491349
    Task type (task_type): formula

Method

POST

Content-Type: application/json

Authentication

Open Platform API Signing

Request Parameters

Required	Parameter	Type	Description
Required	params	string	Algorithm parameters (JSON string)
Required	init_images	object[]	List of media files
Required	task	string	Fixed value: `/v1/ai_audio_qwen_tts/491349`
Required	task_type	string	Fixed value: `formula`
Optional	sync_timeout	int	Defaults to 30; synchronous timeout

The init_images media file parameters are structured as follows:

Required	Parameter	Type	Description
Required	url	string	Audio URL; no audio sample is required in voice design mode
Required	profile	object	Attribute information

profile attribute information:

Required	Parameter	Type	Description
Required	media_profiles	object	Media attribute information
Required	version	string	Fixed value: `v1`

media_profiles media attribute information:

Required	Parameter	Type	Description
Optional	media_data_type	string	Defaults to `url`, indicating that the `url` field contains a media URL

The params inference parameters are provided as a JSON string with the following structure:

Required	Field	Type	Description
Optional	rsp_media_type	string	Defaults to `url`; `jpg` indicates base64
Required	parameter	object	Core algorithm parameter object

parameter algorithm parameter details:

Required	Field	Type	Description
Optional	app	string	Application identifier
Required	task_type	string	Algorithm synthesis mode: `vocal_transformer`, `synth_once`, or `voice_design`
Required	text	string	Target text to synthesize
Conditionally required	instruct	string	Voice description instruction; required for voice design mode and omitted for voice cloning mode
Optional	language	string	Synthesis language; supported only in `voice_design` mode, for example `Chinese`
Optional	uid	string	User identifier used to associate the synthesis request with a user

The modes and their input requirements are as follows:

Mode	parameter.task_type	instruct	Audio Sample
Voice cloning	`vocal_transformer`	Omitted	Required
Voice cloning	`synth_once`	Omitted	Required
Voice design	`vocal_transformer`	Required	Not required
Voice design	`voice_design`	Required	Not required

Request Example

The following example uses synth_once voice cloning mode:

{
  "task": "/v1/ai_audio_qwen_tts/491349",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3NzAxMDQwMA==/bcbc891b-e6ad-417a-408d-98b3b84d3bd2.wave",
      "profile": {
        "media_profiles": {
          "media_data_type": "url"
        },
        "version": "v1"
      }
    }
  ],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"app\":\"your-app\",\"task_type\":\"synth_once\",\"text\":\"要合成的完整句子。\",\"uid\":\"user-1\"}}",
  "sync_timeout": 30
}

Response Fields

Generated results are periodically deleted. Download and save them promptly.

Field	Type	Description
request_id	string	Request identifier
trace_id	string	Trace identifier
code	int	Business status code; `0` indicates that the request was accepted successfully
error_code	int	Error code; `0` on success
message	string	Business message
tips	any	Additional information
data	object	Task status and algorithm result

Fields in data:

Field	Type	Description
status	int	Status code: -1 task not found; 0 created; 1 running; 2 failed; 9 timed out—use the Query API; 10 succeeded
result	object	Algorithm result
progress	number	Task progress in the range 0–1; `1` indicates completion
predict_elapsed	int	Estimated processing time, in milliseconds
create_time	int64	Creation timestamp, in milliseconds
task_id	string	Task ID
custom_task_id	string	Client-defined task ID
trace_id	string	Trace identifier
client_info	string	Client information
init_images	object[]/null	Echo of the input media

Fields in result:

Field	Type	Description
id	string	Unique task identifier
parameters	object	Echo of the algorithm processing parameters, including the synthesized audio result
data	object	Detailed data returned by the algorithm
msg	string	Response message
msg_id	string	Message ID
mtlab_res	object	Underlying algorithm result

The synthesized audio URL is returned in parameters.out_src or result.data.parameter.out_src; the response does not contain urls or images fields.

Fields in result.data:

Field	Type	Description
duration	object	Timing statistics for each processing stage
error_code	number	Algorithm error code; `0` indicates success
error_msg	string	Algorithm error message
extra	object	Extended fields
media_info_list	array	Media information list; an empty array in this response
msg_id	string	Message ID
parameter	object	Echo of the parameters

Fields in duration:

Field	Type	Description
alg_process_time	number	Algorithm processing time, in milliseconds
created_timestamp	number	Task creation timestamp, in seconds
pull_timestamp	number	Resource retrieval timestamp, in seconds
repost_time	number	Retry time
upload_time	number	Upload time, in milliseconds
waiting_time	number	Queue waiting time, in milliseconds

Fields in parameters / parameter:

Field	Type	Description
code	number	Synthesis result code; `0` indicates success
msg	string	Synthesis result message
id	string	Unique identifier for this synthesis request
src	string	Full URL of the source audio used for cloning
clone_ori_path	string	Path of the source audio used for cloning
out_src	string	Output URL of the synthesized audio; it can be accessed or downloaded directly
text	string	Target text synthesized
duration	number	Duration of the synthesized audio, in seconds
name	string	User identifier corresponding to `uid` in the request
create_time	string	Synthesis task creation time in `yyyy-MM-dd HH:mm:ss` format
updated_time	string	Synthesis task update time in `yyyy-MM-dd HH:mm:ss` format
latency	string	Synthesis latency in seconds, for example `14.65`
ts_info	object	Timestamp information (reserved field)

Fields in mtlab_res:

Field	Type	Description
ErrorCode	number	Underlying error code
ErrorMsg	string	Underlying error message
error_code	number	Error code (compatibility field)
error_msg	string	Error message (compatibility field)
media_info_list	array/null	Media information list
msg_id	string	Message ID
parameter	object/null	Parameter information

Response Examples

Successful Response Example

{
  "request_id": "",
  "trace_id": "",
  "code": 0,
  "error_code": 0,
  "message": "success",
  "tips": null,
  "data": {
    "status": 10,
    "result": {
      "id": "t_mt1a3i5n7b04a2e6e0-f8bc-4051-a5aa-af5b4604497c",
      "parameters": {
        "clone_ori_path": "https://obs-open-platform.obs.cn-north-4.myhuaweicloud.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3NzAxMDQwMA%3D%3D/bcbc891b-e6ad-417a-408d-98b3b84d3bd2.wave?AccessKeyId=QLFrateOfrxEG2sqhJ0Y&Expires=1779539428&Signature=TAqSFs0%2BPZP5SW%2B8JZ6YlapXUwc%3D",
        "code": 0,
        "create_time": "2026-05-22 20:30:28",
        "duration": 1.76,
        "id": "5ce81565-bdbc-41df-8782-3e2bca88f661",
        "latency": "14.65",
        "msg": "success",
        "name": "user-1",
        "out_src": "https://mt-aiaudio-release.oss-cn-beijing.aliyuncs.com/temporary/zeroshot/5ce81565-bdbc-41df-8782-3e2bca88f661_0.wav",
        "src": "https://obs-open-platform.obs.cn-north-4.myhuaweicloud.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3NzAxMDQwMA%3D%3D/bcbc891b-e6ad-417a-408d-98b3b84d3bd2.wave?AccessKeyId=QLFrateOfrxEG2sqhJ0Y&Expires=1779539428&Signature=TAqSFs0%2BPZP5SW%2B8JZ6YlapXUwc%3D",
        "text": "要合成的完整句子。",
        "ts_info": {},
        "updated_time": "2026-05-22 20:30:43"
      },
      "data": {
        "duration": {
          "alg_process_time": 14856,
          "created_timestamp": 1779453028,
          "pull_timestamp": 1779453028,
          "repost_time": 0,
          "upload_time": 0,
          "waiting_time": 30
        },
        "error_code": 0,
        "error_msg": "success",
        "extra": {},
        "media_info_list": [],
        "msg_id": "dfa635ba-cad8-41b0-7709-r00924be2f00",
        "parameter": {
          "clone_ori_path": "https://obs-open-platform.obs.cn-north-4.myhuaweicloud.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3NzAxMDQwMA%3D%3D/bcbc891b-e6ad-417a-408d-98b3b84d3bd2.wave?AccessKeyId=QLFrateOfrxEG2sqhJ0Y&Expires=1779539428&Signature=TAqSFs0%2BPZP5SW%2B8JZ6YlapXUwc%3D",
          "code": 0,
          "create_time": "2026-05-22 20:30:28",
          "duration": 1.76,
          "id": "5ce81565-bdbc-41df-8782-3e2bca88f661",
          "latency": "14.65",
          "msg": "success",
          "name": "user-1",
          "out_src": "https://mt-aiaudio-release.oss-cn-beijing.aliyuncs.com/temporary/zeroshot/5ce81565-bdbc-41df-8782-3e2bca88f661_0.wav",
          "src": "https://obs-open-platform.obs.cn-north-4.myhuaweicloud.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3NzAxMDQwMA%3D%3D/bcbc891b-e6ad-417a-408d-98b3b84d3bd2.wave?AccessKeyId=QLFrateOfrxEG2sqhJ0Y&Expires=1779539428&Signature=TAqSFs0%2BPZP5SW%2B8JZ6YlapXUwc%3D",
          "text": "要合成的完整句子。",
          "ts_info": {},
          "updated_time": "2026-05-22 20:30:43"
        }
      },
      "msg": "success",
      "msg_id": "dfa635ba-cad8-41b0-7709-r00924be2f00",
      "mtlab_res": {
        "ErrorCode": 0,
        "ErrorMsg": "",
        "error_code": 0,
        "error_msg": "",
        "media_info_list": null,
        "msg_id": "dfa635ba-cad8-41b0-7709-r00924be2f00",
        "parameter": null
      }
    },
    "progress": 1,
    "predict_elapsed": 10000,
    "create_time": 1779453028327,
    "task_id": "t_mt1a3i5n7b04a2e6e0-f8bc-4051-a5aa-af5b4604497c",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

Query-Required Response Example

Use the Query API to retrieve the 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": {},
    "progress": 0,
    "predict_elapsed": 10000,
    "create_time": 1779453028327,
    "task_id": "t_mt1a3i5n7b04a2e6e0-f8bc-4051-a5aa-af5b4604497c",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

Failed Response Example

Response Status: 400

content-type: application/json; charset=utf-8

{
  "request_id": "",
  "trace_id": "",
  "code": 20001,
  "error_code": 20001,
  "message": "PROCESS_ERROR",
  "tips": null,
  "data": {
    "status": 2,
    "result": {
      "error_code": 20001,
      "error_msg": "PROCESS_ERROR"
    },
    "progress": 0,
    "predict_elapsed": 0,
    "create_time": 1779453028327,
    "task_id": "t_mt1a3i5n7b04a2e6e0-f8bc-4051-a5aa-af5b4604497c",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

API-specific error: 20001 (PROCESS_ERROR), indicating a processing error.

General Error Codes

See API Error Codes for details.

SDK Examples

All examples below use synth_once voice cloning mode and sign the actual request body.

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": {
            "app": "your-app",
            "task_type": "synth_once",
            "text": "要合成的完整句子。",
            "uid": "user-1",
        },
    }
    payload = {
        "task": "/v1/ai_audio_qwen_tts/491349",
        "task_type": "formula",
        "init_images": [
            {
                "url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3NzAxMDQwMA==/bcbc891b-e6ad-417a-408d-98b3b84d3bd2.wave",
                "profile": {
                    "media_profiles": {"media_data_type": "url"},
                    "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_qwen_tts/491349",
  "task_type": "formula",
  "init_images": [{
    "url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3NzAxMDQwMA==/bcbc891b-e6ad-417a-408d-98b3b84d3bd2.wave",
    "profile": {
      "media_profiles": {"media_data_type": "url"},
      "version": "v1"
    }
  }],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"app\":\"your-app\",\"task_type\":\"synth_once\",\"text\":\"要合成的完整句子。\",\"uid\":\"user-1\"}}",
  "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' => [
        'app' => 'your-app',
        'task_type' => 'synth_once',
        'text' => '要合成的完整句子。',
        'uid' => 'user-1',
    ],
]);

$body = json_encode([
    'task' => '/v1/ai_audio_qwen_tts/491349',
    'task_type' => 'formula',
    'init_images' => [
        [
            'url' => 'https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3NzAxMDQwMA==/bcbc891b-e6ad-417a-408d-98b3b84d3bd2.wave',
            'profile' => [
                'media_profiles' => ['media_data_type' => 'url'],
                '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_qwen_tts/491349\",\n" +
                "  \"task_type\": \"formula\",\n" +
                "  \"init_images\": [{\n" +
                "    \"url\": \"https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3NzAxMDQwMA==/bcbc891b-e6ad-417a-408d-98b3b84d3bd2.wave\",\n" +
                "    \"profile\": {\n" +
                "      \"media_profiles\": {\"media_data_type\": \"url\"},\n" +
                "      \"version\": \"v1\"\n" +
                "    }\n" +
                "  }],\n" +
                "  \"params\": \"{\\\"rsp_media_type\\\":\\\"url\\\",\\\"parameter\\\":{\\\"app\\\":\\\"your-app\\\",\\\"task_type\\\":\\\"synth_once\\\",\\\"text\\\":\\\"要合成的完整句子。\\\",\\\"uid\\\":\\\"user-1\\\"}}\",\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);
        }
    }
}

QWEN Voice Cloning