一、相关资源
·智能媒资托管 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
ES Module（推荐）CommonJSimport { 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;// 更新默认 accessTokensmh.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;}