TUTUCLOUD eva 视频融合 API 文档

接口鉴权

参数 sign 生成步骤：

1. 抽取所有请求参数 (类型为 file 的参数不参与签名)。
2. 对 参数名 以字典升序 (a-z) 进行排序。

    sortedParams = {
        "key1": "value1",
        "key2": "value2"
    }

3. 以 参数名参数值 的形式拼接排序后的参数。

    stringParams = "key1value1key2value2"

4. 把从控制台创建应用后获取的私钥 api_secret 作为后缀拼接到上一步生成的字符串后面, 得到 待签名字符串。

    stringParams = "key1value1key2value2api_secret"

5. 最后再对 待签名字符串 用 MD5 摘要算法，得到签名结果 sign (32位小写)。

    sign = md5("key1value1key2value2api_secret")

6. 校验工具

签名示例：

私钥 api_secret = "my_api_secret"

请求参数 = {
   "url": "http://my.test/my.jpg", 
   "api_key": "my_api_key",
   "timestamp": 123456
}

排序后参数 = {
    "api_key": "my_api_key",
    "timestamp": 123456,
    "url": "http://my.test/my.jpg"
}

待签名字符串 = "api_keymy_api_keytimestamp123456urlhttp://my.test/my.jpgmy_api_secret"

sign = "be83843c50dbfe8211256694c1cc5c58"

普通模板 视频渲染请求

POST https://api.eva.tutucloud.com/v1/render

HTTP header

Content-Type: multipart/form-data

参数

参数名	类型	是否必填	说明
api_key	string	是	应用 api_key
sign	string	是	参数签名
tpl_id	int	是	模板ID
tpl_version	string	否	模板版本 (默认取最新版本)
assets	json (array)	是	替换素材数组, 详见 assets 参数 表
args	json	否	渲染可选参数, 详见 args 参数 表
notify_url	string	否	渲染结果异步通知地址.
timestamp	int	否	unix时间戳, 从接口 /timestamp 获取

assets 参数

该参数类型为json数组, 每一个数组项为替换素材的描述。 可替换素材类型为 ( 视频, 图片, 音频, 文本 ), 对应的 id 为 (video_x, image_x, audio_x, text_x)

参数名	类型	是否必填	说明
id	string	是	替换资源 id, 见 模板 可替换素材列表
value	string	是	type 类型为 text, 值为替换的文本内容, 其它类型为 替换文件的 url 链接
audio_mix_weight	float	否	混音系数, 范围 [0, 1], 仅 (video, image, audio) 可用
repeat	int	否	音视频循环, 可选值 [1: 不循环, 2: 循环], 默认值为 2 循环
fill_style	enum	否	替换素材的填充方式, 仅 (video, image) 可用, 枚举值 0: (默认值) 内容拉伸填充, 不保证保持原有的比例, 1: 保持原有尺寸比例。但部分内容可能被剪切, 2: 保持原有尺寸比例。内容被缩放

示例：

assets = [
    {
        "id": "video_1",
        "value": "http://test.my/video.mp4",
        "audio_mix_weight": 0.5
    },
    {
        "id": "image_1",
        "value": "http://test.my/image.jpg"
    },
    {
        "id": "text_2",
        "value": "tutucloud eva"
    },
    ...
]

args 参数

参数名	类型	值范围	默认值	说明
scale	float	(0, 1]	1	视频输出缩放比

示例:

args = {
    "scale": 0.5
}

cURL 请求示例

curl -X POST \
https://api.eva.tutucloud.com/v1/render \
-H 'content-type: multipart/form-data' \
-F api_key=39802830831bed188884e193d8465226 \
-F sign=04b29480233f4def5c875875b6bdc3b1 \
-F tpl_id=123 \
-F tpl_version=g234fdsafda12321 \
-F 'assets=[{"id":"image_1", "value":"http://my.test/my.jpg"},{"id":"text_1","value":"my_replace_text"}]' \
-F 'args={"scale":1}'

