Image Analysis - Analyze Image

參考

服務:: Azure AI Services

API 版本:: 2023-04-01-preview

分析輸入影像。要求包含任何內容類型為 ['image/*'、'application/octet-stream'] 的影像數據流，或包含用來擷取影像數據流的 URL 屬性的 JSON 承載。

POST /imageanalysis:analyze?api-version=2023-04-01-preview

含選擇性參數:

POST /imageanalysis:analyze?features={features}&model-name={model-name}&language={language}&smartcrops-aspect-ratios={smartcrops-aspect-ratios}&gender-neutral-caption={gender-neutral-caption}&api-version=2023-04-01-preview

URI 參數

名稱	位於	必要	類型	Description
api-version	query	True	string	要求的 API 版本。
features	query		VisualFeature[]	要求的視覺功能：tags、objects、caption、denseCaptions、read、smartCrops、people。如果未指定參數「model-name」，則必須指定此參數。
gender-neutral-caption	query		boolean	布爾值旗標，可啟用標題和 denseCaptions 功能的性別中性輔助字幕。如果未指定此參數，預設值為「false」。
language	query		string	輸出產生所需的語言。如果未指定此屬性，則預設值為 "en"。如需支援的語言清單，請參閱 https://aka.ms/cv-languages 。
model-name	query		string	自定義定型模型的名稱。如果未指定參數「features」，則必須指定此參數。
smartcrops-aspect-ratios	query		string	用於 smartCrops 功能的外觀比例清單。外觀比例的計算方式是將目標裁剪寬度除以高度。支援的值介於 0.75 和 1.8 (內含) 之間。多個值應該以逗號分隔。如果未指定此參數，服務會傳回一個裁剪建議，其外觀比例介於 0.5 和 2.0 之間 (包含) 。

要求本文

名稱	必要	類型	Description
url	True	string	影像的可公開連線 URL。

回應

名稱	類型	Description
200 OK	ImageAnalysisResult	成功
Other Status Codes	ErrorResponse	[錯誤] 標題 x-ms-error-code: string

名稱

類型

Description

200 OK

ImageAnalysisResult

成功

Other Status Codes

ErrorResponse

[錯誤]

標題

x-ms-error-code: string

範例

AnalyzeImage_CustomModel

範例要求

HTTP

POST /imageanalysis:analyze?model-name=my_model_name&api-version=2023-04-01-preview

{
  "url": "https://example.com/image.jpg"
}

範例回覆

狀態碼:: 200

{
  "customModelResult": {
    "objectsResult": {
      "values": [
        {
          "id": "1",
          "boundingBox": {
            "x": 197,
            "y": 68,
            "w": 356,
            "h": 394
          },
          "tags": [
            {
              "name": "class1",
              "confidence": 0.92431640625
            }
          ]
        },
        {
          "id": "2",
          "boundingBox": {
            "x": 0,
            "y": 77,
            "w": 241,
            "h": 359
          },
          "tags": [
            {
              "name": "class1",
              "confidence": 0.87890625
            }
          ]
        }
      ]
    }
  },
  "modelVersion": "2023-04-01-preview",
  "metadata": {
    "width": 660,
    "height": 495
  }
}

定義

名稱	Description
AdultMatch	描述成人內容相符的物件。
AdultResult	物件，描述影像是否包含成人導向的內容和/或不雅。
BoundingBox	影像內區域的周框方塊。
CaptionResult	影像描述的簡短描述。
CropRegion	識別用於智慧裁剪的區域。每個要求的外觀比例都會傳回一個區域。
DenseCaption	影像描述的簡短描述。
DenseCaptionsResult	標題清單。
DetectedObject	描述影像中偵測到的物件。
DetectedPerson	在影像中偵測到的人員。
DocumentLine	內容行物件，由相鄰的內容專案序列所組成，例如文字和選取標記。
DocumentPage	從輸入擷取自頁面的內容和版面配置元素。
DocumentSpan	串連內容屬性的連續區域，指定為位移和長度。
DocumentStyle	物件，表示觀察到的文字樣式。
DocumentWord	由連續字元序列組成的 word 物件。對於非空格分隔的語言，例如中文、日文和韓文，每個字元都會以自己的單字表示。
ErrorResponse	發生錯誤時傳回的回應。
ErrorResponseDetails	錯誤資訊。
ErrorResponseInnerError	詳細的錯誤。
ImageAnalysisResult	描述不同類型的影像分析合併結果。
ImageMetadataApiModel	影像元數據資訊，例如高度和寬度。
ImagePredictionResult	描述影像的預測結果。
ImageUrl	具有 URL 的 JSON 檔，指向要分析的影像。
ObjectsResult	描述影像中偵測到的物件。
PeopleResult	物件，描述影像是否包含人員。
ReadResult	讀取作業的結果。
SmartCropsResult	智慧裁剪結果。
Tag	影像中的實體觀察，以及信賴分數。
TagsResult	具有信賴等級的標籤清單。
VisualFeature	要求的視覺功能：tags、objects、caption、denseCaptions、read、smartCrops、people。如果未指定參數「model-name」，則必須指定此參數。

