Skip to main content

​
Overview

ChatAds can analyze product images and return affiliate links, just like it does with text messages. Pass an image URL or a base64-encoded image file, and ChatAds will identify the product and find matching affiliate offers.
Product card carousel showing shoppable items with prices and Shop buttons below an AI-generated interior design image
Semantic image similarity isn’t perfect and can return close, but not perfect responses. Additionally, if the image has multiple products, it’ll be hard for the AI to know what to extract.

​
How It Works

  1. You send a request with input_type set to image_url or image_file
  2. The message field contains the image URL (for image_url) or the base64-encoded image data (for image_file)
  3. ChatAds processes the image to identify the product and return relevant offers with title and URL
  4. Matching affiliate offers are returned in the standard response format
Image requests are billed at 3x the cost per request as text. For instance, if text ads are 0.90 per thousand requests, image requests would be 2.70 per thousand. Image handling requires more bandwidth and is priced accordingly.

​
Parameters

Set input_type to image_url or image_file and pass the image in message. See the API Reference for the full list of parameters.
Use image_title_filter when an image contains multiple products. For example, a desk setup image might include a monitor, keyboard, and mouse — passing image_title_filter: "monitor" ensures only monitor results are returned.

​
Latency

On average, image requests return results in 3-4 seconds.

​
Usage

​
Image URL

Pass a publicly accessible image URL in the message field. The API automatically normalizes URLs — if no scheme is provided (e.g., example.com/photo.jpg), https:// is prepended. Invalid or malformed URLs return a 400 INVALID_INPUT error. 
curl -X POST 'https://api.getchatads.com/v1/chatads/messages' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "message": "https://example.com/product-photo.jpg",
    "input_type": "image_url"
  }'

​
Image File (Base64)

Value must be a base64-encoded JPEG/PNG/WebP, max 10MB. Auto-resized if longest dimension exceeds 1500px. Don’t recommend using API explorer for this.
Try to send images no smaller than 500px in width and no wider than 2000px. We resize to 1500px no matter what, but bigger files can slow down the request.
Pass the raw base64-encoded image data in the message field: 
import { readFileSync } from 'fs';

const imageBase64 = readFileSync('product.jpg', 'base64');
const response = await client.analyze({
  message: imageBase64,
  input_type: "image_file",
});

​
Response

Image requests return up to 3 offers per request, which can be useful for building a carousel format. Each offer includes a product.title, product.image, and affiliate url: 
{
  "data": {
    "status": "filled",
    "offers": [
      {
        "link_text": "",
        "url": "https://www.amazon.com/dp/B09ZGYK6TW/?tag=yourtag-20",
        "product": {
          "title": "The Basket Lady Tall Rectangular Wicker Storage Basket...",
          "image": "https://m.media-amazon.com/images/I/71d1SfodL8L._AC_UF894,1000_QL80_.jpg"
        },
        "offer_source": "Amazon.com"
      },
      {
        "link_text": "",
        "url": "https://www.amazon.com/dp/B0BX9MHKMQ/?tag=yourtag-20",
        "product": {
          "title": "AELS Woven Natural Fibre Magazine Holder...",
          "image": "https://m.media-amazon.com/images/I/8144Ee54nTL.jpg"
        },
        "offer_source": "Amazon.com"
      },
      {
        "link_text": "",
        "url": "https://www.amazon.com/dp/B0D6B8LS2Y/?tag=yourtag-20",
        "product": {
          "title": "Plastic Wicker Baskets for Cube Storage, Set of 3...",
          "image": "https://m.media-amazon.com/images/I/916YeR6yz2L._AC_UF894,1000_QL80_.jpg"
        },
        "offer_source": "Amazon.com"
      }
    ],
    "requested": 3,
    "returned": 3,
    "billed": true
  },
  "error": null,
  "meta": {
    "request_id": "66fea920-6c02-4979-b07d-93914728eeb9",
    "timestamp": "2026-03-09T13:28:28.046029758Z",
    "version": "1.0.0",
    "usage": {
      "monthly_requests": 16,
      "is_free_tier": false,
      "daily_requests": 5,
      "daily_limit": 10000
    }
  }
}

​
Billing

Image requests are billed at 3x the cost of text requests. They count toward your monthly and daily request quotas the same as text, but each image request costs 3 standard requests for billing purposes.

​
Limitations

  • Image URL must be publicly accessible (no authentication required)
  • Image file must be base64-encoded JPEG/PNG/WebP, max 10MB (auto-resized if longest dimension exceeds 1500px)
  • extraction_mode, resolution_mode, and language detection are not applicable for image requests
  • Country and IP-based targeting still apply normally

​
Next Steps

API Reference

Full endpoint documentation

SDK Examples

Image search examples in TypeScript and Python