Media API

2026-10-22

Media API
Libraries
Assets
Understandings
Search
Folders
Batches
Events
Error codes

Media API

Access libraries with an API Key as a Bearer credential.

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

Resource	Reference
Libraries	Libraries
Assets	Assets
Understandings	Understandings
Search	Search
Folders	Folders
Batches	Batches
Events	Events

Error codes

Libraries

Guide →

Base URL and authentication

Create library

POST /media/v1/libraries

Field	Type	Required	Description
models	MediaModelsInput	no	Model call IDs by role; partial updates, null restores defaults
name	string	yes	Name, 1–64 characters; duplicates are allowed
labels	object	no	Labels object; JSON-encode for GET. PATCH replaces the whole object; {} clears it
understanding	object	no	Visual, transcript, and semantic understanding settings

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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
}

List libraries

GET /media/v1/libraries

Parameter	Location	Type	Description
cursor	query	string	Previous next_cursor
limit	query	integer	1–200 items per page, default 50
labels	query	string	Labels object; JSON-encode for GET. PATCH replaces the whole object; {} clears it
status	query	active / deleting	Resource status

Returns: LibraryPage.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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 library

GET /media/v1/libraries/{library_id}

Parameter	Location	Type	Description
library_id	path	string	Library ID

Returns: Library.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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
  }
}

Update library

PATCH /media/v1/libraries/{library_id}

Parameter	Location	Type	Description
library_id	path	string	Library ID

Field	Type	Required	Description
models	MediaModelsInput	no	Model call IDs by role; partial updates, null restores defaults
name	string	no	Name, 1–64 characters; duplicates are allowed
labels	object	no	Labels object; JSON-encode for GET. PATCH replaces the whole object; {} clears it
understanding	object	no	Visual, transcript, and semantic understanding settings

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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 library

DELETE /media/v1/libraries/{library_id}

Parameter	Location	Type	Description
library_id	path	string	Library ID

Returns: Library.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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
  }
}

Restore library

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

Parameter	Location	Type	Description
library_id	path	string	Library ID

Returns: Library.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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
  }
}

Purge library

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

Parameter	Location	Type	Description
library_id	path	string	Library ID

Returns: PurgedLibrary.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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

Field	Type	Required	Description
search	object	yes	Search capabilities; search.image enables visual search
models	MediaModels	yes	Model call IDs by role; partial updates, null restores defaults
id	LibraryId	yes	Resource ID
name	string	yes	Name, 1–64 characters; duplicates are allowed
labels	object	yes	Labels object; JSON-encode for GET. PATCH replaces the whole object; {} clears it
status	LibraryStatus	yes	Resource status
asset_count	number	yes	Asset count
bytes	number	yes	File size in bytes
understanding	UnderstandingSettings	yes	Visual, transcript, and semantic understanding settings
created_at	IsoTimestamp	yes	Creation time
updated_at	IsoTimestamp	yes	Update time
deleted_at	IsoTimestamp / null	yes	Deletion time; null when not deleted
purge_at	IsoTimestamp / null	yes	Recovery deadline

LibraryPage

Field	Type	Required	Description
data	Library[]	yes	Results in this page
next_cursor	string / null	yes	Next-page cursor; null or absent at the end

PurgedLibrary

Field	Type	Required	Description
id	LibraryId	yes	Resource ID
object	"library"	yes	—
purged	true	yes	—

Page

Field	Type	Required	Description
data	JSON[]	yes	Results in this page
next_cursor	string / null	yes	Next-page cursor; null or absent at the end

UnderstandingSettings

Field	Type	Required	Description
visual	boolean	yes	Enable visual understanding
transcript	boolean	yes	Enable transcription
embedding	boolean	yes	Enable semantic understanding

models selects a model call ID (callModelId) for each of three roles. Creating a library without it uses the defaults below. Updates change only the supplied roles; omitted roles remain unchanged. Set a role to null to restore its default, or set models: null to restore all defaults.

Role	Purpose	Default
vision	Visual understanding of images and video frames	`qwen3.8-flash`
embedding	Embed content and search queries for semantic retrieval	`qwen3-vl-embedding`
transcription	Audio transcription	`whisper-large-v3-turbo`

Writes check supplied model call IDs against the model catalog. A missing model returns 400 INVALID_PARAMS with Model <id> is not available; a catalog lookup failure returns 502 UPSTREAM_FAILED. The vision model must support image input, or the request returns 400 INVALID_PARAMS. Unknown roles, blank IDs, and invalid values also return 400.

