Informazioni di riferimento sull'API REST ricerca video

Endpoint:POST https://api.microsoft.ai/v3/search/videos

Richiesta di esempio:

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

Parametro	Required	Type	Default	Description
query	Yes	string	-	Stringa di query di ricerca. La lunghezza massima è di 1000 caratteri.
maxResults	No	integer	30	Numero massimo di risultati da restituire. Il valore predefinito è 30 e il valore massimo è 30.
language	No	string	"en"	Codice di lingua ISO 639-1 di 2 lettere per la lingua dell'interfaccia nei risultati della ricerca. Per l'elenco completo, vedere Lingue supportate .
region	No	string	"US"	Codice paese/area geografica a 2 lettere da cui devono provenire i risultati (ad esempio "US", "JP", "GB" e così via). Per l'elenco completo, vedere Aree supportate .
enablePlaylist	No	boolean	falso	Indica se includere i risultati della playlist in risposta.
freshness	No	string	-	Intervallo di tempo per filtrare i risultati in base alla data di individuazione. Supporta il formato "week", "month", "year" per l'ora relativa o il formato di intervallo di data ISO 8601: "AAAA-MM-GG/AAAA-MM-GG" o "AAAA-MM-GGTHH:mm:ssZ/AAAA-MM-GGTHH:mm:ssZ" per un intervallo date/datetime, usare .. per omettere la data di inizio o di fine.
incorporabile	No	matrice di valori string	-	Filtrare i video in base alle funzionalità di incorporamento. Valori consentiti: "player" (ha un lettore incorporabile). Se non è impostato, non viene applicato alcun filtro.
risoluzione	No	string	-	Filtrare i video in base alla risoluzione minima . Valori: "360p", "480p", "720p", "1080p". Se non è impostato, non viene applicato alcun filtro.
safeSearch	No	string	"strict"	Livello di filtro di ricerca sicuro. Valori: "off", "strict". Il valore predefinito è "strict".
duration	No	string	-	Filtrare i video in base all'intervallo di durata. Valori: "short" (<5 min), "medium" (5-20 min), "long" (>20 min). Se non è impostato, non viene applicato alcun filtro.

Intestazioni della richiesta

Field	Type	Description
host	string	Host per le API di intelligenza artificiale Microsoft: api.microsoft.ai.
x-apikey o autorizzazione	string	La chiave API o Entra ID token di accesso per l'autenticazione.
tipo di contenuto	string	Tipo MIME del corpo della richiesta. Utilizzare il application/json.

Risposta

Risposta video

Field	Type	Description
videoResults	matrice di videoResult	Elenco dei risultati video.
playlist	matrice di playlistResult (facoltativo)	Elenco dei risultati della playlist.
instrumentationClickBase	string	URL di base per fare clic su richieste ping. Aggiungere un instrumentationSuffix valore da un elemento del risultato per formare l'URL ping completo. Presente solo per le applicazioni con il flag del profilo EnableInstrumentationPing. Nota: è anche possibile registrare i clic degli utenti usando il reindirizzamento URL. Quando il reindirizzamento è abilitato, non è necessaria alcuna azione per registrare i clic dell'utente e instrumentationClickBase non verrà inclusa nella risposta. Per istruzioni sull'installazione, vedere la guida alla strumentazione .
instrumentationCitationBase	string	URL di base per le richieste ping del log LLM. Aggiungere un payload DATA per formare l'URL ping completo. Presente solo per le applicazioni con il flag del profilo EnableInstrumentationPing.
traceId	string	ID traccia per il debug.

Note

playlists è un campo facoltativo anche se enablePlaylist è impostato su true.

videoResult

