Media API

2026-10-20

Media API
素材库
素材
理解结果
检索
文件夹
批量操作
事件
错误码

Media API

使用 API Key 作为 Bearer 凭据访问素材库。

https://api.deepraxis.ai/media/v1

资源	参考
素材库	素材库
素材	素材
理解结果	理解结果
检索	检索
文件夹	文件夹
批量操作	批量操作
事件	事件

错误码

素材库

指南 →

基础地址与鉴权

创建库

POST /media/v1/libraries

字段	类型	必填	说明
models	MediaModelsInput	否	各角色的模型调用 ID；局部更新，null 恢复默认
name	string	是	名称，1–64 个字符；允许重名
labels	object	否	标签对象；GET 时传 JSON 字符串；PATCH 整体替换，传 {} 清空
understanding	object	否	视觉、转写与语义理解开关

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
search	object	Search capabilities of this library’s embedding model.
search.image	boolean	Whether this library’s embedding model supports image-based visual search.
models	object	Resolved model call IDs used for new uploads and reprocessing.
models.vision	string	Model call ID for visual descriptions; the model must support image input.
models.embedding	string	Model call ID for search embeddings; must produce compatible vectors and cannot change while assets exist.
models.transcription	string	Model call ID for speech transcription.
id	string	Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
name	string	Display name of the library; duplicate names are allowed.
labels	object	Caller-defined string labels used to organize and filter libraries.
status	string	Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure.
asset_count	number	Number of assets currently stored in the library.
bytes	number	Total source-content size of the library’s assets, in bytes.
understanding	object	Settings controlling understanding tasks for new uploads.
understanding.visual	boolean	Enable captions, tags and OCR for images and video frames.
understanding.transcript	boolean	Enable speech transcription for audio and video soundtracks.
understanding.embedding	boolean	Enable generation of vectors for semantic search.
created_at	string	Time the library was created, in UTC.
updated_at	string	Time library settings, lifecycle or usage were last updated, in UTC.
deleted_at	string \| null	Time the library entered deleting, or null when active or restored.
purge_at	string \| null	Scheduled purge time while the library is deleting; null for an active or restored library.

curl -X POST "https://api.deepraxis.ai/media/v1/libraries" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"walk-lib-r1-MDP-1791733789929","labels":{"sample":"walk-lib-r1-MDP-1791733789929"}}'

HTTP 200

{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "name": "walk-lib-r1-MDP-1791733789929",
  "labels": {
    "sample": "walk-lib-r1-MDP-1791733789929"
  },
  "status": "active",
  "asset_count": 0,
  "bytes": 0,
  "models": {
    "vision": "qwen3.8-flash",
    "embedding": "qwen3-vl-embedding",
    "transcription": "whisper-large-v3-turbo"
  },
  "search": {
    "image": true
  },
  "understanding": {
    "visual": true,
    "transcript": true,
    "embedding": true
  },
  "created_at": "2026-10-11T15:50:04.230Z",
  "updated_at": "2026-10-11T15:50:04.931Z",
  "deleted_at": null,
  "purge_at": null
}

列出库

GET /media/v1/libraries

参数	位置	类型	说明
cursor	query	string	上一页的 next_cursor
limit	query	integer	每页 1–200 条，默认 50
labels	query	string	标签对象；GET 时传 JSON 字符串；PATCH 整体替换，传 {} 清空
status	query	active / deleting	资源状态

返回: LibraryPage.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
data	array<object>	Libraries in this page, ordered by creation time descending.
data[].search	object	Search capabilities of this library’s embedding model.
data[].models	object	Resolved model call IDs used for new uploads and reprocessing.
data[].id	string	Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
data[].name	string	Display name of the library; duplicate names are allowed.
data[].labels	object	Caller-defined string labels used to organize and filter libraries.
data[].status	string	Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure.
data[].asset_count	number	Number of assets currently stored in the library.
data[].bytes	number	Total source-content size of the library’s assets, in bytes.
data[].understanding	object	Settings controlling understanding tasks for new uploads.
data[].created_at	string	Time the library was created, in UTC.
data[].updated_at	string	Time library settings, lifecycle or usage were last updated, in UTC.
data[].deleted_at	string \| null	Time the library entered deleting, or null when active or restored.
data[].purge_at	string \| null	Scheduled purge time while the library is deleting; null for an active or restored library.
next_cursor	string \| null	Opaque token to pass as cursor to listLibraries; null means no further page.

curl -X GET "https://api.deepraxis.ai/media/v1/libraries?labels=%7B%22sample%22%3A%22walk-lib-r1-MDP-1791733789929%22%7D" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "data": [
    {
      "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
      "name": "walk-lib-r1-MDP-1791733789929",
      "status": "active",
      "asset_count": 0,
      "bytes": 0,
      "created_at": "2026-10-11T15:50:04.230Z",
      "updated_at": "2026-10-11T15:50:04.931Z",
      "deleted_at": null,
      "purge_at": null,
      "search": {
        "image": true
      },
      "models": {
        "vision": "qwen3.8-flash",
        "embedding": "qwen3-vl-embedding",
        "transcription": "whisper-large-v3-turbo"
      },
      "labels": {
        "sample": "walk-lib-r1-MDP-1791733789929"
      },
      "understanding": {
        "visual": true,
        "transcript": true,
        "embedding": true
      }
    }
  ],
  "next_cursor": null
}

读取库

GET /media/v1/libraries/{library_id}

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

返回: Library.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
search	object	Search capabilities of this library’s embedding model.
search.image	boolean	Whether this library’s embedding model supports image-based visual search.
models	object	Resolved model call IDs used for new uploads and reprocessing.
models.vision	string	Model call ID for visual descriptions; the model must support image input.
models.embedding	string	Model call ID for search embeddings; must produce compatible vectors and cannot change while assets exist.
models.transcription	string	Model call ID for speech transcription.
id	string	Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
name	string	Display name of the library; duplicate names are allowed.
labels	object	Caller-defined string labels used to organize and filter libraries.
status	string	Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure.
asset_count	number	Number of assets currently stored in the library.
bytes	number	Total source-content size of the library’s assets, in bytes.
understanding	object	Settings controlling understanding tasks for new uploads.
understanding.visual	boolean	Enable captions, tags and OCR for images and video frames.
understanding.transcript	boolean	Enable speech transcription for audio and video soundtracks.
understanding.embedding	boolean	Enable generation of vectors for semantic search.
created_at	string	Time the library was created, in UTC.
updated_at	string	Time library settings, lifecycle or usage were last updated, in UTC.
deleted_at	string \| null	Time the library entered deleting, or null when active or restored.
purge_at	string \| null	Scheduled purge time while the library is deleting; null for an active or restored library.

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

HTTP 200

{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "name": "walk-lib-r1-MDP-1791733789929",
  "status": "active",
  "asset_count": 0,
  "bytes": 0,
  "created_at": "2026-10-11T15:50:04.230Z",
  "updated_at": "2026-10-11T15:50:04.931Z",
  "deleted_at": null,
  "purge_at": null,
  "search": {
    "image": true
  },
  "models": {
    "vision": "qwen3.8-flash",
    "embedding": "qwen3-vl-embedding",
    "transcription": "whisper-large-v3-turbo"
  },
  "labels": {
    "sample": "walk-lib-r1-MDP-1791733789929"
  },
  "understanding": {
    "visual": true,
    "transcript": true,
    "embedding": true
  }
}

更新库

PATCH /media/v1/libraries/{library_id}

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

