끝점:POST https://api.microsoft.ai/v3/search/videos
샘플 요청:
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
| 매개 변수 | 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", "GB" 등). 전체 목록은 지원되는 지역을 참조하세요. |
| enablePlaylist | No | 부울 | 거짓 | 응답에 재생 목록 결과를 포함할지 여부입니다. |
| freshness | No | string | - | 검색 날짜를 기준으로 결과를 필터링할 시간 범위입니다. 상대 시간에 대해 "week", "month", "year" 또는 ISO 8601 날짜 간격 형식을 지원합니다. 날짜/날짜/시간 범위의 경우 "YYYY-MM-DD/YYYY-MM-DDD" 또는 "YYYY-MM-DDTHH:mm:ssZ/YYYY-MM-DDTHH:mm:ssZ"를 사용합니다. 시작 또는 종료 날짜를 생략합니다. |
| embeddable | No | 문자열의 배열 | - | 기능을 포함하여 비디오를 필터링합니다. 허용되는 값: "player"(포함할 수 있는 플레이어 포함) 설정하지 않으면 필터링이 적용되지 않습니다. |
| 해결 방법 | No | string | - | 최소 해상도로 비디오를 필터링합니다. 값: "360p", "480p", "720p", "1080p". 설정하지 않으면 필터링이 적용되지 않습니다. |
| safeSearch | No | string | "strict" | 안전한 검색 필터링 수준입니다. 값: "off", "strict". 기본값은 "strict"입니다. |
| duration | No | string | - | 기간 범위별로 비디오를 필터링합니다. 값: "short"(<5분), "보통"(5~20분), "long"(>20분). 설정하지 않으면 필터링이 적용되지 않습니다. |
요청 헤더
| Field | Type | Description |
|---|---|---|
| host | string | Microsoft AI API용 호스트: api.microsoft.ai. |
| x-apikey 또는 권한 부여 | string | 인증을 위한 API 키 또는 Entra ID 액세스 토큰입니다. |
| 컨텐츠 유형 (content-type) | string | 요청 본문의 MIME 형식입니다.
application/json을 사용합니다. |
응답
비디오 응답
| Field | Type | Description |
|---|---|---|
| videoResults | videoResult 배열 | 비디오 결과 목록입니다. |
| 재생 목록 | playlistResult 배열(선택 사항) | 재생 목록 결과 목록입니다. |
| instrumentationClickBase | string | ping 요청을 클릭하기 위한 기본 URL입니다. 결과 항목의 instrumentationSuffix 값을 추가하여 전체 ping URL을 형성합니다. EnableInstrumentationPing 프로필 플래그가 있는 애플리케이션에만 존재합니다. 참고: URL 리디렉션을 사용하여 사용자 클릭을 기록할 수도 있습니다. 리디렉션을 사용하도록 설정하면 사용자 클릭을 기록하는 작업이 필요하지 않으며 instrumentationClickBase 응답에 포함되지 않습니다. 설치 지침은 계측 가이드 를 참조하세요. |
| instrumentationCitationBase | string | LLM 로그 ping 요청에 대한 기본 URL입니다. 데이터 페이로드를 추가하여 전체 ping URL을 형성합니다. EnableInstrumentationPing 프로필 플래그가 있는 애플리케이션에만 존재합니다. |
| traceId | string | 디버깅을 위한 추적 ID입니다. |
Note
playlists 은 true로 설정된 경우에도 enablePlaylist 선택적 필드입니다.
videoResult
| Field | Type | Description |
|---|---|---|
| title | string | 비디오의 제목 또는 이름입니다. |
| url | string | 비디오의 원본 URL입니다. URL 리디렉션을 사용하도록 설정된 중국 사용자의 경우 이 필드에는 .와 동일한 리디렉션 URL clickUrl이 대신 포함됩니다. |
| domain | string | 결과의 대상 호스트입니다. URL 리디렉션을 사용하도록 설정된 중국 사용자에 대해서만 반환됩니다. |
| description | string | 비디오 콘텐츠에 대한 설명입니다. 비디오 업로더에서 제공하거나 LLM에서 생성합니다. |
| publishedBy | string | 비디오의 업로더 또는 게시자입니다. |
| viewCount | long | 비디오의 보기 수입니다. |
| summary | string | AI에서 생성된 비디오 요약입니다. |
| length | string | HH:MM:SS 형식의 비디오 길이입니다. |
| allowHttpsEmbedding | 부울 | HTTPS 포함이 허용되는지 여부입니다. |
| allowMobileEmbedding | 부울 | 모바일 포함이 허용되는지 여부입니다. |
| embeddingUrl | string | 비디오를 포함하기 위한 URL입니다. |
| 마지막 업데이트됨 | string | 서식이 지정된 문자열로 마지막으로 업데이트된 날짜입니다. |
| bestMomentIndex | integer | 비디오에서 가장 좋은 순간 또는 강조 표시의 인덱스입니다. |
| 순간 | 모멘트 배열 | 비디오 세그먼트/순간의 배열입니다. |
| 썸네일URL | string | 비디오의 썸네일 URL입니다. |
| width | integer | 비디오의 너비(픽셀)입니다. |
| height | integer | 비디오의 높이(픽셀)입니다. |
| isAdult | 부울 | 결과에 성인 콘텐츠가 포함되는지 여부를 나타냅니다. |
| clickUrl | string | Bing을 통해 클릭을 프록시하는 URL을 리디렉션합니다. 클릭 리디렉션을 사용하는 경우에만 존재합니다. |
| instrumentationSuffix | string | 이 결과 항목의 계측 ping URL 베이스에 추가할 접미사입니다. 계측 ping URL과 리디렉션 모두에 대한 K 값으로 clickUrl 사용됩니다. 계측 ping을 사용할 때 표시됩니다. |
Note
위의 필드 중 일부는 선택 사항이며 사용 가능한 경우 제공됩니다.
moment
| Field | Type | Description |
|---|---|---|
| title | string | 모멘트 세그먼트의 제목입니다. |
| description | string | 이 순간에 어떤 일이 일어나는지에 대한 설명입니다. |
| startTime | string | 순간의 시작 시간('d.hh:mm:ss' 형식)입니다. |
| endTime 사이에서 | string | 순간의 종료 시간('d.hh:mm:ss' 형식)입니다. |
| momentUrl | string | 비디오에서 이 특정 순간에 대한 직접 URL입니다. |
Note
moment 는 선택적 응답 개체입니다. 모든 비디오 결과에는 사용할 수 없습니다.
playlistResult
| Field | Type | Description |
|---|---|---|
| title | string | 재생 목록의 제목입니다. |
| description | string | 재생 목록에 대한 설명입니다. |
| 비디오 | 비디오 배열 | 재생 목록의 비디오 배열입니다. |
Note
playlistResult 는 선택적 응답 개체입니다.
비디오
| Field | Type | Description |
|---|---|---|
| title | string | 비디오의 제목입니다. |
| description | string | 비디오에 대한 설명입니다. |
| url | string | 비디오의 URL입니다. |
오류 코드
| 상태 코드 | 오류 범주 | Description | 일반적인 원인 |
|---|---|---|---|
| 200 | Success | 요청이 성공했습니다. | - |
| 400 | 잘못된 요청 | 잘못된 요청 매개 변수입니다. | 필수 필드 누락, 잘못된 매개 변수 값, 형식이 잘못된 JSON |
| 401 | 권한 없음 | 인증이 실패했거나 누락되었습니다. | 잘못된 API 키, x-apikey 헤더 누락 |
| 403 | 사용할 수 없음 | 유효한 자격 증명이지만 권한이 부족합니다. | API 키에 필요한 권한이 없음 |
| 410 | 사라졌다 | HTTPS가 필요합니다. | HTTPS 대신 HTTP를 통해 요청 |
| 415 | 지원되지 않는 미디어 형식 | 콘텐츠 형식은 지원되지 않습니다. | 콘텐츠 형식 헤더가 없거나 잘못되었습니다. |
| 429 | 요청이 너무 많음 | 속도 제한을 초과했습니다. | 시간 창에 요청이 너무 많습니다. |
| 500 | 내부 서버 오류 | 예기치 않은 서버 오류가 발생했습니다. | 임시 서버 문제 |
| 503 | 서비스를 사용할 수 없음 | 서비스를 일시적으로 사용할 수 없습니다. | 유지 관리 또는 임시 중단 |
| 504 | 게이트웨이 시간 제한 | 요청 시간이 초과되었습니다. | 업스트림 서비스 시간 제한 |
자세한 오류 처리 지침은 오류 처리를 참조하세요.