Image Search REST API-referencia

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

Mintakérés:

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

Paraméter	Required	Típus	Default	Description
query	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.
language	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.
region	No	karakterlánc	"US"	Kétbetűs ország-/régiókód, amelyből az eredmények származnak (pl. "US", "JP", "CN"). A teljes listát a Támogatott régiók című témakörben találja.
aspectRatio	No	sztring(enum)	-	Képek szűrése méretarány szerint. Értékek: "négyzet" (nagyjából 1:1), "széles" (szélességi > magasság), "magas" (magasságszélesség > ). Ha nincs beállítva, a rendszer nem alkalmaz szűrést.
color	No	sztring(enum)	-	Képek szűrése képszín alapján. Értékek: "colorOnly" (csak színképeket ad vissza), "monokróm" (csak fekete-fehér képeket ad vissza). Ha nincs beállítva, a rendszer nem alkalmaz szűrést.
safeSearch	No	sztring(enum)	"szigorú"	A biztonságos keresés szűrésének szintje. Értékek: "ki", "szigorú". Az alapértelmezett érték a "szigorú".
imageSize	No	sztring(enum)	-	Képek szűrése méretkategória szerint. Értékek: "kicsi" (<200x200px), "közepes" (szélesség vagy magasság 200-500px), "nagy" (szélesség vagy magasság >=500px), "extraLarge" (>1024x768px). A képpontkorlátokat (maxHeight, minHeight, maxWidth, minWidth) is használhatja egyéni korlátokhoz; A képpontkorlátok elsőbbséget élveznek a képméretekkel szemben, amikor ütköznek. Ha nincs beállítva, a rendszer nem alkalmaz szűrést.
watermarkFree	No	boolean	false	Zárja ki a vízjellel rendelkező képeket. Az alapértelmezett érték false.
maxHeight	No	egész szám	-	Maximális képmagasság képpontban. Az imageSize egyéni korlátokhoz használható.
minHeight	No	egész szám	-	Minimális képmagasság képpontban.
maxWidth	No	egész szám	-	Maximális képszélesség képpontban.
minWidth	No	egész szám	-	Minimális képszélesség képpontban.

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

ImagesResponse

Field	Típus	Description
imageResults	Az ImageResult tömbje	A képeredmények 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 és a nyomkövetéshez.

ImageResult

Field	Típus	Description
title	karakterlánc	A kép címe.
url	karakterlánc	A kép 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 .
domain	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.
hostPageUrl	karakterlánc	A képet üzemeltető weblap URL-címe.
caption	karakterlánc	A kép generált leírása.
width	egész szám	A kép szélessége képpontban.
height	egész szám	A kép magassága képpontban.
thumbnailUrl	karakterlánc	A kép miniatűr forrás URL-címe.
lastUpdatedAt	karakterlánc	A kép utolsó frissített dátuma ISO8601 formátumot követi.
isAdult	boolean	Azt jelzi, hogy a tartalom felnőtt tartalom-e.
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.

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 | Videók Keresés Tallózás | | Hírek Keresés | MCP