Partilhar via


Chamar a API do Image Analysis 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 usando os SDKs de cliente ou a API REST.

Este guia pressupõe que você já criou um recurso Visão e obteve uma chave e uma URL de ponto final. Se você estiver usando um SDK de cliente, também precisará autenticar um objeto de cliente. Para obter mais informações sobre essas etapas, consulte o Guia de 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. 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, coloque 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. Para obter uma descrição de cada recurso, consulte a visão geral do Azure AI Vision. Os exemplos nas seções a seguir adicionam todos os recursos visuais disponíveis, mas para uso prático você provavelmente só precisa 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 requer 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 Objects argumento 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 ou 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 - URL da imagem está mal formatado ou não 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 - Tempo limite de processamento de imagem esgotado
    • 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 o padrão Repetir no guia Padrões de design de nuvem e o padrão de disjuntor relacionado.

  • Explore o conceito de deteção de objetos
  • Consulte a referência da API