字段	类型	必填	说明
models	MediaModelsInput	否	各角色的模型调用 ID；局部更新，null 恢复默认
name	string	否	名称，1–64 个字符；允许重名
labels	object	否	标签对象；GET 时传 JSON 字符串；PATCH 整体替换，传 {} 清空
understanding	object	否	视觉、转写与语义理解开关

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
search	object	Search capabilities of this library’s embedding model.
search.image	boolean	Whether this library’s embedding model supports image-based visual search.
models	object	Resolved model call IDs used for new uploads and reprocessing.
models.vision	string	Model call ID for visual descriptions; the model must support image input.
models.embedding	string	Model call ID for search embeddings; must produce compatible vectors and cannot change while assets exist.
models.transcription	string	Model call ID for speech transcription.
id	string	Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
name	string	Display name of the library; duplicate names are allowed.
labels	object	Caller-defined string labels used to organize and filter libraries.
status	string	Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure.
asset_count	number	Number of assets currently stored in the library.
bytes	number	Total source-content size of the library’s assets, in bytes.
understanding	object	Settings controlling understanding tasks for new uploads.
understanding.visual	boolean	Enable captions, tags and OCR for images and video frames.
understanding.transcript	boolean	Enable speech transcription for audio and video soundtracks.
understanding.embedding	boolean	Enable generation of vectors for semantic search.
created_at	string	Time the library was created, in UTC.
updated_at	string	Time library settings, lifecycle or usage were last updated, in UTC.
deleted_at	string \| null	Time the library entered deleting, or null when active or restored.
purge_at	string \| null	Scheduled purge time while the library is deleting; null for an active or restored library.

curl -X PATCH "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"walk-lib-r1-MDP-1791733789929-updated"}'

HTTP 200

{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "name": "walk-lib-r1-MDP-1791733789929-updated",
  "status": "active",
  "asset_count": 0,
  "bytes": 0,
  "created_at": "2026-10-11T15:50:04.230Z",
  "updated_at": "2026-10-11T15:50:07.147Z",
  "deleted_at": null,
  "purge_at": null,
  "search": {
    "image": true
  },
  "models": {
    "vision": "qwen3.8-flash",
    "embedding": "qwen3-vl-embedding",
    "transcription": "whisper-large-v3-turbo"
  },
  "labels": {
    "sample": "walk-lib-r1-MDP-1791733789929"
  },
  "understanding": {
    "visual": true,
    "transcript": true,
    "embedding": true
  }
}

删除库

DELETE /media/v1/libraries/{library_id}

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

返回: Library.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
search	object	Search capabilities of this library’s embedding model.
search.image	boolean	Whether this library’s embedding model supports image-based visual search.
models	object	Resolved model call IDs used for new uploads and reprocessing.
models.vision	string	Model call ID for visual descriptions; the model must support image input.
models.embedding	string	Model call ID for search embeddings; must produce compatible vectors and cannot change while assets exist.
models.transcription	string	Model call ID for speech transcription.
id	string	Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
name	string	Display name of the library; duplicate names are allowed.
labels	object	Caller-defined string labels used to organize and filter libraries.
status	string	Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure.
asset_count	number	Number of assets currently stored in the library.
bytes	number	Total source-content size of the library’s assets, in bytes.
understanding	object	Settings controlling understanding tasks for new uploads.
understanding.visual	boolean	Enable captions, tags and OCR for images and video frames.
understanding.transcript	boolean	Enable speech transcription for audio and video soundtracks.
understanding.embedding	boolean	Enable generation of vectors for semantic search.
created_at	string	Time the library was created, in UTC.
updated_at	string	Time library settings, lifecycle or usage were last updated, in UTC.
deleted_at	string \| null	Time the library entered deleting, or null when active or restored.
purge_at	string \| null	Scheduled purge time while the library is deleting; null for an active or restored library.

curl -X DELETE "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "name": "walk-lib-r1-MDP-1791733789929-updated",
  "status": "deleting",
  "asset_count": 2,
  "bytes": 140,
  "created_at": "2026-10-11T15:50:04.230Z",
  "updated_at": "2026-10-11T15:50:30.664Z",
  "deleted_at": "2026-10-11T15:50:30.664Z",
  "purge_at": "2026-10-18T15:50:30.664Z",
  "search": {
    "image": true
  },
  "models": {
    "vision": "qwen3.8-flash",
    "embedding": "qwen3-vl-embedding",
    "transcription": "whisper-large-v3-turbo"
  },
  "labels": {
    "sample": "walk-lib-r1-MDP-1791733789929"
  },
  "understanding": {
    "visual": true,
    "transcript": true,
    "embedding": true
  }
}

恢复库

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

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

返回: Library.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
search	object	Search capabilities of this library’s embedding model.
search.image	boolean	Whether this library’s embedding model supports image-based visual search.
models	object	Resolved model call IDs used for new uploads and reprocessing.
models.vision	string	Model call ID for visual descriptions; the model must support image input.
models.embedding	string	Model call ID for search embeddings; must produce compatible vectors and cannot change while assets exist.
models.transcription	string	Model call ID for speech transcription.
id	string	Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
name	string	Display name of the library; duplicate names are allowed.
labels	object	Caller-defined string labels used to organize and filter libraries.
status	string	Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure.
asset_count	number	Number of assets currently stored in the library.
bytes	number	Total source-content size of the library’s assets, in bytes.
understanding	object	Settings controlling understanding tasks for new uploads.
understanding.visual	boolean	Enable captions, tags and OCR for images and video frames.
understanding.transcript	boolean	Enable speech transcription for audio and video soundtracks.
understanding.embedding	boolean	Enable generation of vectors for semantic search.
created_at	string	Time the library was created, in UTC.
updated_at	string	Time library settings, lifecycle or usage were last updated, in UTC.
deleted_at	string \| null	Time the library entered deleting, or null when active or restored.
purge_at	string \| null	Scheduled purge time while the library is deleting; null for an active or restored library.

curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/restore" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

HTTP 200

{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "name": "walk-lib-r1-MDP-1791733789929-updated",
  "status": "active",
  "asset_count": 2,
  "bytes": 140,
  "created_at": "2026-10-11T15:50:04.230Z",
  "updated_at": "2026-10-11T15:50:31.379Z",
  "deleted_at": null,
  "purge_at": null,
  "search": {
    "image": true
  },
  "models": {
    "vision": "qwen3.8-flash",
    "embedding": "qwen3-vl-embedding",
    "transcription": "whisper-large-v3-turbo"
  },
  "labels": {
    "sample": "walk-lib-r1-MDP-1791733789929"
  },
  "understanding": {
    "visual": true,
    "transcript": true,
    "embedding": true
  }
}

立即清除库

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

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

返回: PurgedLibrary.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
id	string	Identifier of the library that was permanently purged.
object	string	Resource discriminator identifying a library receipt.
purged	boolean	True when permanent library cleanup has completed.

curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/purge" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

HTTP 200

{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "object": "library",
  "purged": true
}

Library

字段	类型	必填	说明
search	object	是	检索能力；search.image 为 true 时支持以图搜图
models	MediaModels	是	各角色的模型调用 ID；局部更新，null 恢复默认
id	LibraryId	是	资源 ID
name	string	是	名称，1–64 个字符；允许重名
labels	object	是	标签对象；GET 时传 JSON 字符串；PATCH 整体替换，传 {} 清空
status	LibraryStatus	是	资源状态
asset_count	number	是	素材数量
bytes	number	是	文件字节数
understanding	UnderstandingSettings	是	视觉、转写与语义理解开关
created_at	IsoTimestamp	是	创建时间
updated_at	IsoTimestamp	是	更新时间
deleted_at	IsoTimestamp / null	是	删除时间；未删除为 null
purge_at	IsoTimestamp / null	是	恢复截止时间

LibraryPage

字段	类型	必填	说明
data	Library[]	是	本页结果
next_cursor	string / null	是	下一页游标；没有时为 null 或省略

PurgedLibrary

字段	类型	必填	说明
id	LibraryId	是	资源 ID
object	"library"	是	—
purged	true	是	—

Page

