服务端集成 · 其他 · 批量上传素材

说明如何使用素材上传 SDK 批量上传图片和视频，包括目录扫描、并发、格式过滤和调用参数。

概述

本 SDK 提供便捷的批量上传图片和视频素材功能，支持递归扫描、并发上传、格式过滤等特性。

快速开始

1. 安装

pip install gravity-material-upload

2. 基础用法

from gravity_material_upload import MaterialClient

# 1. 创建客户端
client = MaterialClient(
    # app_key: 请在引力后台-设置-引力开发者中查看
    # URL: https://web.gravity-engine.com/#/manage/develop
    app_key="your_app_key",
)

# 2. 一键上传素材（扫描 + 上传）
client.upload_material(
    source_paths=["./video1.mp4", "./image1.png"],
    recursive=True,
    allowed_extensions=[".png", ".mp4"],
    max_workers=5,
    upload_config={
        "album_id": 123,
        "remark": "your_remark",
    },
    file_renames={
        "video1.mp4": "video_rename",
    },
)

详细参数说明

MaterialClient 参数

参数	类型	必填	说明
`app_key`	str	是	开发者应用密钥，在引力开发者后台获取

upload_material 方法参数

参数	类型	默认值	说明
`source_paths`	str \| List[str]	"./"	目标路径。用法示例： 1. `["./file1.mp4", "./file2.png"]`：仅上传这两个文件 2. `"./"`：上传当前目录下所有匹配的文件 3. `"./data/*.mp4"`：使用通配符匹配文件
`recursive`	bool	True	是否递归搜索子目录
`allowed_extensions`	Tuple[str, ...]	None	自定义文件后缀白名单，仅保留在默认支持列表中的后缀。支持的格式为：视频：mp4/avi/mov 图片：png/jpg/jpeg/gif
`max_workers`	int	5	最大并发上传线程数
`upload_config`	dict	必填	自定义上传配置参数。请在引力素材管理页中复制，再粘贴到代码中（见下图红框部分）
`file_renames`	dict	None	文件重命名映射。key 可以是全名，也可是不含后缀的纯名，value 必须是无后缀纯名；全名时仅对应文件更改名，纯名时同名文件都会匹配。比如 key 为 test 时，test.png 和 test.mp4 会重命名为 test_rename.png、test_rename.mp4

使用示例

示例 1：上传指定文件夹

# 上传 videos 文件夹下的所有视频文件
client.upload_material(
    source_paths="./videos",
    recursive=True,
    allowed_extensions=[".mp4", ".avi", ".mov"],
    upload_config={
        "album_id": 456,
        "remark": "产品宣传视频",
    }
)

示例 2：上传特定文件

# 仅上传指定的两个文件
client.upload_material(
    source_paths=["./banner.png", "./intro.mp4"],
    upload_config={
        "album_id": 789,
        "remark": "首页素材",
    }
)

示例 3：使用通配符匹配

# 上传 data 目录下所有 .jpg 文件
client.upload_material(
    source_paths="./data/*.jpg",
    recursive=False,  # 不扫描子目录
    upload_config={
        "album_id": 101,
        "remark": "用户头像",
    }
)

批量上传素材

本页内容