返回示例

{
    "message": "Success",
    "code": 200,
    "data": {
        "task_id": "GfNE_AXLj0CHizT_9UDVp" // 渲染任务ID, 渲染结果需以此为参数, 请求 /render/task 接口查询
    }
}

如果有提供 notify_url 参数, 服务会在渲染结束后对渲染结果以 POST 方式, 通知内容格式为 content-type:application/json 的形式进行异步通知请求, 如果收到请求返回的 HTTP 响应状态码为 200 则视为通知成功. 如通知失败, 会在6分钟内额外进行7次通知 (分别在 10s 后, 20s 后, 40s 后, 70s 后, 120s 后, 200s 后, 330s 后). 通知内容的 json 示例如下.

// 异步通知内容示例
{
    "message": "Success",
    "code": 200, // 200 为渲染成功, 其它详见返回码
    "task_id": "GfNE_AXLj0CHizT_9UDVp",
    "sign": "14b29480233f4d2f5c875875b6bdc3b3",  // 收到通知请求后需对来源进行验证, 验证方式为 `md5("<task_id>+<api_secret>") == "<sign>"`
    "data": {
        "render_time": 48, // 渲染耗时
        "video": "http://file.eva.tutucloud.com/my.mp4" // 渲染输出视频
    }
}

动态模板 视频渲染请求

POST https://api.eva.tutucloud.com/v1/render/dynamic

HTTP header

Content-Type: multipart/form-data

参数

参数名	类型	是否必填	说明
api_key	string	是	应用 api_key
sign	string	是	参数签名
tpl_id	int	是	模板ID
tpl_version	string	否	模板版本 (默认取最新版本)
assets	json (array)	是	替换素材数组, 详见 assets 参数 表
args	json	否	渲染可选参数, 详见 args 参数 表
notify_url	string	否	渲染结果异步通知地址.
timestamp	int	否	unix时间戳, 从接口 /timestamp 获取

assets 参数

该参数类型为json数组, 每一个数组项为替换素材的描述。 可替换素材类型为 ( 视频, 图片), 关于素材替换说明详细见 用户上传素材和动画模块对应关系

参数名	类型	是否必填	说明
value	string	是	替换文件的 url 链接
fill_style	enum	否	替换素材的填充方式, 枚举值 0: (默认值) 内容拉伸填充, 不保证保持原有的比例, 1: 保持原有尺寸比例。但部分内容可能被剪切, 2: 保持原有尺寸比例。内容被缩放

示例：

assets = [
    {
        "value": "http://test.my/video.mp4"
    },
    {
        "value": "http://test.my/image.jpg",
        "fill_style": 1
    }
    ...
]

args 参数

参数名	类型	值范围	默认值	说明
bgm_path	string			替换背景音乐, 音频文件 URL 链接
scale	float	(0, 1]	1	视频输出缩放比

示例:

args = {
    "bgm_path": "http://test.my/bgm.mp3",
    "scale": 0.5
}

cURL 请求示例

curl -X POST \
https://api.eva.tutucloud.com/v1/render/dynamic \
-H 'content-type: multipart/form-data' \
-F api_key=39802830831bed188884e193d8465226 \
-F sign=04b29480233f4def5c875875b6bdc3b1 \
-F tpl_id=123 \
-F tpl_version=g234fdsafda12321 \
-F 'assets=[{"value":"http://my.test/my.jpg", "fill_style": 2}]' \
-F 'args={"bgm_path": "http://my.test/bgm.mp3"}'

返回示例

{
    "message": "Success",
    "code": 200,
    "data": {
        "task_id": "GfNE_AXLj0CHizT_9UDVp"
    }
}

如果有提供 notify_url 参数, 服务会在渲染结束后对渲染结果以 POST 方式, 通知内容格式为 content-type:application/json 的形式进行异步通知请求, 如果收到请求返回的 HTTP 响应状态码为 200 则视为通知成功. 如通知失败, 会在6分钟内额外进行7次通知 (分别在 10s 后, 20s 后, 40s 后, 70s 后, 120s 后, 200s 后, 330s 后). 通知内容的 json 示例如下.

