Referência da API REST automática

Note

O Auto e o Auto Advanced estão disponíveis para todas as IQ AppID da Web a partir de 17 de novembro de 2026. AppIDs sem acesso completo a documentos obtêm passagens.

Ponto de extremidade:POST https://api.microsoft.ai/v3/auto

Todas as solicitações exigem uma chave de API ou um token de acesso Microsoft Entra ID. Consulte Autenticação para obter instruções de instalação.

Solicitação de exemplo

curl -X POST "https://api.microsoft.ai/v3/auto" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "Microsoft AI announcements",
    "language": "en",
    "region": "US",
    "location": "lat:47.6062;long:-122.3321",
    "mode": "lite",
    "maxResponseLength": 30000,
    "maxCitations": 10,
    "responseFilter": ["web", "news"]
  }'

Exemplo de solicitação com escopo

Para filtrar a recuperação da Web e de notícias em Auto usando um escopo nomeado (consulte Os resultados do filtro com escopos), inclua scopeName e failOnMissingScope:

curl -X POST "https://api.microsoft.ai/v3/auto" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "product setup guide",
    "scopeName": "ProductDocs",
    "failOnMissingScope": true,
    "mode": "lite",
    "responseFilter": ["web", "news"]
  }'

Parameters

Parâmetro Required Tipo Default Description
query Yes cadeia - Consulta de pesquisa, de 1 a 1.000 caracteres.
language No cadeia en Linguagem de interface ISO 639-1 de duas letras.
region No cadeia US Código de mercado de duas letras ou país/região.
mode No cadeia lite lite prioriza a velocidade; advanced prioriza a integralidade.
maxResponseLength No inteiro 30000 Comprimento máximo de conteúdo para resultados da Web, não o tamanho total da resposta. Os valores abaixo de 1500 são fixados em 1500; os valores acima de 500000 são fixados em 500000. Para AppIDs sem acesso completo a documentos, o máximo é 30000.
maxCitations No inteiro 10 Número máximo de citações da Web a serem solicitadas, de 1 a 50. Os valores abaixo de 1 são fixados a 1; os valores acima de 50 são limitados a 50.
location No cadeia - Contexto geográfico em lat:<latitude>;long:<longitude> formato, por exemplo lat:47.6062;long:-122.3321.
responseFilter No Matriz de cadeias de caracteres - Tipos de resposta qualificados: web, , news, timezone, weather, images, videos.
includeSites No Matriz de cadeias de caracteres - Restringe os resultados qualificados da Web a esses sites (domínios com caminhos opcionais), com no máximo 250 entradas. As notícias e outros tipos de resposta não são filtrados. Mantenha a lista curta e relevante para obter melhores resultados. Os caminhos dão suporte a até dois segmentos; caminhos mais profundos são truncados, por isso example.com/a/b/c é tratado como example.com/a/b.
excludeSites No Matriz de cadeias de caracteres - Omite os resultados da Web desses sites (domínios com caminhos opcionais), com no máximo 250 entradas e as mesmas regras de caminho que includeSites. Se um site aparecer em ambas as listas, ele será excluído. As notícias e outros tipos de resposta não são filtrados.
scopeName No cadeia - Um escopo nomeado da coleção atribuída à conta de cobrança do IQ AppID da Web selecionada. Use 1-128 letras ASCII, dígitos, ., _ou -, sem espaço em branco. Para o Auto, os escopos restringem apenas os resultados da Web e do News. Outros tipos de resposta não são filtrados pelo escopo e podem conter resultados fora dele, mesmo quando scopeApplied é true. Omitido ou null significa que nenhum escopo nomeado é solicitado. Veja os resultados do filtro com escopos.
failOnMissingScope No boolean true Controla o fallback para scopeName; omitido ou null significa true. Se o serviço relatar que o escopo não pôde ser aplicado, true retornará HTTP 400 (HandlerInvalidInput) para um escopo ausente confirmado ou HTTP 500 (ScopeFailedToApply) para outras falhas de escopo. false permite a pesquisa sem o escopo, com scopeApplied: false quando esse resultado é relatado. Um escopo válido é aplicado com qualquer um dos valores; zero resultados correspondentes não são uma falha de escopo. Não tem efeito sem um escopo nomeado. Consulte erros de escopo nomeado.

