Video Expansion
Description
Extend any of the four borders of a video and generate content for the added area. The API preserves the first source audio track by default and can also return a comparison video or a feather-blended result.
Video Requirements
- Submit one video URL that the service can download. The file must contain a valid video track. H.264 or H.265 in an MP4 container is recommended.
- Supported containers include
3gp,asf,avi,dv,f4v,flv,m2t,m2ts,m4v,mkv,mod,mov,mp4,mpeg,mpg,mts,qt,rm,rmvb,tod,ts,vob,webm,wmv. Decoding also depends on the codec and file integrity. - Still images, animated images, SWF, WebP, files without a video track, and unsupported display transforms such as arbitrary-angle rotations, shearing, or perspective transforms are not accepted.
Request URL
Production environment: https://openapi-ali.meitu.com
Task submission endpoint: https://openapi-ali.meitu.com/api/v1/push
Task name (task): /v1/Video_Expansion/497075
Task type (task_type): formulaHTTP Method
POST
Content-Type: application/json
Authentication
Use AK/SK signing and obtain API access for the target environment.
Request Parameters
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | params | string | Algorithm parameters encoded as a JSON string. |
| Yes | init_images | object[] | Video list. Submit one item. |
| Yes | task | string | /v1/Video_Expansion/497075 |
| Yes | task_type | string | formula |
init_images
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | url | string | Input video URL. |
| — | profile | object | The example passes an empty object {}. |
params
Pass the algorithm parameters as a JSON string. The decoded fields are listed below.
| Required | Parameter | Type | Description |
|---|---|---|---|
| — | isVideo | boolean | The video request example uses true. |
| Yes | parameter | object | Algorithm parameter object. |
parameter
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | mode | string | Default: expand. Use v2v for a reference video that has already been expanded and resized; both steps are skipped. |
| No | r_h_up, r_h_down | number | Top and bottom expansion ratios relative to the normalized frame height. Each defaults to 0. |
| No | r_w_left, r_w_right | number | Left and right expansion ratios relative to the normalized frame width. Each defaults to 0. |
| No | start_idx | integer | Zero-based starting frame. Default: 0. |
| No | max_num_frames | integer / null | Maximum number of frames to process. Omit it or pass JSON null to process through the end. Zero and negative values are treated as 1 frame. |
| No | out_fps | number / null | Output frame rate, rounded to an integer. Omit it or pass null to use the rounded source frame rate. Invalid explicit values or an unavailable source frame rate fall back to 24. |
| No | max_target_length | integer | Output long edge in expand mode. A valid explicit value takes precedence and is rounded up to an even number. |
| No | target_width, target_height | integer | Hints for deriving the long edge when no valid explicit long edge is set. You can supply just one. They do not set exact output dimensions. |
| No | seed | integer | Random seed. Default: 42. |
| No | keep_source_audio | boolean | Default: true. Pass JSON false for silent output. Strings and null are not accepted. |
| No | compare | boolean | Default: false. Enable to get an additional comparison video. |
| No | blend | boolean | Default: false. Enable to get an additional feather-blended result. Applies only in expand mode. |
| No | sampling_preset | string | Defaults to the service configuration, usually official8. Also accepts four_step and three_step. |
| No | rsp_media_type | string | Returns URLs when omitted. The example uses url. |
Expansion ratios are calculated after normalizing orientation, mirroring, and pixel aspect ratio. In expand mode, output preserves the expanded frame's aspect ratio. If max_target_length is missing, null, 0, or an empty string, the service derives the long edge from the larger valid target dimension, capped at 1280. The fallback without a valid hint is 1024. This cap does not apply to a valid explicit long edge. In v2v mode, output keeps the reference video's dimensions.
If fewer frames remain in the source than requested, only the available frames are returned. Video-track duration is approximately the actual frame count divided by the output frame rate. Audio is encoded as AAC, starts at the source time of the starting frame, and is trimmed or padded with silence to match the output duration. Videos without an audio track produce silent output.
Request Example
Start at the first frame, process up to 249 frames, extend all four sides by 25%, set the output long edge to 1024, and output at 24 fps with audio preserved.
{
"task": "/v1/Video_Expansion/497075",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.mp4",
"profile": {}
}
],
"params": "{\"isVideo\":true,\"parameter\":{\"mode\":\"expand\",\"max_num_frames\":249,\"start_idx\":0,\"out_fps\":24,\"r_h_down\":0.25,\"r_h_up\":0.25,\"r_w_left\":0.25,\"r_w_right\":0.25,\"max_target_length\":1024,\"seed\":9331,\"keep_source_audio\":true,\"rsp_media_type\":\"url\"}}"
}Response Fields
Keep the task identifier returned by submission and continue querying that task if it takes longer than expected. If your application returns the unified gateway field data.task_id, use that identifier with Task Query. The direct algorithm's msg_id belongs to its own query protocol.
The primary video is always media_info_list[0] in the algorithm result, with the role output. For additional videos, inspect media_profiles.media_aux_role: compare is the side-by-side comparison, and blended_output is the feather-blended result. The requested audio policy is in parameter.keep_source_audio; extra.trans_meta.rsp_meta[0].has_audio indicates whether the primary result actually has an audio track.
Response Example
Successful Algorithm Result
{
"error_code": 0,
"error_msg": "",
"media_info_list": [
{
"media_data": "https://example.com/output.mp4",
"media_profiles": {
"media_aux_role": "output",
"media_data_width": 576,
"media_data_height": 1024,
"media_data_fps": 24,
"media_data_frames": 247,
"media_data_duration_sec": 10.291667
}
}
],
"parameter": {
"keep_source_audio": true,
"rsp_media_type": "url"
},
"extra": {
"trans_meta": {
"rsp_meta": [
{
"has_audio": true
}
]
}
}
}Common Error Codes
Common errors: 21102 indicates missing video URL or media fields; 21103, 21104, and 21105 indicate invalid parameter types, values, or JSON; 23201 and 23202 indicate decoding failure or unsupported format; 24301 indicates audio processing failure. See API Error Codes for common gateway errors.
SDK Examples
Fill in your access and secret keys and the video URL, then submit the signed request.
Python
import requests
from sign_sdk import sign
url = "https://openapi-ali.meitu.com/api/v1/push"
body = r'''{
"task": "/v1/Video_Expansion/497075",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.mp4",
"profile": {}
}
],
"params": "{\"isVideo\":true,\"parameter\":{\"mode\":\"expand\",\"max_num_frames\":249,\"start_idx\":0,\"out_fps\":24,\"r_h_down\":0.25,\"r_h_up\":0.25,\"r_w_left\":0.25,\"r_w_right\":0.25,\"max_target_length\":1024,\"seed\":9331,\"keep_source_audio\":true,\"rsp_media_type\":\"url\"}}"
}'''
headers = {"Content-Type": "application/json", sign.HeaderHost: "openapi-ali.meitu.com"}
signer = sign.Signer("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY")
request = signer.sign(url, "POST", headers, body)
with requests.Session() as session:
response = session.send(request, timeout=(10, 60), allow_redirects=False)
print(response.status_code, response.text)Go
package main
import (
"fmt"
"io"
"log"
"net/http"
"time"
"github.com/mtlab/api/signer"
)
func main() {
url := "https://openapi-ali.meitu.com/api/v1/push"
body := `{
"task": "/v1/Video_Expansion/497075",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.mp4",
"profile": {}
}
],
"params": "{\"isVideo\":true,\"parameter\":{\"mode\":\"expand\",\"max_num_frames\":249,\"start_idx\":0,\"out_fps\":24,\"r_h_down\":0.25,\"r_h_up\":0.25,\"r_w_left\":0.25,\"r_w_right\":0.25,\"max_target_length\":1024,\"seed\":9331,\"keep_source_audio\":true,\"rsp_media_type\":\"url\"}}"
}`
headers := make(http.Header)
headers.Set(signer.HeaderHost, "openapi-ali.meitu.com")
headers.Set("Content-Type", "application/json")
s := signer.NewSigner("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY")
req, err := s.Sign(url, http.MethodPost, headers, body)
if err != nil {
log.Fatal(err)
}
client := &http.Client{
Timeout: 60 * time.Second,
CheckRedirect: func(*http.Request, []*http.Request) error {
return http.ErrUseLastResponse
},
}
res, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
result, err := io.ReadAll(res.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(res.StatusCode, string(result))
}PHP
<?php
require_once __DIR__ . '/signer.php';
$url = 'https://openapi-ali.meitu.com/api/v1/push';
$body = <<<'JSON'
{
"task": "/v1/Video_Expansion/497075",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.mp4",
"profile": {}
}
],
"params": "{\"isVideo\":true,\"parameter\":{\"mode\":\"expand\",\"max_num_frames\":249,\"start_idx\":0,\"out_fps\":24,\"r_h_down\":0.25,\"r_h_up\":0.25,\"r_w_left\":0.25,\"r_w_right\":0.25,\"max_target_length\":1024,\"seed\":9331,\"keep_source_audio\":true,\"rsp_media_type\":\"url\"}}"
}
JSON;
$headers = ['Host' => 'openapi-ali.meitu.com', 'Content-Type' => 'application/json'];
$signer = new Signer('YOUR_ACCESS_KEY', 'YOUR_SECRET_KEY');
$curl = $signer->sign($url, 'POST', $headers, $body);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => false,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 60,
]);
$result = curl_exec($curl);
if ($result === false) {
$error = curl_error($curl);
curl_close($curl);
throw new RuntimeException($error);
}
echo curl_getinfo($curl, CURLINFO_HTTP_CODE), PHP_EOL, $result, PHP_EOL;
curl_close($curl);Java
package com.meitu.openai.common;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URI;
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 url = "https://openapi-ali.meitu.com/api/v1/push";
String body = "{\n" +
" \"task\": \"/v1/Video_Expansion/497075\",\n" +
" \"task_type\": \"formula\",\n" +
" \"init_images\": [\n" +
" {\n" +
" \"url\": \"https://example.com/input.mp4\",\n" +
" \"profile\": {}\n" +
" }\n" +
" ],\n" +
" \"params\": \"{\\\"isVideo\\\":true,\\\"parameter\\\":{\\\"mode\\\":\\\"expand\\\",\\\"max_num_frames\\\":249,\\\"start_idx\\\":0,\\\"out_fps\\\":24,\\\"r_h_down\\\":0.25,\\\"r_h_up\\\":0.25,\\\"r_w_left\\\":0.25,\\\"r_w_right\\\":0.25,\\\"max_target_length\\\":1024,\\\"seed\\\":9331,\\\"keep_source_audio\\\":true,\\\"rsp_media_type\\\":\\\"url\\\"}}\"\n" +
"}";
Map<String, String> headers = new HashMap<>();
headers.put("Content-Type", "application/json");
headers.put(Signer.HeaderHost, "openapi-ali.meitu.com");
Signer signer = new Signer("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY");
Map<String, String> signed = signer.sign(url, "POST", headers, body);
HttpURLConnection connection = (HttpURLConnection) URI.create(url).toURL().openConnection();
try {
connection.setRequestMethod("POST");
connection.setConnectTimeout(10000);
connection.setReadTimeout(60000);
connection.setInstanceFollowRedirects(false);
signed.forEach(connection::setRequestProperty);
connection.setDoOutput(true);
try (OutputStream out = connection.getOutputStream()) {
out.write(body.getBytes(StandardCharsets.UTF_8));
}
int status = connection.getResponseCode();
try (InputStream in = status >= 400 ? connection.getErrorStream() : connection.getInputStream()) {
String result = in == null ? "" : new String(in.readAllBytes(), StandardCharsets.UTF_8);
System.out.println(status + " " + result);
}
} finally {
connection.disconnect();
}
}
}