Compartilhar via


Chamar a API da Análise de Imagem 3.2

Este artigo demonstra como chamar a API de Análise de Imagem versão 3.2 para retornar informações sobre os recursos visuais de uma imagem. Ele também mostra como analisar as informações retornadas com os SDKs do cliente ou a API REST.

Este guia pressupõe que você já criou um recurso de Visão e obteve uma chave e uma URL do ponto de extremidade. Se você estiver usando um SDK do cliente, também precisará autenticar um objeto cliente. Para obter mais informações sobre essas etapas, consulte o Início Rápido da Análise de Imagem.

Enviar dados ao serviço

O código neste guia usa imagens remotas referenciadas por URL. Talvez você queira experimentar imagens diferentes por conta própria para ver toda a funcionalidade dos recursos da Análise de Imagem.

Ao analisar uma imagem remota, especifique a URL da imagem formatando o corpo da solicitação como este: {"url":"http://example.com/images/test.jpg"}.

Para analisar uma imagem local, coloque os dados da imagem binária no corpo da solicitação HTTP.

Determinar como processar os dados

Selecionar recursos visuais

A API de Análise fornece acesso a todos os recursos de análise de imagem do serviço. Escolha quais operações fazer com base em seu próprio caso de uso. Para obter uma descrição de cada recurso, consulte a visão geral da Visão de IA do Azure. Os exemplos nas seções a seguir adicionam todos os recursos visuais disponíveis, mas, para uso prático, você provavelmente só precisará de um ou dois.

É possível especificar quais recursos deseja usar definindo os parâmetros de consulta de URL da API Analyze. Um parâmetro pode ter vários valores, separados por vírgulas. Cada recurso que você especificar requer mais tempo de computação, portanto, especifique apenas o que você precisa.

Parâmetro da URL Valor Descrição
features Read lê o texto visível na imagem e o gera como dados JSON estruturados
features Description descreve o conteúdo da imagem com uma frase completa nos idiomas com suporte
features SmartCrops localiza as coordenadas do retângulo que cortam a imagem para uma taxa de proporção desejada, preservando a área de interesse
features Objects Detecta vários objetos dentro de uma imagem, inclusive a localização aproximada. O argumento Objects só está disponível em inglês
features Tags marca a imagem com uma lista detalhada de palavras relacionadas ao conteúdo da imagem

Uma URL preenchida pode se parecer com isto:

<endpoint>/vision/v3.2/analyze?visualFeatures=Tags

Especificar idiomas

Você também pode especificar o idioma dos dados retornados.

O parâmetro de consulta da URL a seguir especifica o idioma. O valor padrão é en.

Parâmetro da URL Valor Descrição
language en Inglês
language es Espanhol
language ja Japonês
language pt Português
language zh Chinês simplificado

Uma URL preenchida pode se parecer com isto:

<endpoint>/vision/v3.2/analyze?visualFeatures=Tags&language=en

Obter resultados do serviço

Esta seção mostra como analisar os resultados da chamada à API. Ele inclui a própria chamada à API.

Observação

Chamadas à API com escopo

Alguns dos recursos na Análise de Imagem podem ser chamados diretamente ou pela chamada à API Analisar. Por exemplo, você pode fazer uma análise com escopo apenas de marcas de imagem fazendo uma solicitação para <endpoint>/vision/v3.2/tag (ou para o método correspondente no SDK). Confira a documentação de referência para ver outros recursos que podem ser chamados separadamente.

O serviço retorna uma resposta HTTP 200 e o corpo contém os dados retornados na forma de uma cadeia de caracteres JSON. O texto a seguir é um exemplo de uma resposta JSON.

{
    "metadata":
    {
        "width": 300,
        "height": 200
    },
    "tagsResult":
    {
        "values":
        [
            {
                "name": "grass",
                "confidence": 0.9960499405860901
            },
            {
                "name": "outdoor",
                "confidence": 0.9956876635551453
            },
            {
                "name": "building",
                "confidence": 0.9893627166748047
            },
            {
                "name": "property",
                "confidence": 0.9853052496910095
            },
            {
                "name": "plant",
                "confidence": 0.9791355729103088
            }
        ]
    }
}

Códigos do Erro

Veja a seguinte lista de possíveis erros e suas respectivas causas:

  • 400
    • InvalidImageUrl - A URL da imagem está mal formatada ou não está acessível
    • InvalidImageFormat - Os dados de entrada não são uma imagem válida
    • InvalidImageSize - A imagem de entrada é muito grande
    • NotSupportedVisualFeature - O tipo de recurso especificado não é válido
    • NotSupportedImage - Imagem sem suporte, por exemplo, pornografia infantil
    • InvalidDetails - Valor do parâmetro detail sem suporte
    • NotSupportedLanguage - Não há suporte para a operação solicitada no idioma especificado
    • BadArgument - Mais detalhes são fornecidos na mensagem de erro
  • 415 – Erro de tipo de mídia sem suporte. O tipo de conteúdo não está dentre os tipos permitidos:
    • Para uma URL de imagem, o Content-Type deve ser application/json
    • Para dados de imagem binários, o Content-Type deve ser application/octet-stream ou multipart/form-data
  • 500
    • FailedToProcess
    • Timeout – O processamento de imagem atingiu o tempo limite
    • InternalServerError

Dica

Ao trabalhar com a Visão de IA do Azure, talvez você encontre falhas transitórias causadas por limites de taxa impostos pelo serviço ou outros problemas transitórios, como interrupções de rede. Para obter informações sobre como lidar com esses tipos de falhas, consulte o Padrão de repetição no guia Padrões de Design de Nuvem e o Padrão disjuntor relacionado.