Once a library contains assets, changing embedding returns 409 LIBRARY_INVALID_STATE with “库中已有素材时不能更换嵌入模型”. A single vector space must use the same model so that existing asset vectors and query vectors remain comparable. Restoring defaults is subject to the same lock if it changes embedding.

Changes to vision or transcription apply only to newly uploaded or reprocessed assets; existing assets are not automatically processed again. Without kinds, reprocess retries only failed kinds. Explicit kinds force reruns of selected ready, failed, or unsupported kinds and replace their results. For example, pass { kinds: ["visual"] } after changing vision, or { kinds: ["transcript"] } after changing transcription.

This PATCH restores only vision to its default and preserves the other roles:

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}}'

New libraries default to qwen3-vl-embedding with visual search; legacy libraries retain bge-m3. Read-only search.image indicates image-search capability. Other models are checked for 1024-dimensional output; incompatible dimensions return INVALID_PARAMS, while unavailable probes or missing caller identity return UPSTREAM_FAILED.

Assets

Guide →

Base URL and authentication

List assets

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
asset_folder	query	string	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root
resource_type	query	image / video / raw	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400
cursor	query	string	Previous next_cursor
limit	query	integer	1–200 items per page, default 50

Returns: AssetPage.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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
}

Upload asset

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
X-Unique-Upload-Id	header	string	Stable identifier shared by every chunk of this upload.
Content-Range	header	string	Chunk byte range: bytes start-end/total; total may be -1 until the final chunk.

Request body

Field	Type	Required	Description
file	string / string	yes	File bytes, HTTPS URL, data URI, or same-account file_…
public_id	string	no	Asset name in delivery URLs; may contain path segments
public_id_prefix	string	no	Path prefix for public_id; a trailing / is optional and exactly one / separates prefix and ID
display_name	string	no	Display name
asset_folder	string	no	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root
use_filename	boolean	no	Use the file name for public_id
unique_filename	boolean	no	Append a unique suffix
use_filename_as_display_name	boolean	no	Use the file name as display_name
filename_override	string	no	Override the original file name
overwrite	boolean	no	Whether to overwrite a matching public ID
tags	string / string[]	no	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list
context	string / object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it
auto_tagging	number	no	Merge tags meeting the threshold after understanding; 0–1
resource_type	image / video / raw / auto	no	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400

Returns: CloudinaryResource.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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
}

Import file

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

Parameter	Location	Type	Description
library_id	path	string	Library ID

Request body

Field	Type	Required	Description
file_id	string	yes	File ID owned by the same account
public_id	string	no	Asset name in delivery URLs; may contain path segments
public_id_prefix	string	no	Path prefix for public_id; a trailing / is optional and exactly one / separates prefix and ID
display_name	string	no	Display name
asset_folder	string	no	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root
use_filename	boolean	no	Use the file name for public_id
unique_filename	boolean	no	Append a unique suffix
use_filename_as_display_name	boolean	no	Use the file name as display_name
filename_override	string	no	Override the original file name
overwrite	boolean	no	Whether to overwrite a matching public ID
tags	string / string[]	no	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list
context	string / object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it
auto_tagging	number	no	Merge tags meeting the threshold after understanding; 0–1
resource_type	image / video / raw / auto	no	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400

Returns: Asset.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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 asset

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
asset_id	path	string	Asset ID

Returns: Asset.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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"
}

Update asset

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
asset_id	path	string	Asset ID

Request body

Field	Type	Required	Description
display_name	string	no	Display name
asset_folder	string	no	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root
tags	string[]	no	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list
context	object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it

Returns: Asset.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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 asset

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
asset_id	path	string	Asset ID

Returns: Deleted.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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
}

Reprocess asset

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
asset_id	path	string	Asset ID

Request body

Field	Type	Required	Description
kinds	ProcessingKind[]	no	Processing kinds to force rerun; omit to retry only failed kinds

Returns: Asset.

Allowed kinds are visual, frames, transcript, and embedding. Without kinds, only failed tasks for the current asset version are rerun. Explicit kinds force selected ready, failed, or unsupported tasks back to pending for a rerun. Tasks already pending or running are skipped unchanged; repeated requests do not enqueue duplicate work.