字段	类型	必填	说明
data	JSON[]	是	本页结果
next_cursor	string / null	是	下一页游标；没有时为 null 或省略

UnderstandingSettings

字段	类型	必填	说明
visual	boolean	是	视觉理解开关
transcript	boolean	是	转写开关
embedding	boolean	是	语义理解开关

模型角色

models 指定三个角色使用的模型调用 ID（callModelId）。创建库时省略它会使用下表默认值；更新时只改传入的角色，未传的角色保持不变。某个角色传 null 恢复该角色默认值，models: null 恢复全部默认值。

角色	用途	默认值
vision	图片与视频帧的视觉理解	`qwen3.8-flash`
embedding	将内容和检索查询生成向量，用于语义检索	`qwen3-vl-embedding`
transcription	音频转写	`whisper-large-v3-turbo`

写入时查询模型目录，校验传入的模型调用 ID。模型不存在返回 400 INVALID_PARAMS，消息为 Model <id> is not available；目录查询失败返回 502 UPSTREAM_FAILED。vision 必须支持图片输入，否则返回 400 INVALID_PARAMS。未知角色、空白 ID 或不合法的值也返回 400。

库中已有素材时不能更换 embedding，返回 409 LIBRARY_INVALID_STATE，消息为「库中已有素材时不能更换嵌入模型」。同一个向量空间必须由同一个模型生成，才能比较已有素材与查询向量；恢复默认值如果改变了 embedding，也受此限制。

修改 vision 或 transcription 只对新上传或重新处理（reprocess）的素材生效，不会自动重跑已有素材。reprocess 不带 kinds 时只重试失败项；显式指定 kinds 时，会强制重跑所选的已成功、失败或不支持项并替换结果。例如，修改 vision 后传入 { kinds: ["visual"] }，修改 transcription 后传入 { kinds: ["transcript"] }。

以下 PATCH 只将 vision 恢复默认，保留其他角色：

curl -X PATCH "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"models":{"vision":null}}'

新建库默认使用 qwen3-vl-embedding，支持以图搜图；旧库保留 bge-m3。只读字段 search.image 表示当前库是否支持以图搜图。选择其他模型时，会验证它能否输出 1024 维向量；无法输出则返回 INVALID_PARAMS，探测不可用或缺少调用者身份返回 UPSTREAM_FAILED。

素材

指南 →

基础地址与鉴权

列出素材

GET /media/v1/libraries/{library_id}/assets

参数	位置	类型	说明
library_id	path	string	库 ID
asset_folder	query	string	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
resource_type	query	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
cursor	query	string	上一页的 next_cursor
limit	query	integer	每页 1–200 条，默认 50

返回: AssetPage.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
data	array<object>	Assets in this page, ordered by creation time descending.
data[].asset_id	string	Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites.
data[].public_id	string	Delivery identifier unique within this library, used in asset URLs.
data[].display_name	string	Human-readable asset name, independent of its delivery identifier.
data[].asset_folder	string	Organizational folder path; the empty string denotes the root folder.
data[].resource_type	string	Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection.
data[].type	string	Public asset delivery mode; upload is the only supported value.
data[].format	string	Detected file format used as the delivery URL extension.
data[].version	number	Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite.
data[].version_id	string	Identifier for this asset version, regenerated on overwrite.
data[].bytes	number	Size of the original source content, in bytes.
data[].etag	string	MD5 digest of the source bytes, as 32 lowercase hexadecimal characters.
data[].width	number	Source image or video width in pixels, when known.
data[].height	number	Source image or video height in pixels, when known.
data[].duration	number	Source audio or video duration in seconds, when known.
data[].pages	number
data[].is_audio	boolean	True for audio-only media, which uses resource_type video.
data[].original_filename	string	Original or overridden source filename with its final extension removed.
data[].tags	array<string>	Labels attached to the asset.
data[].context	object	Custom string metadata; omitted when empty or excluded by the search projection.
data[].created_at	string	Time this asset identity was created, in UTC.
data[].url	string	URL for retrieving this version of the asset’s original content.
data[].secure_url	string	HTTPS delivery URL for this asset version; equal to url.
data[].placeholder	boolean	False because this response represents stored source content.
data[].existing	boolean
data[].processing	object	Progress of understanding and embedding tasks for the asset.
data[].library_id	string	Identifier of the library containing this asset.
data[].sha256	string	SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters.
data[].status	string	Resource status; active identifies an asset that has not been deleted.
data[].semantic	string	Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending.
data[].preview	object	Generated video previews, present once preview generation succeeds.
next_cursor	string \| null	Opaque token to pass as cursor to listAssets; null means no further page.

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

HTTP 200

{
  "data": [
    {
      "asset_id": "9dfa312ef9bc4b00816339b598b1152c",
      "public_id": "walk-lib-r1-MDP-1791733789929-tagged",
      "display_name": "walk-lib-r1-MDP-1791733789929-tagged",
      "asset_folder": "",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791733815,
      "version_id": "26cb8171caa5431b8373ad417fd71e32",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "tags": [
        "docs"
      ],
      "processing": {
        "state": "processing",
        "kinds": {
          "embedding": "pending",
          "visual": "running",
          "tagging": "running"
        },
        "updated_at": "2026-10-11T15:50:17.571Z"
      },
      "created_at": "2026-10-11T15:50:15.996Z",
      "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
      "placeholder": false,
      "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
      "sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
      "status": "active",
      "semantic": "pending"
    },
    {
      "asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
      "public_id": "walk-lib-r1-MDP-1791733789929-plain",
      "display_name": "walk-lib-r1-MDP-1791733789929-plain",
      "asset_folder": "",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791733810,
      "version_id": "fdf3c8cd40c2424d86e8397425a69857",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "tags": [
        "docs"
      ],
      "created_at": "2026-10-11T15:50:10.842Z",
      "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
      "placeholder": false,
      "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
      "sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
      "status": "active",
      "processing": {
        "state": "processing",
        "kinds": {
          "embedding": "pending",
          "visual": "running"
        },
        "updated_at": "2026-10-11T15:50:17.571Z"
      },
      "semantic": "pending"
    }
  ],
  "next_cursor": null
}

上传素材

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

参数	位置	类型	说明
library_id	path	string	库 ID
X-Unique-Upload-Id	header	string	—
Content-Range	header	string	—

请求体

字段	类型	必填	说明
file	string / string	是	文件字节、HTTPS URL、data URI 或同账户 file_…
public_id	string	否	交付地址中的素材名称，可带路径
public_id_prefix	string	否	public_id 的路径前缀；末尾的 / 可有可无，前缀与 ID 之间只保留一个 /
display_name	string	否	显示名称
asset_folder	string	否	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
use_filename	boolean	否	用文件名生成 public_id
unique_filename	boolean	否	自动附加唯一后缀
use_filename_as_display_name	boolean	否	用文件名作为显示名称
filename_override	string	否	覆盖原文件名称
overwrite	boolean	否	是否覆盖同名素材
tags	string / string[]	否	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	string / object	否	自定义文字键值；PATCH 整体替换，传 {} 清空
auto_tagging	number	否	理解后将达到阈值的标签合并；0–1
resource_type	image / video / raw / auto	否	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400