Resposta

Uma resposta de evidência bem-sucedida retorna 200 OK. Cada resultado contém um objeto de evidência tipado e as citações que dão suporte a ele. Evidências sem suporte ou malformadas são omitidas junto com suas citações. Se cada resultado de evidência fornecido for omitido, results estará vazio.

AutoEvidenceResponse

Field Tipo Description
results matriz de AutoEvidenceResult Itens de evidência emparelhados com citações com escopo para esse resultado.
querySignals QuerySignals Sinais de classificação no nível da consulta para a consulta de pesquisa.
scopeApplied booliano (opcional) true significa que o escopo solicitado foi aplicado, não necessariamente sua definição mais recente. false significa que o escopo não foi aplicado; failOnMissingScope: false permite essa resposta não copiada. Omitido quando o serviço não relata um resultado do aplicativo. Sem scopeName, nenhum escopo nomeado é solicitado; não suponha que o campo esteja presente ou sempre false. Descreve a solicitação atual, não a propagação global.
traceId cadeia ID de correlação para depuração e suporte.

QuerySignals

Field Tipo Description
freshness boolean Indica se novos documentos devem ser priorizados em relação a outros documentos para essa consulta.

AutoEvidenceResult

Field Tipo Description
evidence AutoEvidência Evidência digitada gerada.
citations matriz de AutoEvidenceCitation Citações que dão suporte apenas a esse resultado de evidência.

AutoEvidência

O próprio discriminador do objeto type de evidência seleciona o esquema de content. Use o índice de tipo de evidência para localizar a definição correspondente.

Field Tipo Description
type cadeia Discriminador identificando o esquema de evidências. Os valores diferenciam maiúsculas de minúsculas, por exemplo structured/timeZone.
content cadeia de caracteres ou objeto Texto ou conteúdo estruturado cuja forma depende type.

AutoEvidenceCitation

Os campos de citação variam de acordo com o tipo de resposta e os metadados de origem disponíveis. Nem todos os campos estão presentes em cada citação.

Field Tipo Description
contentSource cadeia Fonte de citação.
source cadeia Nome do site citado.
siteIcon cadeia URL do ícone do site citado.
title cadeia Título da citação.
url cadeia URL de citação.
publishedBy cadeia Publisher do conteúdo citado.
hostPageUrl cadeia URL da página que hospeda o conteúdo citado.
lastUpdatedAt cadeia Carimbo de data/hora atualizado pela última vez.
crawledAt cadeia Carimbo de data/hora de rastreamento.
language cadeia Linguagem de conteúdo.
isAdult boolean Se a citação contém conteúdo adulto. Retornado explicitamente quando true; tratar um campo omitido como false.

Citações específicas de resposta também podem incluir os seguintes metadados:

Field Tipo Aplica-se a Description
observedAt cadeia Weather Carimbo de data/hora de observação fornecido pela origem da citação.

Resposta de exemplo

{
  "results": [
    {
      "evidence": {
        "type": "text",
        "content": "Microsoft announced a new set of AI capabilities."
      },
      "citations": [
        {
          "contentSource": "web",
          "url": "https://www.microsoft.com/en-us/ai",
          "title": "Microsoft AI",
          "language": "en"
        }
      ]
    }
  ],
  "querySignals": { "freshness": true },
  "traceId": "00000000000000000000000000000000"
}

Neste exemplo, isAdult é omitido, portanto, os clientes devem tratá-lo como false.

Tipos de evidência

Use esse índice para pesquisar o esquema de um objeto de content evidência. As categorias de resposta na solicitação responseFilter não são iguais aos discriminadores de evidência na resposta: por exemplo, timezone solicita respostas de fuso horário, enquanto o tipo de evidência retornado é structured/timeZone.

Categoria de resposta Evidência type Definição de conteúdo
web text Evidência de texto: conteúdo da cadeia de caracteres.
news text/news Evidência de texto: conteúdo da cadeia de caracteres com uma miniatura opcional.
images media/image Evidência de imagem: dimensões de imagem, legenda e miniatura.
videos media/video Evidência de vídeo: metadados de reprodução, miniatura e momentos opcionais.
weather structured/weather Objeto meteorológico: condições, previsões, alertas e dados de luz solar.
timezone structured/timeZone Objeto de fuso horário: horários locais, deslocamentos UTC e comparações.

