Media Search API - Video Search with Filters and Evidence - SuperApp

Searches videos by query keywords and filter conditions, with optional hit evidence in the response.

Request Method (curl)

curl -X GET \
  "https://example.com/media-intelligence/openapi/search/videos?query=person%20entering%20the%20room&isVip=true&view=list" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: fdafdaf****fafa" \
  -H "X-Access-Key: fdafdaf****fafa" \
  -H "X-Request-Timestamp: 1740471900061" \
  -H "X-Request-Sign: fdafdaf****fafa"

Request Parameters

Property	Type	Mandatory	Description
query	String	yes	Query keywords. URL encoding recommended.
releaseGte	String (ISO 8601)	no	Lower bound (inclusive) for platform release time. Corresponds to the releaseDate field in metaTemplate. Example: 2026-01-01T00:00:00Z.
releaseLte	String (ISO 8601)	no	Upper bound (inclusive) for platform release time. Corresponds to the releaseDate field in metaTemplate. Example: 2026-02-01T00:00:00Z.
publishGte	String (ISO 8601)	no	Lower bound (inclusive) for video publish time. Corresponds to the publishDate field in metaTemplate. Example: 2026-01-01T00:00:00Z.
publishLte	String (ISO 8601)	no	Upper bound (inclusive) for video publish time. Corresponds to the publishDate field in metaTemplate. Example: 2026-02-01T00:00:00Z.
durationMsGte	Integer	no	Lower bound (inclusive) for video duration. Corresponds to durationMs in metaTemplate. Unit: milliseconds.
durationMsLte	Integer	no	Upper bound (inclusive) for video duration. Corresponds to durationMs in metaTemplate. Unit: milliseconds.
videoType	String (CSV)	no	Filters by video type. Corresponds to the videoType field in metaTemplate. Multi-value, comma-separated. Example: Film,TV Series
excludeVideoIds	String (CSV)	no	Video IDs to exclude from results. Corresponds to the videoId field in metaTemplate. Multi-value, comma-separated.
isVip	Boolean	no	Whether to include VIP videos. Corresponds to the isVip field in metaTemplate. Options: true: Retrieve all videos false: Retrieve only non-VIP videos Default: true (retrieves all videos).
isActive	Boolean	no	Whether to return only active videos. Corresponds to the isActive field in metaTemplate. Options: true: return only videos whose isActive is true false: return all videos Default: true
sort	String	no	Sort order: <field_name>:<asc\|desc>. Only score:desc is supported. Default: score:desc.
profile	String	no	Search strategy: fast or balanced. Default: balanced.
rerank	String	no	Enables reranking: on, off, or auto. When set to auto, behavior follows the profile setting. Default: auto.
rerankTruncate	String	no	Truncates results based on relevance after reranking: on, off, or auto. When set to auto, behavior follows the profile setting. Default: auto
rerankScope	String	no	Scope of final returned results. rerank_only: returns only candidates that entered reranking; others are discarded. all: candidates that did not enter reranking may also be returned. Default: all
limit	Integer	no	Maximum number of results to return. Default: 50. System limit: 200 (values above this are capped).
view	String	no	Field preset for response. Options: basic: minimal fields, includes videoId only. list: common fields for list display, includes videoId, videoTitle, videoDesc, releaseDate, durationMs, publishDate, videoType, videoImages, and isVip. Fields correspond to metaTemplate field names. Default: basic.
fields	String (CSV)	no	Specific fields to return from metaTemplate. Multi-value, comma-separated. When both view and fields are specified, fields takes precedence. Unknown fields are ignored. Include videoId to identify videos. Example: videoId,videoTitle.
evidence	String	no	Returns search evidence: on or off. Default: off.
maxFrameEvidence	integer	no	Maximum frame evidence per video. Effective only when evidence=on. Range: 1–20. Default: 3.
maxSegmentEvidence	integer	no	Maximum segment evidence per video. Effective only when evidence=on. Range: 1–20. Default: 3. (Segment search is not currently performed; this parameter has no effect.)
aggregateByType	Boolean	no	Whether to aggregate search results by videoType. Options: false: return a flat list of search results. true: group results by videoType; data.results always contains 5 fixed groups in this order: FILM, VIDEO, SHORT_VIDEO, LIVE_CHANNEL, PLAY_LIST. Default: false Note: When aggregateByType=true, videoType should be included in the returned fields (specified by the view or fields request parameters); otherwise the result may contain empty groups.

