Python SDK

pip install chatads-sdk

from chatads_sdk import ChatAdsClient

# Use context manager for automatic cleanup
with ChatAdsClient(api_key="cak_your_api_key") as client:
    response = client.analyze_message(
        message="The Bose QuietComfort Ultra earbuds are great for commuting. They have solid noise cancellation and a comfortable fit. Battery life is around six hours, which is enough for most people.",
        country="US"
    )

    if response.error is None and response.data and response.data.returned > 0:
        # Access first offer
        offer = response.data.offers[0]
        print(f"link_text: {offer.link_text}")
        print(f"url: {offer.url}")

        # Or iterate all offers
        for i, offer in enumerate(response.data.offers):
            print(f"Offer {i + 1}: {offer.link_text} - {offer.url}")

from chatads_sdk import ChatAdsClient

# Basic usage with context manager (recommended)
with ChatAdsClient(
    api_key="cak_your_api_key",          # Required
    base_url="https://...",               # Optional: custom API URL
    raise_on_failure=True,                # Optional: raise exceptions on API errors
    max_retries=2,                        # Optional: retry failed requests
    retry_backoff_factor=0.75,            # Optional: backoff multiplier between retries
    debug=False,                          # Optional: enable debug logging
) as client:
    # Use client here
    pass

response = client.analyze_message(
    message="Looking for a good yoga mat",
    country="US",
    extraction_mode="fast",     # "none" | "fast" | "standard" (default)
    resolution_mode="standard", # "none" | "standard" (default)
)

# Analyze a product image by URL
response = client.analyze_message(
    message="https://example.com/product-image.jpg",
    input_type="image_url",
    image_title_filter="desk",  # Filter results to only desk products
)

import os
from chatads_sdk import ChatAdsClient

with ChatAdsClient(api_key=os.environ["CHATADS_API_KEY"]) as client:
    response = client.analyze_message(message="...")

export CHATADS_API_KEY=cak_your_api_key

import asyncio
from chatads_sdk import AsyncChatAdsClient, FunctionItemPayload

async def main():
    async with AsyncChatAdsClient(
        api_key="cak_your_api_key",
        max_retries=3,
        debug=True,
    ) as client:
        # Using analyze_message shorthand
        result = await client.analyze_message(
            message="Need data warehousing ideas",
            country="US",
            ip="1.2.3.4",
        )

        print(result.raw)

        # Or using FunctionItemPayload for full control
        payload = FunctionItemPayload(
            message="Best standing desk for home office",
            country="US",
        )
        result = await client.analyze(payload)

        if result.error is None and result.data.returned > 0:
            print(f"Found: {result.data.offers[0].link_text}")

asyncio.run(main())

import asyncio
from chatads_sdk import AsyncChatAdsClient

async def analyze_batch(messages: list[str]):
    async with AsyncChatAdsClient(api_key="cak_your_api_key") as client:
        tasks = [
            client.analyze_message(message=msg, country="US")
            for msg in messages
        ]
        results = await asyncio.gather(*tasks)
        return results

# Usage
messages = [
    "Best noise-cancelling headphones",
    "Top rated standing desks",
    "Ergonomic office chairs",
]
results = asyncio.run(analyze_batch(messages))