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)
Billing	1 credit per search (auto-refunded on failure; the response carries a task_id for task lookup. Every material a search returns is permanently granted to you — from then on, re-sign fresh download links for free and without limit via material re-sign)

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)

💡 Interpreting score: score is a fused recall score (0–1). Scales differ by modality and are not comparable across modalities — video/image use cross-modal text-to-visual embeddings (naturally lower values), while audio uses same-modal text embeddings (naturally higher values). Rule of thumb: video/image results with score > 0.2 are good matches; audio results with score > 0.45 are good matches. Results below these thresholds are mostly weak-relevance fallbacks — consider filtering or truncating accordingly.

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. For video materials, use Material Link Re-signing to get fresh links free and unlimited after expiry (once searched, always granted — no paid re-search needed); for image / audio, re-search for now. Previews cover_url / thumb_url / preview_url do not expire.
• This endpoint takes a single query; call concurrently for batch needs.

🤝 Join the Tonghe New Media Network to unlock internal member benefits: network members (internal) get custom-scope full-library material search (video / image / audio, including concept and non-commercial materials, with a commercial-only filter) and exclusive internal voices. Apply at the Creator Network; once approved, an administrator will enable internal access for you.