> ## Documentation Index > Fetch the complete documentation index at: https://docs.glood.ai/llms.txt > Use this file to discover all available pages before exploring further. # Image Search > Visual (image) search. Accepts a multipart file OR a JSON base64 image / data: URL / http(s) image URL (exactly one source). Images are strictly validated before search. Auth: `Authorization: Bearer ` + `x-shop`. ```json 200 theme={null} { "status": "ok", "products": [ { "product_id": 9311227838783, "title": "Running Shoe", "handle": "running-shoe", "product_type": "Shoes", "vendor": "Acme", "tags": ["sale", "summer"], "price": 49.99, "compare_at_price": 69.99, "display_price": 49.99, "display_compare_at_price": 69.99, "display_currency": "USD", "original_currency": "USD", "currency_rate": 1, "available_for_sale": true, "is_in_stock": true, "total_inventory": 42, "image": { "id": "gid://shopify/ProductImage/1", "url": "https://cdn.shopify.com/s/files/1/shoe.jpg", "width": 800, "height": 800, "alt_text": "Running Shoe" }, "featured_media": null, "media": [], "options": [ { "id": 111, "name": "Size", "position": 1, "values": ["S", "M", "L"] } ], "variants": [], "metafields": [] } ], "pagination": { "total": 60, "page": 1, "limit": 20, "total_pages": 3, "has_next_page": true, "has_prev_page": false }, "search_metadata": { "processing_time": 340, "search_type": "image_vector", "image_analysis": null, "image_caption": "a red running shoe", "search_text": "red running shoe", "has_embedding": true, "errors": [], "dominant_colors": ["#ff0000"] } } ``` ```json 400 - invalid image theme={null} { "error": "Image must be one of jpeg, png, webp" } ``` ## OpenAPI ````yaml POST /api/storefront/v1/headless/image-search openapi: 3.0.1 info: title: Glood.AI API Reference description: Glood.AI API Reference license: name: MIT version: 1.0.0 servers: - url: https://storefront.glood.ai security: - bearerAuth: [] paths: /api/storefront/v1/headless/image-search: servers: - url: https://search.glood.ai post: description: >- Visual (image) search. Accepts a multipart file OR a JSON base64 image / data: URL / http(s) image URL (exactly one source). Images are strictly validated before search. Auth: `Authorization: Bearer ` + `x-shop`. parameters: - name: x-shop in: header description: >- Shopify store URL. Resolves the shop for the request (headless does not accept `?shop=`). required: true schema: type: string example: shop.myshopify.com requestBody: description: Request body content: application/json: schema: $ref: '#/components/schemas/HeadlessImageSearchRequest' multipart/form-data: schema: $ref: '#/components/schemas/HeadlessImageSearchRequest' responses: '200': description: Image search results content: application/json: schema: $ref: '#/components/schemas/HeadlessImageSearchResponse' '400': description: Validation or shop error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: HeadlessImageSearchRequest: type: object description: >- Visual (image) search. Accepts a multipart file, a base64 image, a data: URL, or an http(s) image URL. Images are strictly validated (jpeg/png/webp, 1KB-5MB, 100x100 to 4096x4096) before search. properties: image: type: string description: >- Raw base64 OR a `data:` URL. Exactly one of `image` / `image_url` is required. (Also accepted as a multipart `image` file upload.) image_url: type: string description: >- An http(s) image URL (fetched server-side, SSRF-guarded) OR a `data:` base64 URL. Exactly one of `image` / `image_url` is required. facets: oneOf: - type: object - type: array items: type: object description: Applied filters (object or array form). locale: type: string description: BCP-47 locale. default: en market: type: integer description: Shopify market id. view: type: string description: Product render mode. enum: - product_details - product_ids default: product_details pagination: type: object description: Page-based pagination. properties: page: type: integer description: 1-based page number. minimum: 1 default: 1 limit: type: integer description: Page size. minimum: 1 maximum: 100 default: 20 visitor_id: type: string description: >- Anonymous device/browser UID (the `gl_s_uid` cookie). The primary personalization key; stays stable when a customer logs in. client_id: type: string description: Per-session / per-device identifier. customer_id: type: string description: >- Shopify customer id. Present only when the shopper is logged in; enables customer-level personalization. HeadlessImageSearchResponse: type: object description: Visual search results with pagination and image-analysis metadata. properties: status: type: string description: Response status. example: ok products: type: array description: Product objects (or `{ product_id }` when `view=product_ids`). items: $ref: '#/components/schemas/HeadlessProduct' pagination: type: object description: Page-based pagination. properties: total: type: integer description: Total matching products. page: type: integer description: Current page. limit: type: integer description: Page size. total_pages: type: integer description: Total pages. has_next_page: type: boolean description: Whether a next page exists. has_prev_page: type: boolean description: Whether a previous page exists. search_metadata: type: object description: Image-search diagnostics. properties: processing_time: type: integer description: Total processing time in ms. search_type: type: string description: Engine used. example: image_vector image_analysis: type: object nullable: true description: Structured analysis of the input image, if available. image_caption: type: string nullable: true description: Generated caption for the input image. search_text: type: string nullable: true description: Text derived from the image and used for search. has_embedding: type: boolean nullable: true description: Whether an image embedding was produced. errors: type: array description: Non-fatal processing errors. items: type: object dominant_colors: type: array description: Dominant colors detected in the image. items: type: string example: - '#ff0000' Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string HeadlessProduct: type: object properties: product_id: type: integer description: Unique identifier of the product title: type: string description: Title of the product price: type: number description: Minimum variant price for the product tags: oneOf: - type: string - type: array items: type: string description: >- Product tags. Recommendations return a comma-separated string; search returns an array of strings. product_type: type: string description: Type/category of the product vendor: type: string description: Vendor/brand of the product image: type: object properties: id: type: string url: type: string height: type: integer width: type: integer altText: type: string handle: type: string description: URL handle/slug for the product compare_at_price: type: number description: Original/compare-at price of the product options: type: array items: type: object properties: id: type: integer name: type: string description: Option name (e.g. Size, Color) values: type: array items: type: string position: type: integer variants: type: array items: $ref: '#/components/schemas/HeadlessProductVariant' metafields: oneOf: - type: object description: Key-value map (recommendations). - type: array items: type: object description: A metafield. properties: namespace: type: string description: Metafield namespace. key: type: string description: Metafield key. value: type: string description: Metafield value. description: >- Product metafields. Recommendations return a key-value map; search returns a list of `{ namespace, key, value }`. display_price: type: number nullable: true description: >- Currency-converted price for the requested market (search). Falls back to `price`. display_compare_at_price: type: number nullable: true description: Currency-converted compare-at price for the market (search). display_currency: type: string description: Currency code the display prices are expressed in (search). original_currency: type: string description: Shop's original currency code (search). currency_rate: type: number description: Conversion rate applied to derive display prices (search). available_for_sale: type: boolean description: Whether the product has any variant available for sale (search). is_in_stock: type: boolean description: Whether the product has any in-stock variant (search). total_inventory: type: integer nullable: true description: Total inventory across variants (search). featured_media: type: object nullable: true description: Featured media object (search). media: type: array description: Product media objects (search). items: type: object HeadlessProductVariant: type: object properties: variant_id: type: integer description: Unique identifier of the variant title: type: string description: Title of the variant display_name: type: string description: Human-readable display name of the variant position: type: integer description: Display order position of the variant sku: type: string description: Stock keeping unit identifier selected_options: type: array items: type: object properties: name: type: string description: Option name value: type: string description: Selected value price: oneOf: - type: string - type: number nullable: true description: >- Variant price. Recommendations return a decimal string; search returns a number. compare_at_price: oneOf: - type: string - type: number nullable: true description: >- Variant compare-at price. String (recommendations) or number (search); null when unset. image: type: object properties: id: type: string url: type: string height: type: integer width: type: integer altText: type: string sellable_online_quantity: type: integer description: Quantity available for online sale is_in_stock: type: boolean description: Whether the variant is currently in stock available_for_sale: type: boolean description: Whether the variant is available for purchase securitySchemes: bearerAuth: type: http scheme: bearer ````