HomeDocsConsolePricing

Meidede - Video Slicing

Description

This API slices videos in either GOP (Group of Pictures) mode or frame-index mode and returns the processed video segment.

Version

1.0

Media Requirements

The input media must be provided as a video URL. The original API specification does not state any restrictions on video format, dimensions, file size, or duration.

API URL

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

Method

POST

Content-Type: application/json

Authentication

Open Platform API Signature

Credits cannot be used to pay for API calls. Please visit the MV console to activate this API and purchase or manage resource packages.

Request Parameters

RequiredParameterTypeDescription
YesparamsstringAlgorithm parameters (JSON string)
Yesinit_imagesobject[]Input video list
YestaskstringFixed value: /v1/pvg_video_tc/491344
Yestask_typestringFixed value: formula
Nosync_timeoutintDefaults to 30, in seconds. Frame-index slicing supports asynchronous processing only; set this value to -1 for that mode.

The structure of each multimedia file in init_images is described below.

RequiredParameterTypeDescription
YesurlstringVideo URL or base64-encoded video data
YesprofileobjectMedia attributes

The structure of profile is described below.

RequiredParameterTypeDescription
Yesmedia_profilesobjectMedia properties
YesversionstringFixed value: v1

The structure of media_profiles is described below.

RequiredParameterTypeDescription
Yesmedia_data_typestringurl indicates a URL; use the corresponding video type for base64-encoded data.

The params inference parameter is a JSON string with the following structure.

RequiredFieldTypeDescription
Norsp_media_typestringDefaults to url; the original specification does not state any other supported values.
YesparameterobjectCore video-slicing algorithm parameters

Details of the algorithm parameters in parameter are provided below.

GOP-based slicing:

RequiredFieldTypeDescription
Norepost_urlstringPOST callback URL provided by the client
Yestc_modestringFixed value: gop_slice
Yesstart_gop_numintStarting GOP number
Yesend_gop_numintEnding GOP number
Nooutput_sfs_pathstringIf specified, saves the output audio to the designated shared-disk directory; otherwise, uploads it to the default or specified bucket.
Nooutput_sfs_keystringFile key used when saving to SFS; if omitted, the file is uploaded to the default or specified bucket.

Frame-index slicing and transcoding (asynchronous API only):

RequiredFieldTypeDescription
Yesrepost_urlstringPOST callback URL provided by the client
Yesstart_frame_numintStarting frame index, beginning at 1; valid range: [1, max(video frames)]
Yesend_frame_numintEnding frame index, beginning at 1; valid range: [1, max(video frames)]
Yesencode_fpsintFrame rate; defaults to 30. Passing the source video's original frame rate is recommended.
Yestc_modestringsegment_abr_0 (average bitrate) or segment_crf_1 (variable bitrate); segment_abr_0 is recommended.

Request Example

GOP-based slicing:

{
  "task": "/v1/pvg_video_tc/491344",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3OTM2MTIwMA==/34252f68-76bc-4a31-6829-6981765af226.mp4",
      "profile": {
        "media_profiles": {
          "media_data_type": "url"
        },
        "version": "v1"
      }
    }
  ],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"tc_mode\":\"gop_slice\",\"start_gop_num\":1,\"end_gop_num\":2}}",
  "sync_timeout": 30
}

Frame-index slicing and transcoding:

{
  "task": "/v1/pvg_video_tc/491344",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3OTM2MTIwMA==/34252f68-76bc-4a31-6829-6981765af226.mp4",
      "profile": {
        "media_profiles": {
          "media_data_type": "url"
        },
        "version": "v1"
      }
    }
  ],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"repost_url\":\"https://example.com/video-slice/callback\",\"start_frame_num\":1,\"end_frame_num\":120,\"encode_fps\":30,\"tc_mode\":\"segment_abr_0\"}}",
  "sync_timeout": -1
}

Response Fields

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

Fields in data are described below.

FieldTypeDescription
statusintStatus code: -1 task not found; 0 created; 1 processing; 2 failed; 9 timed out—use the Query API; 10 succeeded.
resultobjectVideo-slicing algorithm result
progressnumberTask progress
predict_elapsedintEstimated processing time, in milliseconds
create_timeint64Creation timestamp, in milliseconds
task_idstringTask ID
custom_task_idstringClient-defined task ID
trace_idstringTrace identifier within data
client_infostringClient information
init_imagesobject[]/nullInput media echoed by the service

Fields in result are described below.

FieldTypeDescription
idstringUnique task identifier
urlsstring[]List of output media URLs
imagesstring[]List of output media; equivalent to urls
parametersobjectAlgorithm parameters and environment information
dataobjectDetailed data returned by the algorithm
msgstringResult message
msg_idstringMessage ID
mtlab_resobjectUnderlying algorithm result
media_info_listobject[]Output media information list

