异步音视频处理

快速入门

又拍云处理(异步音视频处理)基于云存储服务,您在使用它之前,请确保您已经注册又拍云账号并完成实名验证,请确保您已经创建云存储服务

收费方面,见价格

相关阅读:同步视频处理同步音频处理


开发者指南

提交处理任务

请求方法

对已经存在云存储中的音视频文件,以 POST 方法向 http://p0.api.upyun.com/pretreatment/ 提交处理任务,响应中返回任务 task_id。任务以异步的方式处理,处理完成后,回调通知用户处理结果。

curl -X POST \
    http://p0.api.upyun.com/pretreatment/ \
    -H "Authorization: UPYUN <Operator>:<Signature>" \
    -H "Date: <Wed, 29 Oct 2014 02:26:58 GMT>" \
    -H "Content-MD5: <Content-MD5>" \
    -d "accept=json"
    -d "service=<service>" \
    -d "notify_url=<notify_url>" \
    -d "source=<音视频文件相对路径>" \
    -d "tasks=<base64 编码后的任务字符串>" \

认证鉴权

Authorization 详见签名认证

请求参数

参数 类型 必选 说明
service string 音/视频文件所在的服务名
notify_url string 回调通知地址,详见回调通知
source string 原始音/视频文件路径
tasks string 任务信息,详见 tasks 参数说明
accept string 回调信息的格式,值为json

tasks 参数说明

1. 按 JSON 格式组装任务,一次请求 tasks 最多可以提交 10 个任务。 任务参数见功能

[
    {
        "type": "video",                        // 视频转码
        "avopts": "/s/240p(4:3)/as/1/r/30",     // 参数
        "return_info": true,                    // 返回元数据
        "save_as": "/a/b.mp4"                   // 保存路径
    },
    {
        "type": "video",                                        // 视频拼接
        "avopts": "/i/L2EvYi9jLm1wNA==/i/LzEvMi8zLm1wNA==",     // 参数
        "save_as": "/concat/a.mp4"                              // 保存路径
    },
    …
]

2. 把 JSON 字符串 Base64 编码,得到 tasks

W3siYXZvcHRzIjoiL3MvMjQwcCg0OjMpL2FzLzEvci8zMCIsInJldHVybl9pbmZvIjp0cnVlLCJzYXZlX2FzIjoiL2EvYi5tcDQiLCJ0eXBlIjoidmlkZW8ifSx7ImF2b3B0cyI6Ii9pL0wyRXZZaTlqTG0xd05BPT0vaS9MekV2TWk4ekxtMXdOQT09Iiwic2F2ZV9hcyI6Ii9jb25jYXQvYS5tcDQiLCJ0eXBlIjoidmNvbmNhdCJ9XQ==

响应信息

[
    "35f0148d414a688a275bf915ba7cebb2",
    "98adbaa52b2f63d6d7f327a0ff223348",
    "c3103189fa906a5354d29bd807e8dc51",
    …
]

回调通知

任务处理完成后,向 notify_url 发送 HTTP POST 请求,请求体是回调信息。

curl -X POST \
    <notify_url> \
    -H "Authorization: UPYUN <Operator>:<Signature>" \
    -H "Date: <Wed, 29 Oct 2014 02:26:58 GMT>" \
    -H "Content-MD5: <Content-MD5>" \
    -d "service=<service>" \
    # 其他参数...

回调信息

回调信息是 JSON 字符串,参数名及说明如下:

参数 类型 说明
service string 音/视频文件所在的服务名
status_code integer 处理结果状态码,200 表示成功处理,详见状态码表
path array 输出文件保存路径
description string 处理结果描述
task_id string 任务对应的 task_id
info json 输出文件的元数据,仅当 return_infotrue 时,有效
signature(旧) string 回调通知的签名,回调签名(旧)的参数
timestamp(旧) integer 服务端发送回调时的时间戳,回调签名(旧)的参数

回调签名

Authorization 详见签名认证,它提供给客户端,用于验证回调通知的合法性。


上传预处理

在上传音视频文件时,对上传的音视频进行处理,生成一个或多个新的文件,同时保存上传的音视频到又拍云存储。任务以异步的方式处理,处理完成后,回调通知用户处理结果。

支持的 API: FORM API

