# 批量操作 (/docs/api/native/media/batches)



[指南 →](/docs/cloud/services/media/quickstart)

[基础地址与鉴权](/docs/api/native/media)

## 批量操作 [#批量操作]

`POST /media/v1/libraries/{library_id}/batches`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |

### 请求体 [#请求体]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "tag" / "untag" | 是 | 批量操作 |
| tags | string[] | 是 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "set_context" | 是 | 批量操作 |
| context | object | 是 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "move" | 是 | 批量操作 |
| asset_folder | string | 是 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "delete" | 是 | 批量操作 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| selector | BatchSelector | 是 | 按 ID 或表达式选择 |

返回: `Job`.

### 响应 [#响应]

#### HTTP 200 [#http-200]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Generated batch identifier: job_ followed by 32 lowercase hexadecimal characters. |
| library_id | string | Identifier of the library in which the batch operates. |
| action | string | Batch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets. |
| status | string | Job status: queued awaits execution; running is processing items; completed means all items succeeded; completed_with_errors means some succeeded and some failed; failed means all selected items failed. An empty job completes successfully. |
| total | number | Number of distinct assets selected when the job was created. |
| done | number | Number of items successfully processed; failed items are counted separately. |
| failed | number | Number of items that could not be processed successfully. |
| failures | array<object> | Always present, including an empty array before any item failure or when all items succeed. At most 20 item failures are returned. |
| failures[].asset_id | string | Identifier supplied for the failed item; it may identify a missing asset. |
| failures[].code | string | Domain error code explaining the individual item failure. |
| created_at | string | Time the batch job was created, in UTC. |
| finished_at | string | null | Time the job reached a terminal status, or null while queued or running. |

```bash
curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/batches" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"tag","tags":["sample"],"selector":{"ids":["85b7ef616a8b4719a41777a036ebc1d2","00000000000000000000000000000000"]}}'
```

HTTP 200

```json
{
  "id": "job_b562f087623c4756b43813e3dce670ba",
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "action": "tag",
  "status": "queued",
  "total": 2,
  "done": 0,
  "failed": 0,
  "created_at": "2026-10-11T15:50:24.942Z",
  "failures": [],
  "finished_at": null
}
```

## 读取任务 [#读取任务]

`GET /media/v1/libraries/{library_id}/batches/{job_id}`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| job_id | path | string | 任务 ID |

返回: `Job`.

### 响应 [#响应-1]

#### HTTP 200 [#http-200-1]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Generated batch identifier: job_ followed by 32 lowercase hexadecimal characters. |
| library_id | string | Identifier of the library in which the batch operates. |
| action | string | Batch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets. |
| status | string | Job status: queued awaits execution; running is processing items; completed means all items succeeded; completed_with_errors means some succeeded and some failed; failed means all selected items failed. An empty job completes successfully. |
| total | number | Number of distinct assets selected when the job was created. |
| done | number | Number of items successfully processed; failed items are counted separately. |
| failed | number | Number of items that could not be processed successfully. |
| failures | array<object> | Always present, including an empty array before any item failure or when all items succeed. At most 20 item failures are returned. |
| failures[].asset_id | string | Identifier supplied for the failed item; it may identify a missing asset. |
| failures[].code | string | Domain error code explaining the individual item failure. |
| created_at | string | Time the batch job was created, in UTC. |
| finished_at | string | null | Time the job reached a terminal status, or null while queued or running. |

