mediakit 视频剪辑 API​

POST https://api.yu-yu.ai/mediakit/v1/tools/trim-video

本接口对应火山引擎 AI MediaKit 的「视频裁剪（trim-video）」能力：根据指定的开始与结束时间点，从一个较长的视频文件中精确截取片段，生成一个全新的视频文件。提交成功后会返回一个任务 ID，您可以再按任务 ID 查询任务状态并获取裁剪结果。

能力说明​

• 按时间点截取：传入源视频地址与开始、结束时间（单位：秒，支持最多两位小数），服务从源视频中切出该时间段的内容。
• 异步任务：提交接口只负责创建任务，结果需要通过查询接口按 task_id 轮询获取。
• 输出格式：裁剪结果统一输出为 MP4；输出分辨率默认与源视频保持一致。
• 产物地址：未指定落盘位置时返回带有效期的临时下载地址；指定落盘位置后返回对应存储的资源地址。

鉴权​

本接口仅支持 API Key 鉴权，请在 https://api.yu-yu.ai/console 获取 API Key。

调用时需在请求头中携带：

Authorization: Bearer <API_KEY>

提交剪辑任务​

POST https://api.yu-yu.ai/mediakit/v1/tools/trim-video

Body 参数​

model string 必选

调用的模型 ID，本接口固定为 mediakit_trim_video。

video_url string 必选

待裁剪的视频地址。

• 必须是公网可访问的 http:// 或 https:// 地址，长度不超过 2048 个字符。
• 请确保地址在任务执行期间保持可访问、且在有效期内，否则任务会因下载源文件失败而失败。

start_time number 可选

裁剪开始时间，单位为秒，支持最多两位小数。

• 默认值为 0，表示从视频开头开始裁剪。
• 取值范围 [0, 3600]。
• 必须小于 end_time。

end_time number 可选

裁剪结束时间，单位为秒，支持最多两位小数。

• 取值范围 (0, 3600]。
• 必须大于 start_time。
• 建议始终显式传入：本接口默认要求提供 end_time，未传入时提交请求会被拒绝。

media_output_destination string 可选

指定处理产物的目标存储位置，必须以 vod:// 或 tos:// 开头。

• 存储至 VOD：vod://<空间名>
• 存储至 TOS：tos://<桶名>

设置本参数后，任务结果中的地址类字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。

client_token string 可选

用户请求凭证，用于幂等控制。

• 大小写敏感，不超过 64 个 ASCII 可打印字符（0x21~0x7e，即不含空格与控制字符）。
• 携带相同 client_token 的重复提交会返回同一个任务，不会重复创建任务。

callback_args string 可选

自定义回调参数。您提供的内容会在任务完成时通过回调原样返回，便于关联自有业务。

• 最大 512 字节。

callback_url string 可选

用于接收该任务结果回调的地址。

• 必须以 http:// 或 https:// 开头，长度不超过 2048 个字符。
• 传入后，该地址优先于服务侧配置的默认回调地址。

queue_id string 可选

任务提交的目标队列 ID。

• 长度不超过 128 个字符。
• 不传时使用系统自动创建的默认队列。
• 可将不同业务或优先级的任务提交到不同队列，便于按队列管理。

响应参数​

提交成功后同步返回，HTTP 状态码为 200。

success boolean

任务是否提交成功。

• true：提交成功。
• false：提交失败，错误详情见 error 字段。

task_id string

任务的唯一标识。请保存该值，后续通过查询接口获取进度与结果。

request_id string

本次请求的唯一标识，可用于问题排查。

查询任务​

GET https://api.yu-yu.ai/mediakit/v1/tasks/{task_id}

查询指定任务的当前状态与最终结果。任务状态与结果在同一次查询中返回，按固定间隔轮询本接口，直到 status 进入终态即可。

Path 参数​

task_id string 必选

需要查询的任务 ID，取自提交接口的响应体。

响应参数​

success boolean

标识本次查询请求本身是否被成功处理，不代表任务的执行状态。

