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): formula

HTTP Method

POST

Content-Type: application/json

Authentication

Use AK/SK signing and obtain API access for the target environment.

Request Parameters

RequiredParameterTypeDescription
YesparamsstringAlgorithm parameters encoded as a JSON string.
Yesinit_imagesobject[]Video list. Submit one item.
Yestaskstring/v1/Video_Expansion/497075
Yestask_typestringformula

init_images

RequiredParameterTypeDescription
YesurlstringInput video URL.
—profileobjectThe example passes an empty object {}.

params

Pass the algorithm parameters as a JSON string. The decoded fields are listed below.

RequiredParameterTypeDescription
—isVideobooleanThe video request example uses true.
YesparameterobjectAlgorithm parameter object.

parameter

RequiredParameterTypeDescription
NomodestringDefault: expand. Use v2v for a reference video that has already been expanded and resized; both steps are skipped.
Nor_h_up, r_h_downnumberTop and bottom expansion ratios relative to the normalized frame height. Each defaults to 0.
Nor_w_left, r_w_rightnumberLeft and right expansion ratios relative to the normalized frame width. Each defaults to 0.
Nostart_idxintegerZero-based starting frame. Default: 0.
Nomax_num_framesinteger / nullMaximum 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.
Noout_fpsnumber / nullOutput 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.
Nomax_target_lengthintegerOutput long edge in expand mode. A valid explicit value takes precedence and is rounded up to an even number.
Notarget_width, target_heightintegerHints 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.
NoseedintegerRandom seed. Default: 42.
Nokeep_source_audiobooleanDefault: true. Pass JSON false for silent output. Strings and null are not accepted.
NocomparebooleanDefault: false. Enable to get an additional comparison video.
NoblendbooleanDefault: false. Enable to get an additional feather-blended result. Applies only in expand mode.
Nosampling_presetstringDefaults to the service configuration, usually official8. Also accepts four_step and three_step.
Norsp_media_typestringReturns 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

Python SDK

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

Go SDK

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 SDK

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

Java SDK

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