// 异步通知内容示例
{
    "message": "Success",
    "code": 200, // 200 为渲染成功, 其它详见返回码
    "task_id": "GfNE_AXLj0CHizT_9UDVp",
    "sign": "14b29480233f4d2f5c875875b6bdc3b3",  // 收到通知请求后需对来源进行验证, 验证方式为 `md5("<task_id>+<api_secret>") == "<sign>"`
    "data": {
        "render_time": 48, // 渲染耗时
        "video": "http://file.eva.tutucloud.com/my.mp4" // 渲染输出视频
    }
}

视频渲染状态查询

GET https://api.eva.tutucloud.com/v1/render/task

参数

参数名	类型	是否必填	说明
api_key	string	是	应用 api_key
sign	string	是	参数签名
task_id	string	是	task ID (渲染请求返回)
timestamp	int	否	unix时间戳, 从接口 /timestamp 获取

cURL 请求示例

curl -X GET \
'https://api.eva.tutucloud.com/v1/render/task?task_id=GfNE_AXLj0CHizT_9UDVp&api_key=39802830831bed188884e193d8465226&sign=04b29480233f4def5c875875b6bdc3b1'

返回示例

{
    "message": "Success",
    "code": 200, // 200 为渲染成功, 渲染尚未完成时code为 4300, 其它详见返回码
    "data": {     
        "render_time": 48, // 渲染耗时
        "video": "http://file.eva.tutucloud.com/my.mp4" // 渲染输出视频
    }
}

上传替换素材

POST https://api.eva.tutucloud.com/v1/asset

HTTP header

Content-Type: multipart/form-data

参数

参数名	类型	是否必填	说明
api_key	string	是	应用 api_key
sign	string	是	参数签名
file	file	是	文件 列表
timestamp	int	否	unix时间戳, 从接口 /timestamp 获取

cURL 请求示例 (img)

curl -X POST \
https://api.eva.tutucloud.com/v1/asset \
-H 'content-type: multipart/form-data' \
-F api_key=39802830831bed188884e193d8465226 \
-F sign=04b29480233f4def5c875875b6bdc3b1 \
-F file=@my.jpg \
-F file=@my.mp4

返回示例

{
    "message": "Success",
    "code": 200,
    "data": {
        "urls": [
            "http://file.eva.tutucloud.com/my.jpg",
            "http://file.eva.tutucloud.com/my.mp4"
        ]
    }
}

获取时间戳

GET https://api.eva.tutucloud.com/timestamp

如请求其它接口时传了timestamp参数, 服务器则会和当前时间进行比较, 如晚于服务器当前时间超过60秒, 则会拒绝服务。

参数

无

返回示例

{
  "message": "Success",
  "code": 200,
  "data": {
    "timestamp": 1553249584
  }
}

返回码

返回码	说明
200	请求成功
4000	无效的请求
4001	无效的 api_key 参数
4002	缺少必填参数
4003	签名验证失败
4004	获取上传文件失败
4007	文件格式不支持
4008	文件大小超过最大限制
4009	从 url 下载文件失败
4010	服务未开通
4011	余额不足
4014	url 输入文件未找到或已过期
4100	参数 args 格式错误, 应为 json
4300	task 还未处理完成
4301	参数 assets 格式错误, 应为 json
4302	参数 assets 不能为空
4303	assets 替换素材数量超过最大限制
4304	asset 替换素材名称(re_xx_xx)错误, 或不支持
4305	eva 模板未找到
4306	eva 模板文件下载失败或模板版本已失效
4307	task_id 有误, task未找到
4308	task 处理超时
4309	notify_url 不是有效的 url
4340	模板资源文件缺失
500	内部服务错误
5001	服务处理失败
5003	服务不可用