끝점:POST https://api.microsoft.ai/v3/search/images
샘플 요청:
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
| 매개 변수 |
Required |
Type |
Default |
Description |
query |
Yes |
string |
- |
검색 쿼리 문자열입니다. 최대 길이는 1000자입니다. |
maxResults |
No |
integer |
30 |
반환할 최대 결과 수입니다. 기본값은 30이고 최대값은 30입니다. |
language |
No |
string |
"en" |
검색 결과의 인터페이스 언어에 대한 2자 ISO 639-1 언어 코드입니다. 전체 목록은 지원되는 언어 를 참조하세요. |
region |
No |
string |
"US" |
결과가 제공되는 위치에 대한 2자 국가/지역 코드입니다(예: "US", "JP", "CN"). 전체 목록은 지원되는 지역을 참조하세요. |
aspectRatio |
No |
string(enum) |
- |
가로 세로 비율로 이미지를 필터링합니다. 값: "square"(대략 1:1), "wide"(너비 > 높이), "tall"(높이 > 너비) 설정하지 않으면 필터링이 적용되지 않습니다. |
color |
No |
string(enum) |
- |
이미지 색을 사용하여 이미지를 필터링합니다. 값: "colorOnly"(색 이미지만 반환), "단색"(흑백 이미지만 반환). 설정하지 않으면 필터링이 적용되지 않습니다. |
safeSearch |
No |
string(enum) |
"strict" |
안전한 검색 필터링 수준입니다. 값: "off", "strict". 기본값은 "strict"입니다. |
imageSize |
No |
string(enum) |
- |
크기 범주별로 이미지를 필터링합니다. 값: "small"(<200x200px), "medium"(너비 또는 높이 200-500px), "large"(너비 또는 높이 >=500px), "extraLarge"(>1024x768px). 사용자 지정 경계에 픽셀 제약 조건(maxHeight, minHeight, maxWidth, minWidth)을 사용할 수도 있습니다. 픽셀 제약 조건은 충돌할 때 imageSize보다 우선합니다. 설정하지 않으면 필터링이 적용되지 않습니다. |
watermarkFree |
No |
부울 |
거짓 |
워터마크가 있는 이미지를 제외합니다. 기본값은 false입니다. |
maxHeight |
No |
integer |
- |
최대 이미지 높이(픽셀)입니다. 사용자 지정 경계에 대해 imageSize와 함께 사용됩니다. |
minHeight |
No |
integer |
- |
최소 이미지 높이(픽셀)입니다. |
maxWidth |
No |
integer |
- |
최대 이미지 너비(픽셀)입니다. |
minWidth |
No |
integer |
- |
최소 이미지 너비(픽셀)입니다. |
| Field |
Type |
Description |
| host |
string |
Microsoft AI API용 호스트: api.microsoft.ai. |
| x-apikey 또는 권한 부여 |
string |
인증을 위한 API 키 또는 Entra ID 액세스 토큰입니다. |
| 컨텐츠 유형 (content-type) |
string |
요청 본문의 MIME 형식입니다.
application/json을 사용합니다. |
응답
ImagesResponse
| Field |
Type |
Description |
imageResults |
ImageResult 배열 |
이미지 결과 목록입니다. |
instrumentationClickBase |
string |
ping 요청을 클릭하기 위한 기본 URL입니다. 결과 항목의 instrumentationSuffix 값을 추가하여 전체 ping URL을 형성합니다. EnableInstrumentationPing 프로필 플래그가 있는 애플리케이션에만 존재합니다. 참고: URL 리디렉션을 사용하여 사용자 클릭을 기록할 수도 있습니다. 리디렉션을 사용하도록 설정하면 사용자 클릭을 기록하는 작업이 필요하지 않으며 instrumentationClickBase 응답에 포함되지 않습니다. 설치 지침은 계측 가이드 를 참조하세요. |
instrumentationCitationBase |
string |
LLM 로그 ping 요청에 대한 기본 URL입니다. 데이터 페이로드를 추가하여 전체 ping URL을 형성합니다. EnableInstrumentationPing 프로필 플래그가 있는 애플리케이션에만 존재합니다. |
traceId |
string |
디버깅 및 추적에 대한 추적 ID입니다. |
ImageResult
| Field |
Type |
Description |
title |
string |
이미지의 제목입니다. |
url |
string |
이미지의 원본 URL입니다. URL 리디렉션을 사용하도록 설정된 중국 사용자의 경우 이 필드에는 .와 동일한 리디렉션 URL clickUrl이 대신 포함됩니다. |
domain |
string |
결과의 대상 호스트입니다. URL 리디렉션을 사용하도록 설정된 중국 사용자에 대해서만 반환됩니다. |
hostPageUrl |
string |
이미지를 호스트하는 웹 페이지의 URL입니다. |
caption |
string |
이미지에 대한 생성된 설명입니다. |
width |
integer |
이미지의 너비(픽셀)입니다. |
height |
integer |
이미지의 높이(픽셀)입니다. |
thumbnailUrl |
string |
이미지의 썸네일 원본 URL입니다. |
lastUpdatedAt |
string |
이미지의 마지막 업데이트 날짜는 ISO8601 형식을 따릅니다. |
isAdult |
부울 |
콘텐츠가 성인 콘텐츠인지 여부를 나타냅니다. |
clickUrl |
string |
Bing을 통해 클릭을 프록시하는 URL을 리디렉션합니다. 클릭 리디렉션을 사용하는 경우에만 존재합니다. |
instrumentationSuffix |
string |
이 결과 항목의 계측 ping URL 베이스에 추가할 접미사입니다. 계측 ping URL과 리디렉션 모두에 대한 K 값으로 clickUrl 사용됩니다. 계측 ping을 사용할 때 표시됩니다. |
오류 코드
| 상태 코드 |
오류 범주 |
Description |
일반적인 원인 |
| 200 |
Success |
요청이 성공했습니다. |
- |
| 400 |
잘못된 요청 |
잘못된 요청 매개 변수입니다. |
필수 필드 누락, 잘못된 매개 변수 값, 형식이 잘못된 JSON |
| 401 |
권한 없음 |
인증이 실패했거나 누락되었습니다. |
잘못된 API 키, x-apikey 헤더 누락 |
| 403 |
사용할 수 없음 |
유효한 자격 증명이지만 권한이 부족합니다. |
API 키에 필요한 권한이 없음 |
| 410 |
사라졌다 |
HTTPS가 필요합니다. |
HTTPS 대신 HTTP를 통해 요청 |
| 415 |
지원되지 않는 미디어 형식 |
콘텐츠 형식은 지원되지 않습니다. |
콘텐츠 형식 헤더가 없거나 잘못되었습니다. |
| 429 |
요청이 너무 많음 |
속도 제한을 초과했습니다. |
시간 창에 요청이 너무 많습니다. |
| 500 |
내부 서버 오류 |
예기치 않은 서버 오류가 발생했습니다. |
임시 서버 문제 |
| 503 |
서비스를 사용할 수 없음 |
서비스를 일시적으로 사용할 수 없습니다. |
유지 관리 또는 임시 중단 |
| 504 |
게이트웨이 시간 제한 |
요청 시간이 초과되었습니다. |
업스트림 서비스 시간 제한 |
자세한 오류 처리 지침은 오류 처리를 참조하세요.
참고 항목:웹 검색 | 비디오 검색 | 뉴스 검색 | MCP찾아보기 |