Fields in result.data are described below.

FieldTypeDescription
durationobjectProcessing-time statistics for each stage
error_codeintAlgorithm error code; 0 indicates success.
error_msgstringAlgorithm error message
extraobjectExtension fields
media_info_listobject[]Media information list
msg_idstringMessage ID
parameterobjectEchoed parameters

Fields in duration are described below.

FieldTypeDescription
alg_process_timenumberAlgorithm processing time, in milliseconds
created_timestampnumberTask creation timestamp, in seconds
pull_timestampnumberResource retrieval timestamp, in seconds
repost_timenumberRetry duration
upload_timenumberUpload duration, in milliseconds
waiting_timenumberQueue wait time, in milliseconds

Elements of media_info_list are described below.

FieldTypeDescription
media_datastringMedia data URL
media_extraobjectAdditional media information
media_profilesobjectMedia properties

Fields in media_profiles returned by GOP-based slicing are described below.

FieldTypeDescription
media_data_typestringurl indicates that the media data is a URL.
start_frame_numnumberStarting frame number
end_frame_numnumberEnding frame number
ret_frame_numnumberNumber of output video frames
ret_gop_numnumberNumber of output GOPs
ret_video_fpsnumberOutput video frame rate
ret_video_widthnumberOutput video width
ret_video_heightnumberOutput video height
ret_video_typestringVideo codec, such as h264
fn_cost_timenumberSlicing duration, in seconds
fn_work_dirstringSlicing working directory
ret_file_sizenumberOutput file size, in bytes
rsp_media_url_typestringReturned media type, such as mp4
upload_2_flagstringUpload marker; tmp_upload indicates a temporary upload.
upload_costnumberUpload duration, in seconds
upload_cost_framenumberPer-frame upload duration, in seconds

Fields in parameters and result.data.parameter are described below.

FieldTypeDescription
app_versionstringApplication version
container_available_zonestringAvailability zone
download_costnumberDownload duration, in milliseconds
pvg_versionstringPVG version
rsp_media_typestringReturned media type; url indicates a URL.

Fields in mtlab_res are described below.

FieldTypeDescription
ErrorCodenumberUnderlying error code
ErrorMsgstringUnderlying error message
error_codenumberCompatibility field for the error code
error_msgstringCompatibility field for the error message
media_info_listobject[]/nullMedia information list
msg_idstringMessage ID
parameterobject/nullParameter information

Error codes specific to this API:

ErrorCodeError MessageDescription
20001PROCESS_ERRORProcessing error

Response Examples

Successful Response Example

