端點：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 | 類型 | Default | Description |
|---|---|---|---|---|
| 查詢 | Yes | 字串 | - | 一個搜尋查詢字串。 長度上限為 1000 個字元。 |
| maxResults | No | 整數 | 30 | 要傳回的結果數目上限。 預設值是30，最高值是30。 |
| 語言 | No | 字串 | 「en」 | 搜尋結果中介面語言的兩字母 ISO 639-1 語言代碼。 完整列表請參閱 支援語言 。 |
| 區域 | No | 字串 | "US" | 一個兩字母的國家/地區代碼，表示結果應該來自哪裡（例如「US」、「JP」、「GB」等）。 完整列表請參閱 支援區域 。 |
| enablePlaylist | No | boolean | 假的 | 是否包含播放清單，回應。 |
| freshness | No | 字串 | - | 根據發現日期篩選結果的時間範圍。 支援「週」、「月」、「年」來表示相對時間，或 ISO 8601 日期間隔格式：「YYYY-MM-DD/YYYY-MM-DD」或「YYYY-MM-DDTHH：MM：SSZ/YYYY-MM-DDTHH：mm：ssZ」，用於日期/日期時間範圍，請使用 .. 省略開始或結束日期。 |
| 可嵌入 | No | 字串陣列 | - | 透過嵌入功能過濾影片。 允許的值：「player」（可嵌入播放器）。 未設定時，則不會被過濾。 |
| 解析 | No | 字串 | - | 依 最低 解析度過濾影片。 數值：「360p」、「480p」、「720p」、「1080p」。 未設定時，則不會被過濾。 |
| safeSearch | No | 字串 | 「嚴格」 | 安全搜尋篩選的層級。 價值觀：「關」、「嚴格」。 預設是「嚴格」。 |
| duration | No | 字串 | - | 依照影片長度範圍篩選。 數值：「短」（<5 分鐘）、 「中」（5–20 分鐘）、 「長」（>20 分鐘）。 未設定時，則不會被過濾。 |
要求標頭
| Field | 類型 | Description |
|---|---|---|
| 主持人 | 字串 | Microsoft AI API 主機： api.microsoft.ai |
| x-apikey 或 授權 | 字串 | 你的 API 金鑰或 Entra ID 存取權杖用於認證。 |
| 內容類型 | 字串 | 請求實體的 MIME 類型。 請使用 application/json。 |
回應
影片回應
| Field | 類型 | Description |
|---|---|---|
| 影片結果 | videoResult 陣列 | 影片結果列表。 |
| 播放清單 | 播放列表結果陣列（可選） | 播放清單結果列表。 |
| 儀器 ClickBase | 字串 | 點擊ping請求的基礎網址。 從 instrumentationSuffix 結果項目附加一個值，形成完整的 ping URL。 僅用於帶有 EnableInstrumentationPing 設定檔標誌的應用程式。 注意：使用者點擊也可透過網址重定向來記錄。 啟用重定向時，無需操作記錄使用者點擊，且 instrumentationClickBase 回應中不會包含。 請參閱 儀器安裝指南 以了解設定說明。 |
| 儀器引用基礎 | 字串 | LLM 日誌 ping 請求的基礎網址。 附加一個 DATA payload 以形成完整的 ping URL。 僅用於帶有 EnableInstrumentationPing 設定檔標誌的應用程式。 |
| traceId | 字串 | 用於除錯的追蹤識別碼。 |
Note
playlists 即使 enablePlaylist 設為 true，仍是可選欄位。
影片結果
| Field | 類型 | Description |
|---|---|---|
| title | 字串 | 影片的標題或名稱。 |
| url | 字串 | 影片的原始網址。 對於啟用 URL 重定向的中國用戶，此欄位會包含與 clickUrl相同的重定向 URL。 |
| 網域 | 字串 | 結果的目的地主機。 僅針對啟用 URL 重定向的中國用戶退回。 |
| description | 字串 | 影片內容說明。 這部分由影片上傳者提供，或由大型語言模型（LLM）產生。 |
| 出版人 | 字串 | 影片上傳者或發布者。 |
| 瀏覽次數 | long | 影片的觀看次數。 |
| 摘要 | 字串 | AI 生成的影片摘要。 |
| length | 字串 | 影片長度為 HH：MM：SS 格式。 |
| 允許HttpsEmbedding | boolean | 是否允許 HTTPS 嵌入。 |
| allowMobileEmbedding | boolean | 行動嵌入是否被允許。 |
| 嵌入網址 | 字串 | 嵌入影片的網址。 |
| 最後更新時間 | 字串 | 最後更新日期以格式化字串呈現。 |
| 最佳時刻索引 | 整數 | 影片中最精彩的時刻或亮點的索引。 |
| 瞬間 | 矩陣列 | 各種影片片段/時刻。 |
| 縮圖網址 | 字串 | 影片縮圖網址。 |
| width | 整數 | 影片的寬度（以像素為單位）。 |
| height | 整數 | 影片的高度（像素單位）。 |
| 是成人 | boolean | 顯示結果是否包含成人內容。 |
| 點擊網址 | 字串 | 透過 Bing 將點擊的代理網址重新導轉。 只有在啟用點擊重定向時才會出現。 |
| 配器後綴 | 字串 | 附加於此結果項目的儀器 ping URL 基底後綴。 用作儀器 ping URL 與重定向的 clickUrl K 值。 啟用儀器 ping 時仍會顯示。 |
Note
上述幾個欄位為可選選項——若有，則會提供。
時刻
| Field | 類型 | Description |
|---|---|---|
| title | 字串 | 當下標題單元。 |
| description | 字串 | 描述此刻發生的事情。 |
| startTime | 字串 | 以格式「d.hh：mm：ss」開始此刻。 |
| endTime | 字串 | 此刻結束時間，格式為 'd.hh：mm：ss'。 |
| momentUrl | 字串 | 影片中這個特定時刻的直接網址。 |
Note
moment 是一個可選的回應物件。 並非每個影片結果都能使用。
播放清單結果
| Field | 類型 | Description |
|---|---|---|
| title | 字串 | 播放清單的標題。 |
| description | 字串 | 播放清單說明。 |
| 影片 | 視訊陣列 | 播放清單裡有各種影片。 |
Note
playlistResult 是一個可選的回應物件。
影片
| Field | 類型 | Description |
|---|---|---|
| title | 字串 | 影片標題。 |
| description | 字串 | 影片說明。 |
| url | 字串 | 影片的 URL。 |
錯誤代碼
| 狀態代碼 | 錯誤類別 | Description | 常見的原因 |
|---|---|---|---|
| 200 | Success | 請求成功。 | - |
| 400 | 錯誤的請求 | 請求參數無效。 | 缺少必填欄位、參數值無效、JSON 格式錯誤 |
| 401 | Unauthorized | 驗證失敗或缺失。 | API 金鑰無效，缺少 x-apikey 標頭 |
| 403 | 禁止 | 有效的憑證，但權限不足。 | API 金鑰缺乏所需權限 |
| 410 | 消失了 | 需要 HTTPS 認證。 | 請求是透過 HTTP 而非 HTTPS 進行的 |
| 415 | 不支援媒體類型 | 內容類型不支援。 | 缺少或錯誤的內容類型標頭 |
| 429 | 過多要求 | 速率超過上限。 | 時間窗口內請求太多 |
| 500 | 內部伺服器錯誤 | 未預期的伺服器錯誤。 | 臨時伺服器問題 |
| 503 | 服務不可用 | 服務暫時無法使用。 | 維護或暫時停電 |
| 504 | 閘道逾時 | 要求已逾時。 | 上游服務逾時 |
如需詳細的錯誤處理指引，請參見 錯誤處理。