Video Search REST API-referencia

Végpont:POST https://api.microsoft.ai/v3/search/videos

Mintakérés:

curl -X POST "https://api.microsoft.ai/v3/search/videos" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "cute puppy videos",
    "maxResults": 30,
    "language": "en",
    "region": "US"
  }'

Parameters

Paraméter	Required	Típus	Default	Description
lekérdezés	Yes	karakterlánc	-	Keresési lekérdezési sztring. A maximális hossz 1000 karakter.
maxResults	No	egész szám	30	A visszaadandó eredmények maximális száma. Az alapértelmezett érték 30, a maximális érték pedig 30.
nyelv	No	karakterlánc	"en"	Kétbetűs ISO 639-1 nyelvi kód a keresési eredmények felületi nyelvéhez. A teljes lista támogatott nyelvei című témakörben talál további információt.
régió	No	karakterlánc	"US"	Kétbetűs ország-/régiókód, amelyből az eredmények származnak (pl. "US", "JP", "GB", stb.). A teljes listát a Támogatott régiók című témakörben találja.
enablePlaylist	No	boolean	false	A lejátszási lista eredményének megadása válaszként.
freshness	No	karakterlánc	-	Az eredményeket a felderítési dátum alapján szűrni kívánt időtartomány. Támogatja a "week", "month", "year" értéket a relatív időhöz, vagy az ISO 8601 dátumintervallum formátumot: "YYYY-MM-DD/YYYY-MM-DD" vagy "YYYY-MM-DDTHH:mm:ssZ/YYYY-MM-DDTHH:mm:ssZ" dátum-/dátum/időtartomány esetén. a kezdési vagy befejezési dátum kihagyásához.
beágyazható	No	sztringtömb	-	Videók szűrése a képességek beágyazásával. Engedélyezett értékek: "player" (beágyazható lejátszóval rendelkezik). Ha nincs beállítva, a rendszer nem alkalmaz szűrést.
felbontás	No	karakterlánc	-	Videók szűrése minimális felbontással. Értékek: "360p", "480p", "720p", "1080p". Ha nincs beállítva, a rendszer nem alkalmaz szűrést.
safeSearch	No	karakterlánc	"szigorú"	A biztonságos keresés szűrésének szintje. Értékek: "ki", "szigorú". Az alapértelmezett érték a "szigorú".
duration	No	karakterlánc	-	Videók szűrése időtartamtartomány szerint. Értékek: "rövid" (<5 perc), "közepes" (5–20 perc), "hosszú" (>20 perc). Ha nincs beállítva, a rendszer nem alkalmaz szűrést.

Kérelemfejlécek

Field	Típus	Description
állomás	karakterlánc	Gazdagép Microsoft AI API-khoz: api.microsoft.ai.
x-apikey vagy Engedélyezés	karakterlánc	Az API-kulcs vagy Entra ID hozzáférési jogkivonat hitelesítéshez.
tartalomtípus	karakterlánc	A kérelem törzsének MIME-típusa. Használja a application/json.

Response

Videók válasza

Field	Típus	Description
videoResults	a videoResult tömbje	A videó eredményeinek listája.
lejátszási listák	playlistResult tömb (nem kötelező)	A lejátszási lista eredményeinek listája.
instrumentationClickBase	karakterlánc	A kattintási pingelési kérelmek alap URL-címe. Adjon hozzá egy instrumentationSuffix értéket egy eredményelemből a teljes ping URL-cím létrehozásához. Csak az EnableInstrumentationPing profiljelzővel rendelkező alkalmazások esetén jelenik meg. Megjegyzés: A felhasználói kattintások URL-átirányítással is naplózhatók. Ha az átirányítás engedélyezve van, nincs szükség műveletre a felhasználói kattintások naplózásához, és instrumentationClickBase nem lesz belefoglalva a válaszba. A beállítási utasításokért tekintse meg a Instrumentation útmutatót .
instrumentationCitationBase	karakterlánc	Az LLM-napló pingelési kérelmeinek alap URL-címe. Fűzze hozzá a DATA hasznos adatait a teljes ping URL-cím létrehozásához. Csak az EnableInstrumentationPing profiljelzővel rendelkező alkalmazások esetén jelenik meg.
traceId	karakterlánc	Nyomkövetési azonosító a hibakereséshez.

Note

playlists nem kötelező mező akkor is, ha enablePlaylist igaz értékre van állítva.

videoResult

