腾讯云智能媒资托管（SMH）从零到一对接实战指南
引言：为什么需要智能媒资托管
在移动互联网与人工智能深度融合的今天，图片、视频、文档等非结构化数据正以指数级速度增长。无论是个人相册的云端备份、企业网盘的协同办公，还是电商平台的商品图集管理，开发者都面临着一系列共同的挑战：海量媒体文件的可靠存储、高效的目录式管理、精细化的用户权限隔离、以及基于AI的智能处理能力。传统方案往往需要组合对象存储、数据处理服务、账号体系、文件管理前端等多个组件，开发周期长、维护成本高。
腾讯云智能媒资托管（Smart Media Hosting，SMH）正是为解决这些痛点而生。它是一项基于对象存储（COS）和数据万象（CI）的多媒体及文件资源托管服务。SMH不仅提供了数据的存储与管理等基础能力，还集成了腾讯云先进的AI技术，支持对图片、视频、文档等媒体内容进行编辑处理、标签分类、人脸识别等多种智能化操作。简单来说，SMH是构建在COS和CI之上的PaaS层中间件，它为开发者屏蔽了底层存储与处理的复杂性，提供了开箱即用的目录式文件管理、ToC账号体系、以及场景化的数据处理能力。
本文将从产品概念、环境准备、核心对接流程、多端SDK集成、API调用、安全管理到成本优化，全方位拆解腾讯云智能媒资托管的对接使用方法，并辅以大量可运行的代码示例，帮助开发者快速上手。
需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联
一、认识SMH：核心概念与产品架构
1.1 媒体库（Library）
媒体库是智能媒资托管中最大的一级单元划分，每一个媒体库完全独立。目前SMH支持创建两种类型的媒体库：媒体类型媒体库（模拟相册概念）和文件类型媒体库（模拟硬盘概念）。在创建媒体库时，系统会自动生成媒体库ID（LibraryId）和媒体库密钥（LibrarySecret）。媒体库ID用于唯一标识一个媒体库，调用所有API时均需指定；媒体库密钥则用于调用与访问令牌相关的接口，验证调用者合法性。
值得注意的是，仅在创建、删除和修改媒体库的部分设置时需要使用腾讯云账户登录控制台操作，其他所有操作均通过调用API来实现，不再要求持有腾讯云账户。这意味着开发者可以将SMH无缝集成到自己的产品中，最终用户无需感知腾讯云的存在。
1.2 租户空间（Space）与用户隔离
SMH引入了Space（租户空间）这一层资源实体，每个Space拥有独立的标识（SpaceId）、独立的访问令牌、独立的权益配置（如存储配额、限速等）。这种设计实现了严格的用户隔离，业务方可以根据独立的SpaceId对单个用户进行访问控制、权益配置和管理，非常适合搭建面向C端用户的产品。
在创建媒体库时可以选择是否启用多租户模式。如果开启，则可以通过API动态创建、删除和修改隔离的租户空间。如果未开启则为单租户模式，整个媒体库即视为一个租户空间。
1.3 访问令牌（Access Token）
访问令牌是SMH权限体系的核心。除了通过控制台进行的媒体库管理、操作访问令牌本身的请求以及开启公有读后的读请求外，所有其他请求均需使用访问令牌进行身份验证和识别。访问令牌通过在服务端调用生成访问令牌API生成，生成时需指定媒体库ID和媒体库密钥。由于媒体库密钥需要保密，绝不能在客户端保存和使用，因此生成访问令牌的API必须在后端服务中调用。
访问令牌默认有效期为24小时，可在生成时指定其他有效期。在使用访问令牌发起请求时，SMH会自动为该令牌续期，将有效期延长为默认的24小时或指定时长。因此，只要用户每次访问SMH的间隔时间小于有效期，该令牌将一直有效。
1.4 用户身份识别
SMH本身不托管用户信息，但允许在生成访问令牌时传入用户身份识别（如您系统中已有用户体系的ID、用户名或微信小程序的openid）。这样，在后续的文件操作中，SMH可以记录操作者是谁，方便您进行审计或进一步的业务处理。
二、环境准备与媒体库创建
2.1 账号准备
使用SMH服务前，需要先注册腾讯云账号并完成实名认证。完成认证后，登录腾讯云控制台，在云产品列表中找到'智能媒资托管'服务并开通。
2.2 创建媒体库
创建媒体库有两种方式：控制台创建和API创建。
方式一：控制台创建
登录智能媒资托管控制台，单击'媒体库管理'，然后点击'新建媒体库'。在弹出的对话框中根据实际需求进行设置，包括媒体库名称、类型（媒体类型或文件类型）、是否启用多租户模式等。创建完成后，控制台会展示为您生成的专属域名（如 smhxxx.api.tencentsmh.cn），该域名是您访问所有服务的前提。
方式二：API Explorer创建
进入API Explorer工具页面，调用CreateLibrary接口创建媒体库。创建完成后，登录SMH控制台查看媒体库创建情况。
2.3 获取关键信息
媒体库创建完成后，您需要获取以下关键信息以备后续使用：
- 专属域名（basePath）：格式为 smhxxx.api.tencentsmh.cn，是访问所有API的入口。
- 媒体库ID（LibraryId）：唯一标识媒体库。
- 媒体库密钥（LibrarySecret）：用于生成访问令牌，必须保存在服务端，严禁暴露在客户端。
三、访问令牌的生成与安全管理
访问令牌是所有API操作的前提，其生成流程直接关系到整个系统的安全性。下面详细讲解令牌的生成机制与最佳实践。
3.1 为什么令牌生成必须在服务端
生成访问令牌需要用到媒体库密钥（LibrarySecret），而该密钥具有对媒体库的完全操作权限。如果在前端（如浏览器或移动App）中暴露该密钥，任何用户都可以通过调试工具获取并滥用，导致严重的安全风险。因此，生成访问令牌的API必须在您自己的后端服务中调用。
3.2 标准令牌颁发流程
一个标准的令牌颁发流程如下：
- 用户在前端完成登录（如账密登录、短信验证、微信登录等）。
- 前端将用户登录凭证发送到您的业务后端。
- 业务后端验证用户身份后，根据该用户在业务中的角色，映射到SMH中对应的权限。
- 业务后端使用媒体库密钥调用SMH的生成访问令牌API，生成一个具有特定权限和有效期的访问令牌。
- 业务后端将访问令牌返回给前端。
- 前端在后续所有SMH API请求中携带该令牌。
3.3 生成访问令牌的API调用示例
以下是一个使用Python在后端生成访问令牌的示例：
import requests
import json
def generate_access_token(library_id, library_secret, space_id=None, user_id=None, expires_in=86400):
url = 'https://smh.tencentcloudapi.com/' # 实际API地址请参考官方文档
headers = {
'Content-Type': 'application/json'
}
payload = {
'LibraryId': library_id,
'LibrarySecret': library_secret,
'SpaceId': space_id, # 可选，多租户模式下指定用户空间
'UserId': user_id, # 可选，用于记录操作者
'ExpiresIn': expires_in # 有效期，单位秒，默认86400（24小时）
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 200:
data = response.json()
return {
'accessToken': data.get('AccessToken'),
'expiresIn': data.get('ExpiresIn')
}
else:
raise Exception(f'Failed to generate token: {response.text}')
# 使用示例
token_info = generate_access_token(
library_id='smh3ptyc9mscifdi',
library_secret='your_library_secret_here',
space_id='space1x8mfjgno6nyy',
user_id='user_12345',
expires_in=7200 # 2小时有效期
)
print(f'Access Token: {token_info['accessToken']}')
print(f'Expires In: {token_info['expiresIn']} seconds')3.4 令牌的续期与失效
访问令牌过期后，前端需要从后端重新获取新的令牌。在SDK中，通常提供了自动续期机制，例如在JavaScript SDK中，可以通过onTokenRefresh回调实现自动续期。当令牌过期时，SDK会自动调用该回调从后端获取新令牌并重试请求，业务层无需关心续期时机。
此外，SMH也提供了强制删除访问令牌的接口，当用户修改密码、遗失设备或需要主动禁用指定用户的访问时，可以调用相关接口强制删除指定用户的访问令牌。
四、多端SDK集成指南
腾讯云为SMH提供了丰富的多端SDK，包括JavaScript/TypeScript（浏览器端）、Node.js、iOS、Android等，极大地降低了不同平台下的接入成本。
4.1 JavaScript/TypeScript SDK（浏览器端）
smh-js-sdk是专为浏览器端设计的JavaScript/TypeScript SDK，支持文件上传（含秒传、分片、断点续传）、下载、短链、目录管理、搜索与增量同步等完整功能。
安装
npm install smh-js-sdk初始化与配置
import { SMHClient } from 'smh-js-sdk';
const client = new SMHClient({
basePath: 'https://smhxxx.api.tencentsmh.cn', // 专属域名
libraryId: 'your-library-id',
spaceId: 'your-space-id',
accessToken: 'your-access-token', // 由后端服务签发
maxRetries: 3, // 可选，请求失败重试次数，默认3
timeout: 30000 // 可选，请求超时时间（毫秒），默认30000
});自动续期配置
const client = new SMHClient({
basePath: 'https://smhxxx.api.tencentsmh.cn',
libraryId: 'your-library-id',
spaceId: 'your-space-id',
accessToken: 'your-access-token',
onTokenRefresh: async () => {
// 调用后端服务获取新token
const response = await fetch('/api/refresh-smh-token');
const { accessToken } = await response.json();
return accessToken;
}
});文件上传示例
// 上传文件
const uploadTask = await client.file.uploadFile({
filePath: '/photos/2026/07/',
file: fileObject, // 来自或拖拽
onProgress: (progress) => {
console.log(`上传进度: ${progress.percent}%`);
}
});
// 等待上传完成
await uploadTask.done();列出目录内容
const contents = await client.file.listDirectory({
dirPath: '/photos/2026/07/'
});
contents.forEach(item => {
console.log(`${item.isDir ? '[目录]' : '[文件]'} ${item.name}`);
});4.2 Node.js SDK
smh-node-sdk为Node.js环境提供了完整的SMH服务接口。
npm install smh-node-sdkconst { SMHClient } = require('smh-node-sdk');
const client = new SMHClient({
basePath: 'https://smhxxx.api.tencentsmh.cn',
libraryId: 'your-library-id',
spaceId: 'your-space-id',
accessToken: 'your-access-token'
});
// 使用方式与JS SDK类似
async function uploadFile() {
const result = await client.file.uploadFile({
filePath: '/documents/report.pdf',
file: fs.createReadStream('./local-report.pdf')
});
console.log('上传完成:', result);
}4.3 iOS SDK
iOS SDK通过CocoaPods集成。
pod 'QCloudCOSSMH/Api'设置访问域名与初始化
#import
// 设置专属域名
[QCloudSMHBaseRequest setBaseRequestHost:@'.api.tencentsmh.cn'
targetType:QCloudECDTargetRelease]; 实现访问令牌协议
- (void)accessTokenWithRequest:(QCloudSMHBizRequest *)request
urlRequest:(NSURLRequest *)urlRequst
compelete:(QCloudSMHAuthentationContinueBlock)continueBlock {
// 从您的后端服务获取访问令牌
QCloudSMHSpaceInfo *spaceInfo = [QCloudSMHSpaceInfo new];
spaceInfo.accessToken = @'your_access_token';
spaceInfo.expiresIn = @'86400';
spaceInfo.libraryId = @'your_library_id';
spaceInfo.spaceId = @'your_space_id';
continueBlock(spaceInfo, nil);
}4.4 Android SDK
Android SDK通过MavenCentral集成。
// 项目级build.gradle
repositories {
google()
mavenCentral()
}
// 应用级build.gradle
dependencies {
implementation 'com.qcloud.cos:smh-android:1.2.39'
}实现访问令牌提供者
class MySMHSimpleUser : SMHSimpleUser() {
override val libraryId: String get() = 'smh3ptyc9mscifdi'
override val userSpace: UserSpace get() = UserSpace(
userId = 'user_12345',
spaceId = 'space1x8mfjgno6nyy'
)
override suspend fun provideAccessToken(): AccessToken {
// 从后端服务获取访问令牌
val token = 'your_access_token'
val expiresIn = 86400L // 24小时
val startTime = System.currentTimeMillis()
return AccessToken(token, startTime, expiresIn)
}
}
// 初始化SMHCollection
val mySMHSimpleUser = MySMHSimpleUser()
val smhCollection = SMHCollection(mySMHSimpleUser)五、RESTful API调用详解
除了使用SDK，您也可以直接通过RESTful API与SMH服务交互。SMH的API接口为RESTful形式且支持CORS，可以通过任何支持标准HTTPS请求的编程库发起请求。
5.1 API请求结构
SMH API支持就近地域接入，推荐使用就近地域接入域名 smh.tencentcloudapi.com。对于对时延敏感的业务，可以指定带地域的域名，例如广州地域的域名为 smh.ap-guangzhou.tencentcloudapi.com。
所有API请求均通过HTTPS进行通信。支持的HTTP请求方法包括POST（推荐）和GET。POST请求的Content-Type支持application/json（推荐，需使用签名方法v3）、application/x-www-form-urlencoded和multipart/form-data。
5.2 请求头与认证
在发起API请求时，需要在请求头中携带访问令牌进行身份认证：
Authorization: Bearer {access_token}5.3 目录管理API示例
创建目录
POST /api/v1/directory/{libraryId}/{spaceId}/{dirPath}
Authorization: Bearer {accessToken}
Content-Type: application/json
{
'conflictResolutionStrategy': 'rename'
}删除目录
DELETE /api/v1/directory/{libraryId}/{spaceId}/{dirPath}
Authorization: Bearer {accessToken}5.4 文件操作API示例
上传文件（简单上传）
PUT /api/v1/file/{libraryId}/{spaceId}/{filePath}
Authorization: Bearer {accessToken}
Content-Type: application/octet-stream
[文件二进制数据]下载文件
GET /api/v1/file/{libraryId}/{spaceId}/{filePath}
Authorization: Bearer {accessToken}删除文件
DELETE /api/v1/file/{libraryId}/{spaceId}/{filePath}
Authorization: Bearer {accessToken}5.5 异步搜索API
SMH提供了异步搜索功能，用于在大量文件中快速检索。发起异步搜索任务时，接口会在约2秒内返回，如果已有部分或全部搜索结果，则返回已搜索出的结果的第一页（每页20个）。返回结果中的hasMore字段指示是否还有更多结果，而不应仅根据contents的数量来判断。
六、AI媒体处理能力集成
SMH基于数据万象（CI）提供了丰富的媒体处理能力。这些能力可以通过API直接调用，无需额外集成其他SDK。
6.1 图片处理
支持图片裁剪、缩放、旋转、水印、格式转换等操作。在处理请求中通过指定处理参数即可实现：
GET /api/v1/file/{libraryId}/{spaceId}/{imagePath}?imageMogr2/thumbnail/200x200/format/jpg
Authorization: Bearer {accessToken}上述请求将图片缩放为200x200像素并转换为JPEG格式。
6.2 内容审核
支持对图片、视频、音频等内容进行智能审核，识别涉黄、涉暴、涉政等违规内容。审核结果可以用于内容治理和合规管理。
6.3 文档预览
支持将Office文档（Word、Excel、PPT等）转换为HTML或图片格式进行在线预览，无需用户本地安装Office软件。
6.4 视频处理
支持视频转码、截帧、智能封面提取等操作。例如，提取视频的第5秒帧作为封面：
GET /api/v1/file/{libraryId}/{spaceId}/{videoPath}?ci-process=snapshot&time=5&format=jpg
Authorization: Bearer {accessToken}6.5 AI智能分析
SMH集成了腾讯云先进的AI技术，支持对媒体内容进行标签分类、人脸识别等智能分析。这些能力可以广泛应用于相册自动分类、智能检索等场景。
七、权限体系与安全管理
7.1 多层级权限模型
SMH的权限体系支持从媒体库、租户空间到目录、文件的多层级控制。基于独立访问令牌的身份验证，允许业务全局或独立用户身份与媒体库、租户空间及目录、文件级别的访问控制形成交叉授权体系。这种灵活的权限模型可以支撑丰富的应用场景，如企业网盘中不同部门对不同目录的读写权限控制。
7.2 数据加密传输
所有API请求均通过HTTPS进行通信，确保数据在传输过程中的安全。SMH支持SSL加密传输，有效防止数据被窃听或篡改。
7.3 防盗链配置
SMH提供防盗链功能，可屏蔽恶意来源的访问。您可以在控制台或通过API配置允许的Referer白名单，防止其他网站盗用您的媒体资源链接，从而节省流量费用并保护内容版权。
7.4 密钥安全管理最佳实践
- 严禁在前端暴露媒体库密钥：LibrarySecret拥有对媒体库的完全控制权，只能在服务端使用。
- 使用短期有效的访问令牌：根据业务需要设置合理的令牌有效期，不建议设置过长。
- 最小权限原则：生成访问令牌时只授予必要的权限，避免授予过高的权限。
- 定期轮换密钥：定期更换媒体库密钥，降低密钥泄露带来的风险。
- 监控与审计：利用SMH的操作记录功能，结合用户身份识别，对敏感操作进行审计。
八、成本构成与优化策略
8.1 计费项详解
SMH采用后付费方式，按照实际使用量计费，次月3-7日出本月账单。主要计费项包括：
- 存储费用：按照存储容量和存储时长计算，由COS收取。标准存储单价约为0.15元/GB/月。
- 流量费用：指外网下行流量费用，按照实际产生的流量计算。
- 用户服务费用：SMH的平台服务费用。
- 数据处理费用：由数据万象（CI）收取，包括图片处理、内容审核、文档预览等。
8.2 成本优化策略
充分利用内网访问：如果您的应用部署在腾讯云CVM等产品上，可以通过内网访问SMH服务，从而免除外网下行流量费用。
合理选择存储类型：对于访问频率较低的数据，可以将其转换为低频存储或归档存储，显著降低存储成本。
配置生命周期规则：通过配置生命周期管理策略，自动将超过指定时间的文件转换为更低成本的存储类型，或自动删除过期文件。
控制外网流量：通过防盗链配置、CDN加速等方式，减少直接的外网访问流量。
监控与告警：在腾讯云控制台配置账单告警，当费用超过设定阈值时及时收到通知，避免预算超支。
九、常见应用场景
SMH可广泛应用于多种场景：
- 云相册：支持用户将手机照片视频自动同步上云，提供智能分类、人脸识别、相册管理等功能。
- 企业网盘：搭建企业级文件共享与协同平台，支持多用户权限管理、文件版本控制、在线预览等。
- 媒资工作站：为媒体行业提供视频、音频、图片等素材的统一存储、管理与分发。
- Agent云空间：为AI Agent应用提供文件存储与上下文管理空间。
- 内容协作平台：支持多用户对协同文件进行在线编辑，实时同步编辑结果，自动生成历史版本。
十、常见问题解答
问1：SMH和COS有什么区别？我该选哪个？
答：SMH是基于COS之上的PaaS级存储处理解决方案。COS提供的是底层的对象存储能力，而SMH在COS之上增加了ToC账号管理能力、高效的目录式文件管理、以及场景化的AI处理能力。如果您需要构建面向最终用户的网盘、相册等应用，希望快速获得完整的文件管理和用户体系，SMH是更高效的选择；如果您只需要纯粹的存储服务，COS即可满足需求。
问2：访问令牌过期了怎么办？
答：访问令牌默认有效期为24小时，过期后需要重新生成。在实际业务中，建议在前端SDK中配置自动续期机制（如JavaScript SDK的onTokenRefresh回调），当令牌过期时SDK会自动从后端获取新令牌并重试请求。如果使用RESTful API直接调用，则需要在前端捕获401错误后主动向后端请求新令牌并重试。
问3：媒体库密钥（LibrarySecret）不小心泄露了怎么办？
答：如果媒体库密钥泄露，攻击者可以生成任意访问令牌并操作您的媒体库。请立即登录SMH控制台，在媒体库管理页面重新生成新的媒体库密钥。生成新密钥后，旧的密钥将立即失效。同时，建议检查是否有异常操作记录，并评估是否需要进一步的安全加固。
问4：SMH支持哪些文件类型？有大小限制吗？
答：SMH支持几乎所有文件类型，包括图片、视频、音频、文档、压缩包等。单个文件的上传大小限制取决于您的存储配置和网络环境，通常支持GB级别的大文件上传，并且SDK内置了分片上传和断点续传功能，可以稳定上传超大文件。
问5：如何控制用户的存储配额？
答：在多租户模式下，每个租户空间（Space）拥有独立的权益配置，包括存储配额。您可以在创建租户空间时指定存储配额上限，也可以通过API动态调整。当用户存储使用量达到配额上限时，后续的上传请求将会被拒绝。
问6：SMH的数据安全性和可靠性如何？
答：SMH的媒资数据存储于腾讯云对象存储（COS）中，数据跨多架构、多设备冗余存储，提供异地容灾和资源隔离，保证业界领先的数据持久性。同时，所有API请求均通过HTTPS加密传输，支持防盗链和细粒度的文件读写权限控制。
