素材库

批量操作

请求、对象与响应。

指南 →

基础地址与鉴权

批量操作

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

参数位置类型说明
library_idpathstring库 ID

请求体

字段类型必填说明
action"tag" / "untag"是批量操作
tagsstring[]是素材标签。上传可传逗号分隔字符串(每项去首尾空白、丢弃空项)、数组或重复的 tags 字段;PATCH 只接受数组并整体替换
字段类型必填说明
action"set_context"是批量操作
contextobject是自定义文字键值;PATCH 整体替换,传 {} 清空
字段类型必填说明
action"move"是批量操作
asset_folderstring是组织文件夹;不改变 public_id。按它列出时只匹配这一层、不含子文件夹;空字符串表示根
字段类型必填说明
action"delete"是批量操作
字段类型必填说明
selectorBatchSelector是按 ID 或表达式选择

返回: Job.

响应

HTTP 200

Successful response.

application/json

名称类型说明
idstringGenerated batch identifier: job_ followed by 32 lowercase hexadecimal characters.
library_idstringIdentifier of the library in which the batch operates.
actionstringBatch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets.
statusstringJob 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.
totalnumberNumber of distinct assets selected when the job was created.
donenumberNumber of items successfully processed; failed items are counted separately.
failednumberNumber of items that could not be processed successfully.
failuresarray<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_idstringIdentifier supplied for the failed item; it may identify a missing asset.
failures[].codestringDomain error code explaining the individual item failure.
created_atstringTime the batch job was created, in UTC.
finished_atstring | nullTime the job reached a terminal status, or null while queued or running.
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

{
  "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_idpathstring库 ID
job_idpathstring任务 ID

返回: Job.

响应

HTTP 200

Successful response.

application/json

名称类型说明
idstringGenerated batch identifier: job_ followed by 32 lowercase hexadecimal characters.
library_idstringIdentifier of the library in which the batch operates.
actionstringBatch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets.
statusstringJob 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.
totalnumberNumber of distinct assets selected when the job was created.
donenumberNumber of items successfully processed; failed items are counted separately.
failednumberNumber of items that could not be processed successfully.
failuresarray<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_idstringIdentifier supplied for the failed item; it may identify a missing asset.
failures[].codestringDomain error code explaining the individual item failure.
created_atstringTime the batch job was created, in UTC.
finished_atstring | nullTime the job reached a terminal status, or null while queued or running.
curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/batches/job_b562f087623c4756b43813e3dce670ba" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "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_idpathstring库 ID

请求体

字段类型必填说明
action"tag" / "untag"是批量操作
tagsstring[]是素材标签。上传可传逗号分隔字符串(每项去首尾空白、丢弃空项)、数组或重复的 tags 字段;PATCH 只接受数组并整体替换
字段类型必填说明
action"set_context"是批量操作
contextobject是自定义文字键值;PATCH 整体替换,传 {} 清空
字段类型必填说明
action"move"是批量操作
asset_folderstring是组织文件夹;不改变 public_id。按它列出时只匹配这一层、不含子文件夹;空字符串表示根
字段类型必填说明
action"delete"是批量操作
字段类型必填说明
selectorBatchSelector是按 ID 或表达式选择

返回: Job.

响应

HTTP 200

Successful response.

application/json

名称类型说明
idstringGenerated batch identifier: job_ followed by 32 lowercase hexadecimal characters.
library_idstringIdentifier of the library in which the batch operates.
actionstringBatch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets.
statusstringJob 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.
totalnumberNumber of distinct assets selected when the job was created.
donenumberNumber of items successfully processed; failed items are counted separately.
failednumberNumber of items that could not be processed successfully.
failuresarray<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_idstringIdentifier supplied for the failed item; it may identify a missing asset.
failures[].codestringDomain error code explaining the individual item failure.
created_atstringTime the batch job was created, in UTC.
finished_atstring | nullTime the job reached a terminal status, or null while queued or running.
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

{
  "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_idpathstring库 ID
job_idpathstring任务 ID

返回: Job.

响应

HTTP 200

Successful response.

application/json

名称类型说明
idstringGenerated batch identifier: job_ followed by 32 lowercase hexadecimal characters.
library_idstringIdentifier of the library in which the batch operates.
actionstringBatch operation: tag adds labels, untag removes labels, set_context replaces custom metadata, move changes asset_folder, and delete removes selected assets.
statusstringJob 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.
totalnumberNumber of distinct assets selected when the job was created.
donenumberNumber of items successfully processed; failed items are counted separately.
failednumberNumber of items that could not be processed successfully.
failuresarray<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_idstringIdentifier supplied for the failed item; it may identify a missing asset.
failures[].codestringDomain error code explaining the individual item failure.
created_atstringTime the batch job was created, in UTC.
finished_atstring | nullTime the job reached a terminal status, or null while queued or running.
curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/jobs/job_3c2fe728de054c7396058c7438b289d2" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "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

字段类型必填说明
idJobId是资源 ID
library_idLibraryId是库 ID
actiontag / untag / set_context / move / delete是批量操作
status"queued" / "running" / "completed" / "completed_with_errors" / "failed"是资源状态
totalnumber是任务素材总数
donenumber是已完成数量;分片响应中表示是否完成
failednumber是失败数量
failuresobject[]是—
created_atIsoTimestamp是创建时间
finished_atIsoTimestamp / null是结束时间;未结束为空

BatchSelector

字段类型必填说明
idsAssetId[]是素材 ID 列表
字段类型必填说明
expressionstring是结构化查询表达式;空表达式返回全部素材
exclusionsAssetId[]否从选择中排除的素材 ID

BatchAction

字段类型必填说明
action"tag" / "untag"是批量操作
tagsstring[]是素材标签。上传可传逗号分隔字符串(每项去首尾空白、丢弃空项)、数组或重复的 tags 字段;PATCH 只接受数组并整体替换
字段类型必填说明
action"set_context"是批量操作
contextobject是自定义文字键值;PATCH 整体替换,传 {} 清空
字段类型必填说明
action"move"是批量操作
asset_folderstring是组织文件夹;不改变 public_id。按它列出时只匹配这一层、不含子文件夹;空字符串表示根
字段类型必填说明
action"delete"是批量操作
导出

本页内容