Kinds must apply to the asset type: images have visual and embedding; audio has transcript and embedding; video has frames, visual, transcript, and embedding; raw files have none. When no requested kind applies, the request returns 400 INVALID_PARAMS listing the kinds available for that asset. When some apply, only those are processed and the rest are ignored (the returned Asset has no field naming ignored kinds; check processing.kinds).

Rerunning visual, frames, or transcript immediately supersedes the old results and sets embedding and the asset’s semantic state to pending. The previous vectors keep serving semantic search until the new vectors are written, so the asset does not drop out of results while it is reprocessed; matches in that window may show the asset name instead of the old caption. Reads return only current results by default; use include_superseded=true to inspect history. The request returns the updated Asset immediately; processing completes asynchronously.

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 '{}'

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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

Field	Type	Required	Description
data	Asset[]	yes	Results in this page
next_cursor	string / null	yes	Next-page cursor; null or absent at the end

CloudinaryResource

Field	Type	Required	Description
asset_id	AssetId	yes	Asset ID
public_id	string	yes	Asset name in delivery URLs; may contain path segments
display_name	string	yes	Display name
asset_folder	string	yes	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root
resource_type	ResourceType	yes	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400
type	DeliveryType	yes	Resource or event type
format	string	yes	File format
version	number	yes	Delivery version
version_id	string	yes	Version identifier
bytes	number	yes	File size in bytes
etag	string	yes	File checksum
width	number	no	Width in pixels
height	number	no	Height in pixels
duration	number	no	Duration in seconds
pages	number	no	Document pages
is_audio	boolean	no	Whether this is audio
original_filename	string	no	Original file name
tags	string[]	yes	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list
context	object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it
created_at	IsoTimestamp	yes	Creation time
url	string	yes	Original-file URL
secure_url	string	yes	HTTPS delivery URL
placeholder	false	yes	Always false
existing	boolean	no	Whether an existing asset was returned without overwrite
processing	Processing	no	Overall and per-kind processing states

Asset

Field	Type	Required	Description
asset_id	AssetId	yes	Asset ID
public_id	string	yes	Asset name in delivery URLs; may contain path segments
display_name	string	yes	Display name
asset_folder	string	yes	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root
resource_type	ResourceType	yes	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400
type	DeliveryType	yes	Resource or event type
format	string	yes	File format
version	number	yes	Delivery version
version_id	string	yes	Version identifier
bytes	number	yes	File size in bytes
etag	string	yes	File checksum
width	number	no	Width in pixels
height	number	no	Height in pixels
duration	number	no	Duration in seconds
pages	number	no	Document pages
is_audio	boolean	no	Whether this is audio
original_filename	string	no	Original file name
tags	string[]	yes	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list
context	object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it
created_at	IsoTimestamp	yes	Creation time
url	string	yes	Original-file URL
secure_url	string	yes	HTTPS delivery URL
placeholder	false	yes	Always false
existing	boolean	no	Whether an existing asset was returned without overwrite
processing	Processing	yes	Overall and per-kind processing states
library_id	LibraryId	yes	Library ID
sha256	string	yes	Content checksum
status	"active"	yes	Resource status
semantic	"pending" / "ready" / "unavailable"	yes	Searchable semantically when ready
preview	object	no	Preview poster and storyboard

Deleted

Field	Type	Required	Description
deleted	true	yes	Deletion result

Processing

Field	Type	Required	Description
state	ProcessingState	yes	Overall processing state
kinds	object	yes	Per-kind processing states
updated_at	IsoTimestamp	yes	Update time

Storyboard

Field	Type	Required	Description
url	string	yes	Original-file URL
tiles	number	yes	Storyboard tile count
interval_ms	number	yes	Tile interval in milliseconds
tile_width	number	yes	Tile width
tile_height	number	yes	Tile height

Understandings

Reprocess existing assets

Transcript hallucination filtering

Transcript segments are normalized by converting full-width characters to half-width, lowercasing, and removing leading and trailing whitespace and punctuation. Segments that become empty or exactly match a known hallucination phrase are discarded. Matching is whole-segment only: “thank you for the report” is retained.

The phrase list includes: thank you; thanks for watching; thank you for watching; please subscribe; subscribe; you; bye; 字幕由amara.org社区提供; 请不吝点赞订阅转发打赏支持明镜与点点栏目; 谢谢观看; 优优独播剧场——yoyo television series exclusive.

Discarded segments do not enter transcript text, keyword indexes, or transcript vectors. If all segments are filtered, the transcript understanding remains ready, content is an empty string, and data is { "filtered_segments": n }, where n counts the discarded segments. No transcript vectors are generated for that asset.