参数名是 apps,参数值是 JSON 数组。一个 apps 最多允许包含 10 个音视频处理任务。 任务参数见功能

举例

apps = [
    {                                               // 异步音视频处理任务
        "name": "naga",                             // 异步任务名称,必填。naga 表示异步音视频处理服务
        "type": "<type>",                           // 功能标识,必填
        "avopts": "<avopts>",                       // 处理参数,必填
        "return_info": true/false,                  // 是否返回元数据,选填
        "save_as": "<save_as>",                     // 结果音频/视频保存路径,选填
        "notify_url": "<notify_url>"                // 回调地址,不填时使用上传参数中的 notify_url
    },
    {
        "name": "naga",
        "type": "video",
        "avopts": "/s/240p(4:3)/as/1/r/30",
        "return_info": true,
        "save_as": "/a/b.mp4",
    },
    ......
]

回调通知

任务处理完成后,向 notify_url 地址发送回调通知。详见 「音视频处理」 > 「回调通知」。


进度查询

请求方法

通过 task_id,以 GET 方法向 http://p0.api.upyun.com/status/ 提交进度查询任务。

curl http://p0.api.upyun.com/status?service=<service>&task_ids=<task_id1>,<task_id2>,<task_id3> \
    -H "Authorization: UPYUN <Operator>:<Signature>" \
    -H "Date: <Wed, 29 Oct 2014 02:26:58 GMT>"

认证鉴权

Authorization 详见签名认证

代码实现 详见代码示例

查询参数

参数 类型 必选 说明
service string 音/视频文件所在的服务名
task_ids string 任务集,多个 task_id 使用 , 连接,最多 20 个 task_id

响应信息

{
  "tasks": {
      "35f0148d414a688a275bf915ba7cebb2": 100,
      "98adbaa52b2f63d6d7f327a0ff223348": 20,
      "c3103189fa906a5354d29bd807e8dc51": null,
      …
  }
}

20 表示任务进度百分比,100 表示任务处理完成,-1 表示任务处理失败,null 表示任务尚未开始。如果长时间是 null,请反馈给售后或您的商务经理。


结果查询

请求方法

通过 task_id,以 GET 方法向 http://p0.api.upyun.com/result/ 提交处理结果查询任务。

curl http://p0.api.upyun.com/result?service=<service>&task_ids=<task_id1>,<task_id2>,<task_id3> \
    -H "Authorization: UPYUN <Operator>:<Signature>" \
    -H "Date: <Wed, 29 Oct 2014 02:26:58 GMT>"

认证鉴权

Authorization 详见签名认证

代码实现 详见代码示例

查询参数

参数 类型 必选 说明
service string 音/视频文件所在的服务名
task_ids string 任务集,多个 task_id 使用 , 连接,最多 20 个 task_id

响应信息

{
    "9d9c32b63a1034834e77672c6f51f661": {
        "path": ["/v2.mp4"],
        "signature": "4042c1f07f546d28",
        "status_code": 200,
        "service": "service",
        "description": "OK",
        "task_id": "9d9c32b63a1034834e77672c6f51f661",
        "timestamp": 1472010905
    },
    "3438a54b4991e8d4a46a003bc15e9867": {
        "path": ["/v2.mp4"],
        "signature": "1c49be9b672394ff",
        "status_code": 200,
        "service": "service",
        "description": "OK",
        "task_id": "3438a54b4991e8d4a46a003bc15e9867",
        "timestamp": 1472010684
    }
    …
}

状态码表

状态码 说明
200 处理成功
400 参数错误
401 参数错误
404 文件不存在
5xx 服务端错误。如遇此类错误,请反馈给售后或您的商务经理

支持格式

类型 输入格式 输出格式
视频容器格式 AVI、MP4、FLV、MOV、3GP、ASF、WMV、M3U8(TS)、MPG、F4V、M4V、MKV、VOB(SVCD/DVD)等 MP4、FLV、M3U8(TS) 等
音频容器格式 MP3、OGG、M4A、SILK 等 MP4、MP3、OGG 等
视频编码格式 H.264/AVC 、H.263、H.263+、MPEG-2、MPEG-4、VP8、VP9、Quicktime、RealVideo、Windows Media Video 等 H.264/AVC、VP8、H.265/HEVC、VP9 等
音频编码格式 MP1、MP2、MP3、AAC、AC-3、Vorbis、PCM、RealAudio、Windows Media Audio 等 AAC、MP3 等

