提出 Vision API 要求

Cloud Vision API 是 REST API，會使用 HTTP POST 作業，對您在要求中傳送的圖片執行資料分析。API 會使用 JSON 格式處理要求和回應。

摘要

  • 要求是傳送至 https://vision.googleapis.com/v1/images:annotate 的 POST 要求。
  • 您必須驗證要求。
  • 要求主體看起來會像這樣。 回應看起來會像這樣，但欄位會因註解類型而異。
  • 以下說明如何使用 cURL 傳送要求。
  • 此外，還有用戶端程式庫。
  • 想觀看快速示範嗎？只要拖曳即可！

端點

Vision API 包含單一端點 (https://vision.googleapis.com/v1/images)，支援一種 HTTP 要求方法 (annotate)：

POST https://vision.googleapis.com/v1/images:annotate

驗證

POST 要求必須傳遞 API 金鑰或 OAuth 權杖，才能通過驗證。詳情請參閱「驗證」頁面。

JSON 要求格式

POST 要求的內文包含 JSON 物件，其中含有單一 requests 清單，該清單本身則包含一或多個 AnnotateImageRequest 型別的物件：

{
  "requests":[
    {
      "image":{
        "content":"/9j/7QBEUGhvdG9...image contents...eYxxxzj/Coa6Bax//Z"
      },
      "features":[
        {
          "type":"LABEL_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}

每個要求：

  • 必須包含 requests 清單。

在 requests 清單中：

  • image 會指定圖片檔。可以傳送為 base64 編碼字串、Cloud Storage 檔案位置或可公開存取的網址。詳情請參閱「提供圖片」一節。

  • features 列出要在圖片上執行的註解類型。您可以指定一或多個類型，以及要為每個類型傳回的 maxResults。

  • imageContext (上例未顯示) 會指定服務的提示，協助註解：邊界方塊、語言和裁剪提示顯示比例。

提供圖片

您可以在要求中透過下列三種方式提供圖片：

  • 以 Base64 編碼的圖片字串形式。如果圖片儲存在本機，您可以將圖片轉換為字串，並做為 image.content 的值傳遞：

    {
  "requests":[
    {
      "image":{
        "content":"/9j/7QBEUGhvdG9zaG9...image contents...fXNWzvDEeYxxxzj/Coa6Bax//Z"
      },
      "features":[
        {
          "type":"FACE_DETECTION",
          "maxResults":10
        }
      ]
    }
  ]
}

    如需在各種平台上進行編碼的操作說明，請參閱「Base64 編碼」。

  • 以 Cloud Storage URI 的形式。將完整 URI 做為 image.source.imageUri 的值傳遞：

    {
  "requests":[
    {
      "image":{
        "source":{
          "imageUri":
            "gs://bucket_name/path_to_image_object"
        }
      },
      "features":[
        {
          "type":"LABEL_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}

    Cloud Storage 中的檔案必須可供您使用的驗證方法存取。如果您使用 API 金鑰，檔案必須可公開存取。如果您使用服務帳戶，建立服務帳戶的使用者必須能存取該檔案。

  • 以公開存取的 HTTP 或 HTTPS 網址形式。將網址做為 image.source.imageUri 的值傳遞：

    {
  "requests":[
    {
      "image":{
        "source":{
          "imageUri":
            "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png"
        }
      },
      "features":[
        {
          "type":"LOGO_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}

    從 HTTP/HTTPS 網址擷取圖片時，Google 無法保證要求會完成。如果指定主機拒絕要求 (例如因要求節流或阻斷服務防護)，或 Google 為防止濫用而限制對網站的要求，您的要求可能會失敗。最佳做法是不要在正式版應用程式中，使用外部代管的圖片。

JSON 回應格式

annotate 要求會收到 AnnotateImageResponse 類型的 JSON 回應。 雖然每種功能類型的要求都很類似，但每種功能類型的回應可能大不相同。如需完整資訊，請參閱 Vision API 參考資料。

以下程式碼顯示下方相片的標籤偵測回應範例：

{
  "responses": [
    {
      "labelAnnotations": [
        {
          "mid": "/m/0bt9lr",
          "description": "dog",
          "score": 0.97346616
        },
        {
          "mid": "/m/09686",
          "description": "vertebrate",
          "score": 0.85700572
        },
        {
          "mid": "/m/01pm38",
          "description": "clumber spaniel",
          "score": 0.84881884
        },
        {
          "mid": "/m/04rky",
          "description": "mammal",
          "score": 0.847575
        },
        {
          "mid": "/m/02wbgd",
          "description": "english cocker spaniel",
          "score": 0.75829375
        }
      ]
    }
  ]
}

用戶端程式庫

Google 提供多種程式語言的用戶端程式庫，可簡化建立及傳送要求，以及接收及剖析回應的程序。

如需安裝和使用說明，請參閱用戶端程式庫。