Note

The following fields depend on metadata provided at video upload time (as defined in the metaTemplate object). They take effect only when the corresponding metaTemplate fields are populated correctly; otherwise, filtering may be invalid or results inaccurate: releaseGte, releaseLte, publishGte, publishLte, durationMsGte, durationMsLte, videoType, excludeVideoIds, and isVip.

Response Parameters

data

Name

Type

Sample Values

Description

tookMs

integer

187

Search latency in milliseconds.

results

Array<searchResult> | Array<aggregatedSearchResultGroup>

When aggregateByType=false, returns a list of searchResult.

When aggregateByType=true, returns a list of aggregatedSearchResultGroup.

aggregatedSearchResultGroup Object Definition

Name	Type	Sample Values	Description
type	String	"FILM"	Video type group name. The current fixed output order is: FILM, VIDEO, SHORT_VIDEO, LIVE_CHANNEL, PLAY_LIST.
total	Integer	12	Total number of matched results in the current group.
content	Array<searchResult>		Search results belonging to the current videoType group. The order of items is consistent with the final ranking order.

searchResult Object Definition

Name	Type	Sample Values	Description
score	Float	0.9861	Relevance score. Distribution depends on model and index strategy.
video	object<searchResultVideo>		Video metadata object. Fields controlled by view or fields parameter.
evidence	object<searchResultEvidence>		Search evidence. Returned only when evidence=on.

searchResultVideo Object Definition

The fields in searchResultVideo are controlled by the view and fields request parameters. Unknown fields are ignored; missing fields are omitted. The following example uses view=list with no fields parameter.

Name	Type	Sample Values	Description
videoId	String	"vid_001"	Unique video ID.
videoTitle	String	"Captain America"	Video title.
videoDesc	String	"A WWII superhero origin story..."	Video description.
releaseDate	String (ISO 8601)	2026-01-15T12:34:56Z	Platform release time.
publishDate	String (ISO 8601)	2026-01-15T12:34:56Z	Video publish time.
durationMs	String	7265000	Video duration in milliseconds.
videoType	String	"Film"	Video type.
isVip	Boolean	true	Whether the video is VIP content.
videoImages	Array	["https://img.example.com/cover.jpg"]	Image URLs (covers, posters, etc.).

searchResultEvidence Object Definition

Name	Type	Sample Values	Description
metadata	Array<searchResultEvidenceMetadata>	-	Metadata hit evidence list.
frames	Array<searchResultEvidenceFrame>	-	Frame-level evidence list. Count limited by maxFrameEvidence.
segments	Array<searchResultEvidenceSegment>	-	Segment-level evidence list. Count limited by maxSegmentEvidence. (Segment search is not currently performed; this field is not returned.)

searchResultEvidenceMetadata Object Definition

Name	Type	Sample Values	Description
field	String	videoTitle	The name of the matched field.
snippets	Array<String>	["<em>Captain</em> <em>America</em> ..."]	List of matched text snippets (may contain highlight tags).

searchResultEvidenceFrame Object Definition

Name	Type	Sample Values	Description
id	String	xoeUN	Frame ID.
timestampMs	Integer	81000	Frame timestamp in milliseconds.
snippets	Array	["<em>Captain</em> <em>America</em> ..."]	Hit interpretation text for this frame. May contain highlight tags.

searchResultEvidenceSegment Object Definition

