You need to enable JavaScript to run this app.
文档中心
视频点播

视频点播

复制全文
下载 pdf
调用方式
如何调用 OpenAPI
复制全文
下载 pdf
如何调用 OpenAPI

本文档介绍在不同开发阶段调用视频点播 OpenAPI 的方法,帮助您从快速测试顺利过渡到生产环境的稳定集成。

准备工作

调用视频点播 OpenAPI 前,需获取 API 访问密钥(AK/SK)。其中,AK(Access Key ID)用于标识调用者身份,SK(Secret Access Key)用于计算请求签名。您可以在 API 访问密钥页面创建并获取 AK/SK,具体操作请参见 API 访问密钥管理

主账号拥有资源的所有权限,其访问密钥一旦泄露,可能威胁账号下所有资源的安全。建议您创建仅具备所需最小权限的 IAM 用户,并使用该用户的 AK/SK 调用 OpenAPI。具体操作请参见 创建 IAM 用户并授权。请妥善保管 SK,避免将 AK/SK 明文写入工程代码或提交到代码仓库。

测试与调试

方式 1:通过 API Explorer 在线调试

在开发初期,推荐使用火山引擎提供的 API Explorer 工具。它集成了在线调试、签名生成和代码示例等功能,可以极大提升您的调试效率。

  1. 登录 API Explorer
  2. 在页面左侧导航栏切换版本号,并找到您想要调试的 OpenAPI。
  3. 仔细阅读页面右侧的文档说明,了解接口的功能和参数要求。
  4. 输入参数区域填写请求参数。
  5. 单击发起调试按钮。
  6. 调试结果页签下,您可以查看完整的响应结果、响应头和原始请求数据。
    Image

方式 2:获取可运行的 curl 命令

除了直接在线调试,API Explorer 还提供强大的签名与代码生成功能。您填写完参数后,它可以自动生成一个包含了正确签名的、可直接在终端执行的 curl 命令,以便您快速进行本地测试或排查问题。

  1. 前往 API Explorer,填写以下信息:
    1. 输入参数区域填写必填参数。
    2. 签名工具页签下填写 AK/SK/Host。
      Image
  2. 单击生成签名
  3. 签名工具页签最下方即可获取 curl 命令。
    Image

生产环境集成

当您需要在生产环境的应用程序中调用 OpenAPI 时,视频点播提供以下两种方式。

方式 1:集成服务端 SDK(推荐)

强烈建议您在项目中集成火山引擎官方提供的服务端 SDK。SDK 封装了所有底层的通信逻辑,尤其是处理了复杂的请求签名过程。您只需关注业务逻辑的实现,通过简单的方法调用即可发起 API 请求,极大地降低了开发门槛和出错风险。

SDK 版本说明

视频点播的 OpenAPI 正在逐步从 V1.0 SDK 迁移至新一代的 V2.0 SDK

  • V2.0 SDK:架构更统一,设计更规范,是未来的主要方向。推荐优先使用
  • V1.0 SDK:用于调用 V2.0 暂未覆盖的存量接口。

如何选择 SDK 版本?

在当前过渡阶段,V2.0 SDK 支持的接口还很有限。因此,如果您的业务需要使用完整的视频点播功能(例如,既要上传视频,又要进行 AI 处理,然后获取处理后的视频地址),您必须在项目中同时集成 V1.0 和 V2.0 两个版本的 SDK。推荐的集成与调用策略:

  1. 同时集成:在您的项目中,同时添加 V1.0 和 V2.0 两个 SDK 的依赖。
  2. 按需调用
    • 当需要调用下文“V2.0 支持列表”中的接口时,使用 V2.0 SDK 的客户端实例。
    • 当需要调用下文“V2.0 支持列表”之外的所有其他接口(如 GetPlayInfo, UploadMediaByUrl 等)时,使用 V1.0 SDK 的客户端实例。
  3. 关注更新:建议您定期关注 V2.0 SDK 的版本更新日志,以便在新接口获得支持后,逐步将调用逻辑迁移至 V2.0。

V2.0 SDK:集成与使用

V2.0 支持列表

功能模块

OpenAPI

媒体处理

AI 视频翻译

V2.0 源码地址和集成说明

编程语言

源码地址

集成文档

Java

volcengine-java-sdk

集成 SDK

Python

volcengine-python-sdk

集成 SDK

PHP

volcengine-php-sdk

集成 SDK

Go

volcengine-go-sdk

集成 SDK

Node.js

暂不支持

V2.0 调用示例

本节以 StartExecution - 提交媒体处理任务接口为例,展示使用 VOD SDK V2.0 时如何调用点播接口。

import com.volcengine.ApiClient;
import com.volcengine.ApiException;
import com.volcengine.sign.Credentials;
import com.volcengine.vod20250101.Vod20250101Api;
import com.volcengine.vod20250101.model.*;

