Understandings

Reprocess existing assets

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.

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

Understandings

On this page