Praxis文档
控制台
素材库

素材库

请求、对象与响应。

指南 →

基础地址与鉴权

创建库

POST /media/v1/libraries

请求体

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

返回: Library.

响应

HTTP 200

Successful response.

application/json

名称类型说明
searchobjectSearch capabilities of this library’s embedding model.
search.imagebooleanWhether this library’s embedding model supports image-based visual search.
modelsobjectResolved model call IDs used for new uploads and reprocessing.
models.visionstringModel call ID for visual descriptions; the model must support image input.
models.embeddingstringModel call ID for search embeddings; must produce compatible vectors and cannot change while assets exist.
models.transcriptionstringModel call ID for speech transcription.
idstringGenerated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
namestringDisplay name of the library; duplicate names are allowed.
labelsobjectCaller-defined string labels used to organize and filter libraries.
statusstringLibrary 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_countnumberNumber of assets currently stored in the library.
bytesnumberTotal source-content size of the library’s assets, in bytes.
understandingobjectSettings controlling understanding tasks for new uploads.
understanding.visualbooleanEnable captions, tags and OCR for images and video frames.
understanding.transcriptbooleanEnable speech transcription for audio and video soundtracks.
understanding.embeddingbooleanEnable generation of vectors for semantic search.
created_atstringTime the library was created, in UTC.
updated_atstringTime library settings, lifecycle or usage were last updated, in UTC.
deleted_atstring | nullTime the library entered deleting, or null when active or restored.
purge_atstring | nullScheduled purge time while the library is deleting; null for an active or restored library.
curl -X POST "https://api.deepraxis.ai/media/v1/libraries" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"walk-lib-r1-MDP-1791733789929","labels":{"sample":"walk-lib-r1-MDP-1791733789929"}}'

HTTP 200

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

列出库

GET /media/v1/libraries

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

返回: LibraryPage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
dataarray<object>Libraries in this page, ordered by creation time descending.
data[].searchobjectSearch capabilities of this library’s embedding model.
data[].modelsobjectResolved model call IDs used for new uploads and reprocessing.
data[].idstringGenerated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
data[].namestringDisplay name of the library; duplicate names are allowed.
data[].labelsobjectCaller-defined string labels used to organize and filter libraries.
data[].statusstringLibrary 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_countnumberNumber of assets currently stored in the library.
data[].bytesnumberTotal source-content size of the library’s assets, in bytes.
data[].understandingobjectSettings controlling understanding tasks for new uploads.
data[].created_atstringTime the library was created, in UTC.
data[].updated_atstringTime library settings, lifecycle or usage were last updated, in UTC.
data[].deleted_atstring | nullTime the library entered deleting, or null when active or restored.
data[].purge_atstring | nullScheduled purge time while the library is deleting; null for an active or restored library.
next_cursorstring | nullOpaque token to pass as cursor to listLibraries; null means no further page.
curl -X GET "https://api.deepraxis.ai/media/v1/libraries?labels=%7B%22sample%22%3A%22walk-lib-r1-MDP-1791733789929%22%7D" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

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

读取库

GET /media/v1/libraries/{library_id}

参数位置类型说明
library_idpathstring库 ID

返回: Library.

响应

HTTP 200

Successful response.

application/json

名称类型说明
searchobjectSearch capabilities of this library’s embedding model.
search.imagebooleanWhether this library’s embedding model supports image-based visual search.
modelsobjectResolved model call IDs used for new uploads and reprocessing.
models.visionstringModel call ID for visual descriptions; the model must support image input.
models.embeddingstringModel call ID for search embeddings; must produce compatible vectors and cannot change while assets exist.
models.transcriptionstringModel call ID for speech transcription.
idstringGenerated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
namestringDisplay name of the library; duplicate names are allowed.
labelsobjectCaller-defined string labels used to organize and filter libraries.
statusstringLibrary 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_countnumberNumber of assets currently stored in the library.
bytesnumberTotal source-content size of the library’s assets, in bytes.
understandingobjectSettings controlling understanding tasks for new uploads.
understanding.visualbooleanEnable captions, tags and OCR for images and video frames.
understanding.transcriptbooleanEnable speech transcription for audio and video soundtracks.
understanding.embeddingbooleanEnable generation of vectors for semantic search.
created_atstringTime the library was created, in UTC.
updated_atstringTime library settings, lifecycle or usage were last updated, in UTC.
deleted_atstring | nullTime the library entered deleting, or null when active or restored.
purge_atstring | nullScheduled purge time while the library is deleting; null for an active or restored library.
curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

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

更新库

PATCH /media/v1/libraries/{library_id}

参数位置类型说明
library_idpathstring库 ID

请求体

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

返回: Library.

响应

HTTP 200

Successful response.

application/json

名称类型说明
searchobjectSearch capabilities of this library’s embedding model.
search.imagebooleanWhether this library’s embedding model supports image-based visual search.
modelsobjectResolved model call IDs used for new uploads and reprocessing.
models.visionstringModel call ID for visual descriptions; the model must support image input.
models.embeddingstringModel call ID for search embeddings; must produce compatible vectors and cannot change while assets exist.
models.transcriptionstringModel call ID for speech transcription.
idstringGenerated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
namestringDisplay name of the library; duplicate names are allowed.
labelsobjectCaller-defined string labels used to organize and filter libraries.
statusstringLibrary 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_countnumberNumber of assets currently stored in the library.
bytesnumberTotal source-content size of the library’s assets, in bytes.
understandingobjectSettings controlling understanding tasks for new uploads.
understanding.visualbooleanEnable captions, tags and OCR for images and video frames.
understanding.transcriptbooleanEnable speech transcription for audio and video soundtracks.
understanding.embeddingbooleanEnable generation of vectors for semantic search.
created_atstringTime the library was created, in UTC.
updated_atstringTime library settings, lifecycle or usage were last updated, in UTC.
deleted_atstring | nullTime the library entered deleting, or null when active or restored.
purge_atstring | nullScheduled purge time while the library is deleting; null for an active or restored library.
curl -X PATCH "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"walk-lib-r1-MDP-1791733789929-updated"}'