As definições abaixo descrevem campos públicos. Os campos podem ser omitidos quando não disponíveis; um campo omitido não implica uma medida zero ou uma resposta vazia. Os metadados de origem e a atribuição pertencem às citações do resultado delimitador, em vez de um envelope de resposta repetido em cada definição.

Exemplos são fragmentos ilustrativos evidence , não respostas completas. Consulte a resposta de exemplo para a estrutura e citations o delimitamentoresults.

Evidência de texto

For text (Web) and text/news (News), content é uma cadeia de caracteres em vez de um objeto. As evidências de notícias também podem incluir um thumbnail lado content.

Field Tipo Description
content cadeia Evidência de texto para o resultado.
thumbnail objeto (opcional) Miniatura de notícias com url (cadeia de caracteres), width (inteiro) e height (inteiro). As dimensões estão em pixels.
{
  "type": "text/news",
  "content": "An example news summary.",
  "thumbnail": {
    "url": "https://example.com/news-thumbnail.jpg",
    "width": 320,
    "height": 180
  }
}

Evidência de imagem

For media/image, content is an image object. A URL da imagem de origem, a URL da página de hospedagem, o título e as datas de origem são fornecidos nas citações do resultado quando disponíveis.

Campo do conteúdo Tipo Description
caption cadeia Descrição gerada da imagem.
width inteiro Largura da imagem em pixels.
height inteiro Altura da imagem em pixels.
thumbnailUrl cadeia URL da imagem em miniatura.
lastUpdatedAt cadeia Data de origem no formato ISO 8601, quando disponível.
{
  "type": "media/image",
  "content": {
    "caption": "An example city skyline.",
    "width": 1920,
    "height": 1080,
    "thumbnailUrl": "https://example.com/skyline-thumbnail.jpg"
  }
}

Evidência de vídeo

For media/video, content is a video object. Os detalhes da origem, como o título do vídeo, a URL, o publicador e a data de origem, são fornecidos nas citações do resultado quando disponíveis.

Campo do conteúdo Tipo Description
description cadeia Descrição do conteúdo do vídeo.
summary cadeia Resumo curto ou realce do vídeo.
viewCount inteiro Número de exibições de vídeo.
length cadeia Duração do vídeo em HH:MM:SS formato.
allowHttpsEmbedding boolean Se a inserção HTTPS é permitida.
allowMobileEmbedding boolean Se a inserção móvel é permitida.
embeddingUrl cadeia URL para inserir o vídeo.
thumbnailUrl cadeia URL de miniatura de vídeo.
width inteiro Largura do vídeo em pixels.
height inteiro Altura do vídeo em pixels.
lastUpdatedAt cadeia Data de origem no formato ISO 8601, quando disponível.
bestMomentIndex inteiro Índice do melhor momento ou realce, quando disponível.
moments matriz de VideoMoment Segmentos de vídeo, quando disponíveis. A matriz pode estar vazia.
{
  "type": "media/video",
  "content": {
    "viewCount": 1200,
    "length": "00:02:30",
    "thumbnailUrl": "https://example.com/video-thumbnail.jpg",
    "moments": []
  }
}

VideoMoment

Field Tipo Description
title cadeia Título do segmento.
description cadeia Descrição do segmento.
startTime cadeia Hora de início do segmento no d.hh:mm:ss formato.
endTime cadeia Hora de término do segmento no d.hh:mm:ss formato.
momentUrl cadeia Direcionar a URL para o segmento.

Objeto weather

Quando uma consulta é sobre o clima, o Auto pode retornar um structured/weather resultado por local. Os campos são incluídos quando disponíveis. Leia medidas numéricas junto com units; não suponha que um sistema de unidade fixo.

