移除影像中的背景
重要
這項功能現在已被取代。 2025 年 3 月 31 日,Azure AI 影像分析 4.0 區段 API 和背景移除服務將會淘汰。 此服務的所有要求都會在此日期之後失敗。
開放原始碼 佛羅倫薩 2 模型的 分割功能可能符合您的需求。 它會傳回 Alpha 地圖,標示前景和背景之間的差異,但不會編輯原始影像以移除背景。 安裝佛羅倫薩 2 模型,並試用其區域以分割功能。
如需完整功能的背景移除,請考慮第三方公用程式,例如 BiRefNet。
本文示範如何呼叫影像分析 4.0 API 以分割影像 (將幕前與背景分開)。 此外也會說明如何剖析傳回的資訊。
重要
您只能透過直接的 REST API 呼叫來進行背景移除。 無法透過 SDK 來進行。
重要
背景移除僅適用於特定 Azure 區域。 請參閱區域可用性
必要條件
本指南假設您已成功按照快速入門頁面所描述的步驟。 這表示:
- 您已建立視覺資源,並已取得金鑰和端點 URL。
- 您已成功對服務進行
curl.exe
呼叫 (或使用替代工具)。 您可以根據這裡的範例修改curl.exe
呼叫。
快速入門會說明如何從影像中擷取視覺特徵。 不過,其概念類似於背景移除。 因此,從這個快速入門開始並進行修改會對您有幫助。
對服務的驗證
若要向影像分析服務進行驗證,您需要 電腦視覺 金鑰和端點 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
。
選取模式
將查詢字串 mode 設定為以下兩個值之一。 如果您想要進行影像分割,此查詢字串是必要項目。
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 回應中的內部錯誤碼和訊息
- 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
- 針對影像 URL,Content-Type 應為
-
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 視覺時,您可能會遇到由於服務強制執行速率限制或其他暫時性問題 (例如網路中斷) 而導致的暫時性失敗。 如需如何處理這些失敗類型的相關資訊,請參閱《雲端設計模式》指南中的重試模式,以及相關的斷路器模式。