You need to enable JavaScript to run this app.
导航
提交转码任务
最近更新时间:2024.11.29 16:12:07首次发布时间:2023.12.25 16:48:06

本接口支持向状态为运行中的任务队列,提交以一条或多条 URL/URI 资源转码执行任务组成的转码任务。

说明

  • 仅当队列为运行中时可向该队列提交任务,请您在控制台或调用 GetImageTranscodeQueues 接口查看任务队列状态是否为运行中。
  • 一条任务队列(QueueId)可包含多个转码任务(TaskId),一个转码任务可由一条或多条 URL/URI 转码执行任务(EntryId)组成。

注意事项

  • 请求频率:单用户请求频率限制为 10 次/秒
  • 超时时间:超时时间为 10 秒
  • 服务地址:veImageX 在全球多个区域部署,每个区域有自己对应的 OpenAPI 域名,不支持跨区域调用。具体详情请查看服务地址

请求说明

  • 请求方式:POST
  • 请求地址:https://imagex.volcengineapi.com/?Action=CreateImageTranscodeTask&Version=2023-05-01

调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数

参数类型是否必选示例值描述
Content-TypeStringapplication/json请求头字段

Query

参数类型是否必选示例值描述
ActionStringCreateImageTranscodeTask接口名称。当前 API 的名称为 CreateImageTranscodeTask
VersionString2023-05-01接口版本。当前 API 的版本为 2023-05-01

Body

参数类型是否必选示例值描述
QueueIdString649a9dbc3***64d44cf5b0任务队列名称 ID。缺省情况下提交至账号默认任务队列。您可通过调用GetImageTranscodeQueues获取该账号下全部任务队列 ID。

ServiceId

String

5s****fo

服务 ID。

  • 您可以在 veImageX 控制台 服务管理页面,在创建好的图片服务中获取服务 ID。
  • 您也可以通过 OpenAPI 的方式获取服务 ID,具体请参考获取所有服务信息
TemplateStringtplv-5s****fo-33.jpeg转码模板。您可通过调用 GetAllImageTemplates 获取指定服务下全部模版信息。

DataType

String

uri

数据类型,取值如下所示:

  • uri:指定 ServiceId 下存储 URI。
  • url:公网可访问的 URL。

DataList

Array of String

["http://demo.com/example.png"]

DataListFilelist二选一必填,同时配置时,DataList优先生效。
待转码的图片 uri 或 url 列表,建议最多不超过 10 万条。

  • DataType取值uri,此处请传入指定 ServiceId 下的存储 URI。
  • DataType取值url,此处请传入公网可访问的 URL。

FileList

Array of String

["tos-cn-i-5s***fo/a.txt","tos-cn-i-5s***fo/uridemo.txt"]

DataListFilelist二选一必填,同时配置时,DataList优先生效。
待转码的图片 uri 或 url 文件列表。具体使用方式如下:

  1. 在 txt、csv 文件内填写指定数据类型的待转码图片地址,每行填写一个,建议最多不超过 10 万条。
  2. 将该文件上传至指定服务后,获取其存储 URI。
  3. 将该存储 URI,传入 FileList
CallbackConfObject of CallbackConf-任务回调配置。缺省情况下默认使用队列回调配置。

ResKeyList

Array of String

["name1","name2"]

转码产物的 Storekey 列表,仅当DataList不为空时有效,长度需与DataList长度一致。不传时默认使用固定规则生成产物的 Storekey。填写规则如下:

  • 使用 UTF-8 编码。
  • 长度必须在 1~1024 个字符之间。
  • 不能以反斜线(\)开头。
  • 不支持 \a\b\t\n\v\f\r 字符。

EnableExif

Boolean

false

转码是否保留 exif。取值如下所示:

  • true:保留
  • false:(默认)不保留

CallbackConf

参数类型是否必选示例值描述
MethodStringHTTP回调方式。仅支持取值HTTP
EndpointStringhttps://demo.com回调 HTTP 请求地址,用于接收转码结果详情。支持使用 https 和 http 协议。

DataFormat

String

JSON

回调数据格式。取值如下所示:

  • XML
  • JSON(默认)
ArgsStringproduct id业务自定义回调参数,将在回调消息的callback_args中透传出去。具体回调参数请参考回调内容

Type

String

task

回调的维度类型,缺省情况下按照条目级别进行回调。取值如下所示:

  • task:将按照任务级别进行回调。可分批回调,一个批次内最多一次性可回调 2 万条图片转码条目执行信息。
  • entry:将按照条目级别进行回调。当该条目执行完毕,将立即产生回调。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数

参数类型示例值描述
TaskIdString649b9d3****5537684010a7任务 ID

请求示例

POST https://imagex.volcengineapi.com/?Action=CreateImageTranscodeTask&Version=2023-05-01
{
    "QueueId": "649a9dbc3***64d44cf5b0",
    "ServiceId": "5s****fo",
    "Template": "tplv-5s****fo-33.jpeg",
    "DataType": "uri",
    "DataList": [],
    "FileList": [
        "tos-cn-i-5s***fo/a.txt",
        "tos-cn-i-5s***fo/uridemo.txt"
    ],
    "ResKeyList": [
        "name1",
        "name2"
    ],
    "EnableExif": true
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "CreateImageTranscodeTask",
        "Version": "2023-05-01",
        "Service": "ImageX",
        "Region": "cn-north-1"
    },
    "Result": {
        "TaskId": "649b9d3****5537684010a7"
    }
}

错误码

本接口无特有的错误码。更多信息请见公共错误码以及 veImageX 错误码

服务端 SDK

veImageX 提供了配套的开发工具集 SDK,支持多种编程语言,帮助您更方便的调用 API。

历史版本

2018-08-01 版本 CreateImageTranscodeTask 接口文档现已停止维护,建议您参考本文档使用最新版本。