视频扩展
描述
按指定比例向视频的上下左右扩展画面,并生成扩展区域的内容。默认保留原视频的第一条音轨,也可返回对比视频或羽化回贴结果。
视频要求
- 每次提交一个服务可下载的视频 URL,文件须包含有效视频轨。推荐 H.264 或 H.265 编码的 MP4。
- 支持的容器包括
3gp、asf、avi、dv、f4v、flv、m2t、m2ts、m4v、mkv、mod、mov、mp4、mpeg、mpg、mts、qt、rm、rmvb、tod、ts、vob、webm、wmv。能否解码还取决于编码及文件完整性。 - 不支持静态图片、动图、SWF、WebP、无视频轨文件,以及任意角度旋转、剪切或透视等不受支持的显示变换。
调用 URL
正式环境:https://openapi-ali.meitu.com
任务提交接口:https://openapi-ali.meitu.com/api/v1/push
任务名称(task):/v1/Video_Expansion/497075
任务类型(task_type):formula调用方法
POST
Content-Type: application/json
权限
使用 AK/SK 签名,并开通对应环境的接口权限。
请求参数
| 是否必选 | 参数名 | 类型 | 参数说明 |
|---|---|---|---|
| 是 | params | string | 算法参数(JSON 字符串)。 |
| 是 | init_images | object[] | 视频列表,传一项。 |
| 是 | task | string | /v1/Video_Expansion/497075 |
| 是 | task_type | string | formula |
init_images
| 是否必选 | 参数名 | 类型 | 参数说明 |
|---|---|---|---|
| 是 | url | string | 输入视频 URL。 |
| — | profile | object | 示例传空对象 {}。 |
params
算法参数以 JSON 字符串传入,解码后的字段如下。
| 是否必选 | 参数名 | 类型 | 参数说明 |
|---|---|---|---|
| — | isVideo | boolean | 视频请求示例为 true。 |
| 是 | parameter | object | 算法参数对象。 |
parameter
| 是否必选 | 参数名 | 类型 | 参数说明 |
|---|---|---|---|
| 否 | mode | string | 默认 expand。传 v2v 时使用已扩边、已缩放的参考视频,不再扩边或缩放。 |
| 否 | r_h_up、r_h_down | number | 向上、向下扩展的比例,以正向画面高度为基准;默认各为 0。 |
| 否 | r_w_left、r_w_right | number | 向左、向右扩展的比例,以正向画面宽度为基准;默认各为 0。 |
| 否 | start_idx | integer | 起始帧,第一帧为 0,默认 0。 |
| 否 | max_num_frames | integer / null | 最多处理的帧数。省略或传 JSON null 时处理到视频末尾;0 或负数按 1 帧处理。 |
| 否 | out_fps | number / null | 输出帧率,取整输出。省略或传 null 时,使用源帧率取整;源帧率无效或显式传入非法值时使用 24。 |
| 否 | max_target_length | integer | expand 模式的输出长边,设置有效值时优先使用,向上对齐到偶数。 |
| 否 | target_width、target_height | integer | 未指定有效长边时用于推导长边,可只传一个;不是精确输出尺寸。 |
| 否 | seed | integer | 随机种子,默认 42。 |
| 否 | keep_source_audio | boolean | 默认 true。传 JSON false 输出无声视频;不接受字符串或 null。 |
| 否 | compare | boolean | 默认 false;开启后附加对比视频。 |
| 否 | blend | boolean | 默认 false;开启后附加羽化回贴结果,仅 expand 生效。 |
| 否 | sampling_preset | string | 默认由服务配置决定,通常为 official8;也接受 four_step、three_step。 |
| 否 | rsp_media_type | string | 省略时以 URL 返回结果;示例使用 url。 |
扩展比例以视频方向、镜像及像素宽高比规范化后的画面为准。expand 保持扩展后的宽高比。若 max_target_length 缺失、为 null、0 或空字符串,取有效目标宽高中较大的值,自动推导的长边最高为 1280;没有有效提示时使用 1024。有效显式长边不受此自动推导上限约束。v2v 保持输入参考视频尺寸。
源视频剩余帧数不足时,只返回可用帧。视频轨时长约为“实际帧数 ÷ 输出帧率”。音频转为 AAC,从对应起始帧的源时间开始,按输出时长裁切或补静音;无源音轨时输出无声视频。
输入值示例
下面从第一帧开始,最多处理 249 帧,四边各扩展 25%,设置输出长边为 1024,按 24 fps 输出并保留音频。
{
"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\"}}"
}返回值说明
保存投递返回的任务标识,查询同一任务,不因等待超时重复投递。若应用返回统一网关的 data.task_id,按 任务查询 使用该标识;算法直连的 msg_id 只用于对应的直连查询协议。
主视频是算法结果中 media_info_list[0],角色为 output。附加结果按 media_profiles.media_aux_role 区分:compare 是横向对比视频,blended_output 是羽化回贴视频。parameter.keep_source_audio 表示本次音频策略;extra.trans_meta.rsp_meta[0].has_audio 表示主结果是否实际有音轨。
返回值示例
算法处理成功示例
{
"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
}
]
}
}
}通用的错误代码与信息
常见错误:21102 表示视频 URL 或媒体字段缺失;21103、21104、21105 表示参数类型、取值或 JSON 有误;23201、23202 表示视频解码失败或不支持该格式;24301 表示音频处理失败。网关通用错误见 API 错误码。
SDK 调用示例
填写 AK/SK 和视频 URL 后,使用签名后的请求提交任务。
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();
}
}
}