移除影像中的背景

文章
06/13/2024

本文示範如何呼叫影像分析 4.0 API 來分割影像（分隔前景與背景）。此外也會說明如何剖析傳回的資訊。

重要

背景移除只能透過直接 REST API 呼叫來使用。它無法透過 SDK 取得。

必要條件

本指南假設您已成功按照快速入門頁面所描述的步驟。這表示：

您已建立視覺資源，並取得密鑰和端點 URL。
您已成功對服務進行 curl.exe 呼叫 (或使用替代工具)。您可以根據這裡的範例修改 curl.exe 呼叫。

快速入門說明如何從影像擷取視覺功能。不過，概念類似於背景移除。因此，您可以從快速入門開始和進行修改中獲益。

重要

背景移除僅適用於特定 Azure 區域。請參閱區域可用性

驗證服務

若要對影像分析服務進行驗證，您需要電腦視覺金鑰和端點 URL。

提示

請勿在程式碼中直接包含索引碼，且切勿公開張貼索引碼。如需更多驗證選項 (例如 Azure Key Vault)，請參閱 Azure AI 服務安全性文章。

藉由新增 HTTP 要求標頭 Ocp-Apim-Subscription-Key 並將其設定為您的視覺金鑰來完成驗證。呼叫 URL <endpoint>/computervision/imageanalysis:segment?api-version=2023-02-01-preview，其中 <endpoint> 是您唯一電腦視覺端點 URL。如需新增至此 URL 的另一個查詢字串，請參閱選取模式一節。

選取要分析的影像

本指南中的程式碼使用 URL 所參考的遠端影像。您可以自行嘗試不同的影像，以瞭解影像分析功能的各種能力。

分析遠端影像時，您可以用下列格式輸入要求本文，以指定影像的 URL：{"url":"https://learn.microsoft.com/azure/ai-services/computer-vision/images/windows-kitchen.jpg"}。 Content-Type 應為 application/json。

若要分析本地影像，您須將二進位影像資料放入 HTTP 要求本文中。 Content-Type 應為 application/octet-stream 或 multipart/form-data。

選取模式

將查詢字串模式設定為這兩個值的其中一個。如果您想要進行影像分割，此查詢字串是必要項目。

URL 參數	值	Description
`mode`	`backgroundRemoval`	輸出偵測到前景物件、背景為透明的影像。
`mode`	`foregroundMatting`	輸出灰階透明圖層遮罩的影像，顯示不透明的、偵測到的前景物件。

backgroundRemoval 的填入 URL 看起來如下所示：<endpoint>/computervision/imageanalysis:segment?api-version=2023-02-01-preview&mode=backgroundRemoval

取得服務的結果

本節說明如何進行 API 呼叫以及剖析結果。

服務會在 Content-Type: image/png 成功時傳回 200 HTTP 回應，而本文會以二進位串流的形式包含傳回的 PNG 影像。

例如，假設背景移除是在下列影像上執行：

水岸城市的相片。

成功發出背景移除呼叫時，下列四通道 PNG 影像是 backgroundRemoval 模式的回應：

水岸城市的相片；天空是透明的。

下列單通道 PNG 影像是 foregroundMatting 模式的回應：

城市天際線的透明圖層遮罩。

若是 foregroundMatting 模式，API 傳回的影像大小與原始影像大小相同，但若是 backgroundRemoval 模式，最大是 1600 萬像素 (保留影像比例)。

錯誤碼

發生錯誤時，影像分析服務回應會包含有錯誤碼和錯誤訊息的 JSON 承載。它也可能包含以內部錯誤碼和訊息形式出現的其他詳細資料。例如：

{
    "error":
    {
        "code": "InvalidRequest",
        "message": "Analyze query is invalid.",
        "innererror":
        {
            "code": "NotSupportedVisualFeature",
            "message": "Specified feature type is not valid"
        }
    }
}

以下是常見的錯誤及其原因清單。清單項目會以下列格式呈現：

HTTP 回應碼
- JSON 回應中的錯誤碼和訊息
  - [選擇性] JSON 回應中的內部錯誤碼和訊息

常見錯誤清單：

400 Bad Request
- InvalidRequest - Image URL is badly formatted or not accessible. 請確定影像 URL 有效且可公開存取。
- InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes. 藉由壓縮和/或調整大小來減少影像的大小，然後重新提交您的要求。
- InvalidRequest - The feature 'Caption' is not supported in this region. 只有特定 Azure 區域才支援此功能。如需支援的 Azure 區域清單，請參閱快速入門必要條件。
- InvalidRequest - The provided image content type ... is not supported. 要求中的 HTTP 標頭 Content-Type 不是允許的類型：
  - 針對影像 URL，Content-Type 應為 application/json
  - 針對二進位影像資料，Content-Type 應為 application/octet-stream 或 multipart/form-data
- InvalidRequest - Either 'features' or 'model-name' needs to be specified in the query parameter.
- InvalidRequest - Image format is not valid
  - InvalidImageFormat - Image format is not valid. 如需支援的影像格式，請參閱影像需求一節。
- InvalidRequest - Analyze query is invalid
  - NotSupportedVisualFeature - Specified feature type is not valid. 請確定 features 查詢字串具有有效的值。
  - NotSupportedLanguage - The input language is not supported. 請根據下表，確定 language 查詢字串對選取的視覺特徵而言是有效值。
  - BadArgument - 'smartcrops-aspect-ratios' aspect ratio is not in allowed range [0.75 to 1.8]
401 PermissionDenied
- 401 - Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.
404 Resource Not Found
- 404 - Resource not found. 服務根據 model-name 查詢字串提供的名稱，找不到自訂模型。

提示

使用 Azure AI 視覺時，您可能會遇到由服務強制執行的速率限制或其他暫時性問題所造成的暫時性失敗，例如網路中斷。如需如何處理這些失敗類型的相關資訊，請參閱《雲端設計模式》指南中的重試模式，以及相關的斷路器模式。

下一步

背景移除概念

分享方式：