AdultMatch

描述成人內容相符的物件。

名稱	類型	Description
confidence	number	值，表示相符成人內容的信賴等級。
isMatch	boolean	值，指出影像是否符合成人內容。

AdultResult

物件，描述影像是否包含成人導向的內容和/或不雅。

名稱	類型	Description
adult	AdultMatch	描述成人內容相符的物件。
gore	AdultMatch	描述成人內容相符的物件。
racy	AdultMatch	描述成人內容相符的物件。

BoundingBox

影像內區域的周框方塊。

名稱	類型	Description
h	integer	以像素為單位，從區域左上方點測量的高度。
w	integer	從區域左上方點測量的寬度，以像素為單位。
x	integer	區域左上方點的左座標，以像素為單位。
y	integer	區域左上方點的頂端座標，以像素為單位。

CaptionResult

影像描述的簡短描述。

名稱	類型	Description
confidence	number	服務在標題中擁有的信賴等級。
text	string	標題的文字。

CropRegion

識別用於智慧裁剪的區域。每個要求的外觀比例都會傳回一個區域。

名稱	類型	Description
aspectRatio	number	裁剪區域的外觀比例。
boundingBox	BoundingBox	影像內區域的周框方塊。

DenseCaption

影像描述的簡短描述。

名稱	類型	Description
boundingBox	BoundingBox	影像內區域的周框方塊。
confidence	number	服務在標題中擁有的信賴等級。
text	string	標題的文字。

DenseCaptionsResult

標題清單。

名稱	類型	Description
values	DenseCaption[]	標題清單。

DetectedObject

描述影像中偵測到的物件。

名稱	類型	Description
boundingBox	BoundingBox	影像內區域的周框方塊。
id	string	偵測到物件的標識碼。
tags	Tag[]	偵測到物件的分類信賴度。

DetectedPerson

在影像中偵測到的人員。

名稱	類型	Description
boundingBox	BoundingBox	影像內區域的周框方塊。
confidence	number	在影像中觀察到人員的信賴分數，值範圍從 0 到 1。

DocumentLine

內容行物件，由相鄰的內容專案序列所組成，例如文字和選取標記。

名稱	類型	Description
boundingBox	number[]	線條的周框方塊。
content	string	依讀取順序串連自主項目的內容。
spans	DocumentSpan[]	讀取順序串連內容的行位置。

DocumentPage

從輸入擷取自頁面的內容和版面配置元素。

