Informazioni di riferimento sulle API REST di Ricerca immagini

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

Richiesta di esempio:

curl -X POST "https://api.microsoft.ai/v3/search/images" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H 'content-type: application/json' \
  -d '{
    "query": "cats",
    "maxResults": 2,
    "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 di 2 lettere da cui devono provenire i risultati (ad esempio "US", "JP", "CN"). Per l'elenco completo, vedere Aree supportate .
aspectRatio	No	string(enum)	-	Filtrare le immagini in base alle proporzioni. Valori: "quadrato" (approssimativamente 1:1), "wide" (altezza larghezza > ), "tall" (larghezza altezza > ). Se non è impostato, non viene applicato alcun filtro.
color	No	string(enum)	-	Filtrare le immagini in base al colore dell'immagine. Valori: "colorOnly" (restituisce solo immagini a colori), "monocromatico" (restituisce solo immagini nere e bianche). Se non è impostato, non viene applicato alcun filtro.
safeSearch	No	string(enum)	"strict"	Livello di filtro di ricerca sicuro. Valori: "off", "strict". Il valore predefinito è "strict".
imageSize	No	string(enum)	-	Filtrare le immagini in base alla categoria delle dimensioni. Valori: "small" (<200x200px), "medium" (width or height 200-500px), "large" (width or height >=500px), "extraLarge" (>1024x768px). Può anche usare vincoli pixel (maxHeight, minHeight, maxWidth, minWidth) per i limiti personalizzati; I vincoli pixel hanno la precedenza su imageSize quando sono in conflitto. Se non è impostato, non viene applicato alcun filtro.
watermarkFree	No	boolean	falso	Escludere immagini con filigrana. Il valore predefinito è false.
maxHeight	No	integer	-	Altezza massima dell'immagine in pixel. Usato con imageSize per i limiti personalizzati.
minHeight	No	integer	-	Altezza minima dell'immagine in pixel.
maxWidth	No	integer	-	Larghezza massima dell'immagine in pixel.
minWidth	No	integer	-	Larghezza minima dell'immagine in pixel.

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

ImagesResponse

Field	Type	Description
imageResults	matrice di ImageResult	Elenco dei risultati dell'immagine.
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 e il rilevamento.

ImageResult

Field	Type	Description
title	string	Titolo dell'immagine.
url	string	URL di origine dell'immagine. 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.
hostPageUrl	string	URL della pagina Web che ospita l'immagine.
caption	string	Descrizione generata dell'immagine.
width	integer	Larghezza dell'immagine, in pixel.
height	integer	Altezza dell'immagine, in pixel.
thumbnailUrl	string	URL dell'origine dell'anteprima dell'immagine.
lastUpdatedAt	string	La data dell'ultimo aggiornamento dell'immagine segue ISO8601 formato.
isAdult	boolean	Indica se il 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.

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:Ricercavideo Ricerca | | WebCerca | notizie | MCP