Gravity Material Upload

Python SDK，用于批量上传图片和视频素材。

文档：https://help.gravity-engine.com/docs/material-upload

功能特性

• 🔍 智能文件扫描 — 支持扫描目录、指定文件、通配符匹配，自动过滤有效的图片/视频文件
• 📤 分片上传 — 基于 TOS 对象存储的分片上传，支持大文件传输
• 📊 进度显示 — 双层进度条实时展示文件级和字节级上传进度
• 🖼️ 自动解析 — 自动获取图片/视频的宽高、时长、MD5 等元信息

支持的文件格式

快速开始

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,                           # 是否递归搜索子目录，在source_paths传入目录时生效
    allowed_extensions=[".png", ".mp4"], # 可选：自定义文件后缀白名单
    max_workers=5,                            # 可选：最大并发上传数
    upload_config={                           # 必填：自定义上传配置参数
        "album_id": 123,
        "remark": "your_remark",
    },
    file_renames={                            # 可选：文件重命名映射  key可以是全名，也可是不含后缀的纯名，value必须是无后缀纯名，全名时仅对应文件更改名，纯名时同名文件都会匹配，比如 key为test时，test.png和test.mp4会重命名为 test_rename.png  , test_rename.mp4 
        "video1.mp4": "video_rename",
    },
)

MaterialClient 参数说明

upload_material() 参数说明

环境要求

• Python >= 3.7

许可证

Apache-2.0