Guide →

Base URL and authentication

List understandings

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
asset_id	path	string	Asset ID
include_superseded	query	boolean	Include superseded results; only true or false
kind	query	caption / tags / ocr / transcript / frame	Understanding or processing kind; filters the understanding list
cursor	query	string	Previous next_cursor
limit	query	integer	1–200 items per page, default 200

Returns: UnderstandingPage.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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

Field	Type	Required	Description
data	Understanding[]	yes	Results in this page
next_cursor	string / null	yes	Next-page cursor; null or absent at the end

Understanding

Field	Type	Required	Description
id	UnderstandingId	yes	Resource ID
asset_id	AssetId	yes	Asset ID
asset_version	number	yes	Asset version understood
kind	UnderstandingKind	yes	Understanding or processing kind; filters the understanding list
producer	string	yes	Understanding producer
producer_version	string	yes	Producer version
segment	Segment / null	yes	Start/end milliseconds; null for whole assets
status	"ready" / "failed"	yes	Resource status
content	string / null	yes	Text content
data	JSON / null	yes	Results in this page
confidence	number / null	yes	Confidence; may be null
error	object / null	yes	Error code and message; null on success
superseded	boolean	yes	Whether superseded by a newer version
created_at	IsoTimestamp	yes	Creation time

Segment

Field	Type	Required	Description
start_ms	number	yes	Segment start in milliseconds
end_ms	number	yes	Segment end in milliseconds

Search

expression accepts expressions; semantic and search accept natural language. Semantic search returns ready assets only.

Expression syntax

Guide →

Base URL and authentication

Expression search

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

Parameter	Location	Type	Description
library_id	path	string	Library ID

Request body

Field	Type	Required	Description
expression	string	no	Structured query expression; an empty expression returns every asset
sort_by	object[]	no	Sort fields and directions
max_results	integer	no	Up to 500; Search defaults to 100, Admin to 10
next_cursor	string	no	Next-page cursor; null or absent at the end
with_field	tags / context[]	no	Include tags or context
aggregate	AggregateField[]	no	Aggregation fields

Returns: ExpressionSearchResult.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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"
    }
  ]
}

Visual search

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

Parameter	Location	Type	Description
library_id	path	string	Library ID

Request body

Field	Type	Required	Description
asset_id	AssetId	no	Asset ID
image	object	no	Query image object: base64 data and image MIME type
top_k	integer	no	Maximum hits, 1–50
filter	string	no	Expression filter

Returns: SemanticSearchResult.

Available when library search.image is true; unsupported libraries return LIBRARY_INVALID_STATE. JPEG, PNG, WebP and GIF are accepted, with a maximum decoded size of 10 MiB. Each asset returns its highest-scoring match; videos identify the best frame. qwen3-vl-embedding uses 0.35 for image similarity. Measurements on 2026-10-10: variants of the same image scored 0.82–0.96, similar scenes 0.38–0.66, and unrelated images at most 0.34.

Provide exactly one of asset_id or image: { data, mime }. Asset queries reuse existing image understanding and exclude the source asset; videos use the first frame. Incomplete understanding returns LIBRARY_INVALID_STATE. Uploaded image data is base64. top_k defaults to 20 and accepts 1–50; filter uses the semantic-search expression syntax. Only image similarity is searched. The response shares semantic search’s hits, embedding_producer and not_ready_excluded fields. matches.kind is image; snippet uses the latest caption or asset name. Deleted assets, old versions and replaced understanding are excluded.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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.

Semantic search

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

Parameter	Location	Type	Description
library_id	path	string	Library ID

Request body

Field	Type	Required	Description
query	string	yes	Describe what you want to find
filter	string	no	Expression filter
top_k	integer	no	Maximum hits, 1–50
mode	hybrid / semantic	no	hybrid combines keywords and semantics; semantic uses semantics only

Returns: SemanticSearchResult.

With bge-m3, vector candidates must have cosine similarity ≥ 0.55 before keyword fusion, including newly understood content. Calibration on seven demo assets on 2026-10-09 found relevant results at approximately 0.58 or higher (0.581–0.729), irrelevant results at most 0.523, and wholly unrelated queries at most 0.478. qwen3-vl-embedding text queries use 0.40 against text content (captions, transcripts) and 0.25 against image content. Other models remain uncalibrated and unfiltered. Keyword matches are unaffected. Queries unrelated to the library return an empty list; mode=semantic returns only results meeting the vector threshold.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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.