{
  "request_id": "",
  "trace_id": "",
  "code": 0,
  "error_code": 0,
  "message": "success",
  "tips": null,
  "data": {
    "status": 10,
    "result": {
      "id": "t_mt1a3i5n7bb13bac96-0d76-4297-9bcb-c47403840e93",
      "urls": [
        "https://obs-large.mtlab.meitu.com/mtopen/ff56d688358849259556be0f50065a60/25fa22ba-8c0d-41fe-50a7-a978f38e5cee.mp4"
      ],
      "images": [
        "https://obs-large.mtlab.meitu.com/mtopen/ff56d688358849259556be0f50065a60/25fa22ba-8c0d-41fe-50a7-a978f38e5cee.mp4"
      ],
      "parameters": {
        "app_version": "1.1.23",
        "container_available_zone": "bj-alibjop0",
        "download_cost": 217,
        "pvg_version": "10.0.0.2.213",
        "rsp_media_type": "url"
      },
      "data": {
        "duration": {
          "alg_process_time": 281,
          "created_timestamp": 1779445581,
          "pull_timestamp": 1779445581,
          "repost_time": 0,
          "upload_time": 125,
          "waiting_time": 32
        },
        "error_code": 0,
        "error_msg": "success",
        "extra": {},
        "media_info_list": [
          {
            "media_data": "https://obs-large.mtlab.meitu.com/mtopen/ff56d688358849259556be0f50065a60/25fa22ba-8c0d-41fe-50a7-a978f38e5cee.mp4",
            "media_extra": {},
            "media_profiles": {
              "end_frame_num": 2,
              "fn_cost_time": 0.28,
              "fn_work_dir": "/tmp/slice/f26a132f-daa7-4c6a-4e73-r009ce57aaa4",
              "media_data_type": "url",
              "ret_file_size": 2419909,
              "ret_frame_num": 152,
              "ret_gop_num": 1,
              "ret_video_fps": 19,
              "ret_video_height": 1280,
              "ret_video_type": "h264",
              "ret_video_width": 720,
              "rsp_media_url_type": "mp4",
              "start_frame_num": 1,
              "upload_2_flag": "tmp_upload",
              "upload_cost": 1,
              "upload_cost_frame": 0
            }
          }
        ],
        "msg_id": "f26a132f-daa7-4c6a-4e73-r009ce57aaa4",
        "parameter": {
          "app_version": "1.1.23",
          "container_available_zone": "bj-alibjop0",
          "download_cost": 217,
          "pvg_version": "10.0.0.2.213",
          "rsp_media_type": "url"
        }
      },
      "msg": "success",
      "msg_id": "f26a132f-daa7-4c6a-4e73-r009ce57aaa4",
      "mtlab_res": {
        "ErrorCode": 0,
        "ErrorMsg": "",
        "error_code": 0,
        "error_msg": "",
        "media_info_list": null,
        "msg_id": "f26a132f-daa7-4c6a-4e73-r009ce57aaa4",
        "parameter": null
      },
      "media_info_list": [
        {
          "media_data": "https://obs-large.mtlab.meitu.com/mtopen/ff56d688358849259556be0f50065a60/25fa22ba-8c0d-41fe-50a7-a978f38e5cee.mp4",
          "media_extra": {},
          "media_profiles": {
            "end_frame_num": 2,
            "fn_cost_time": 0.28,
            "fn_work_dir": "/tmp/slice/f26a132f-daa7-4c6a-4e73-r009ce57aaa4",
            "media_data_type": "url",
            "ret_file_size": 2419909,
            "ret_frame_num": 152,
            "ret_gop_num": 1,
            "ret_video_fps": 19,
            "ret_video_height": 1280,
            "ret_video_type": "h264",
            "ret_video_width": 720,
            "rsp_media_url_type": "mp4",
            "start_frame_num": 1,
            "upload_2_flag": "tmp_upload",
            "upload_cost": 1,
            "upload_cost_frame": 0
          }
        }
      ]
    },
    "progress": 1,
    "predict_elapsed": 10000,
    "create_time": 1779445581190,
    "task_id": "t_mt1a3i5n7bb13bac96-0d76-4297-9bcb-c47403840e93",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

Pending 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": 1779445581190,
    "task_id": "t_mt1a3i5n7bb13bac96-0d76-4297-9bcb-c47403840e93",
    "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": 1779445581190,
    "task_id": "t_mt1a3i5n7bb13bac96-0d76-4297-9bcb-c47403840e93",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

General Error Codes

For details, 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": {
            "tc_mode": "gop_slice",
            "start_gop_num": 1,
            "end_gop_num": 2,
        },
    }
    payload = {
        "task": "/v1/pvg_video_tc/491344",
        "task_type": "formula",
        "init_images": [
            {
                "url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3OTM2MTIwMA==/34252f68-76bc-4a31-6829-6981765af226.mp4",
                "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/pvg_video_tc/491344",
  "task_type": "formula",
  "init_images": [{
    "url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3OTM2MTIwMA==/34252f68-76bc-4a31-6829-6981765af226.mp4",
    "profile": {
      "media_profiles": {"media_data_type": "url"},
      "version": "v1"
    }
  }],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"tc_mode\":\"gop_slice\",\"start_gop_num\":1,\"end_gop_num\":2}}",
  "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' => [
        'tc_mode' => 'gop_slice',
        'start_gop_num' => 1,
        'end_gop_num' => 2,
    ],
]);

$body = json_encode([
    'task' => '/v1/pvg_video_tc/491344',
    'task_type' => 'formula',
    'init_images' => [
        [
            'url' => 'https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3OTM2MTIwMA==/34252f68-76bc-4a31-6829-6981765af226.mp4',
            '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/pvg_video_tc/491344\",\n" +
                "  \"task_type\": \"formula\",\n" +
                "  \"init_images\": [{\n" +
                "    \"url\": \"https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTc3OTM2MTIwMA==/34252f68-76bc-4a31-6829-6981765af226.mp4\",\n" +
                "    \"profile\": {\n" +
                "      \"media_profiles\": {\"media_data_type\": \"url\"},\n" +
                "      \"version\": \"v1\"\n" +
                "    }\n" +
                "  }],\n" +
                "  \"params\": \"{\\\"rsp_media_type\\\":\\\"url\\\",\\\"parameter\\\":{\\\"tc_mode\\\":\\\"gop_slice\\\",\\\"start_gop_num\\\":1,\\\"end_gop_num\\\":2}}\",\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);
        }
    }
}