# 理解结果 (/docs/api/native/media/understandings)



## 重新理解已有素材 [#重新理解已有素材]

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

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

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

## 转写幻听过滤 [#转写幻听过滤]

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

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

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

[指南 →](/docs/cloud/services/media/quickstart)

[基础地址与鉴权](/docs/api/native/media)

## 读取理解 [#读取理解]

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

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

返回: `UnderstandingPage`.

### 响应 [#响应]

#### HTTP 200 [#http-200]

Successful response.

**application/json**

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

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

HTTP 200

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

## UnderstandingPage [#understandingpage]

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

## Understanding [#understanding]

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

## Segment [#segment]

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