预置模板

同等清晰度下,建议优先使用 16:9 的宽高比。特别地,窄带高清也可以使用。

清晰度 模板名 分辨率 码率
4K 2160p(16:9) 3840x2160,16:9 ≤ 8000Kbps
2K 1440p(16:9) 2560x1440,16:9 ≤ 4000Kbps
FHD/全高清 1080p(16:9) 1920x1080,16:9 ≤ 2560Kbps
HD/高清 720p(16:9) 1280x720,16:9 ≤ 1500Kbps
HD/高清 720p(4:3) 960x720,4:3 ≤ 1500Kbps
LD/标清 540p(16:9) 960x540,16:9 ≤ 800Kbps
LD/标清 480p(16:9) 854x480,16:9 ≤ 800Kbps
SD/流畅 480p(4:3) 640x480,4:3 ≤ 500Kbps
SD/流畅 360p(16:9) 640x360,16:9 ≤ 500Kbps
SD/流畅 240p(4:3) 320x240,4:3 ≤ 300Kbps

视频转码

参数 类型 必选 说明
type string 固定值,video,表示标准转码
avopts string 视频转码参数,格式为 /key1/value1/key2/value2/...,参数见「参数」
save_as string 输出文件保存路径,默认使用原始视频所在目录+系统随机生成的文件名+原始视频后缀
return_info boolean 回调信息是否包含输出文件的元数据,元数据格式为 JSON,默认 false

常用参数

参数 类型 必选 说明
/vb/<bitrate> integer 视频比特率,单位 kbps,默认按照视频原始比特率处理
/s/<scale> string 视频分辨率,默认按照原始分辨率处理。见「注」
/as/<auto_scale> boolean 是否根据分辨率自动调整视频的比例,默认 false。仅当传递了 s 参数时有效
/r/<frame_rate> integer 视频帧率,默认按照原始帧率处理。推荐值:2530
/sp/<rotate> string 旋转角度,默认按照原始视频角度处理。可选值:auto(自动扶正)90180270
/sm/<map_metadata> boolean 是否保留视频元数据,默认 true
/acodec/<audio_codec> string 设置音频编码器,默认按照音频原始编码器处理。可选值:libmp3lamelibfdk_aaccopy
/vcodec/<video_codec> string 设置视频编码器,默认按照视频原始编码器处理。可选值:libx264libtheoralibx265libvpx-vp9libvpxcopy
/an/<disable_audio> boolean 是否禁掉音频,默认 false
/vn/<disable_video> boolean 是否禁掉视频,默认 false
/su/<accelerate_factor> float 视频加速倍数,默认 1.0。取值范围 [1.0,10.0]
/ar/<audio_sample_rate> integer 音频采样率,单位 Hz,默认按照原始采样率处理。可选值:4410048000320002205024000160000
/ac/<audio_channel> float 音频声道数,默认按照原始声道数处理。常用值:1表示单声道(mono),2表示立体声(stereo),5.17.1
/sar/<sar> string 采样长宽比,格式 w:h,常用值 1:14:316:9
/dar/<dar> string 显示长宽比,格式 w:h,常用值 1:14:316:9
/pv/<pv> string H264 Profile,常用值 baselinemainhigh
/level/<level> float H264 Level,常用值 3.03.14.04.14.2
/f/<format> string 视频格式。当输出文件没有后缀时,需要指定,其余时候根据输出文件后缀名自动判定

切片参数

参数 类型 必选 说明
/ht/<hls_time> string 每片时长,单位 s(秒),默认 10

水印参数

参数 类型 必选 说明
/wmImg/<watermark_img> string 水印图片相对路径,需要安全的 Base64 编码。图片格式支持 pngwebp
/wmGravity/<wmGravity> string 水印图片放置方位,默认 northeast。见「注」
/wmDx/<watermark_dx> integer 水印图片横偏移量,单位 px,当 wmGravitynortheast 时,默认 -20
横偏移量取值正负的依据:往 east 方向偏移,为正;往 west 方向偏移,为负
/wmDy/<watermark_dy> integer 水印图片纵偏移量,单位 px,当 wmGravitynortheast 时,默认 15
纵偏移量取值正负的依据:往 south 方向偏移,为正;往 north 方向偏移,为负