名稱	類型	Description
angle	number	以順時針方向測量內容的一般方向，以 (-180、180 之間的度為單位。
height	number	影像/PDF 的高度，分別以圖元/英吋為單位。
lines	DocumentLine[]	從頁面擷取的行，可能同時包含文字和視覺元素。
pageNumber	integer	輸入檔中以 1 起始的頁碼。
spans	DocumentSpan[]	讀取順序中頁面的位置串連內容。
width	number	影像/PDF 的寬度，分別以圖元/英吋為單位。
words	DocumentWord[]	從頁面擷取的字組。

DocumentSpan

串連內容屬性的連續區域，指定為位移和長度。

名稱	類型	Description
length	integer	範圍所代表內容中的字元數。
offset	integer	範圍所代表之內容的以零起始的索引。

DocumentStyle

物件，表示觀察到的文字樣式。

名稱	類型	Description
confidence	number	正確識別樣式的信賴度。
isHandwritten	boolean	是手動寫入的內容。
spans	DocumentSpan[]	樣式所套用之串連內容中的文字專案位置。

DocumentWord

由連續字元序列組成的 word 物件。對於非空格分隔的語言，例如中文、日文和韓文，每個字元都會以自己的單字表示。

名稱	類型	Description
boundingBox	number[]	單字的周框方塊。
confidence	number	正確擷取字組的信賴度。
content	string	文字內容的文字內容。
span	DocumentSpan	串連內容屬性的連續區域，指定為位移和長度。

ErrorResponse

發生錯誤時傳回的回應。

名稱	類型	Description
error	ErrorResponseDetails	錯誤資訊。

ErrorResponseDetails

錯誤資訊。

名稱	類型	Description
code	string	錯誤碼。
details	ErrorResponseDetails[]	詳細錯誤清單。
innererror	ErrorResponseInnerError	詳細的錯誤。
message	string	錯誤訊息。
target	string	錯誤的目標。

ErrorResponseInnerError

詳細的錯誤。

名稱	類型	Description
code	string	錯誤碼。
innererror	ErrorResponseInnerError	詳細的錯誤。
message	string	錯誤訊息。

ImageAnalysisResult

描述不同類型的影像分析合併結果。

名稱	類型	Description
adultResult	AdultResult	物件，描述影像是否包含成人導向的內容和/或不雅。
captionResult	CaptionResult	影像描述的簡短描述。
customModelResult	ImagePredictionResult	描述影像的預測結果。
denseCaptionsResult	DenseCaptionsResult	標題清單。
metadata	ImageMetadataApiModel	影像元數據資訊，例如高度和寬度。
modelVersion	string	模型版本。
objectsResult	ObjectsResult	描述影像中偵測到的物件。
peopleResult	PeopleResult	物件，描述影像是否包含人員。
readResult	ReadResult	讀取作業的結果。
smartCropsResult	SmartCropsResult	智慧裁剪結果。
tagsResult	TagsResult	具有信賴等級的標籤清單。

ImageMetadataApiModel

影像元數據資訊，例如高度和寬度。

名稱	類型	Description
height	integer	影像的高度，以像素為單位。
width	integer	影像的寬度，以像素為單位。

ImagePredictionResult

描述影像的預測結果。

名稱	類型	Description
objectsResult	ObjectsResult	描述影像中偵測到的物件。
tagsResult	TagsResult	具有信賴等級的標籤清單。

ImageUrl

具有 URL 的 JSON 檔，指向要分析的影像。

名稱	類型	Description
url	string	影像的可公開連線 URL。

ObjectsResult

描述影像中偵測到的物件。

名稱	類型	Description
values	DetectedObject[]	偵測到物件的陣列。

PeopleResult

物件，描述影像是否包含人員。

名稱	類型	Description
values	DetectedPerson[]	偵測到的人員陣列。

ReadResult

讀取作業的結果。

名稱	類型	Description
content	string	依閱讀順序串連所有文字和視覺元素的字串表示。
pages	DocumentPage[]	分析的頁面清單。
stringIndexType	string	用來計算字串位移和長度的方法，可能的值包括：'textElements'、'unicodeCodePoint'、'utf16CodeUnit' 等。
styles	DocumentStyle[]	擷取的字型樣式。

SmartCropsResult

智慧裁剪結果。

名稱	類型	Description
values	CropRegion[]	裁剪影像的建議區域。

Tag

影像中的實體觀察，以及信賴分數。

名稱	類型	Description
confidence	number	觀察到實體的信賴等級。
name	string	實體的名稱。

TagsResult

具有信賴等級的標籤清單。

名稱	類型	Description
values	Tag[]	具有信賴等級的標籤清單。

VisualFeature

要求的視覺功能：tags、objects、caption、denseCaptions、read、smartCrops、people。如果未指定參數「model-name」，則必須指定此參數。

名稱	類型	Description
caption	string
denseCaptions	string
objects	string
people	string
read	string
smartCrops	string
tags	string

共用方式為

Image Analysis - Analyze Image

URI 參數

要求本文

回應

範例

AnalyzeImage_CustomModel

範例要求

範例回覆

定義

AdultMatch

AdultResult

BoundingBox

CaptionResult

CropRegion

DenseCaption

DenseCaptionsResult

DetectedObject

DetectedPerson

DocumentLine

DocumentPage

DocumentSpan

DocumentStyle

DocumentWord

ErrorResponse

ErrorResponseDetails

ErrorResponseInnerError

ImageAnalysisResult

ImageMetadataApiModel

ImagePredictionResult

ImageUrl

ObjectsResult

PeopleResult

ReadResult

SmartCropsResult

Tag

TagsResult

VisualFeature

其他資源