视频扩展

描述

按指定比例向视频的上下左右扩展画面,并生成扩展区域的内容。默认保留原视频的第一条音轨,也可返回对比视频或羽化回贴结果。

视频要求

  • 每次提交一个服务可下载的视频 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 签名,并开通对应环境的接口权限。

请求参数

是否必选参数名类型参数说明
是paramsstring算法参数(JSON 字符串)。
是init_imagesobject[]视频列表,传一项。
是taskstring/v1/Video_Expansion/497075
是task_typestringformula

init_images

是否必选参数名类型参数说明
是urlstring输入视频 URL。
—profileobject示例传空对象 {}。

params

算法参数以 JSON 字符串传入,解码后的字段如下。

是否必选参数名类型参数说明
—isVideoboolean视频请求示例为 true。
是parameterobject算法参数对象。

parameter

是否必选参数名类型参数说明
否modestring默认 expand。传 v2v 时使用已扩边、已缩放的参考视频,不再扩边或缩放。
否r_h_up、r_h_downnumber向上、向下扩展的比例,以正向画面高度为基准;默认各为 0。
否r_w_left、r_w_rightnumber向左、向右扩展的比例,以正向画面宽度为基准;默认各为 0。
否start_idxinteger起始帧,第一帧为 0,默认 0。
否max_num_framesinteger / null最多处理的帧数。省略或传 JSON null 时处理到视频末尾;0 或负数按 1 帧处理。
否out_fpsnumber / null输出帧率,取整输出。省略或传 null 时,使用源帧率取整;源帧率无效或显式传入非法值时使用 24。
否max_target_lengthintegerexpand 模式的输出长边,设置有效值时优先使用,向上对齐到偶数。
否target_width、target_heightinteger未指定有效长边时用于推导长边,可只传一个;不是精确输出尺寸。
否seedinteger随机种子,默认 42。
否keep_source_audioboolean默认 true。传 JSON false 输出无声视频;不接受字符串或 null。
否compareboolean默认 false;开启后附加对比视频。
否blendboolean默认 false;开启后附加羽化回贴结果,仅 expand 生效。
否sampling_presetstring默认由服务配置决定,通常为 official8;也接受 four_step、three_step。
否rsp_media_typestring省略时以 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

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