Field	Type	Description
title	string	Titolo o nome del video.
url	string	URL di origine del video. Per gli utenti della Cina con reindirizzamento URL abilitato, questo campo contiene invece lo stesso URL di reindirizzamento di clickUrl.
domain	string	Host di destinazione per il risultato. Restituito solo per gli utenti della Cina con reindirizzamento URL abilitato.
description	string	Descrizione del contenuto video. Viene fornito dal caricatore video o generato da un LLM.
publishedBy	string	Uploader o editore del video.
viewCount	long	Numero di visualizzazioni del video.
summary	string	Riepilogo video generato dall'intelligenza artificiale.
length	string	Lunghezza del video in formato HH:MM:SS.
allowHttpsEmbedding	boolean	Indica se l'incorporamento HTTPS è consentito.
allowMobileEmbedding	boolean	Indica se l'incorporamento per dispositivi mobili è consentito.
embeddingUrl	string	URL per l'incorporamento del video.
ultimoAggiornatoAt	string	Data dell'ultimo aggiornamento come stringa formattata.
bestMomentIndex	integer	Indice del momento migliore o evidenziazione nel video.
Momenti	matrice di momenti	Matrice di segmenti/momenti video.
thumbnailUrl	string	URL di anteprima del video.
width	integer	Larghezza del video in pixel.
height	integer	Altezza del video in pixel.
isAdult	boolean	Indica se il risultato include contenuto per adulti.
clickUrl	string	URL di reindirizzamento che esegue il proxy del clic tramite Bing. Presente solo quando il clic di reindirizzamento è abilitato.
instrumentationSuffix	string	Suffisso da aggiungere alla base dell'URL ping di strumentazione per questo elemento del risultato. Usato come valore K sia per l'URL ping di strumentazione che per il clickUrl reindirizzamento. Presente quando è abilitato il ping di strumentazione.

Note

Molti dei campi precedenti sono facoltativi, se disponibili.

momento

Field	Type	Description
title	string	Titolo del segmento del momento.
description	string	Descrizione di ciò che accade in questo momento.
startTime	string	Ora di inizio del momento in formato 'd.hh:mm:ss'.
endTime	string	Ora di fine del momento in formato 'd.hh:mm:ss'.
momentUrl	string	URL diretto a questo momento specifico nel video.

Note

moment è un oggetto di risposta facoltativo. Non è disponibile per ogni risultato video.

playlistResult

Field	Type	Description
title	string	Titolo della playlist.
description	string	Descrizione della playlist.
video	matrice di video	Matrice di video nella playlist.

Note

playlistResult è un oggetto di risposta facoltativo.

video

Field	Type	Description
title	string	Titolo del video.
description	string	Descrizione del video.
url	string	URL del video.

Codici di errore

Codice di stato	Categoria errore	Description	Cause comuni
200	Operazione completata	La richiesta è stata accolta.	-
400	Richiesta non valida	Parametri di richiesta non validi.	Campi obbligatori mancanti, valori di parametro non validi, JSON in formato non valido
401	Unauthorized	Autenticazione non riuscita o mancante.	Chiave API non valida, intestazione x-apikey mancante
403	Non consentito	Credenziali valide ma autorizzazioni insufficienti.	La chiave API non dispone delle autorizzazioni necessarie
410	Sparito	HTTPS obbligatorio.	Richiesta effettuata tramite HTTP invece di HTTPS
415	Tipo di supporto non supportato	Tipo di contenuto non supportato.	Intestazione di tipo contenuto mancante o non corretta
429	Troppe richieste	Limite di velocità superato.	Troppe richieste nell'intervallo di tempo
500	Errore interno del server	Errore server imprevisto.	Problema temporaneo del server
503	Servizio non disponibile	Servizio temporaneamente non disponibile.	Manutenzione o interruzione temporanea
504	Timeout gateway	Tempo di attesa della richiesta scaduto.	Timeout del servizio Upstream

Per indicazioni dettagliate sulla gestione degli errori, vedere Gestione degli errori.

---

Vedere anche:Ricerca | WebSfoglia | immaginiricerca | notizie Ricerca | MCP