Chamar a API do Image Analysis 3.2

Este artigo demonstra como chamar a API do Image Analysis 3.2 para retornar informações sobre os recursos visuais de uma imagem. Ele também mostra como analisar as informações retornadas usando os SDKs de cliente ou a API REST.

Este guia pressupõe que você já criou um recurso de visão e obteve uma chave e um URL de ponto final. Se você estiver usando um SDK de cliente, também precisará autenticar um objeto de cliente. Se você não tiver feito essas etapas, siga o início rápido para começar.

Enviar dados ao serviço

O código neste guia usa imagens remotas referenciadas por URL. Você pode querer experimentar imagens diferentes por conta própria para ver a capacidade completa dos recursos de Análise de Imagem.

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

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

Determinar como processar os dados

Selecionar recursos visuais

A API Analyze dá 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. Consulte a visão geral para obter uma descrição de cada recurso. Os exemplos nas seções abaixo adicionam todos os recursos visuais disponíveis, mas para uso prático você provavelmente precisará apenas de um ou dois.

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

Parâmetro de URL valor Description
features Read lê o texto visível na imagem e o produz como dados JSON estruturados.
features Description descreve o conteúdo da imagem com uma frase completa em idiomas suportados.
features SmartCrops Localiza as coordenadas do retângulo que cortariam a imagem para uma proporção desejada, preservando a área de interesse.
features Objects Deteta vários objetos dentro de uma imagem, incluindo 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.

Um URL preenchido pode ter esta aparência:

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

Especificar línguas

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

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

Parâmetro de URL valor Description
language en Inglês
language es Espanhol
language ja Japonês
language pt Português
language zh Chinês Simplificado

Um URL preenchido pode ter esta aparência:

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

Obter resultados do serviço

Esta seção mostra como analisar os resultados da chamada de API. Inclui a própria chamada de API.

Nota

Chamadas de API com escopo

Alguns dos recursos da Análise de Imagem podem ser chamados diretamente, bem como por meio da chamada da API Analyze. Por exemplo, você pode fazer uma análise de escopo apenas de tags de imagem fazendo uma solicitação para <endpoint>/vision/v3.2/tag (ou para o método correspondente no SDK). Consulte a documentação de referência para outros recursos que podem ser chamados separadamente.

O serviço retorna uma 200 resposta HTTP 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 de erro

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

  • 400
    • InvalidImageUrl - O URL da imagem está mal formatado 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 não suportado detail .
    • NotSupportedLanguage - A operação solicitada não é suportada no idioma especificado.
    • BadArgument - Mais detalhes são fornecidos na mensagem de erro.
  • 415 - Erro de tipo de mídia não suportado. O Content-Type não está nos tipos permitidos:
    • Para um URL de imagem, Content-Type deve ser application/json
    • Para dados de imagem binária, Content-Type deve ser application/octet-stream ou multipart/form-data
  • 500
    • FailedToProcess
    • Timeout - O tempo limite de processamento de imagem expirou.
    • InternalServerError

Gorjeta

Ao trabalhar com o Azure AI Vision, você pode encontrar 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 Repetir padrão no guia Padrões de design de nuvem e o padrão de disjuntor relacionado.

Próximos passos

  • Explore os artigos conceituais para saber mais sobre cada recurso.
  • Consulte a referência da API para saber mais sobre a funcionalidade da API.