提出 Vision API 要求

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

摘要

  • 要求是 POST 要求，會傳送至 https://vision.googleapis.com/v1/images:annotate。
  • 您必須authenticate要求。
  • 要求主體如下所示。回應看起來有點像這個，但欄位會因你使用的註解類型而有所不同。
  • 以下說明如何使用 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 提供多種程式語言的用戶端程式庫，以簡化建立及傳送要求，以及接收及剖析回應的程序。

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