全部产品
Search

搜索本产品

    媒体处理：AddMedia - 新增媒体

    文档中心

    媒体处理：AddMedia - 新增媒体

    更新时间：May 09, 2025

    提交新增媒体作业。

    接口说明

    • 当在 OSS 上有存量视频时，可以通过此接口处理存量视频，从而避免重新上传视频到 OSS。如果已经配置过工作流，上传媒体文件到 OSS 后，OSS 会自动通知 MPS。根据设置的 OSS Bucket，Object 自动匹配处于激活状态的工作流自动执行，因此通常情况下不需要手动调用 AddMedia 接口处理文件。
    • 只有指定激活状态的工作流处理媒体文件时，才会自动获取媒体信息；不指定工作流或指定其他状态的工作流时，不会获取媒体信息。

    QPS 限制

    本接口的单用户 QPS 限制为 100 次/秒。超过限制，API 调用会被限流，这可能会影响您的业务，请合理调用。更多信息，请参见 QPS 限制。

    调试

    您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

    授权信息

    下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

    • 操作：是指具体的权限点。
    • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
    • 资源类型：是指操作中支持授权的资源类型。具体说明如下：
      • 对于必选的资源类型，用前面加 * 表示。
      • 对于不支持资源级授权的操作，用全部资源表示。
    • 条件关键字：是指云产品自身定义的条件关键字。
    • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
    操作访问级别资源类型条件关键字关联操作
    mts:AddMediacreate
    *全部资源
    *
      无
    		无

    请求参数

    名称类型必填描述示例值
    FileURLstring是

    输入文件的路径，可以通过 MPS 或 OSS 控制台获取。详细触发规则请参见下文中工作流触发匹配规则。

    • 仅支持 OSS HTTP 地址，不支持 CDN 地址和 HTTPS 地址。
    • 不超过 3200 字节。
    • URL 遵循 RFC 2396（UTF-8 编码，并进行 URLEncode）。更多信息，请参见 URLEncode 说明。
    		http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.mp4
    Titlestring否

    媒体标题。

    • 长度限制不超过 128 个字节。
    • UTF-8 编码。
    		mytest
    Descriptionstring否

    描述。

    • 长度限制不超过 1024 个字节。
    • UTF-8 编码。
    		A test video
    CoverURLstring否

    封面 URL。即您需要设置的封面的存储地址，可以通过 MPS 控制台 > 工作流管理 > 媒体 Bucket或OSS 控制台 > 我的访问路径获取。

    • 不超过 3200 字节。
    • URL 遵循 RFC 2396（UTF-8 编码，并进行 URLEncode）。更多信息，请参见 URLEncode 说明。
    		http://bucket.oss-cn-hangzhou.aliyuncs.com/example/1.png
    Tagsstring否

    标签列表。

    说明 媒体处理中，每个媒体的每个标签都是独立的，可以通过搜索媒体库来查找所有设置了相同标签的媒体。

    • 用半角逗号（,）分隔，不超过 16 个标签。

    • 单个标签不能超过 32 个字节。

    • UTF-8 编码。

    		tag1,tag2
    MediaWorkflowIdstring否

    媒体工作流 ID。可通过 MPS 控制台或新增媒体工作流接口获取。

    		07da6c65da7f458997336e0de192****
    MediaWorkflowUserDatastring否

    媒体工作流用户自定义数据。

    • 不超过 1024 字节。
    • UTF-8 编码。
    		test
    InputUnbindboolean否

    是否检查指定的工作流支持输入路径。此处建议您选择检查（true），避免因路径出错而导致的错误。取值：

    • true：检查

    • false：不检查

    		false
    CateIdlong否

    媒体所属类目 ID。不允许为负数。

    		123
    OverrideParamsstring否

    覆盖参数。

    • 示例 1：HLS 打包字幕覆盖{“WebVTTSubtitleOverrides”,[{“RefActivityName”:”subtitleNode”,”WebVTTSubtitleURL”:”http://test.oss-cn-hangzhou.aliyuncs.com/example1.vtt"}]}。
    • 示例 2：DASH 打包字幕覆盖 {“subtitleTransNodeName”:{“InputConfig”:{“Format”:”stl”,”InputFile”:{“URL”:”http://subtitleBucket.oss-cn-hangzhou.aliyuncs.com/package/example/CENG.stl"}}}}。
    		{“subtitleTransNodeName”:{“InputConfig”:{“Format”:”stl”,”InputFile”:{“URL”:”http://exampleBucket.oss-cn-hangzhou.aliyuncs.com/package/example/CENG.stl"}}}}

    工作流触发匹配规则

    规则匹配执行策略如下：以新增文件的路径为基础，检查工作流绑定的位置，如果新增文件的路径中包含规则绑定的字符串则匹配，不包含则不匹配。例如：http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test1.flv规则：

    1、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/          匹配
2、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/            匹配
3、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/              匹配
4、http://bucket.oss-cn-hangzhou.aliyuncs.com/                匹配
5、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.flv  匹配
6、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/CC/         不匹配
7、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B2/           不匹配
8、http://bucket.oss-cn-hangzhou.aliyuncs.com/A2/B/C/         不匹配
    说明 在新增媒体工作流时，请您不要配置一个工作流的输入路径为另外一个工作流的输入路径的前缀，否则会一个增量文件触发两次工作流执行实例。例如：两个工作流的输入路径分别配置 test 和 test1，则当输入文件上传到 test1 文件夹下同样满足 test 前缀，因此会触发两次工作流执行实例。

    匹配文件扩展名

    触发要求必须是多媒体文件，媒体库服务是通过文件扩展名来判断的。文件或者没有扩展名（文件名中不包含扩展名分割符号“.”），或者扩展名符合下面的规则：

    说明 对于 swf，截图及转码服务质量不保障。
    类型扩展名
    视频3gp, asf, avi, dat, dv, flv, f4v, gif, m2t, m3u8, m4v, mj2, mjpeg, mkv, mov, mp4, mpe, mpg, mpeg, mts, ogg, qt, rm, rmvb, swf, ts, vob, wmv, webm
    音频aac, ac3, acm, amr, ape, caf, flac, m4a, mp3, ra, wav, wma, aiff

    媒体工作流消息

    媒体工作流采用 阿里云轻量消息队列（原 MNS） 发送消息给视频云服务接入方，媒体工作流会在（Start/Report）活动节点完成时发送消息，若需要接收消息，需要在 Start 活动上设置队列/通知名称，媒体工作流产生的消息存储在队列/通知中，可以使用 轻量消息队列（原 MNS） SDK 获取消息，消息规格如下：

    名称类型描述
    RunIdString工作流执行 ID。
    NameString活动名称。
    TypeString活动类型。范围：Report、Start
    StateString活动状态。范围：Fail、Success
    CodeString错误码。如果活动状态是 Fail 时，会给出具体的错误码。
    MessageString错误消息。如果活动状态是 Fail 时，会给出详细的错误描述信息。
    MediaWorkflowExecutionMediaWorkflowExecution媒体工作流执行信息。

    返回参数

    名称类型描述示例值
    object

    返回参数。

    RequestIdstring

    请求 ID。

    		05F8B913-E9F3-4A6F-9922-48CADA0FFAAD
    Mediaobject

    媒体信息。

    CreationTimestring

    创建时间。

    		2016-09-20T03:02:40Z
    CateIdlong

    类目 ID。

    		1
    Heightstring

    媒体文件高度。

    		1280
    CensorStatestring

    视频审核状态。取值：

    • Initiated：初始（上传成功审核未完成）。

    • Pass：通过（上传成功审核已通过）。

    		Initiated
    Tagsarray

    标签。

    Tagstring

    标签列表。

    		tag,tag2
    Bitratestring

    码率。

    		1148.77
    MediaIdstring

    媒体 ID。

    		3e6149d5a8c944c09b1a8d2dc3e4****
    Fileobject

    原文件。

    Statestring

    文件状态。此处默认为 Normal（正常）。

    		Normal
    URLstring

    文件 URL。

    		http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.mp4
    PublishStatestring

    媒体发布状态，表示是否对外发布媒体。取值：

    • Initiated：初始。
    • UnPublish：未发布，OSS 播放文件权限为 Private。
    • Published：已发布，OSS 播放文件权限为 Default。
    		Published
    Descriptionstring

    描述。长度不超过 1024 个字节。

    		A test video
    Widthstring

    媒体文件宽度。

    		1280
    Sizestring

    媒体文件大小。

    		379860
    CoverURLstring

    封面 URL。

    		http://bucket.oss-cn-hangzhou.aliyuncs.com/example/1.png
    RunIdListarray

    媒体工作流执行实例 ID 列表。

    RunIdstring

    已执行的媒体工作流执行实例 ID 列表，半角逗号（,）分隔。

    		{"RunId":["cbad98d35629470fa05ff393d347****"]}
    Durationstring

    媒体文件时长。

    		2.645333
    Fpsstring

    媒体文件帧率。

    		25.0
    Titlestring

    媒体标题。长度不超过 128 个字节。

    		mytest.mp4
    Formatstring

    格式。支持 mov，mp4，m4a，3gp，3g2，mj2。

    		mp4

    示例

    正常返回示例

    JSON格式

    {
  "RequestId": "05F8B913-E9F3-4A6F-9922-48CADA0FFAAD",
  "Media": {
    "CreationTime": "2016-09-20T03:02:40Z",
    "CateId": 1,
    "Height": 1280,
    "CensorState": "Initiated",
    "Tags": {
      "Tag": [
        "tag,tag2"
      ]
    },
    "Bitrate": 1148.77,
    "MediaId": "3e6149d5a8c944c09b1a8d2dc3e4****",
    "File": {
      "State": "Normal",
      "URL": "http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.mp4"
    },
    "PublishState": "Published",
    "Description": "A test video",
    "Width": 1280,
    "Size": 379860,
    "CoverURL": "http://bucket.oss-cn-hangzhou.aliyuncs.com/example/1.png",
    "RunIdList": {
      "RunId": [
        {
          "RunId": [
            "cbad98d35629470fa05ff393d347****"
          ]
        }
      ]
    },
    "Duration": 2.645333,
    "Fps": 25,
    "Title": "mytest.mp4",
    "Format": "mp4"
  }
}

    错误码

    访问错误中心查看更多错误码。

    变更历史

    变更时间变更内容概要操作
    暂无变更历史