northwest     |     north      |     northeast
              |                |
              |                |
--------------+----------------+--------------
              |                |
west          |     center     |          east
              |                |
--------------+----------------+--------------
              |                |
              |                |
southwest     |     south      |     southeast

剪辑参数

参数 类型 必选 说明
/ss/<start_time> string 剪辑开始时间,格式为 HH:MM:SS,默认视频开始时间
/es/<end_time> string 剪辑结束时间,格式为 HH:MM:SS,默认视频结束时间

动图参数

save_as 的后缀名指定为 gifwebp,实现视频转码成动态图片。

参数 类型 必选 说明
/cr/<concat_reverse> boolean 向视频结尾处添加倒序的内容。功能效果是,正序内容+倒序内容

拼接参数

拼接的视频分辨率需要保持一致,拼接参数不能与其他参数混用。如果要混用,请分做两个任务,使用链式处理

参数 类型 必选 说明
/i/<video> string 需要后置拼接视频文件的相对路径,需要安全的 Base64 编码
多个需要拼接视频按 /i/<video>/i/<video>/... 方式进行连接。见「注」
/h/<video> string 需要前置拼接视频文件的相对路径,需要安全的 Base64 编码
多个需要拼接视频按 /h/<video>/h/<video>/... 方式进行连接。见「注」
/codec/<codec> string 设置视频编码器,默认不需要设置。可选值:copy。见「注」


窄带高清

通过对视频的编码进行优化,平均降低视频大小 30%。特别地,暂时只支持 H.264 编码。

参数 类型 必选 说明
type string 固定值,nbhd,表示窄带高清
avopts string 视频转码参数,格式为 /key1/value1/key2/value2/...,参数见「参数」
return_info boolean 回调信息是否包含输出文件的元数据,元数据格式为 JSON,默认 false
save_as string 输出文件保存路径,默认原始视频所在目录+系统随机生成的文件名

常用参数

参数 类型 必选 说明
/ct/<codec_type> string 视频编码器选择,默认 h264,可选值只能是h264或者h265
/scene/<scene> string 视频内容场景,默认 auto,服务根据视频内容智能选择。场景参数见「注」
/s/<scale> string 视频分辨率,默认按照原始分辨率处理。见「注」
/as/<auto_scale> boolean 是否根据分辨率自动调整视频的比例,默认 false。仅当传递了 s 参数时有效
/r/<frame_rate> integer 视频帧率,默认按照原始帧率处理。推荐值:2530
/sp/<rotate> string 旋转角度,默认按照原始视频角度处理。可选值:auto(自动扶正)90180270
/sm/<map_metadata> boolean 是否保留视频元数据,默认 true
/su/<accelerate_factor> float 视频加速倍数,默认 1.0。取值范围 [1.0,10.0]
/ar/<audio_sample_rate> integer 音频采样率,单位 Hz,默认按照原始采样率处理。可选值:4410048000320002205024000160000
/f/<format> string 视频格式。当输出文件没有后缀时,需要指定,其余时候根据输出文件后缀名自动判定

切片参数

参数 类型 必选 说明
/ht/<hls_time> string 每片时长,单位 s(秒),默认 10

水印参数

参数 类型 必选 说明
/wmImg/<watermark_img> string 水印图片相对路径,需要安全的 Base64 编码。图片格式支持 pngwebp
/wmGravity/<wmGravity> string 水印图片放置方位,默认 northeast。见「注」
/wmDx/<watermark_dx> integer 水印图片横偏移量,单位 px,当 wmGravitynortheast 时,默认 -20
横偏移量取值正负的依据:往 east 方向偏移,为正;往 west 方向偏移,为负
/wmDy/<watermark_dy> integer 水印图片纵偏移量,单位 px,当 wmGravitynortheast 时,默认 15
纵偏移量取值正负的依据:往 south 方向偏移,为正;往 north 方向偏移,为负

northwest     |     north      |     northeast
              |                |
              |                |
--------------+----------------+--------------
              |                |
west          |     center     |          east
              |                |
--------------+----------------+--------------
              |                |
              |                |
southwest     |     south      |     southeast

剪辑参数

