帮你快速理解、总结文档立即下载
文档中心>智能媒资托管>业务级 API 文档>目录或相簿操作接口>创建目录或相簿

创建目录或相簿

最近更新时间：2026-08-18 20:40:01
我的收藏

本页目录：

功能描述

本接口用于在指定的媒体库或空间内创建新的 目录或相簿，当 媒体库 类型为媒体类型时可使用。
您可通过创建目录或相簿对文件进行分类整理、结构化上传与管理，操作清晰简便，尤其适合个人相册、作品集、活动影像等场景的快速搭建与管理。
说明：
需要 admin、space_admin 或 create_directory 权限。有关权限详情请参见 生成访问令牌接口。
媒体类型媒体库可以进一步设置是否为分相簿媒体库。当设置为不分相簿时，则不允许创建目录或相簿，当设置为分相簿时，仅允许创建1层目录或相簿；文件类型媒体库不限制目录层数。
自动创建中间所需的各级父目录。
即使 ConflictResolutionStrategy 为 rename，如果路径中的某一父级实际为文件，则依然会返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码。

请求

请求示例

PUT /api/v1/directory/`{LibraryId}`/`{SpaceId}`/`{DirPath}`?conflict_resolution_strategy=`{ConflictResolutionStrategy}`&access_token=`{AccessToken}`&user_id=`{UserId}`&with_inode=`{WithInode}`

请求参数

请求参数
描述
类型
是否必选
LibraryId
媒体库 ID，在媒体托管控制台创建媒体库后获取，请参见 创建媒体库
String
是
SpaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则为具体 ID，获取请参见 创建租户空间
String
是
DirPath
目录路径或相簿名。
对于多级目录，使用斜杠(`/`)分隔，例如 `foo/bar`。
对于根目录，该参数留空。
String
否
ConflictResolutionStrategy
最后一级目录冲突时的处理方式：
ask: 冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码
rename：冲突时自动重命名最后一级目录
默认为 ask
String
否
AccessToken
访问令牌，获取请参见 生成访问令牌
String
是
UserId
用户身份识别，当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份，详情请参见 生成访问令牌接口
String
否
WithInode
0 或 1，是否返回 inode，即文件目录 ID，默认不返回
Number
否

请求体

application/json（可选），指定目录的元数据信息。如果不需要设置元数据，请求体可以为空。
请求体示例：
{
    "metaData": {
        "x-smh-meta-custom-key": "custom-value",
        "x-smh-meta-source": "third-party-system"
    },
    "labels": ["重要", "项目A"],
    "localCreationTime": "2026-04-22T08:00:00Z",
    "localModificationTime": "2026-04-22T08:00:00Z"
}
请求体字段说明：
请求参数
描述
类型
是否必选
metaData
自定义元数据键值对，可选参数，类型为 object (map[string]string)，key 为小写字符串
Object
否
labels
目录标签列表
String Array
否
localCreationTime
目录对应的本地创建时间，时间戳字符串
String
否
localModificationTime
目录对应的本地修改时间，时间戳字符串
String
否

响应

响应码

创建成功，返回 HTTP 201 Created。

响应体

空，无响应体（ConflictResolutionStrategy 为 ask 且 WithInode 为0）或 application/json（ConflictResolutionStrategy 为 rename 或 WithInode 为1）。
响应体示例：
ConflictResolutionStrategy 为 ask 且 WithInode 为1：
{
    "creationTime": "2025-09-29T02:53:09.000z",
    "inode": "b63393076d249110000631c316d9751a"
}
ConflictResolutionStrategy 为 rename 且 WithInode 为0：
{ 
    "creationTime": "2025-09-29T02:53:09.000z",
    "path": [ "foo", "bar (1)" ]
}
ConflictResolutionStrategy 为 rename 且 WithInode 为1：
{ 
    "creationTime": "2025-09-29T02:53:09.000z",
    "path": [ "foo", "bar (1)" ],
    "inode": "b63393076d249110000631c316d9751a"
}
响应体字段说明：
响应参数
描述
类型
creationTime
创建时间
String
path
表示最终的目录或相簿路径，因为可能存在自动重命名，所以这里的最终路径可能不等同于创建目录或相簿时指定的路径
String
inode
最后一级文件目录 ID
String

错误码

该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。
中国站