HTTP 200

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

删除库

DELETE /media/v1/libraries/{library_id}

参数位置类型说明
library_idpathstring库 ID

返回: Library.

响应

HTTP 200

Successful response.

application/json

名称类型说明
searchobjectSearch capabilities of this library’s embedding model.
search.imagebooleanWhether this library’s embedding model supports image-based visual search.
modelsobjectResolved model call IDs used for new uploads and reprocessing.
models.visionstringModel call ID for visual descriptions; the model must support image input.
models.embeddingstringModel call ID for search embeddings; must produce compatible vectors and cannot change while assets exist.
models.transcriptionstringModel call ID for speech transcription.
idstringGenerated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
namestringDisplay name of the library; duplicate names are allowed.
labelsobjectCaller-defined string labels used to organize and filter libraries.
statusstringLibrary 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_countnumberNumber of assets currently stored in the library.
bytesnumberTotal source-content size of the library’s assets, in bytes.
understandingobjectSettings controlling understanding tasks for new uploads.
understanding.visualbooleanEnable captions, tags and OCR for images and video frames.
understanding.transcriptbooleanEnable speech transcription for audio and video soundtracks.
understanding.embeddingbooleanEnable generation of vectors for semantic search.
created_atstringTime the library was created, in UTC.
updated_atstringTime library settings, lifecycle or usage were last updated, in UTC.
deleted_atstring | nullTime the library entered deleting, or null when active or restored.
purge_atstring | nullScheduled purge time while the library is deleting; null for an active or restored library.
curl -X DELETE "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

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

恢复库

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

参数位置类型说明
library_idpathstring库 ID

返回: Library.

响应

HTTP 200

Successful response.

application/json

名称类型说明
searchobjectSearch capabilities of this library’s embedding model.
search.imagebooleanWhether this library’s embedding model supports image-based visual search.
modelsobjectResolved model call IDs used for new uploads and reprocessing.
models.visionstringModel call ID for visual descriptions; the model must support image input.
models.embeddingstringModel call ID for search embeddings; must produce compatible vectors and cannot change while assets exist.
models.transcriptionstringModel call ID for speech transcription.
idstringGenerated library identifier: lib_ followed by 32 lowercase hexadecimal characters.
namestringDisplay name of the library; duplicate names are allowed.
labelsobjectCaller-defined string labels used to organize and filter libraries.
statusstringLibrary 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_countnumberNumber of assets currently stored in the library.
bytesnumberTotal source-content size of the library’s assets, in bytes.
understandingobjectSettings controlling understanding tasks for new uploads.
understanding.visualbooleanEnable captions, tags and OCR for images and video frames.
understanding.transcriptbooleanEnable speech transcription for audio and video soundtracks.
understanding.embeddingbooleanEnable generation of vectors for semantic search.
created_atstringTime the library was created, in UTC.
updated_atstringTime library settings, lifecycle or usage were last updated, in UTC.
deleted_atstring | nullTime the library entered deleting, or null when active or restored.
purge_atstring | nullScheduled purge time while the library is deleting; null for an active or restored library.
curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/restore" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

HTTP 200

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

立即清除库

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

参数位置类型说明
library_idpathstring库 ID

返回: PurgedLibrary.

响应

HTTP 200

Successful response.

application/json

名称类型说明
idstringIdentifier of the library that was permanently purged.
objectstringResource discriminator identifying a library receipt.
purgedbooleanTrue 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

字段类型必填说明
searchobject是检索能力；search.image 为 true 时支持以图搜图
modelsMediaModels是各角色的模型调用 ID；局部更新，null 恢复默认
idLibraryId是资源 ID
namestring是名称，1–64 个字符；允许重名
labelsobject是标签对象；GET 时传 JSON 字符串；PATCH 整体替换，传 {} 清空
statusLibraryStatus是资源状态
asset_countnumber是素材数量
bytesnumber是文件字节数
understandingUnderstandingSettings是视觉、转写与语义理解开关
created_atIsoTimestamp是创建时间
updated_atIsoTimestamp是更新时间
deleted_atIsoTimestamp / null是删除时间；未删除为 null
purge_atIsoTimestamp / null是恢复截止时间

LibraryPage

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

PurgedLibrary

字段类型必填说明
idLibraryId是资源 ID
object"library"是—
purgedtrue是—

Page

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

UnderstandingSettings

字段类型必填说明
visualboolean是视觉理解开关
transcriptboolean是转写开关
embeddingboolean是语义理解开关

模型角色

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

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

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

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

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

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

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

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

Media API

库、素材与检索的 API 参考。

素材

请求、对象与响应。

导出
本页 Markdown本节 Markdown整本 PDF

本页内容

创建库请求体响应HTTP 200列出库响应HTTP 200读取库响应HTTP 200更新库请求体响应HTTP 200删除库响应HTTP 200恢复库响应HTTP 200立即清除库响应HTTP 200LibraryLibraryPagePurgedLibraryPageUnderstandingSettings模型角色