Field	Típus	Description
title	karakterlánc	A videó címe vagy neve.
url	karakterlánc	A videó forrás URL-címe. Az URL-átirányítást engedélyező kínai felhasználók esetében ez a mező ehelyett ugyanazt az átirányítási URL-címet tartalmazza, mint clickUrla .
tartomány	karakterlánc	Az eredmény cél állomása. Csak olyan kínai felhasználók esetében adja vissza, akiknél engedélyezve van az URL-átirányítás.
description	karakterlánc	A videó tartalmának leírása. Ezt vagy a videófeltöltő biztosítja, vagy egy LLM hozza létre.
publishedBy	karakterlánc	A videó feltöltője vagy közzétevője.
viewCount	long	A videó megtekintéseinek száma.
összegzés	karakterlánc	AI által létrehozott videó összefoglalása.
length	karakterlánc	A videó hossza HH:MM:SS formátumban.
engedélyezésHttpsEmbedding	boolean	Engedélyezi-e a HTTPS-beágyazást.
allowMobileEmbedding	boolean	Engedélyezi-e a mobilbeágyazást.
embeddingUrl	karakterlánc	A videó beágyazásának URL-címe.
utolsóFrissítveAt	karakterlánc	Az utolsó frissített dátum formázott sztringként.
bestMomentIndex	egész szám	A videó legjobb pillanatának vagy kiemelésének indexe.
Pillanatok	a pillanat tömbje	Videószegmensek/pillanatok tömbje.
thumbnailUrl	karakterlánc	A videó miniatűr URL-címe.
width	egész szám	A videó szélessége képpontban.
height	egész szám	A videó magassága képpontban.
isAdult	boolean	Azt jelzi, hogy az eredmény tartalmaz-e felnőtt tartalmat.
clickUrl	karakterlánc	Átirányítási URL-cím, amely a Bingen keresztül irányítja át a kattintást. Csak akkor jelenik meg, ha a kattintás átirányítása engedélyezve van.
instrumentationSuffix	karakterlánc	Utótag az eredményelem rendszerállapot-ping URL-alapjához való hozzáfűzéshez. A rendszerállapot pingELÉSI URL-címéhez és az clickUrl átirányításhoz egyaránt K-értékként használatos. Akkor jelenik meg, ha a rendszerállapot-ping engedélyezve van.

Note

A fenti mezők közül több nem kötelező – ha elérhetők, szolgáljuk ki őket.

pillanat

Field	Típus	Description
title	karakterlánc	A pillanatszegmens címe.
description	karakterlánc	Leírás arról, hogy mi történik ebben a pillanatban.
startTime	karakterlánc	A pillanat kezdő időpontja "d.hh:mm:ss" formátumban.
endTime	karakterlánc	A pillanat befejezési ideje "d.hh:mm:ss" formátumban.
momentUrl	karakterlánc	A videó adott pillanatának közvetlen URL-címe.

Note

moment nem kötelező válaszobjektum. Nem érhető el minden videoeredményhez.

playlistResult

Field	Típus	Description
title	karakterlánc	A lejátszási lista címe.
description	karakterlánc	A lejátszási lista leírása.
videos	a videó tömbje	A lejátszási lista videóinak tömbje.

Note

playlistResult nem kötelező válaszobjektum.

videó

Field	Típus	Description
title	karakterlánc	A videó címe.
description	karakterlánc	A videó leírása.
url	karakterlánc	A videó URL-címe.

Hibakódok

Állapotkód	Hibakategória	Description	Gyakori okok
200	Success	A kérés sikeres volt.	-
400	Hibás kérés	Érvénytelen kérelemparaméterek.	Hiányzó kötelező mezők, érvénytelen paraméterértékek, hibásan formázott JSON
401	Unauthorized	A hitelesítés sikertelen vagy hiányzik.	Érvénytelen API-kulcs, hiányzó x-apikey fejléc
403	Forbidden	Érvényes hitelesítő adatok, de nem megfelelő engedélyek.	Az API-kulcs nem rendelkezik szükséges engedélyekkel
410	Eltűnt	HTTPS szükséges.	HTTPS helyett HTTP-en keresztül küldött kérelem
415	Nem támogatott médiatípus	A tartalomtípus nem támogatott.	Hiányzó vagy helytelen tartalomtípusú fejléc
429	Túl sok kérés	Túllépte a sebességkorlátot.	Túl sok kérés az időablakban
500	Belső kiszolgálóhiba	Váratlan kiszolgálóhiba.	Ideiglenes kiszolgálóval kapcsolatos probléma
503	A szolgáltatás nem érhető el	A szolgáltatás átmenetileg nem érhető el.	Karbantartás vagy ideiglenes kimaradás
504	Átjáró időkorlát túllépve	A kérés túllépte az időkorlátot.	Upstream szolgáltatás időtúllépése

A hibakezeléssel kapcsolatos részletes útmutatásért tekintse meg a Hibakezelés című témakört.

---

Lásd még:Web Search Browse | | News Search | Images Search | MCP