# 批量上传素材

> 来源：https://help.gravity-engine.com/docs/server-integration/other-apis/upload-creatives
> 说明如何使用素材上传 SDK 批量上传图片和视频，包括目录扫描、并发、格式过滤和调用参数。





## 概述 [#概述]

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

## 快速开始 [#快速开始]

### 1. 安装 [#1-安装]

```bash
pip install gravity-material-upload
```

### 2. 基础用法 [#2-基础用法]

```python
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    | 是      | 开发者应用密钥，在[引力开发者后台](https://web.gravity-engine.com/#/manage/develop)获取 |

**upload\_material 方法参数**

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

## 使用示例 [#使用示例]

### 示例 1：上传指定文件夹 [#示例-1上传指定文件夹]

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

### 示例 2：上传特定文件 [#示例-2上传特定文件]

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

### 示例 3：使用通配符匹配 [#示例-3使用通配符匹配]

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