You need to enable JavaScript to run this app.
视频点播

视频点播

复制全文
OpenAPI 参考
如何调用 OpenAPI
复制全文
如何调用 OpenAPI

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

测试与调试

方式 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 文档。

最近更新时间:2025.12.18 20:25:05
这个页面对您有帮助吗?
有用
有用
无用
无用