Campo do conteúdo Tipo Description
location cadeia Nome do local, por exemplo Seattle, Washington.
url cadeia URL de atribuição de clima para o local. A mesma URL está na citação do resultado.
units objeto Sistema de unidade (system) e as unidades para temperature, speed, , pressure, distance, heighte time.
alerts matriz de WeatherAlert Alertas meteorológicos ativos ou recentes para o local, filtrados pelo país ou região do usuário.
currentWeather objeto Condições atuais, incluindo condition, dayPeriod, , temperature, feelsLike, universalThermalClimateIndex, humidity, dewPoint, pressure, visibility, , uv, , uvLevel, windSpeed, , windDirection, , windGust, airQualitye observedAt quando disponível.
forecastedWeather matriz de objetos Previsões diárias com validDate, condition, , temperatureHigh, feelsLikeHightemperatureLow, feelsLikeLow, , precipitationChancechuva e quantidades de neve, humidity, day, , nighte almanachourly previsões quando disponíveis.
sunlight objeto Nascer do sol, pôr do sol, nascer da lua, conjunto de luas e fase da lua para uma data específica, quando a consulta pede uma.

A corrente airQuality pode conter index, severitye primaryPollutantvalidAt. Uma previsão humidity diária pode conter high e low. Suas day sub-previsões night podem conter condition, precipitationChancee windSpeedwindDirection. Contém almanac dados de sol e lua para validDate.

{
  "type": "structured/weather",
  "content": {
    "location": "Seattle, Washington",
    "units": {
      "system": "Imperial",
      "temperature": "F"
    },
    "currentWeather": {
      "condition": "Cloudy",
      "temperature": 50
    }
  }
}

WeatherAlert

Field Tipo Description
id cadeia Identificador de alerta do provedor, quando disponível.
name cadeia Nome do evento meteorológico, por exemplo Frost.
severity cadeia Severidade, por exemplo Advisory, Watchou Warning.
status cadeia Status do alerta, por exemplo Ongoing.
issuingAuthority cadeia Organização que emitiu o alerta, por exemplo National Weather Service.
url cadeia Link para a autoridade emissora. Incluído quando a origem o fornece.
description cadeia Descrição do perigo e área afetada.
safetyGuidance cadeia Ações de segurança recomendadas, quando disponíveis.
issuedAt effectiveAt expiresAt cadeia Quando o alerta foi emitido, entra em vigor e expira.

Objeto de fuso horário

Para structured/timeZone, content descreve os horários locais ou compara dois fusos horários. Uma pesquisa de local pode retornartimeZones; uma comparação pode, em vez disso, retornar startTimeZonee endTimeZonetimeDifference. Não exija todos esses campos em todas as respostas.

Campo do conteúdo Tipo Description
description cadeia Resumo da resposta legível por humanos, quando disponível.
timeZones matriz de TimeZoneEntry Entradas para uma resposta de hora de local único ou de vários locais.
startTimeZone TimeZoneEntry Fuso horário de origem para uma comparação.
endTimeZone TimeZoneEntry Fuso horário de destino para uma comparação.
timeDifference cadeia Descrição de diferença de tempo legível para uma comparação.
{
  "type": "structured/timeZone",
  "content": {
    "timeZones": [
      {
        "timeZoneName": "Pacific Standard Time",
        "timeZoneAbbreviation": "PST",
        "location": "Seattle, Washington",
        "utcOffset": -8,
        "utcTime": "Monday, 2026-11-16T05:00:00Z",
        "localTime": "Sunday, 2026-11-15T21:00:00-08:00"
      }
    ]
  }
}

TimeZoneEntry

Field Tipo Description
timeZoneName cadeia Nome do fuso horário completo.
timeZoneAbbreviation cadeia Abreviação, por exemplo PST ou IST.
location cadeia Cidade, país ou região associada à entrada.
utcOffset número Deslocamento UTC em horas. Pode ser fracionário, por exemplo 5.5, ou omitido quando não disponível.
utcTime cadeia Hora UTC como uma cadeia de caracteres formatada.
localTime cadeia Hora local como uma cadeia de caracteres formatada.

As cadeias de caracteres de tempo podem incluir um prefixo de dia da semana; não suponha que sejam carimbos de data/hora ISO 8601.

Códigos de erro

Código de status Description
200 A solicitação foi bem-sucedida, incluindo uma pesquisa válida sem resultados.
400 Parâmetros inválidos ou JSON malformado.
401 Credenciais de autenticação ausentes ou inválidas.
403 O IQ AppID da Web autenticado não está habilitado para Auto.
429 Taxa ou limite de cota excedido.
500 Falha de serviço interno.
503 Um serviço necessário não está disponível.
504 A solicitação atingiu o tempo limite.

Para obter o esquema de erro compartilhado e as diretrizes de repetição, consulte Tratamento de erro.