```bash
curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/batches/job_b562f087623c4756b43813e3dce670ba" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

HTTP 200

```json
{
  "id": "job_b562f087623c4756b43813e3dce670ba",
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "action": "tag",
  "status": "completed_with_errors",
  "total": 2,
  "done": 1,
  "failed": 1,
  "created_at": "2026-10-11T15:50:24.942Z",
  "failures": [
    {
      "asset_id": "00000000000000000000000000000000",
      "code": "ASSET_NOT_FOUND"
    }
  ],
  "finished_at": "2026-10-11T15:50:27.555Z"
}
```

## 批量操作别名 [#批量操作别名]

`POST /media/v1/libraries/{library_id}/assets:batch`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |

### 请求体 [#请求体-1]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "tag" / "untag" | 是 | 批量操作 |
| tags | string[] | 是 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "set_context" | 是 | 批量操作 |
| context | object | 是 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "move" | 是 | 批量操作 |
| asset_folder | string | 是 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "delete" | 是 | 批量操作 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| selector | BatchSelector | 是 | 按 ID 或表达式选择 |

返回: `Job`.

### 响应 [#响应-2]

#### HTTP 200 [#http-200-2]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Generated batch identifier: job_ followed by 32 lowercase hexadecimal characters. |
| library_id | string | Identifier of the library in which the batch operates. |
| action | string | Batch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets. |
| status | string | Job status: queued awaits execution; running is processing items; completed means all items succeeded; completed_with_errors means some succeeded and some failed; failed means all selected items failed. An empty job completes successfully. |
| total | number | Number of distinct assets selected when the job was created. |
| done | number | Number of items successfully processed; failed items are counted separately. |
| failed | number | Number of items that could not be processed successfully. |
| failures | array<object> | Always present, including an empty array before any item failure or when all items succeed. At most 20 item failures are returned. |
| failures[].asset_id | string | Identifier supplied for the failed item; it may identify a missing asset. |
| failures[].code | string | Domain error code explaining the individual item failure. |
| created_at | string | Time the batch job was created, in UTC. |
| finished_at | string | null | Time the job reached a terminal status, or null while queued or running. |

```bash
curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets:batch" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"tag","tags":["sample"],"selector":{"ids":["85b7ef616a8b4719a41777a036ebc1d2"]}}'
```

HTTP 200

```json
{
  "id": "job_3c2fe728de054c7396058c7438b289d2",
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "action": "tag",
  "status": "queued",
  "total": 1,
  "done": 0,
  "failed": 0,
  "created_at": "2026-10-11T15:50:29.266Z",
  "failures": [],
  "finished_at": null
}
```

## 读取任务别名 [#读取任务别名]

`GET /media/v1/libraries/{library_id}/jobs/{job_id}`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| job_id | path | string | 任务 ID |

返回: `Job`.

### 响应 [#响应-3]

#### HTTP 200 [#http-200-3]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Generated batch identifier: job_ followed by 32 lowercase hexadecimal characters. |
| library_id | string | Identifier of the library in which the batch operates. |
| action | string | Batch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets. |
| status | string | Job status: queued awaits execution; running is processing items; completed means all items succeeded; completed_with_errors means some succeeded and some failed; failed means all selected items failed. An empty job completes successfully. |
| total | number | Number of distinct assets selected when the job was created. |
| done | number | Number of items successfully processed; failed items are counted separately. |
| failed | number | Number of items that could not be processed successfully. |
| failures | array<object> | Always present, including an empty array before any item failure or when all items succeed. At most 20 item failures are returned. |
| failures[].asset_id | string | Identifier supplied for the failed item; it may identify a missing asset. |
| failures[].code | string | Domain error code explaining the individual item failure. |
| created_at | string | Time the batch job was created, in UTC. |
| finished_at | string | null | Time the job reached a terminal status, or null while queued or running. |

```bash
curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/jobs/job_3c2fe728de054c7396058c7438b289d2" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

HTTP 200

```json
{
  "id": "job_3c2fe728de054c7396058c7438b289d2",
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "action": "tag",
  "status": "completed",
  "total": 1,
  "done": 1,
  "failed": 0,
  "created_at": "2026-10-11T15:50:29.266Z",
  "failures": [],
  "finished_at": "2026-10-11T15:50:29.494Z"
}
```

## Job [#job]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | JobId | 是 | 资源 ID |
| library_id | LibraryId | 是 | 库 ID |
| action | tag / untag / set_context / move / delete | 是 | 批量操作 |
| status | "queued" / "running" / "completed" / "completed_with_errors" / "failed" | 是 | 资源状态 |
| total | number | 是 | 任务素材总数 |
| done | number | 是 | 已完成数量；分片响应中表示是否完成 |
| failed | number | 是 | 失败数量 |
| failures | object[] | 是 | — |
| created_at | IsoTimestamp | 是 | 创建时间 |
| finished_at | IsoTimestamp / null | 是 | 结束时间；未结束为空 |

## BatchSelector [#batchselector]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| ids | AssetId[] | 是 | 素材 ID 列表 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| expression | string | 是 | 结构化查询表达式；空表达式返回全部素材 |
| exclusions | AssetId[] | 否 | 从选择中排除的素材 ID |

## BatchAction [#batchaction]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "tag" / "untag" | 是 | 批量操作 |
| tags | string[] | 是 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "set_context" | 是 | 批量操作 |
| context | object | 是 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "move" | 是 | 批量操作 |
| asset_folder | string | 是 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | "delete" | 是 | 批量操作 |