General Material Search

Search the copyrighted material library with a single natural-language description or keywords across three modalities — video / image / audio — and get back direct download URLs for the full original assets, plus previews, specs and tags. Returns synchronously, no polling required. For finding material by keyword and downloading it directly.

Difference from Video Material Search (for Smart Editing): smart editing returns the best-matching in-clip time ranges (segments) for timeline assembly; general search returns a download link for the whole asset.

Search Endpoint

Basic Info

Item	Value
Method	POST
Path	/task/material_search
Content-Type	application/json
Auth	Authorization header (pass the API Key directly)
Response	Synchronous search results (not an async task)

Request Body

Field	Type	Required	Default	Description
scope	string	Yes	—	Material type: clip (video) / image / audio; one type per request
query	string	Yes	—	Natural-language description or keywords
top_k	integer	No	20	Number of results, max 50
diversity	boolean	No	false	De-duplicate near-identical material
request_id	string	No	—	uuid, echoed back, for idempotency / tracing

Request Example

curl -X POST https://api.ai-mcn.tv:10000/task/material_search \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "clip",
    "query": "aerial view of a city at night",
    "top_k": 20,
    "diversity": true,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Success Response Example (scope=clip)

{
  "code": 200,
  "msg": "success",
  "data": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "recalled": 64,
    "total": 20,
    "results": [
      {
        "id": 2693564728807342,
        "score": 0.87,
        "download_url": "https://cdn.example.com/nmcn/material/video_clip/raw/2693564728807342.mp4?expires=1750086000&sign=Xa1b2C3d4E5f6G7h8I9j0k",
        "cover_url": "https://cdn.example.com/nmcn/material/video_clip/keyframe/2693564728807342/cover.jpg",
        "preview_url": "https://cdn.example.com/nmcn/material/video_clip/preview/2693564728807342.mp4",
        "duration": 12.4,
        "width": 3840,
        "height": 2160,
        "fps": 25,
        "orientation": "landscape",
        "note": "Aerial city night view with dense towers and light trails.",
        "tags": ["city", "night", "aerial", "traffic"]
      }
    ]
  }
}

Response Fields

Top level:

Field	Type	Description
request_id	string	Echoes the request request_id
recalled	integer	Total recalled (before filtering), for observability
total	integer	Number of results returned
results	array	Result list, sorted by score; fields vary by scope (see below)

Video (scope=clip) result fields:

Field	Type	Description
id	integer	Material id
score	number	Relevance score (after rerank, descending)
download_url	string	Temporary full-clip download URL (mp4, expires in 24h via ?expires=&sign=)
cover_url	string	Cover image (does not expire)
preview_url	string	Low-bitrate preview proxy (does not expire)
duration	number	Duration (seconds)
width / height	integer	Resolution (pixels)
fps	number	Frame rate
orientation	string	landscape / portrait / square
note	string	Material text description
tags	array<string>	AI attribute tags

Image (scope=image) result fields:

Field	Type	Description
id	integer	Material id
score	number	Relevance score
download_url	string	Temporary original-image download URL (expires in 24h)
thumb_url	string	Thumbnail (does not expire)
width / height	integer	Resolution (pixels)
note	string	Material text description
tags	array<string>	AI attribute tags

Audio (scope=audio) result fields:

Field	Type	Description
id	integer	Material id
score	number	Relevance score
download_url	string	Temporary original-track download URL (mp3, expires in 24h)
accompaniment_url	string	Accompaniment (off-vocal) download URL (signed, only when audio_type=song)
cover_url	string	Cover image (does not expire)
title	string	Track title
author	string	Artist / creator
duration	number	Duration (seconds)
audio_type	string	song / pure (instrumental)
note	string	Material text description
tags	array<string>	AI attribute tags

Error Codes

Code	HTTP	Description	Resolution
400	400	Invalid params / body (bad scope, empty query, top_k out of range)	Check request params
6502	401	Authentication failed	Check the API Key in the Authorization header
6401	6401	Upstream search service unavailable	Retry later
6402	6402	Upstream search service timeout	Retry later

Limits

• top_k is capped at 50 (clamped automatically).
• A single request takes a single scope (no cross-modality mixing); call separately for multiple modalities.
• Download URLs download_url (and audio accompaniment_url) expire in 24h; re-search for fresh links. Previews cover_url / thumb_url / preview_url do not expire.
• This endpoint takes a single query; call concurrently for batch needs.