Libraries

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.

Libraries

Create library

Request body

Response

HTTP 200

List libraries

Response

HTTP 200

Get library

Response

HTTP 200

Update library

Request body

Response

HTTP 200

Delete library

Response

HTTP 200

Restore library

Response

HTTP 200

Purge library

Response

HTTP 200

Library

LibraryPage

PurgedLibrary

Page

UnderstandingSettings

Model roles

On this page