Faça um pedido da API Vision

A API Cloud Vision é uma API REST que usa operações HTTP POST para realizar a análise de dados em imagens que envia no pedido. A API usa JSON para pedidos e respostas.

Resumo

  • Os pedidos são pedidos POST para https://vision.googleapis.com/v1/images:annotate.
  • Tem de autenticar os seus pedidos.
  • O corpo do pedido tem o seguinte aspeto: . As respostas têm um aspeto semelhante a este, mas os campos variam consoante o tipo de anotação que está a fazer.
  • Veja como enviar um pedido com o cURL.
  • Também existem bibliotecas cliente.
  • Procura uma demonstração rápida? Basta arrastar e largar!

Ponto final

A API Vision consiste num único ponto final (https://vision.googleapis.com/v1/images) que suporta um método de pedido HTTP (annotate):

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

Autenticação

O pedido POST tem de ser autenticado através da transmissão de uma chave da API ou de um token OAuth. Para obter detalhes, consulte a página Autenticar.

Formato de pedido JSON

O corpo do seu pedido POST contém um objeto JSON com uma única requests lista, que, por sua vez, contém um ou mais objetos do tipo AnnotateImageRequest:

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

Todos os pedidos:

  • Tem de conter uma lista requests.

Na lista requests:

  • image especifica o ficheiro de imagem. Pode ser enviado como uma string codificada em base64, uma localização de ficheiro do Cloud Storage ou um URL acessível publicamente. Consulte a secção Fornecer a imagem para ver detalhes.

  • features apresenta os tipos de anotação a realizar na imagem. Pode especificar um ou vários tipos, bem como o maxResults a devolver para cada um.

  • imageContext (não apresentado no exemplo acima) especifica sugestões para o serviço para ajudar com a anotação: caixas delimitadoras, idiomas e proporções de sugestões de recorte.

Fornecer a imagem

Pode fornecer a imagem no seu pedido de uma de três formas:

  • Como uma string de imagem codificada em base64. Se a imagem estiver armazenada localmente, pode convertê-la numa string e transmiti-la como o valor de image.content:

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

    Consulte o artigo Codificação base64 para ver instruções sobre a codificação em várias plataformas.

  • Como um URI do Cloud Storage. Transmita o URI completo como o valor de image.source.imageUri:

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

    O ficheiro no Cloud Storage tem de estar acessível ao método de autenticação que está a usar. Se estiver a usar uma chave da API, o ficheiro tem de estar acessível publicamente. Se estiver a usar uma conta de serviço, o ficheiro tem de estar acessível ao utilizador que criou a conta de serviço.

  • Como um URL HTTP ou HTTPS acessível publicamente. Transmita o URL como o valor de 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
        }
      ]
    }
  ]
}

    Quando obtém imagens de URLs HTTP/HTTPS, a Google não pode garantir que o pedido será concluído. O seu pedido pode falhar se o anfitrião especificado recusar o pedido (por exemplo, devido à limitação de pedidos ou à prevenção de DoS) ou se a Google limitar os pedidos ao site para prevenção de abusos. Como prática recomendada, não dependa de imagens alojadas externamente para aplicações de produção.

Formato de resposta JSON

O pedido annotate recebe uma resposta JSON do tipo AnnotateImageResponse. Embora os pedidos sejam semelhantes para cada tipo de funcionalidade, as respostas para cada tipo de funcionalidade podem ser bastante diferentes. Consulte a referência da API Vision para obter informações completas.

O código abaixo demonstra uma resposta de deteção de etiquetas de exemplo para a foto mostrada abaixo:

{
  "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
        }
      ]
    }
  ]
}

Bibliotecas cliente

A Google fornece bibliotecas cliente em várias linguagens de programação para simplificar o processo de criação e envio de pedidos, bem como de receção e análise de respostas.

Consulte as bibliotecas de cliente para ver instruções de instalação e utilização.