移除影像中的背景

本文示範如何呼叫影像分析 4.0 API 以分割影像 (將幕前與背景分開)。 此外也會說明如何剖析傳回的資訊。

必要條件

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

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

快速入門會說明如何從影像中擷取視覺特徵。 不過，其概念類似於背景移除。 因此，從這個快速入門開始並進行修改會對您有幫助。

驗證服務

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

藉由新增 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。

選取模式

將查詢字串 mode 設定為以下兩個值之一。 如果您想要進行影像分割，此查詢字串是必要項目。

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 查詢字串提供的名稱，找不到自訂模型。

下一步

背景移除概念