返回: CloudinaryResource.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
asset_id	string	Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites.
public_id	string	Delivery identifier unique within this library, used in asset URLs.
display_name	string	Human-readable asset name, independent of its delivery identifier.
asset_folder	string	Organizational folder path; the empty string denotes the root folder.
resource_type	string	Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection.
type	string	Public asset delivery mode; upload is the only supported value.
format	string	Detected file format used as the delivery URL extension.
version	number	Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite.
version_id	string	Identifier for this asset version, regenerated on overwrite.
bytes	number	Size of the original source content, in bytes.
etag	string	MD5 digest of the source bytes, as 32 lowercase hexadecimal characters.
width	number	Source image or video width in pixels, when known.
height	number	Source image or video height in pixels, when known.
duration	number	Source audio or video duration in seconds, when known.
pages	number
is_audio	boolean	True for audio-only media, which uses resource_type video.
original_filename	string	Original or overridden source filename with its final extension removed.
tags	array<string>	Labels attached to the asset.
context	object	Custom string metadata; omitted when empty or excluded by the search projection.
context.custom	object	Caller-supplied metadata entries with string values.
created_at	string	Time this asset identity was created, in UTC.
url	string	URL for retrieving this version of the asset’s original content.
secure_url	string	HTTPS delivery URL for this asset version; equal to url.
placeholder	boolean	False because this response represents stored source content.
existing	boolean	True when overwrite=false returns the asset already stored under the requested public_id.
processing	object	Processing progress, included when auto_tagging was requested.
processing.state	string
processing.kinds	object	Processing states by kind. tagging is present when auto_tagging was requested and follows visual understanding.
processing.updated_at	string	Time the processing state was last updated, in UTC.
done	boolean	False while more chunks are needed before the asset is complete. / True when the final chunk has completed the asset upload.
upload_id	string	Upload session identifier supplied in X-Unique-Upload-Id; reuse it for subsequent chunks.

curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"file":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==","public_id":"walk-lib-r1-MDP-1791733789929-tagged","tags":["docs"],"auto_tagging":0.6}'

HTTP 200

{
  "asset_id": "9dfa312ef9bc4b00816339b598b1152c",
  "public_id": "walk-lib-r1-MDP-1791733789929-tagged",
  "display_name": "walk-lib-r1-MDP-1791733789929-tagged",
  "asset_folder": "",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791733815,
  "version_id": "26cb8171caa5431b8373ad417fd71e32",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "processing": {
    "state": "pending",
    "kinds": {
      "visual": "pending",
      "embedding": "pending",
      "tagging": "pending"
    },
    "updated_at": "2026-10-11T15:50:15.996Z"
  },
  "created_at": "2026-10-11T15:50:15.996Z",
  "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
  "placeholder": false
}

导入文件

POST /media/v1/libraries/{library_id}/assets/import

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

请求体

字段	类型	必填	说明
file_id	string	是	同账户文件 ID
public_id	string	否	交付地址中的素材名称，可带路径
public_id_prefix	string	否	public_id 的路径前缀；末尾的 / 可有可无，前缀与 ID 之间只保留一个 /
display_name	string	否	显示名称
asset_folder	string	否	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
use_filename	boolean	否	用文件名生成 public_id
unique_filename	boolean	否	自动附加唯一后缀
use_filename_as_display_name	boolean	否	用文件名作为显示名称
filename_override	string	否	覆盖原文件名称
overwrite	boolean	否	是否覆盖同名素材
tags	string / string[]	否	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	string / object	否	自定义文字键值；PATCH 整体替换，传 {} 清空
auto_tagging	number	否	理解后将达到阈值的标签合并；0–1
resource_type	image / video / raw / auto	否	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400

返回: Asset.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
asset_id	string	Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites.
public_id	string	Delivery identifier unique within this library, used in asset URLs.
display_name	string	Human-readable asset name, independent of its delivery identifier.
asset_folder	string	Organizational folder path; the empty string denotes the root folder.
resource_type	string	Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection.
type	string	Public asset delivery mode; upload is the only supported value.
format	string	Detected file format used as the delivery URL extension.
version	number	Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite.
version_id	string	Identifier for this asset version, regenerated on overwrite.
bytes	number	Size of the original source content, in bytes.
etag	string	MD5 digest of the source bytes, as 32 lowercase hexadecimal characters.
width	number	Source image or video width in pixels, when known.
height	number	Source image or video height in pixels, when known.
duration	number	Source audio or video duration in seconds, when known.
pages	number
is_audio	boolean	True for audio-only media, which uses resource_type video.
original_filename	string	Original or overridden source filename with its final extension removed.
tags	array<string>	Labels attached to the asset.
context	object	Custom string metadata; omitted when empty or excluded by the search projection.
context.custom	object	Caller-supplied metadata entries with string values.
created_at	string	Time this asset identity was created, in UTC.
url	string	URL for retrieving this version of the asset’s original content.
secure_url	string	HTTPS delivery URL for this asset version; equal to url.
placeholder	boolean	False because this response represents stored source content.
existing	boolean
processing	object	Progress of understanding and embedding tasks for the asset.
processing.state	string
processing.kinds	object	Processing states by kind. tagging is present when auto_tagging was requested and follows visual understanding.
processing.updated_at	string	Time the processing state was last updated, in UTC.
library_id	string	Identifier of the library containing this asset.
sha256	string	SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters.
status	string	Resource status; active identifies an asset that has not been deleted.
semantic	string	Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending.
preview	object	Generated video previews, present once preview generation succeeds.
preview.poster_url	string	Delivery URL of the video’s first-frame poster.
preview.storyboard	object	Preview sprite sheet with tile dimensions and sample spacing.

读取素材

GET /media/v1/libraries/{library_id}/assets/{asset_id}

参数	位置	类型	说明
library_id	path	string	库 ID
asset_id	path	string	素材 ID

返回: Asset.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
asset_id	string	Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites.
public_id	string	Delivery identifier unique within this library, used in asset URLs.
display_name	string	Human-readable asset name, independent of its delivery identifier.
asset_folder	string	Organizational folder path; the empty string denotes the root folder.
resource_type	string	Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection.
type	string	Public asset delivery mode; upload is the only supported value.
format	string	Detected file format used as the delivery URL extension.
version	number	Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite.
version_id	string	Identifier for this asset version, regenerated on overwrite.
bytes	number	Size of the original source content, in bytes.
etag	string	MD5 digest of the source bytes, as 32 lowercase hexadecimal characters.
width	number	Source image or video width in pixels, when known.
height	number	Source image or video height in pixels, when known.
duration	number	Source audio or video duration in seconds, when known.
pages	number
is_audio	boolean	True for audio-only media, which uses resource_type video.
original_filename	string	Original or overridden source filename with its final extension removed.
tags	array<string>	Labels attached to the asset.
context	object	Custom string metadata; omitted when empty or excluded by the search projection.
context.custom	object	Caller-supplied metadata entries with string values.
created_at	string	Time this asset identity was created, in UTC.
url	string	URL for retrieving this version of the asset’s original content.
secure_url	string	HTTPS delivery URL for this asset version; equal to url.
placeholder	boolean	False because this response represents stored source content.
existing	boolean
processing	object	Progress of understanding and embedding tasks for the asset.
processing.state	string
processing.kinds	object	Processing states by kind. tagging is present when auto_tagging was requested and follows visual understanding.
processing.updated_at	string	Time the processing state was last updated, in UTC.
library_id	string	Identifier of the library containing this asset.
sha256	string	SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters.
status	string	Resource status; active identifies an asset that has not been deleted.
semantic	string	Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending.
preview	object	Generated video previews, present once preview generation succeeds.
preview.poster_url	string	Delivery URL of the video’s first-frame poster.
preview.storyboard	object	Preview sprite sheet with tile dimensions and sample spacing.

curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets/85b7ef616a8b4719a41777a036ebc1d2" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
  "public_id": "walk-lib-r1-MDP-1791733789929-plain",
  "display_name": "walk-lib-r1-MDP-1791733789929-plain",
  "asset_folder": "",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791733810,
  "version_id": "fdf3c8cd40c2424d86e8397425a69857",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "created_at": "2026-10-11T15:50:10.842Z",
  "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "placeholder": false,
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
  "status": "active",
  "processing": {
    "state": "processing",
    "kinds": {
      "embedding": "pending",
      "visual": "running"
    },
    "updated_at": "2026-10-11T15:50:17.571Z"
  },
  "semantic": "pending"
}

更新素材

