Referencia de la API REST de Image Search

Punto final:POST https://api.microsoft.ai/v3/search/images

Solicitud de ejemplo:

curl -X POST "https://api.microsoft.ai/v3/search/images" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H 'content-type: application/json' \
  -d '{
    "query": "cats",
    "maxResults": 2,
    "language": "en",
    "region": "US"
  }'

Parameters

Parámetro Required Tipo Default Description
query Sí string - Cadena de consulta de búsqueda. La longitud máxima es de 1000 caracteres.
maxResults No integer 30 Número máximo de resultados que se van a devolver. El valor predeterminado es 30 y el valor máximo es 30.
language No string "en" Código de idioma ISO 639-1 de 2 letras para el idioma de la interfaz en los resultados de la búsqueda. Consulte Idiomas admitidos para obtener la lista completa.
region No string "US" Código de país o región de 2 letras para el que deben proceder los resultados (por ejemplo, "US", "JP", "CN"). Consulte Regiones admitidas para obtener la lista completa.
aspectRatio No string(enum) - Filtre las imágenes por relación de aspecto. Valores: "cuadrado" (aproximadamente 1:1), "ancho" (alto de ancho > ), "alto" ( > ancho alto). Cuando no se establece, no se aplica ningún filtrado.
color No string(enum) - Filtrar imágenes por color de imagen. Valores: "colorOnly" (solo devuelven imágenes de color), "monocromo" (solo devuelven imágenes blancas y negras). Cuando no se establece, no se aplica ningún filtrado.
safeSearch No string(enum) "strict" Nivel de filtrado de búsqueda segura. Valores: "off", "strict". El valor predeterminado es "strict".
imageSize No string(enum) - Filtrar imágenes por categoría de tamaño. Valores: "small" (200x200px), "medium" (width or height 200-500px), "large" (<width or height >=500px), "extraLarge" (>1024x768px). También puede usar restricciones de píxeles (maxHeight, minHeight, maxWidth, minWidth) para límites personalizados; Las restricciones de píxeles tienen prioridad sobre imageSize cuando entran en conflicto. Cuando no se establece, no se aplica ningún filtrado.
watermarkFree No booleano falso Excluir imágenes con marca de agua. El valor predeterminado es falso.
maxHeight No integer - Alto máximo de la imagen en píxeles. Se usa con imageSize para límites personalizados.
minHeight No integer - Altura mínima de la imagen en píxeles.
maxWidth No integer - Ancho máximo de la imagen en píxeles.
minWidth No integer - Ancho mínimo de la imagen en píxeles.

Encabezados de solicitud

Field Tipo Description
host string Host para las API de IA de Microsoft: api.microsoft.ai.
x-apikey o Authorization string La clave de API o Entra ID token de acceso para la autenticación.
content-type (tipo de contenido) string Tipo MIME del cuerpo de la solicitud. Utilice application/json.

Respuesta

ImagesResponse

Field Tipo Description
imageResults matriz de ImageResult Lista de resultados de la imagen.
instrumentationClickBase string Dirección URL base para hacer clic en solicitudes de ping. Anexe un instrumentationSuffix valor de un elemento de resultado para formar la dirección URL de ping completa. Solo está presente para las aplicaciones con la marca de perfil EnableInstrumentationPing. Nota: Los clics de usuario también se pueden registrar mediante el redireccionamiento de direcciones URL. Cuando la redirección está habilitada, no se requiere ninguna acción para registrar los clics del usuario y instrumentationClickBase no se incluirá en la respuesta. Consulte la guía de instrumentación para obtener instrucciones de configuración.
instrumentationCitationBase string Dirección URL base para las solicitudes de ping de registro de LLM. Anexe una carga DE DATOS para formar la dirección URL de ping completa. Solo está presente para las aplicaciones con la marca de perfil EnableInstrumentationPing.
traceId string Identificador de seguimiento para la depuración y el seguimiento.

ImageResult

Field Tipo Description
title string Título de la imagen.
url string Dirección URL de origen de la imagen. Para los usuarios de China con redirección de direcciones URL habilitadas, este campo contiene la misma dirección URL de redireccionamiento que clickUrl.
domain string Host de destino para el resultado. Solo se devuelve para los usuarios de China con el redireccionamiento de direcciones URL habilitado.
hostPageUrl string Dirección URL de la página web que hospeda la imagen.
caption string Descripción generada de la imagen.
width integer Ancho de la imagen, en píxeles.
height integer Alto de la imagen, en píxeles.
thumbnailUrl string Dirección URL de origen de miniatura de la imagen.
lastUpdatedAt string La última fecha actualizada de la imagen sigue ISO8601 formato.
isAdult booleano Indica si el contenido es contenido para adultos.
clickUrl string Url de redirección que proxie el clic a través de Bing. Solo está presente cuando el redireccionamiento de clics está habilitado.
instrumentationSuffix string Sufijo que se va a anexar a la base de dirección URL de ping de instrumentación para este elemento de resultado. Se usa como valor K para la dirección URL de ping de instrumentación y el clickUrl redireccionamiento. Presente cuando el ping de instrumentación está habilitado.

Códigos de error

Código de estado Categoría de error Description Causas comunes
200 Success La solicitud tuvo éxito. -
400 Solicitud incorrecta Parámetros de solicitud no válidos. Faltan campos obligatorios, valores de parámetro no válidos, JSON con formato incorrecto
401 Unauthorized Error de autenticación o falta. Clave de API no válida, falta el encabezado x-apikey
403 Prohibida Credenciales válidas pero permisos insuficientes. La clave de API carece de permisos necesarios
410 Pasado (Gone) SE requiere HTTPS. Solicitud realizada a través de HTTP en lugar de HTTPS
415 Tipo de medio no admitido No se admite el tipo de contenido. Falta o falta un encabezado de tipo de contenido incorrecto
429 Demasiadas solicitudes Se superó el límite de velocidad. Demasiadas solicitudes en el período de tiempo
500 Error interno del servidor Error inesperado del servidor. Problema de servidor temporal
503 Servicio no disponible El servicio no está disponible temporalmente. Interrupción temporal o mantenimiento
504 Tiempo de espera de puerta de enlace Se ha agotado el tiempo de espera para la solicitud. Tiempo de espera del servicio ascendente

Para obtener instrucciones detalladas sobre el control de errores, consulte Control de errores.

Consulte también:Web Search | Videos Search | | | MCP

  • Se actualizó por última vez el