Semantic search alias

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

Parameter	Location	Type	Description
library_id	path	string	Library ID

Request body

Field	Type	Required	Description
query	string	yes	Describe what you want to find
filter	string	no	Expression filter
top_k	integer	no	Maximum hits, 1–50
mode	hybrid / semantic	no	hybrid combines keywords and semantics; semantic uses semantics only

Returns: SemanticSearchResult.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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

Field	Type	Required	Description
total_count	number	yes	Matching count
time	number	yes	Search time in whole milliseconds, measured by the service
next_cursor	string	no	Next-page cursor; null or absent at the end
resources	SearchAsset[]	yes	Assets in this page
aggregations	object	no	Counts by requested fields
total_count_exact	boolean	no	Whether the count is exact
aggregations_exact	boolean	no	Whether aggregations are exact

SemanticSearchResult

Field	Type	Required	Description
hits	SemanticHit[]	yes	Search hits
embedding_producer	string	yes	Semantic understanding producer
not_ready_excluded	number	yes	Assets excluded because they are not ready

SearchAsset

Field	Type	Required	Description
asset_id	AssetId	yes	Asset ID
public_id	string	yes	Asset name in delivery URLs; may contain path segments
display_name	string	yes	Display name
asset_folder	string	yes	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root
resource_type	ResourceType	yes	image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400
type	DeliveryType	yes	Resource or event type
format	string	yes	File format
version	number	yes	Delivery version
version_id	string	yes	Version identifier
bytes	number	yes	File size in bytes
etag	string	yes	File checksum
width	number	no	Width in pixels
height	number	no	Height in pixels
duration	number	no	Duration in seconds
pages	number	no	Document pages
is_audio	boolean	no	Whether this is audio
original_filename	string	no	Original file name
tags	string[]	no	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list
context	object	no	Custom text key/value pairs; PATCH replaces the whole map, {} clears it
created_at	IsoTimestamp	yes	Creation time
url	string	yes	Original-file URL
secure_url	string	yes	HTTPS delivery URL
placeholder	false	yes	Always false
existing	boolean	no	Whether an existing asset was returned without overwrite
processing	Processing	yes	Overall and per-kind processing states
library_id	LibraryId	yes	Library ID
sha256	string	yes	Content checksum
status	"active"	yes	Resource status
semantic	"pending" / "ready" / "unavailable"	yes	Searchable semantically when ready
preview	object	no	Preview poster and storyboard

SemanticHit

Field	Type	Required	Description
asset	Asset	yes	Matching asset
score	number	yes	Relevance score
semantic_score	number / null	no	—
matches	SemanticMatch[]	yes	Matched content and segment times

SemanticMatch

Field	Type	Required	Description
kind	UnderstandingKind / "metadata" / "image"	yes	Understanding or processing kind; filters the understanding list
understanding_id	UnderstandingId / null	yes	Understanding ID; null for metadata matches
segment	Segment / null	yes	Start/end milliseconds; null for whole assets
snippet	string	yes	Matching text snippet

Folders

Guide →

Base URL and authentication

List folders

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
parent	query	string	Parent folder path; omit or use an empty string for the root. Returns every child folder of that level at once without paging; limit or cursor returns 400

Returns: Folders.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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

Field	Type	Required	Description
folders	object[]	yes	Folders

Batches

Guide →

Base URL and authentication

Create batch

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

Parameter	Location	Type	Description
library_id	path	string	Library ID

Request body

Field	Type	Required	Description
action	"tag" / "untag"	yes	Batch action
tags	string[]	yes	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list

Field	Type	Required	Description
action	"set_context"	yes	Batch action
context	object	yes	Custom text key/value pairs; PATCH replaces the whole map, {} clears it

Field	Type	Required	Description
action	"move"	yes	Batch action
asset_folder	string	yes	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root

Field	Type	Required	Description
action	"delete"	yes	Batch action

Field	Type	Required	Description
selector	BatchSelector	yes	Select by IDs or expression

Returns: Job.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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 batch

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
job_id	path	string	Job ID

Returns: Job.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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"
}

Batch assets alias

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

Parameter	Location	Type	Description
library_id	path	string	Library ID

Request body

Field	Type	Required	Description
action	"tag" / "untag"	yes	Batch action
tags	string[]	yes	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list

Field	Type	Required	Description
action	"set_context"	yes	Batch action
context	object	yes	Custom text key/value pairs; PATCH replaces the whole map, {} clears it