PATCH /media/v1/libraries/{library_id}/assets/{asset_id}

参数	位置	类型	说明
library_id	path	string	库 ID
asset_id	path	string	素材 ID

请求体

字段	类型	必填	说明
display_name	string	否	显示名称
asset_folder	string	否	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
tags	string[]	否	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	object	否	自定义文字键值；PATCH 整体替换，传 {} 清空

返回: Asset.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
asset_id	string	Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites.
public_id	string	Delivery identifier unique within this library, used in asset URLs.
display_name	string	Human-readable asset name, independent of its delivery identifier.
asset_folder	string	Organizational folder path; the empty string denotes the root folder.
resource_type	string	Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection.
type	string	Public asset delivery mode; upload is the only supported value.
format	string	Detected file format used as the delivery URL extension.
version	number	Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite.
version_id	string	Identifier for this asset version, regenerated on overwrite.
bytes	number	Size of the original source content, in bytes.
etag	string	MD5 digest of the source bytes, as 32 lowercase hexadecimal characters.
width	number	Source image or video width in pixels, when known.
height	number	Source image or video height in pixels, when known.
duration	number	Source audio or video duration in seconds, when known.
pages	number
is_audio	boolean	True for audio-only media, which uses resource_type video.
original_filename	string	Original or overridden source filename with its final extension removed.
tags	array<string>	Labels attached to the asset.
context	object	Custom string metadata; omitted when empty or excluded by the search projection.
context.custom	object	Caller-supplied metadata entries with string values.
created_at	string	Time this asset identity was created, in UTC.
url	string	URL for retrieving this version of the asset’s original content.
secure_url	string	HTTPS delivery URL for this asset version; equal to url.
placeholder	boolean	False because this response represents stored source content.
existing	boolean
processing	object	Progress of understanding and embedding tasks for the asset.
processing.state	string
processing.kinds	object	Processing states by kind. tagging is present when auto_tagging was requested and follows visual understanding.
processing.updated_at	string	Time the processing state was last updated, in UTC.
library_id	string	Identifier of the library containing this asset.
sha256	string	SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters.
status	string	Resource status; active identifies an asset that has not been deleted.
semantic	string	Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending.
preview	object	Generated video previews, present once preview generation succeeds.
preview.poster_url	string	Delivery URL of the video’s first-frame poster.
preview.storyboard	object	Preview sprite sheet with tile dimensions and sample spacing.

curl -X PATCH "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets/85b7ef616a8b4719a41777a036ebc1d2" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"display_name":"walk-lib-r1-MDP-1791733789929-plain"}'

HTTP 200

{
  "asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
  "public_id": "walk-lib-r1-MDP-1791733789929-plain",
  "display_name": "walk-lib-r1-MDP-1791733789929-plain",
  "asset_folder": "",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791733810,
  "version_id": "fdf3c8cd40c2424d86e8397425a69857",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "created_at": "2026-10-11T15:50:10.842Z",
  "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "placeholder": false,
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
  "status": "active",
  "processing": {
    "state": "processing",
    "kinds": {
      "embedding": "pending",
      "visual": "running"
    },
    "updated_at": "2026-10-11T15:50:17.571Z"
  },
  "semantic": "pending"
}

删除素材

DELETE /media/v1/libraries/{library_id}/assets/{asset_id}

参数	位置	类型	说明
library_id	path	string	库 ID
asset_id	path	string	素材 ID

返回: Deleted.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
deleted	boolean	True once this asset has been removed from the library.

curl -X DELETE "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets/e5f3de0d8609482d8b351894b133c8cb" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "deleted": true
}

重新处理素材

POST /media/v1/libraries/{library_id}/assets/{asset_id}/reprocess

参数	位置	类型	说明
library_id	path	string	库 ID
asset_id	path	string	素材 ID

请求体

字段	类型	必填	说明
kinds	ProcessingKind[]	否	要强制重跑的处理种类；省略时只重试失败项

返回: Asset.

kinds 可选 visual、frames、transcript、embedding。不带 kinds 时，只重跑当前素材版本的失败任务。显式传 kinds 时，所选的 ready、failed、unsupported 任务会重置为 pending 并强制重跑；pending 或 running 任务原样跳过，重复请求不会重复入队。

kinds 必须适用于素材类型：图片为 visual、embedding；音频为 transcript、embedding；视频为 frames、visual、transcript、embedding；raw 没有可重跑的种类。全部不适用时返回 400 INVALID_PARAMS，消息列出该素材可用的 kinds；部分适用时只处理适用的种类，其余忽略（返回的 Asset 没有字段说明被忽略的种类，请以 processing.kinds 为准）。

重跑 visual、frames 或 transcript 时，旧结果立即标记为 superseded，同时将 embedding 与素材的 semantic 置为 pending。旧向量继续服务语义检索，直到新的向量写入后才被替换，因此重新处理期间素材不会从检索结果中消失；期间命中片段可能显示素材名称而非旧描述。默认读取只返回当前结果；使用 include_superseded=true 可查看历史。请求立即返回更新后的 Asset，处理异步完成。

curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets/${ASSET_ID}/reprocess" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
asset_id	string	Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites.
public_id	string	Delivery identifier unique within this library, used in asset URLs.
display_name	string	Human-readable asset name, independent of its delivery identifier.
asset_folder	string	Organizational folder path; the empty string denotes the root folder.
resource_type	string	Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection.
type	string	Public asset delivery mode; upload is the only supported value.
format	string	Detected file format used as the delivery URL extension.
version	number	Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite.
version_id	string	Identifier for this asset version, regenerated on overwrite.
bytes	number	Size of the original source content, in bytes.
etag	string	MD5 digest of the source bytes, as 32 lowercase hexadecimal characters.
width	number	Source image or video width in pixels, when known.
height	number	Source image or video height in pixels, when known.
duration	number	Source audio or video duration in seconds, when known.
pages	number
is_audio	boolean	True for audio-only media, which uses resource_type video.
original_filename	string	Original or overridden source filename with its final extension removed.
tags	array<string>	Labels attached to the asset.
context	object	Custom string metadata; omitted when empty or excluded by the search projection.
context.custom	object	Caller-supplied metadata entries with string values.
created_at	string	Time this asset identity was created, in UTC.
url	string	URL for retrieving this version of the asset’s original content.
secure_url	string	HTTPS delivery URL for this asset version; equal to url.
placeholder	boolean	False because this response represents stored source content.
existing	boolean
processing	object	Progress of understanding and embedding tasks for the asset.
processing.state	string
processing.kinds	object	Processing states by kind. tagging is present when auto_tagging was requested and follows visual understanding.
processing.updated_at	string	Time the processing state was last updated, in UTC.
library_id	string	Identifier of the library containing this asset.
sha256	string	SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters.
status	string	Resource status; active identifies an asset that has not been deleted.
semantic	string	Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending.
preview	object	Generated video previews, present once preview generation succeeds.
preview.poster_url	string	Delivery URL of the video’s first-frame poster.
preview.storyboard	object	Preview sprite sheet with tile dimensions and sample spacing.

AssetPage

字段	类型	必填	说明
data	Asset[]	是	本页结果
next_cursor	string / null	是	下一页游标；没有时为 null 或省略

CloudinaryResource

字段	类型	必填	说明
asset_id	AssetId	是	素材 ID
public_id	string	是	交付地址中的素材名称，可带路径
display_name	string	是	显示名称
asset_folder	string	是	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
resource_type	ResourceType	是	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
type	DeliveryType	是	资源或事件类型
format	string	是	文件格式
version	number	是	交付版本号
version_id	string	是	版本标识
bytes	number	是	文件字节数
etag	string	是	文件校验标识
width	number	否	宽度像素
height	number	否	高度像素
duration	number	否	时长秒数
pages	number	否	文档页数
is_audio	boolean	否	是否为音频
original_filename	string	否	原文件名称
tags	string[]	是	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	object	否	自定义文字键值；PATCH 整体替换，传 {} 清空
created_at	IsoTimestamp	是	创建时间
url	string	是	原文件地址
secure_url	string	是	HTTPS 交付地址
placeholder	false	是	固定为 false
existing	boolean	否	未覆盖时是否返回已有素材
processing	Processing	否	整体与各项理解状态