参数 类型 必选 说明
/ss/<start_time> string 剪辑开始时间,格式为 HH:MM:SS,默认视频开始时间
/es/<end_time> string 剪辑结束时间,格式为 HH:MM:SS,默认视频结束时间

视频截图

参数 类型 必选 说明
type string 固定值,thumbnail
avopts string 视频转码参数,格式为 /key1/value1/key2/value2/...,参数见「截图参数」
return_info boolean 回调信息是否包含输出文件的元数据,元数据格式为 JSON,默认 false
save_as string 输出文件保存路径,默认原始视频所在目录+系统随机生成的文件名。见「注」

截图参数

参数 类型 必选 说明
/o/<thumb_single> boolean 是否单张截图,单张截图为 true,多张截图为 false
/n/<thumb_amount> integer 截图数量。当 o 参数为 false 时,有效;当 o 参数为 true 时,无效
/ss/<thumb_start> string 截图开始时间,格式为 HH:MM:SS,默认 00:00:00
/es/<thumb_end> string 截图结束时间,格式为  HH:MM:SS,默认视频结束时间。当 o 参数为 true 时,无效
/s/<thumb_scale> string 截图尺寸,格式为 宽:高,默认视频原始尺寸
/f/<thumb_format> string 截图输出格式,默认 jpg。图片格式支持 pngjpg。见「注」


音频转码

参数 类型 必选 说明
type string 固定值,audio
avopts string 视频转码参数,格式为 /key1/value1/key2/value2/...,参数见「参数」
return_info boolean 回调信息是否包含输出文件的元数据,元数据格式为 JSON,默认 false
save_as string 输出文件保存路径,默认原始音频所在目录+系统随机生成的文件名

常用参数

参数 类型 必选 说明
/f/<format> string 音频格式,当输出文件没有后缀时,需要指定,其余时候根据输出文件后缀名自动判定
/ac/<audio_channel> integer 声道,默认 2
/ab/<audio_bitrate> integer 比特率,单位 kbps,默认按照音频原始比特率处理
/vbr/<audio_vbr> integer Variable bitrate, 默认按照音频原始 VBR 处理。取值范围 [0-9]
/sm/<map_metadata> boolean 是否保留音频 metadata,默认 true

剪辑参数

拼接参数不能与其他参数混用,请注意。如果要混用,请分做两个任务,使用链式处理

参数 类型 必选 说明
/ss/<start_time> string 剪辑开始时间,格式为 HH:MM:SS,默认视频开始时间
/es/<end_time> string 剪辑结束时间,格式为 HH:MM:SS,默认视频结束时间

拼接参数

拼接参数不能与其他参数混用。如果要混用,请分做两个任务,使用链式处理

参数 类型 必选 说明
/i/<audio> string 需要拼接音频文件的相对路径,需要安全的 Base64 编码
多个需要拼接音频文件按 /i/<audio>/i/<audio>/... 方式进行连接


元数据获取

获取音/视频文件的元信息。

参数 类型 必选 说明
type string 固定值,probe

链式处理

多个任务按提交任务参数的先后顺序,对原文件进行链式处理。

参数 类型 必选 说明
type string 固定值,chain
avopts string 链式处理参数,格式为 /type1/key1/value1/type2/key2/value2...,参数见「参数」
return_info boolean 回调信息是否包含输出文件的元数据,元数据格式为 JSON,默认 false
save_as string 输出文件保存路径,默认原始音频所在目录+系统随机生成的文件名

链式处理参数

参数 类型 必选 说明
/<type>/<avopts> string 多个功能标识 type 以及其对应的处理参数 avopts

请求样例

{
    "type": "chain",
    "avopts": "/video/i/Zm9vLm1wNA==/video/s/480p(16:9)/wmImg/L3Rlc3QvbG9nby5wbmc=",
    "save_as": "/foo.jpg"
}

上述任务先解析 /video/i/Zm9vLm1wNA== 部分,和源视频进行拼接;之后解析 /video/s/480p(16:9)/vb/300/r/25/vcodec/libx264/wmImg/L3Rlc3QvbG9nby5wbmc=,将上一步输出的视频的分辨率转码成 480p(16:9) 并同时加上水印;最后输出文件保存至 /foo.mp4


如有疑问请 联系我们