Field	Type	Required	Description
action	"move"	yes	Batch action
asset_folder	string	yes	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root

Field	Type	Required	Description
action	"delete"	yes	Batch action

Field	Type	Required	Description
selector	BatchSelector	yes	Select by IDs or expression

Returns: Job.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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 job alias

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
job_id	path	string	Job ID

Returns: Job.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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

Field	Type	Required	Description
id	JobId	yes	Resource ID
library_id	LibraryId	yes	Library ID
action	tag / untag / set_context / move / delete	yes	Batch action
status	"queued" / "running" / "completed" / "completed_with_errors" / "failed"	yes	Resource status
total	number	yes	Total assets in this job
done	number	yes	Completed count; completion flag for chunk responses
failed	number	yes	Failure count
failures	object[]	yes	—
created_at	IsoTimestamp	yes	Creation time
finished_at	IsoTimestamp / null	yes	Completion time; null while unfinished

BatchSelector

Field	Type	Required	Description
ids	AssetId[]	yes	Asset IDs

Field	Type	Required	Description
expression	string	yes	Structured query expression; an empty expression returns every asset
exclusions	AssetId[]	no	Asset IDs excluded from selection

BatchAction

Field	Type	Required	Description
action	"tag" / "untag"	yes	Batch action
tags	string[]	yes	Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list

Field	Type	Required	Description
action	"set_context"	yes	Batch action
context	object	yes	Custom text key/value pairs; PATCH replaces the whole map, {} clears it

Field	Type	Required	Description
action	"move"	yes	Batch action
asset_folder	string	yes	Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root

Field	Type	Required	Description
action	"delete"	yes	Batch action

Events

Page by seq: asc with after_seq, desc with before_seq. Never combine both cursors.

Guide →

Base URL and authentication

List events

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

Parameter	Location	Type	Description
library_id	path	string	Library ID
after_seq	query	integer	Ascending cursor; cannot combine with before_seq
before_seq	query	integer	Descending cursor; cannot combine with after_seq
order	query	asc / desc	asc (default) or desc
limit	query	integer	1–200 items per page, default 50

Returns: MediaEventPage.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
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

Field	Type	Required	Description
data	MediaEvent[]	yes	Results in this page
next_cursor	string / null	yes	Next-page cursor; null or absent at the end

MediaEvent

Field	Type	Required	Description
seq	number	yes	Increasing event sequence within the library
id	string	yes	Resource ID
type	MediaEventType	yes	Resource or event type
processed_at	IsoTimestamp	yes	Event timestamp
library_id	LibraryId	yes	Library ID
asset_id	AssetId	no	Asset ID
job_id	JobId	no	Job ID
kind	ProcessingKind	no	Understanding or processing kind; filters the understanding list
detail	object	no	Event details

Error codes

Guide →

Native APIs return error.code, error.message, and error.details. Compatible APIs return error.message and repeat it in X-Cld-Error; non-ASCII header messages are percent-encoded.

Code	Native HTTP	Compatible HTTP	Retryable
LIBRARY_NOT_FOUND	404	404	no
ASSET_NOT_FOUND	404	404	no
JOB_NOT_FOUND	404	404	no
UNDERSTANDING_NOT_FOUND	404	404	no
LIBRARY_INVALID_STATE	409	400	no
INVALID_PARAMS	400	400	no
INVALID_EXPRESSION	400	400	no
UNSUPPORTED	400	400	no
NOT_IMPLEMENTED	501	400	no
FILE_TOO_LARGE	413	400	no
FILE_EMPTY	400	400	no
UNSUPPORTED_MEDIA	415	400	no
FETCH_FAILED	400	400	no
LIMIT_EXCEEDED	400	400	no
CHUNK_INVALID	400	400	no
RATE_LIMITED	429	420	yes
CAPACITY	503	500	yes
UPSTREAM_FAILED	502	500	yes

Use backoff for retryable errors. For other errors, correct the request or resource state first.

Model configuration errors

400 INVALID_PARAMS: a model call ID is unavailable (Model <id> is not available), the vision model does not support image input, or models contains unknown roles, blank IDs, or invalid values.
409 LIBRARY_INVALID_STATE: changing embedding when the library contains assets, including a reset that changes the model. The message is “库中已有素材时不能更换嵌入模型”.
502 UPSTREAM_FAILED: the model catalog cannot be queried while writing model configuration; retry with backoff.