• true：服务端成功处理了本次查询。
• false：查询请求失败，原因见 error 字段。

task_id string

所查询任务的唯一标识。

task_type string

任务类型，本接口的任务类型为 trim-video。

status string

任务当前状态，取值见任务状态说明。

result object

任务成功时返回的结果对象，仅当 status 为 completed 时返回。

• result.video_url string：裁剪后视频的文件地址，格式为 MP4。
  • 未设置 media_output_destination 时：返回一个 https 临时下载地址，有效期为 24 小时，请及时下载或转存。
  • 设置了 media_output_destination 时：返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 形式的存储地址。
• result.duration number：输出视频的时长，单位：秒，可能带小数。
• result.resolution string：输出视频的分辨率，例如 1080p（默认与源视频一致）。

error object

任务失败时返回的错误详情对象，仅当 status 为 failed 时返回。

• error.code string：错误码，例如 DownloadFailed。
• error.message string：错误描述信息，用于展示或记录日志。
• error.param string：可选，指示导致错误的具体参数名。
• error.type string：错误类型。任务执行出错时为 TaskError。

expires_at integer

任务结果的过期时间戳（Unix 时间戳，单位：秒）。仅当任务成功且有结果时返回。

created_at integer

任务创建时间戳（Unix 时间戳，单位：秒）。

finished_at integer

任务完成时间戳（Unix 时间戳，单位：秒），仅当 status 为 completed 或 failed 时返回。

request_id string

本次查询请求的唯一标识，可用于问题排查。

queue_id string

任务所属的队列 ID。

请求示例​

提交剪辑任务

curl -X POST 'https://api.yu-yu.ai/mediakit/v1/tools/trim-video' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "mediakit_trim_video",
    "video_url": "https://example.com/full_video.mp4",
    "start_time": 10.5,
    "end_time": 60
  }'

查询任务

curl -X GET 'https://api.yu-yu.ai/mediakit/v1/tasks/{task_id}' \
  -H 'Authorization: Bearer <API_KEY>'

响应示例​

提交成功

{
  "success": true,
  "task_id": "task-1a2b3c4d5e6f7g8h",
  "request_id": "req_9f8e7d6c5b4a39281706"
}

查询：任务进行中

{
  "success": true,
  "task_id": "task-1a2b3c4d5e6f7g8h",
  "task_type": "trim-video",
  "status": "running",
  "created_at": 1777291767,
  "request_id": "req_9f8e7d6c5b4a39281706"
}

查询：任务成功

{
  "success": true,
  "task_id": "task-1a2b3c4d5e6f7g8h",
  "task_type": "trim-video",
  "status": "completed",
  "result": {
    "video_url": "https://example.com/trimmed_output.mp4?auth_key=...",
    "duration": 49.5,
    "resolution": "1080p"
  },
  "expires_at": 1777464650,
  "created_at": 1777291767,
  "finished_at": 1777291851,
  "request_id": "req_9f8e7d6c5b4a39281706"
}

查询：任务失败

{
  "success": true,
  "task_id": "task-1a2b3c4d5e6f7g8h",
  "task_type": "trim-video",
  "status": "failed",
  "error": {
    "code": "DownloadFailed",
    "message": "Failed to download file from the provided URL. Please check if the URL is correct and publicly accessible.",
    "param": "video_url",
    "type": "TaskError"
  },
  "created_at": 1777291767,
  "finished_at": 1777291802,
  "request_id": "req_9f8e7d6c5b4a39281706"
}

参数错误（提交阶段同步返回）

{
  "success": false,
  "task_id": "",
  "request_id": "req_9f8e7d6c5b4a39281706",
  "error": {
    "code": "InvalidParameter",
    "message": "end_time 必须大于 start_time",
    "param": "end_time",
    "type": "BadRequest"
  }
}

任务状态说明​

常见错误​

HTTP 状态码与错误码

任务级错误

当查询响应中 status 为 failed 时，错误详情位于 error 对象内，error.type 恒为 TaskError，error.code 由服务返回（例如 DownloadFailed）。