Name	Type	Sample Values	Description
id	String	sicNF	Segment ID.
startMs	Integer	80000	Segment start time in milliseconds.
endMs	Integer	92000	Segment end time in milliseconds.
snippets	Array	["<em>Captain</em> <em>America</em> ..."]	Hit interpretation text for this segment. May contain highlight tags.

Timeout Handling

Timeout	Timeout Policy
3s	The server returns HTTP 408 (errorCode=ERR_REQUEST_TIMEOUT) on timeout. Retry with the same parameters.

Example

Request Example

curl -X GET \
  "https://example.com/media-intelligence/openapi/search/videos?query=person%20entering%20the%20room&releaseGte=2026-01-01T00:00:00Z&releaseLte=2026-02-01T00:00:00Z&durationMsGte=10000&durationMsLte=7200000&videoType=Film,TV%20Series&excludeVideoIds=vid_bad_1,vid_bad_2&isVip=true&sort=score:desc&profile=balanced&rerank=auto&limit=30&view=list&evidence=on&maxFrameEvidence=3&maxSegmentEvidence=3" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: fdafdaf****fafa" \
  -H "X-Access-Key: fdafdaf****fafa" \
  -H "X-Request-Timestamp: 1740471900061" \
  -H "X-Request-Sign: fdafdaf****fafa"

Response Example (aggregateByType=false)

HTTP/1.1 200 OK
Content-Type:application/json

{
    "success": true,
    "data": {
        "tookMs": 187,
        "results": [
            {
                "score": 0.9861,
                "video": {
                    "videoId": "vid_001",
                    "videoTitle": "Captain America",
                    "videoDesc": "A WWII superhero origin story...",
                    "releaseDate": "2026-01-15T12:34:56Z",
                    "publishDate": "2026-01-15T12:34:56Z",
                    "durationMs": 7265000,
                    "videoType": "Film",
                    "isVip": true,
                    "videoImages": ["https://img.example.com/cover.jpg"]
                },
                "evidence": {
                    "metadata": [
                    {"field": "videoTitle", "snippets": ["<em>Captain</em> <em>America</em>"]},
                    {"field": "videoDesc", "snippets": ["<em>Captain</em> <em>America</em>: The First Avenger is set during World War II and centers on Steve Rogers,"]}
                    ],
                    "frames": [
                        {
                            "id": "xoeUN",
                            "timestampMs": 81000,
                            "snippets": [
                                "<em>Captain</em> <em>America</em>: The First Avenger is set during World War II and centers on Steve Rogers,"
                            ]
                        }
                    ]
                }
            }
        ]
    },
    "errorCode": null,
    "errorMsg": null,
    "extraData": null,
    "traceId": "b97fb1b4399a524276e9a0bd6a7ad7f3",
    "env": null,
    "i18nShifted": false,
    "errorArgs": null,
    "other": null
}

Response Example (aggregateByType=true)

HTTP/1.1 200 OK
Content-Type:application/json

{
  "success": true,
  "data": {
    "tookMs": 203,
    "results": [
      {
        "type": "FILM",
        "total": 1,
        "content": [
          {
            "score": 0.9861,
            "video": {
              "videoId": "vid_001",
              "videoTitle": "Captain America",
              "videoType": "FILM",
              "videoImages": ["https://img.example.com/cover.jpg"],
              "isVip": true
            },
            "evidence": null
          }
        ]
      },
      {
        "type": "VIDEO",
        "total": 0,
        "content": []
      },
      {
        "type": "SHORT_VIDEO",
        "total": 0,
        "content": []
      },
      {
        "type": "LIVE_CHANNEL",
        "total": 0,
        "content": []
      },
      {
        "type": "PLAY_LIST",
        "total": 0,
        "content": []
      }
    ]
  },
  "errorCode": null,
  "errorMsg": null,
  "extraData": null,
  "traceId": "b97fb1b4399a524276e9a0bd6a7ad7f3",
  "env": null,
  "i18nShifted": false,
  "errorArgs": null,
  "other": null
}