帮你快速理解、总结文档立即下载
文档中心>智能媒资托管>SDK 文档>JavaScript SDK>快速入门

快速入门

最近更新时间：2026-09-30 16:51:31
我的收藏

本页目录：

相关资源

智能媒资托管 SMH 的 JavaScript SDK 源码：源码快速下载、smh-js-sdk 包
产品文档：SMH 产品文档
控制台：SMH 控制台

环境配置与准备

浏览器需支持 File API、ArrayBuffer、BigInt、WebAssembly 等基本 HTML5 特性。
说明：
推荐使用 Chrome 67+、Firefox 68+、Safari 14+、Edge 79+ 等现代浏览器。
登录 智能媒资托管控制台，开通 SMH 服务并创建媒体库。获取媒体库 ID（libraryId）和专属域名（basePath）。


安装 SDK

npm
yarn
pnpm
npm install smh-js-sdk
yarn add smh-js-sdk
pnpm add smh-js-sdk

初始化 SMH 服务

引入 SDK

ES Module（推荐）
CommonJS
import { SMHClient } from 'smh-js-sdk';
const { SMHClient } = require('smh-js-sdk');

初始化 SMHClient

const smh = new SMHClient({
    basePath: 'https://smhxxx.api.tencentsmh.cn', // 专属域名
    accessToken: 'your-access-token',  // 由后端服务创建
    libraryId: 'your-library-id',
    spaceId: 'your-space-id',
});

SMHClient 初始化参数

参数名
参数描述
类型
是否必填
默认值
basePath
API 服务地址（推荐使用专属域名）
String
否
https://api.tencentsmh.cn（默认公共域名，必须使用专属域名覆盖）
accessToken
访问令牌
String
否
-
libraryId
媒体库 ID
String
否
-
spaceId
空间 ID
String
否
-
maxRetries
网络错误/超时/5xx 自动重试次数
Number
否
3
retryDelay
重试基础间隔（毫秒），按指数退避递增
Number
否
1000
timeout
请求超时时间（毫秒）
Number
否
30000
onTokenRefresh
访问令牌过期时的自动续期回调，返回新令牌字符串的 Promise；令牌过期（403 InvalidAccessToken）时 SDK 自动调用并重试原请求
() => Promise<String>
否
-

AccessToken 续期

accessToken 有有效期限制（默认 24 小时），过期后需要调用 renewToken 进行续期：
// 检查 token 是否即将过期，如过期则续期
const renewResponse = await smh.token.renewToken({
    libraryId: 'your-library-id',
    accessToken: 'your-access-token', // 待续期的访问令牌
});

const newAccessToken = renewResponse.data.accessToken;
const newExpiresIn = renewResponse.data.expiresIn;

// 更新默认 accessToken
smh.setDefaultAccessToken(newAccessToken);

console.log('Token 续期成功，新的有效期:', newExpiresIn, '秒');
更推荐的方式是初始化时配置 onTokenRefresh 回调，令牌过期（HTTP 403 且错误码 InvalidAccessToken）时 SDK 会自动调用该回调获取新令牌并重试原请求，无需业务侧手动续期：
const smh = new SMHClient({
    basePath: 'https://smhxxx.api.tencentsmh.cn',
    libraryId: 'your-library-id',
    spaceId: 'your-space-id',
    accessToken: 'your-access-token',
    // 令牌过期时自动续期（回调应请求业务后端重新签发令牌）
    onTokenRefresh: async () => {
        const res = await fetch('/api/refresh-smh-token');
        const data = await res.json();
        return data.accessToken;
    },
});
注意：
建议在业务逻辑中提前进行续期以避免请求失败。

删除访问令牌

令牌不再需要时可主动删除使其立即失效：
// 删除指定访问令牌（立即失效）
await smh.token.deleteToken({
    libraryId: 'your-library-id',
    accessToken: 'your-access-token',
});

// 删除特定用户的全部访问令牌（需要媒体库密钥，可选 clientId/sessionId 进一步限定范围）
await smh.token.deleteUserTokens({
    libraryId: 'your-library-id',
    librarySecret: 'your-library-secret',
    userId: 'user-id',
});
两个接口成功均返回 HTTP 204，无响应体。

快速开始示例

使用 API

完成初始化和令牌获取后，即可调用各种 API 进行文件操作：

// 获取文件详细信息
const res = await smh.file.infoFile({
    spaceId: 'your-space-id',
    filePath: '/test.xlsx',
    info: 1,
    historyId: '123',
    purpose: 'preview',
});

if (res.status === 200) {
    console.log('文件信息获取成功', res.data);
}

错误处理

SDK 抛出的错误统一包装为 SMHError，可通过 code 判断错误类型、通过 response.serverCode 获取服务端原始错误码：
import { SMHError, ErrorCode, ServerErrorCode } from 'smh-js-sdk';

try {
    const res = await smh.file.infoFile({
        filePath: '/test.xlsx',
        info: 1,
    });
    console.log(res.data);
} catch (error) {
    if (error instanceof SMHError) {
        console.error(error.message); // 友好化错误信息，优先展示
        if (error.code === ErrorCode.NETWORK_ERROR) {
            console.warn('网络异常');
        }
        if (error.response?.serverCode === ServerErrorCode.NoPermission) {
            console.warn('没有权限');
        }
        console.log(error.status, error.reqId); // 排障信息
    }
    throw error;
}

中国站