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

快速入门

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

本页目录：

相关资源

智能媒资托管 SMH 的 Node SDK：smh-node-sdk 包
产品文档：SMH 产品文档
控制台：SMH 控制台

环境配置与准备

Node.js 版本 >= 16.0.0。
登录 智能媒资托管控制台，开通 SMH 服务并创建媒体库。获取媒体库 ID（libraryId）、媒体库密钥（librarySecret）和专属域名（basePath）。


安装 SDK

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

初始化 SMH 服务

引入 SDK

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

初始化 SMHClient

方式一：服务端直接创建令牌（推荐）
Node 服务端可以安全地保存 librarySecret，推荐直接在服务端创建访问令牌并注入客户端：
const smh = new SMHClient({
    basePath: 'https://smhxxx.api.tencentsmh.cn', // 专属域名
});

// 服务端用媒体库密钥直接创建访问令牌
const tokenRes = await smh.token.createToken({
    libraryId: 'your-library-id',
    librarySecret: 'your-library-secret',
    spaceId: 'your-space-id',
    userId: 'user-id',
});

// 注入为客户端默认值，后续调用自动携带
smh.setDefaultAccessToken(tokenRes.data.accessToken);
smh.setDefaultLibraryId('your-library-id');
smh.setDefaultSpaceId('your-space-id');
方式二：使用已有令牌初始化
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
baseOptions
附加的 axios 请求配置
Object
否
-

AccessToken 续期

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

const newAccessToken = renewResponse.data.accessToken;

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

console.log('Token 续期成功，新的有效期:', renewResponse.data.expiresIn, '秒');
注意：
Node SDK 不提供浏览器版 SDK 的 onTokenRefresh 自动续期回调，令牌过期（HTTP 403 InvalidAccessToken）会直接抛错，请在业务逻辑中提前续期以避免请求失败（例如按 expiresIn 定时续期）。

快速开始示例

使用 API

完成初始化和令牌获取后，即可调用各种 API 进行文件操作：
// 获取文件详细信息
const res = await smh.file.infoFile({
    spaceId: 'your-space-id',
    filePath: '/test.xlsx',
    info: 1,
});

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

错误处理

API 调用失败时抛出 axios 错误，可通过 error.response 获取服务端返回的 HTTP 状态码与错误码；SDK 的上传下载等高层封装抛出的错误为 SMHError（含 code/message/reqId 等排障信息）：
try {
    const res = await smh.file.infoFile({
        filePath: '/test.xlsx',
        info: 1,
    });
    console.log(res.data);
} catch (error) {
    if (error.response) {
        // 服务端返回的错误：HTTP 状态码 + 错误码 + 请求 ID
        console.error('服务端错误:', error.response.status, error.response.data);
        console.error('请求 ID:', error.response.headers?.['x-request-id']);
    } else if (error.request) {
        // 网络层异常（无响应）
        console.error('网络异常:', error.message);
    } else {
        console.error('错误:', error.message);
    }
    throw error;
}

删除访问令牌

令牌不再需要时可主动删除使其立即失效：
// 删除指定访问令牌（立即失效）
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，无响应体。
中国站