Asset

字段	类型	必填	说明
asset_id	AssetId	是	素材 ID
public_id	string	是	交付地址中的素材名称，可带路径
display_name	string	是	显示名称
asset_folder	string	是	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
resource_type	ResourceType	是	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
type	DeliveryType	是	资源或事件类型
format	string	是	文件格式
version	number	是	交付版本号
version_id	string	是	版本标识
bytes	number	是	文件字节数
etag	string	是	文件校验标识
width	number	否	宽度像素
height	number	否	高度像素
duration	number	否	时长秒数
pages	number	否	文档页数
is_audio	boolean	否	是否为音频
original_filename	string	否	原文件名称
tags	string[]	是	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	object	否	自定义文字键值；PATCH 整体替换，传 {} 清空
created_at	IsoTimestamp	是	创建时间
url	string	是	原文件地址
secure_url	string	是	HTTPS 交付地址
placeholder	false	是	固定为 false
existing	boolean	否	未覆盖时是否返回已有素材
processing	Processing	是	整体与各项理解状态
library_id	LibraryId	是	库 ID
sha256	string	是	内容校验摘要
status	"active"	是	资源状态
semantic	"pending" / "ready" / "unavailable"	是	ready 时可语义检索
preview	object	否	预览海报和故事板

Deleted

字段	类型	必填	说明
deleted	true	是	删除结果

Processing

字段	类型	必填	说明
state	ProcessingState	是	整体处理状态
kinds	object	是	各项处理状态
updated_at	IsoTimestamp	是	更新时间

Storyboard

字段	类型	必填	说明
url	string	是	原文件地址
tiles	number	是	故事板画面数
interval_ms	number	是	画面间隔毫秒数
tile_width	number	是	单个画面宽度
tile_height	number	是	单个画面高度

理解结果

重新理解已有素材

转写幻听过滤

转写片段先做全角转半角、转小写并去除首尾空白和标点。规范化后为空，或整段命中常见幻听短语表时，丢弃该片段。仅完整匹配，不做子串匹配，例如 “thank you for the report” 会保留。

短语表包括：thank you、thanks for watching、thank you for watching、please subscribe、subscribe、you、bye、字幕由amara.org社区提供、请不吝点赞订阅转发打赏支持明镜与点点栏目、谢谢观看、优优独播剧场——yoyo television series exclusive。

被过滤的片段不进入转写文字、关键词索引或转写向量。全部被过滤时，transcript 理解仍为 ready，content 为空字符串，data 为 { "filtered_segments": n }，n 是被过滤的片段数；该素材不会生成转写向量。

指南 →

基础地址与鉴权

读取理解

GET /media/v1/libraries/{library_id}/assets/{asset_id}/understandings

参数	位置	类型	说明
library_id	path	string	库 ID
asset_id	path	string	素材 ID
include_superseded	query	boolean	包含已被新版本替代的结果；只接受 true 或 false
kind	query	caption / tags / ocr / transcript / frame	理解或处理种类；列出理解结果时按此筛选
cursor	query	string	上一页的 next_cursor
limit	query	integer	每页 1–200 条，默认 200

返回: UnderstandingPage.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
data	array<object>	Understanding results in this page, ordered by creation time ascending.
data[].id	string	Generated identifier of this understanding result.
data[].asset_id	string	Identifier of the asset from which this result was produced.
data[].asset_version	number	Asset version processed to produce this result; compare with the asset’s current version.
data[].kind	string	Result kind: caption is a visual description, tags are recognized labels, ocr is text recognized in the image, transcript is speech text, and frame is a description of a video segment.
data[].producer	string	Producer model identifier; a failure may use the configured model when no model response is available.
data[].producer_version	string
data[].segment	object \| null	Source-media time range for a frame or transcript segment; null for results without a segment.
data[].status	string	Result status: ready contains completed output; failed records an error.
data[].content	string \| null	Text output, such as a caption, recognized text or transcript; null for structured-only or failed results.
data[].data	any \| null	Structured producer output, such as recognized labels or frame details; null when absent.
data[].confidence	number \| null
data[].error	object \| null	Failure code and message, or null for a successful result.
data[].superseded	boolean	Whether a newer result or asset version has replaced this result. Excluded from listing unless include_superseded is true.
data[].created_at	string	Time this immutable result was recorded, in UTC.
next_cursor	string \| null	Opaque token to pass as cursor to listUnderstandings; null means no further page.

curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets/9339cdae93804c0c8c65d5189ef1f646/understandings" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "data": [],
  "next_cursor": null
}

UnderstandingPage

字段	类型	必填	说明
data	Understanding[]	是	本页结果
next_cursor	string / null	是	下一页游标；没有时为 null 或省略

Understanding

字段	类型	必填	说明
id	UnderstandingId	是	资源 ID
asset_id	AssetId	是	素材 ID
asset_version	number	是	理解对应的素材版本
kind	UnderstandingKind	是	理解或处理种类；列出理解结果时按此筛选
producer	string	是	理解生成者
producer_version	string	是	生成者版本
segment	Segment / null	是	起止毫秒；整份素材为 null
status	"ready" / "failed"	是	资源状态
content	string / null	是	理解的文字内容
data	JSON / null	是	本页结果
confidence	number / null	是	置信度；可能为空
error	object / null	是	错误码与消息；成功时为空
superseded	boolean	是	是否被新版本替代
created_at	IsoTimestamp	是	创建时间

Segment

字段	类型	必填	说明
start_ms	number	是	片段开始毫秒
end_ms	number	是	片段结束毫秒

检索

expression 接受表达式；semantic 与 search 接受自然语言。语义检索只返回就绪素材。

表达式语法

指南 →

基础地址与鉴权

表达式检索

POST /media/v1/libraries/{library_id}/search/expression

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

请求体

字段	类型	必填	说明
expression	string	否	结构化查询表达式；空表达式返回全部素材
sort_by	object[]	否	排序字段与方向
max_results	integer	否	最多 500；检索默认 100，Admin 默认 10
next_cursor	string	否	下一页游标；没有时为 null 或省略
with_field	tags / context[]	否	额外返回 tags 或 context
aggregate	AggregateField[]	否	统计字段

返回: ExpressionSearchResult.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
total_count	number	Number of matching assets across pages; a lower bound when total_count_exact is false.
time	number	Elapsed search time in whole milliseconds.
next_cursor	string	Continuation token for the next page; omitted when no further page is available.
resources	array<object>	Assets in this page, ordered by sort_by; tags and context follow with_field.
resources[].asset_id	string	Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites.
resources[].public_id	string	Delivery identifier unique within this library, used in asset URLs.
resources[].display_name	string	Human-readable asset name, independent of its delivery identifier.
resources[].asset_folder	string	Organizational folder path; the empty string denotes the root folder.
resources[].resource_type	string	Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection.
resources[].type	string	Public asset delivery mode; upload is the only supported value.
resources[].format	string	Detected file format used as the delivery URL extension.
resources[].version	number	Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite.
resources[].version_id	string	Identifier for this asset version, regenerated on overwrite.
resources[].bytes	number	Size of the original source content, in bytes.
resources[].etag	string	MD5 digest of the source bytes, as 32 lowercase hexadecimal characters.
resources[].width	number	Source image or video width in pixels, when known.
resources[].height	number	Source image or video height in pixels, when known.
resources[].duration	number	Source audio or video duration in seconds, when known.
resources[].pages	number
resources[].is_audio	boolean	True for audio-only media, which uses resource_type video.
resources[].original_filename	string	Original or overridden source filename with its final extension removed.
resources[].tags	array<string>	Labels attached to the asset.
resources[].context	object	Custom string metadata; omitted when empty or excluded by the search projection.
resources[].created_at	string	Time this asset identity was created, in UTC.
resources[].url	string	URL for retrieving this version of the asset’s original content.
resources[].secure_url	string	HTTPS delivery URL for this asset version; equal to url.
resources[].placeholder	boolean	False because this response represents stored source content.
resources[].existing	boolean
resources[].processing	object	Progress of understanding and embedding tasks for the asset.
resources[].library_id	string	Identifier of the library containing this asset.
resources[].sha256	string	SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters.
resources[].status	string	Resource status; active identifies an asset that has not been deleted.
resources[].semantic	string	Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending.
resources[].preview	object	Generated video previews, present once preview generation succeeds.
aggregations	object	Requested facet counts, keyed by facet name and then by field value.
total_count_exact	boolean	Whether total_count covers all matches; false indicates a bounded partial count.
aggregations_exact	boolean	Whether the returned facet counts cover all matching assets.

curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/search/expression" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"expression":"tags:docs"}'

HTTP 200

{
  "total_count": 2,
  "total_count_exact": true,
  "time": 0,
  "resources": [
    {
      "asset_id": "9dfa312ef9bc4b00816339b598b1152c",
      "public_id": "walk-lib-r1-MDP-1791733789929-tagged",
      "display_name": "walk-lib-r1-MDP-1791733789929-tagged",
      "asset_folder": "",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791733815,
      "version_id": "26cb8171caa5431b8373ad417fd71e32",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "processing": {
        "state": "processing",
        "kinds": {
          "embedding": "pending",
          "visual": "running",
          "tagging": "running"
        },
        "updated_at": "2026-10-11T15:50:17.571Z"
      },
      "created_at": "2026-10-11T15:50:15.996Z",
      "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
      "placeholder": false,
      "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
      "sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
      "status": "active",
      "semantic": "pending"
    },
    {
      "asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
      "public_id": "walk-lib-r1-MDP-1791733789929-plain",
      "display_name": "walk-lib-r1-MDP-1791733789929-plain",
      "asset_folder": "",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791733810,
      "version_id": "fdf3c8cd40c2424d86e8397425a69857",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "created_at": "2026-10-11T15:50:10.842Z",
      "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
      "placeholder": false,
      "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
      "sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
      "status": "active",
      "processing": {
        "state": "processing",
        "kinds": {
          "embedding": "pending",
          "visual": "running"
        },
        "updated_at": "2026-10-11T15:50:17.571Z"
      },
      "semantic": "pending"
    }
  ]
}

以图搜图

POST /media/v1/libraries/{library_id}/search/visual

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

请求体

字段	类型	必填	说明
asset_id	AssetId	否	素材 ID
image	object	否	查询图片对象，data 为 base64，mime 为图片类型
top_k	integer	否	命中数，1–50
filter	string	否	表达式筛选条件

返回: SemanticSearchResult.

库的 search.image 为 true 时可用；不支持的库返回 LIBRARY_INVALID_STATE。图片仅接受 JPEG、PNG、WebP、GIF，解码后最大 10 MiB。每个素材返回最高分命中，视频定位到最佳帧。qwen3-vl-embedding 的图片相似度门槛为 0.35。标定来自 2026-10-10 的测试：同图变体 0.82–0.96，同类场景 0.38–0.66，无关图片最高 0.34。

asset_id 与 image: { data, mime } 必须且只能给一个。asset_id 复用已有图片理解并排除素材自身；视频使用第一帧，未完成理解返回 LIBRARY_INVALID_STATE。上传图片的 data 为 base64。top_k 默认 20，范围 1–50；filter 使用与 semantic 相同的表达式。仅检索图片相似内容，返回与 semantic 相同的 hits、embedding_producer、not_ready_excluded；matches.kind 为 image，snippet 为最新描述或素材名称。删除、旧版本及已替换的理解不会出现在结果中。

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
hits	array<object>	Ranked assets up to top_k; an empty array means no eligible matches were found.
hits[].asset	object	Asset matched by the query.
hits[].score	number	Ranking score: cosine similarity for semantic or visual search; normalized rank-fusion score for hybrid search. Higher values rank first.
hits[].semantic_score	number \| null	Cosine similarity for hybrid hits with a semantic match; null for keyword-only hybrid hits. Omitted outside hybrid mode.
hits[].matches	array<object>	Supporting content or metadata matches contributing to this asset’s hit.
embedding_producer	string	Embedding model identifier used for the query, or for the source asset embedding in an asset-based visual query.
not_ready_excluded	number	Number of distinct candidate asset identifiers, or unresolved vector identifiers, excluded because their vectors or assets were missing, deleted or stale; not a count of all pending assets in the library.

语义检索

POST /media/v1/libraries/{library_id}/search/semantic

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

请求体

字段	类型	必填	说明
query	string	是	用自然语言描述要找的内容
filter	string	否	表达式筛选条件
top_k	integer	否	命中数，1–50
mode	hybrid / semantic	否	hybrid 结合关键词与语义；semantic 仅语义

返回: SemanticSearchResult.

使用 bge-m3 时，向量候选在与关键词结果融合前按余弦相似度 ≥ 0.55 筛选，新完成的内容也使用相同门槛。门槛依据 2026-10-09 的 7 个演示素材标定：相关结果最低约 0.58（0.581–0.729），不相关结果最高 0.523；完全无关的查询最高 0.478。qwen3-vl-embedding 的文字查询对文字内容（描述、转写）门槛为 0.40，对图片内容门槛为 0.25；其他模型尚未标定，暂不过滤。关键词命中不受此门槛影响。查询与库内容都不相关时返回空列表；mode=semantic 只返回达到向量门槛的结果。

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
hits	array<object>	Ranked assets up to top_k; an empty array means no eligible matches were found.
hits[].asset	object	Asset matched by the query.
hits[].score	number	Ranking score: cosine similarity for semantic or visual search; normalized rank-fusion score for hybrid search. Higher values rank first.
hits[].semantic_score	number \| null	Cosine similarity for hybrid hits with a semantic match; null for keyword-only hybrid hits. Omitted outside hybrid mode.
hits[].matches	array<object>	Supporting content or metadata matches contributing to this asset’s hit.
embedding_producer	string	Embedding model identifier used for the query, or for the source asset embedding in an asset-based visual query.
not_ready_excluded	number	Number of distinct candidate asset identifiers, or unresolved vector identifiers, excluded because their vectors or assets were missing, deleted or stale; not a count of all pending assets in the library.

语义检索别名

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

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

请求体

字段	类型	必填	说明
query	string	是	用自然语言描述要找的内容
filter	string	否	表达式筛选条件
top_k	integer	否	命中数，1–50
mode	hybrid / semantic	否	hybrid 结合关键词与语义；semantic 仅语义

返回: SemanticSearchResult.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
hits	array<object>	Ranked assets up to top_k; an empty array means no eligible matches were found.
hits[].asset	object	Asset matched by the query.
hits[].score	number	Ranking score: cosine similarity for semantic or visual search; normalized rank-fusion score for hybrid search. Higher values rank first.
hits[].semantic_score	number \| null	Cosine similarity for hybrid hits with a semantic match; null for keyword-only hybrid hits. Omitted outside hybrid mode.
hits[].matches	array<object>	Supporting content or metadata matches contributing to this asset’s hit.
embedding_producer	string	Embedding model identifier used for the query, or for the source asset embedding in an asset-based visual query.
not_ready_excluded	number	Number of distinct candidate asset identifiers, or unresolved vector identifiers, excluded because their vectors or assets were missing, deleted or stale; not a count of all pending assets in the library.