public class TestVod20250101 {
    public static void main(String[] args) throws Exception {
        // 请在环境变量或本地 ~/.volc/config 文件中配置您的 Access Key ID (AK) 和 Secret Access Key (SK)。详细说明,请见 https://www.volcengine.com/docs/4/65641。
        // SDK 会自动从环境变量或 ~/.volc/config 文件中读取 AK 和 SK。
        // 在测试过程中,您可以使用以下代码片段。但是请勿直接将 AK 和 SK 保存到工程代码中,否则可能导致 AK 和 SK 泄露,威胁您账号下所有资源的安全。
        String ak = "your ak"; // 替换成你自己的 AK
        String sk = "your sk"; // 替换成你自己的 SK
        String region = "cn-north-1";

        ApiClient apiClient = new ApiClient()
                .setCredentials(Credentials.getCredentials(ak, sk))
                .setRegion(region);
        Vod20250101Api vod20250101Api = new Vod20250101Api(apiClient);
        StartExecutionRequest request = new StartExecutionRequest();
        InputForStartExecutionInput input = new InputForStartExecutionInput();
        input.setType("Vid");
        input.setVid("v1234567890test1234567890");
        request.setInput(input);
        OperationForStartExecutionInput operation = new OperationForStartExecutionInput();
        operation.setType("Task");
        TaskForStartExecutionInput task = new TaskForStartExecutionInput();
        task.setType("Highlight");
        HighlightForStartExecutionInput highlight = new HighlightForStartExecutionInput();
        task.setHighlight(highlight);
        operation.setTask(task);
        request.setOperation(operation);
        ControlForStartExecutionInput control = new ControlForStartExecutionInput();
        control.setClientToken("testToken");
        request.setControl(control);


        try {
            StartExecutionResponse response = vod20250101Api.startExecution(request);
            System.out.println(response);
        } catch (ApiException e) {
            System.out.println(e.getResponseBody());
        }
    }
}

V1.0 SDK:集成与使用

除上述 V2.0 列表之外的所有其他视频点播 OpenAPI,目前仍需使用 V1.0 SDK 进行调用。

编程语言

源码地址

集成文档

Java

volc-sdk-java

集成 Java SDK

Python

volc-sdk-python

集成 Python SDK

PHP

volc-sdk-php

集成 PHP SDK

Go

volc-sdk-golang

集成 Go SDK

Node.js

volc-sdk-nodejs

安装

方式 2:手动构造请求

如果您使用的编程语言没有官方 SDK 支持,或有其他特殊需求,您可以自行构造完整的 HTTP 请求。此方式要求您在代码中手动处理所有请求细节,特别是签名计算部分

完整请求结构

一个有效的 OpenAPI 请求必须包含:请求行 + 请求头(含签名)+ 请求体。完整结构如下:

# -------------------- Part 1: 请求行 --------------------
[Method] https://[Host]/?Action=[Action]&Version=[Version]

# -------------------- Part 2: 请求头 --------------------
Host: [参考下文说明]   
Content-Type: [参考下文说明] 
X-Date: [动态生成的当前 UTC 时间]
X-Content-Sha256: [根据 Part 3 请求体计算出的 SHA256 哈希值]
Authorization: [必须生成签名,用于鉴权]

# -------------------- Part 3: 请求体 --------------------
# 对于 POST 请求,这里是“接口特有参数”
{
    "Parameter1": "Value1",
    "Parameter2": "Value2",
    ...
}

各部分详细说明

请求行
[Method] https://[Host]/?Action=[Action]&Version=[Version]
  • [Method][Host][Action][Version]:可在具体 OpenAPI 文档中获取。以 StartExecution 接口为例,如下图所示:
    Image
  • [Host]:服务接入地址,请参见服务地址

请求头(需携带鉴权签名)

参数

如何获取 / 构造

[Host]

服务接入地址,与请求行中的 Host 保持一致。

[Content-Type]

资源的 MIME 类型。对于 POST 请求,固定为 application/json;Get 请求中,该值可为空。

[X-Date]

请求时间, UTC 格式(ISO 8601),精确到秒,例如 20201230T081805Z

[X-Content-Sha256]

请求体的 SHA256 哈希值。若请求体为空,则使用一个固定的哈希值。

[Authorization]

签名鉴权。为保证请求者身份的合法性以及请求在传输过程中不被恶意篡改,火山引擎会对每一个 OpenAPI 请求进行签名验证。服务端会使用相同的机制对收到的请求计算签名,并与您在请求中提供的签名进行比对。若验证失败,请求将被拒绝。详细的签名构造流程和加密算法,请参见签名方法

  • 快速获取签名:可使用 API Explorer 的签名工具功能,输入 AK、SK、服务地址等信息,自动生成请求签名和可执行的 curl 命令,可直接用于测试或作为代码参考。详见获取可运行的 curl 命令
  • 手动构造签名:火山引擎提供了多种语言的签名示例代码,您可以直接参考或修改使用。
    • 签名示例代码GolangPythonJavaPHPNode.js
    • 如何使用签名示例代码:上述示例是一个通用的框架。您需要根据具体需求修改文件中的配置信息和调用参数。
      • 替换配置变量
        • AKSK:在 API访问密钥页面创建并获取。
        • Service:视频点播的服务名固定为 vod
        • RegionHost:请参见服务地址
      • 设置接口参数
        • Action / Version:可在具体 OpenAPI 文档中获取
        • BodyQuery:根据具体 OpenAPI 文档的要求填写您的业务参数。

请求体

JSON 格式,包含接口所需的业务参数。详细结构和字段说明,请参见对应的 OpenAPI 文档。

最近更新时间:2026.07.29 10:45:00
这个页面对您有帮助吗?
有用
有用
无用
无用