Rest-API-Referenz für die Bildsuche

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

Beispielanforderung:

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

Parameter	Required	Typ	Vorgabe	Description
query	Yes	string	-	Eine Suchabfragezeichenfolge. Die maximale Länge beträgt 1000 Zeichen.
maxResults	No	integer	30	Maximale Anzahl der zurückzugebenden Ergebnisse. Der Standardwert ist 30, und der Maximalwert ist 30.
language	No	string	„de“	Ein 2-Buchstaben-ISO 639-1-Sprachcode für die Schnittstellensprache in den Suchergebnissen. Die vollständige Liste finden Sie unter "Unterstützte Sprachen ".
region	No	string	"US"	Ein 2-Buchstaben-Länder-/Regionscode für den Ort, aus dem die Ergebnisse stammen sollen (z. B. "US", "JP", "CN"). Die vollständige Liste finden Sie unter "Unterstützte Regionen ".
aspectRatio	No	string(enum)	-	Filtert Bilder nach Seitenverhältnis. Werte: "quadratisch" (ungefähr 1:1), "breit" (Breite Höhe > ), "hoch" (Höhe der Höhe > ). Wenn sie nicht festgelegt ist, wird keine Filterung angewendet.
color	No	string(enum)	-	Filtert Bilder nach Bildfarbe. Werte: "colorOnly" (nur Farbbilder zurückgeben), "Monochrom" (nur Schwarzweißbilder zurückgeben). Wenn sie nicht festgelegt ist, wird keine Filterung angewendet.
safeSearch	No	string(enum)	"streng"	Ebene der sicheren Suchfilterung. Werte: "off", "strict". Der Standardwert ist "strict".
imageSize	No	string(enum)	-	Filtert Bilder nach Größenkategorie. Werte: "klein" (<200x200px), "mittel" (Breite oder Höhe 200-500px), "groß" (Breite oder Höhe >=500px), "extraLarge" (>1024x768px). Kann auch Pixeleinschränkungen (maxHeight, minHeight, maxWidth, minWidth) für benutzerdefinierte Grenzen verwenden; Pixeleinschränkungen haben Vorrang vor "imageSize", wenn sie konflikte. Wenn sie nicht festgelegt ist, wird keine Filterung angewendet.
watermarkFree	No	boolean	Falsch	Bilder mit Wasserzeichen ausschließen. Die Standardeinstellung ist "false".
maxHeight	No	integer	-	Maximale Bildhöhe in Pixel. Wird mit imageSize für benutzerdefinierte Grenzen verwendet.
minHeight	No	integer	-	Minimale Bildhöhe in Pixel.
maxWidth	No	integer	-	Maximale Bildbreite in Pixel.
minWidth	No	integer	-	Minimale Bildbreite in Pixel.

Anforderungsheader

Feld	Typ	Description
host	string	Host für Microsoft AI-APIs: api.microsoft.ai.
x-apikey oder Autorisierung	string	Ihr API-Schlüssel oder Entra ID Zugriffstoken für die Authentifizierung.
Inhaltstyp	string	MIME-Typ des Anforderungstexts. Verwenden Sie application/json.

Antwort

ImagesResponse

Feld	Typ	Description
imageResults	Array von ImageResult	Liste der Bildergebnisse.
instrumentationClickBase	string	Basis-URL zum Klicken auf Pinganforderungen. Fügen Sie einen instrumentationSuffix Wert aus einem Ergebniselement an, um die vollständige Ping-URL zu bilden. Nur für Anwendungen mit dem EnableInstrumentationPing-Profilflagge vorhanden. Hinweis: Benutzerklicks können auch mithilfe der URL-Umleitung protokolliert werden. Wenn die Umleitung aktiviert ist, ist keine Aktion erforderlich, um Benutzerklicks zu protokollieren und instrumentationClickBase nicht in die Antwort eingeschlossen. Anweisungen zum Einrichten finden Sie im Handbuch zur Instrumentierung .
instrumentationCitationBase	string	Basis-URL für LLM-Protokollpinganforderungen. Fügen Sie eine DATA-Nutzlast an, um die vollständige Ping-URL zu bilden. Nur für Anwendungen mit dem EnableInstrumentationPing-Profilflagge vorhanden.
traceId	string	Ablaufverfolgungs-ID zum Debuggen und Nachverfolgen.

ImageResult

Feld	Typ	Description
title	string	Der Titel des Bilds.
url	string	Die Quell-URL des Bilds. Für China-Benutzer mit aktivierter URL-Umleitung enthält dieses Feld stattdessen dieselbe Umleitungs-URL wie clickUrl.
domain	string	Der Zielhost für das Ergebnis. Wird nur für China-Benutzer mit aktivierter URL-Umleitung zurückgegeben.
hostPageUrl	string	Die URL der Webseite, die das Bild hosten soll.
caption	string	Generierte Beschreibung des Bilds.
width	integer	Die Breite des Bilds in Pixel.
height	integer	Die Höhe des Bilds in Pixel.
thumbnailUrl	string	Die URL der Miniaturansichtsquelle des Bilds.
lastUpdatedAt	string	Das datum der letzten Aktualisierung des Bilds folgt ISO8601 Format.
isAdult	boolean	Gibt an, ob der Inhalt erwachsener Inhalt ist.
clickUrl	string	Umleitungs-URL, die den Klick durch Bing proxiest. Nur vorhanden, wenn die Klickumleitung aktiviert ist.
instrumentationSuffix	string	Suffix, das an die URL-Basis der Instrumentierung für dieses Ergebniselement angefügt werden soll. Wird als K-Wert sowohl für die Ping-URL der Instrumentation als auch für die clickUrl Umleitung verwendet. Vorhanden, wenn die Instrumentierungs-Ping aktiviert ist.

Fehlercodes

Statuscode	Fehlerkategorie	Description	Häufige Ursachen
200	Success	Die Anfrage war erfolgreich.	-
400	Ungültige Anforderung	Ungültige Anforderungsparameter.	Fehlende erforderliche Felder, ungültige Parameterwerte, falsch formatierter JSON-Code
401	Unauthorized	Fehler bei der Authentifizierung oder fehlender Authentifizierung.	Ungültiger API-Schlüssel, fehlender x-apikey-Header
403	Verboten	Gültige Anmeldeinformationen, aber unzureichende Berechtigungen.	API-Schlüssel verfügt nicht über erforderliche Berechtigungen
410	Nicht vorhanden (Gone)	HTTPS erforderlich.	Anforderung über HTTP anstelle von HTTPS
415	Nicht unterstützter Medientyp	Der Inhaltstyp wird nicht unterstützt.	Fehlender oder falscher Inhaltstypheader
429	Zu viele Anforderungen	Das Ratenlimit wurde überschritten.	Zu viele Anforderungen im Zeitfenster
500	Interner Serverfehler	Unerwarteter Serverfehler.	Temporäres Serverproblem
503	Dienst nicht verfügbar	Der Dienst ist vorübergehend nicht verfügbar.	Wartung oder vorübergehender Ausfall
504	Gateway-Zeitüberschreitung	Zeitüberschreitung bei der Anforderung.	Timeout des Upstream-Diensts

Ausführliche Anleitungen zur Fehlerbehandlung finden Sie unter "Fehlerbehandlung".

---

Siehe auch:Web search | Videos Search | | News Search | MCP