ExpressionSearchResult

字段	类型	必填	说明
total_count	number	是	匹配总数
time	number	是	检索耗时，整数毫秒，由服务端测得
next_cursor	string	否	下一页游标；没有时为 null 或省略
resources	SearchAsset[]	是	本页素材
aggregations	object	否	按请求字段统计
total_count_exact	boolean	否	计数是否精确
aggregations_exact	boolean	否	统计是否精确

SemanticSearchResult

字段	类型	必填	说明
hits	SemanticHit[]	是	检索命中
embedding_producer	string	是	语义理解生成者
not_ready_excluded	number	是	因未就绪而排除的素材数

SearchAsset

字段	类型	必填	说明
asset_id	AssetId	是	素材 ID
public_id	string	是	交付地址中的素材名称，可带路径
display_name	string	是	显示名称
asset_folder	string	是	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
resource_type	ResourceType	是	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
type	DeliveryType	是	资源或事件类型
format	string	是	文件格式
version	number	是	交付版本号
version_id	string	是	版本标识
bytes	number	是	文件字节数
etag	string	是	文件校验标识
width	number	否	宽度像素
height	number	否	高度像素
duration	number	否	时长秒数
pages	number	否	文档页数
is_audio	boolean	否	是否为音频
original_filename	string	否	原文件名称
tags	string[]	否	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	object	否	自定义文字键值；PATCH 整体替换，传 {} 清空
created_at	IsoTimestamp	是	创建时间
url	string	是	原文件地址
secure_url	string	是	HTTPS 交付地址
placeholder	false	是	固定为 false
existing	boolean	否	未覆盖时是否返回已有素材
processing	Processing	是	整体与各项理解状态
library_id	LibraryId	是	库 ID
sha256	string	是	内容校验摘要
status	"active"	是	资源状态
semantic	"pending" / "ready" / "unavailable"	是	ready 时可语义检索
preview	object	否	预览海报和故事板

SemanticHit

字段	类型	必填	说明
asset	Asset	是	命中的素材
score	number	是	相关度分数
semantic_score	number / null	否	—
matches	SemanticMatch[]	是	匹配内容与片段时间

SemanticMatch

字段	类型	必填	说明
kind	UnderstandingKind / "metadata" / "image"	是	理解或处理种类；列出理解结果时按此筛选
understanding_id	UnderstandingId / null	是	对应的理解记录；元数据命中为空
segment	Segment / null	是	起止毫秒；整份素材为 null
snippet	string	是	命中文字片段

文件夹

指南 →

基础地址与鉴权

列出文件夹

GET /media/v1/libraries/{library_id}/folders

参数	位置	类型	说明
library_id	path	string	库 ID
parent	query	string	父文件夹路径；省略或空字符串为根。一次返回这一层的全部子文件夹，不分页；传 limit 或 cursor 返回 400

返回: Folders.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
folders	array<object>	All immediate child folders of parent, sorted by path.
folders[].name	string	Final path segment naming the child folder.
folders[].path	string	Full folder path relative to the library root.
folders[].asset_count	number	Number of assets in this folder and all descendant folders.

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

HTTP 200

{
  "folders": [
    {
      "name": "examples",
      "path": "examples",
      "asset_count": 1
    }
  ]
}

Folders

字段	类型	必填	说明
folders	object[]	是	文件夹列表

批量操作

指南 →

基础地址与鉴权

批量操作

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

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.

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_id	path	string	库 ID
job_id	path	string	任务 ID

返回: Job.

响应

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.

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_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

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.

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_id	path	string	库 ID
job_id	path	string	任务 ID

返回: Job.

响应

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.

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

字段	类型	必填	说明
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

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

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

BatchAction

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

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

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

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

事件

按 seq 翻页：asc 配 after_seq，desc 配 before_seq；两个游标不可同用。

指南 →

基础地址与鉴权

读取事件

GET /media/v1/libraries/{library_id}/events

参数	位置	类型	说明
library_id	path	string	库 ID
after_seq	query	integer	升序游标；不可与 before_seq 同用
before_seq	query	integer	降序游标；不可与 after_seq 同用
order	query	asc / desc	asc 默认升序或 desc 降序
limit	query	integer	每页 1–200 条，默认 50

返回: MediaEventPage.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
data	array<object>	Events in this page, ordered by sequence in the requested direction.
data[].seq	number	Increasing sequence number within this library; use it with after_seq or before_seq to page through events.
data[].id	string	Unique identifier of this recorded event.
data[].type	string	Type of lifecycle, asset, processing, search or batch change recorded.
data[].processed_at	string	Time this event was recorded, in UTC.
data[].library_id	string	Identifier of the library whose event was recorded.
data[].asset_id	string	Related asset identifier, when the event concerns an asset.
data[].job_id	string	Related batch job identifier, when present.
data[].kind	string	Related processing task: visual, frames, transcript or embedding.
data[].detail	object	Event-specific details, such as changed values, reprocessing kinds or failed-item counts.
next_cursor	string \| null	Last returned sequence as a string when more events exist; convert to a number and pass as after_seq for asc or before_seq for desc. Null means no further page.

curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/events?limit=1" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "data": [
    {
      "seq": 1,
      "id": "2cd2cd71-1fc5-41fc-aeb0-29583af9b900",
      "type": "library.status_provisioning",
      "processed_at": "2026-10-09T09:34:09.858Z",
      "library_id": "lib_fff73e25733449b1bf6f880d91f5c045"
    }
  ],
  "next_cursor": "1"
}

MediaEventPage

字段	类型	必填	说明
data	MediaEvent[]	是	本页结果
next_cursor	string / null	是	下一页游标；没有时为 null 或省略

MediaEvent

字段	类型	必填	说明
seq	number	是	库内递增的事件序号
id	string	是	资源 ID
type	MediaEventType	是	资源或事件类型
processed_at	IsoTimestamp	是	事件时间
library_id	LibraryId	是	库 ID
asset_id	AssetId	否	素材 ID
job_id	JobId	否	任务 ID
kind	ProcessingKind	否	理解或处理种类；列出理解结果时按此筛选
detail	object	否	事件详情

错误码

指南 →

自有 API 返回 error.code、error.message、error.details。兼容接口返回 error.message，并通过 X-Cld-Error 响应头重复消息；非 ASCII 消息在响应头中使用百分号编码。

领域码	自有 HTTP	兼容 HTTP	可重试
LIBRARY_NOT_FOUND	404	404	否
ASSET_NOT_FOUND	404	404	否
JOB_NOT_FOUND	404	404	否
UNDERSTANDING_NOT_FOUND	404	404	否
LIBRARY_INVALID_STATE	409	400	否
INVALID_PARAMS	400	400	否
INVALID_EXPRESSION	400	400	否
UNSUPPORTED	400	400	否
NOT_IMPLEMENTED	501	400	否
FILE_TOO_LARGE	413	400	否
FILE_EMPTY	400	400	否
UNSUPPORTED_MEDIA	415	400	否
FETCH_FAILED	400	400	否
LIMIT_EXCEEDED	400	400	否
CHUNK_INVALID	400	400	否
RATE_LIMITED	429	420	是
CAPACITY	503	500	是
UPSTREAM_FAILED	502	500	是

可重试错误采用退避重试；其它错误先修正请求或资源状态。

模型配置错误

400 INVALID_PARAMS：模型调用 ID 不存在（Model <id> is not available）、vision 模型不支持图片输入，或 models 含未知角色、空白 ID 或不合法的值。
409 LIBRARY_INVALID_STATE：库中已有素材时更换 embedding，包括恢复默认值导致模型改变。消息为「库中已有素材时不能更换嵌入模型」。
502 UPSTREAM_FAILED：写入模型配置时无法查询模型目录；可退避重试。