素材

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

响应

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

响应

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 整体替换，传 {} 清空

响应

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	是	单个画面高度

素材

列出素材

响应

HTTP 200

上传素材

请求体

响应

HTTP 200

导入文件

请求体

响应

HTTP 200

读取素材

响应

HTTP 200

更新素材

请求体

响应

HTTP 200

删除素材

响应

HTTP 200

重新处理素材

请求体

响应

HTTP 200

AssetPage

CloudinaryResource

Asset

Deleted

Processing

Storyboard

本页内容