Fazer uma solicitação da API Vision

A API Cloud Vision é uma API REST que usa operações HTTP POST para realizar análise de dados nas imagens enviadas na solicitação. A API usa o JSON para solicitações e para respostas.

Resumo

Endpoint

A API Vision consiste em um único endpoint (https://vision.googleapis.com/v1/images) compatível com um método de solicitação HTTP (annotate):

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

Autenticação

Para se autenticar, a solicitação POST precisa transmitir uma chave de API ou um token OAuth. Para ver detalhes, consulte a página Autenticar.

Formato de solicitação JSON

O corpo da solicitação POST contém um objeto JSON, com uma única lista de requests, que inclui um ou mais objetos do tipo AnnotateImageRequest:

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

Cada solicitação:

  • precisa conter uma lista de requests.

Na lista de requests:

  • image especifica o arquivo de imagem. Ele pode ser enviado como uma string codificada em base64, um local de arquivo do Cloud Storage ou um URL acessível publicamente. Consulte Como fornecer a imagem para detalhes;

  • features lista os tipos de anotação para execução na imagem. É possível especificar um ou vários tipos, além de maxResults a ser retornado para cada um;

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

Como fornecer a imagem

Você pode fornecer a imagem na solicitação de uma destas três maneiras:

  • Como uma string de imagem codificada em base64. Se a imagem estiver armazenada localmente, será possível convertê-la em uma 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 Codificação em base64 para ver instruções sobre codificação em várias plataformas.

  • Como um URI do Cloud Storage. Insira 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 arquivo no Cloud Storage precisa ser acessível pelo método de autenticação utilizado. Se você estiver usando uma chave de API, o arquivo precisará estar publicamente acessível. Se você estiver usando uma conta de serviço, o arquivo precisará estar acessível para o usuário que criou a conta do serviço.

  • Como um URL HTTP ou HTTPS acessível publicamente. Insira 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
        }
      ]
    }
  ]
}

    Ao buscar imagens de URLs HTTP/HTTPS, o Google não pode garantir que a solicitação seja concluída. A solicitação poderá falhar se o host especificado negá-la (por exemplo, por causa de limitação da solicitação ou prevenção de DOS) ou se o Google limitar as solicitações ao site para prevenção de abuso. Como prática recomendada, não dependa de imagens hospedadas externamente para aplicativos de produção.

Formato de resposta JSON

A solicitação annotate recebe uma resposta JSON do tipo AnnotateImageResponse. As solicitações são semelhantes para cada tipo de recurso, mas as respostas para cada um deles podem ser bastante diferentes. Consulte Referência da API Vision para ver informações detalhadas.

O código abaixo contém uma amostra de resposta de detecção de marcadores para esta foto:

{
  "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 de cliente

O Google fornece bibliotecas de cliente em várias linguagens de programação para simplificar o processo de criar e enviar solicitações e receber e analisar as respostas.

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