Batch-Tagging Product Photos with a Vision Model on the Aggregator

Why Use a Vision Model for Product Tagging?

Manual tagging of product photos is slow and error-prone. A vision-capable model can automatically generate structured tags—such as color, category, material, and style—from each image. By using an API aggregator, you access multiple vision models (e.g., Claude, GPT, DeepSeek) with one API key and a unified billing system, simplifying integration and cost tracking.

Pipeline Overview

A throughput-oriented pipeline has four stages:

1. Image Collection: Gather image URLs or binary data from your source (e.g., database, CSV).
2. Request Dispatch: Send each image to the vision model with a prompt requesting structured tags (e.g., JSON).
3. Concurrency Management: Control the number of simultaneous requests to stay within rate limits and avoid overwhelming the API.
4. Result Aggregation: Collect responses, parse tags, and store them alongside image metadata.

Concurrency Caps and Throughput

Vision models often have rate limits (requests per minute or tokens per minute). The aggregator abstracts provider-specific limits, but you still need to manage concurrency to maximize throughput without hitting errors.

• Start conservative: Begin with a small number of concurrent requests (e.g., 5–10) and monitor for rate-limit errors.
• Use exponential backoff: On 429 (Too Many Requests) responses, retry with increasing delays.
• Implement a queue: A worker pool with a bounded queue lets you control concurrency and handle bursts.
• Consider batch endpoints: Some providers offer batch processing at lower cost, but this may increase latency. Check if the aggregator supports batch requests.
• Monitor and adjust: Track success rate and latency; increase concurrency gradually until you see diminishing returns or errors.

The goal is to keep the pipeline saturated without triggering throttling. The aggregator's unified API means you can switch models if one is rate-limited, but each model may have different limits.

Cost Calculation

Costs depend on the model and the number of tokens (input + output). For vision models, input tokens include image tokens, which vary by resolution and model. The aggregator charges official price × 1.3 for usage. Key contributors receive credits at official price × 1.1 (or × 1.2 for premium models).

To estimate per-image cost:

1. Determine the average token count per image for your chosen model (refer to provider docs).
2. Multiply by the model's official price per token.
3. Apply the aggregator's multiplier (× 1.3).

For example, if an image costs $0.001 in official tokens, you pay $0.0013. If you are a key contributor, you receive credits worth $0.0011 (or $0.0012) per image processed.

Tip: Resize images to the minimum resolution that still yields accurate tags. Smaller images use fewer tokens and reduce cost.

Implementation Steps

1. Set up your API key: Obtain an API key from the aggregator and top up with USDC on Base (no KYC).
2. Prepare your images: Ensure images are accessible via URL or can be sent as base64. Optimize file size.
3. Craft a prompt: Request tags in a structured format, e.g., Return a JSON object with keys: category, color, material, style.
4. Build a worker pool: Use a library like concurrent.futures in Python or async with aiohttp to manage concurrency.
5. Handle errors: Implement retries for transient failures and log permanent errors.
6. Parse and store tags: Extract the JSON from the response and save it to your database.

Example Code Snippet (Python)

import asyncio
import aiohttp
from aiohttp import ClientSession

API_KEY = "your_api_key"
ENDPOINT = "https://api.aggregator.com/v1/chat/completions"
MODEL = "claude-3-vision"  # example

async def tag_image(session, image_url):
    payload = {
        "model": MODEL,
        "messages": [
            {"role": "user", "content": [
                {"type": "text", "text": "Return a JSON object with keys: category, color, material, style."},
                {"type": "image_url", "image_url": {"url": image_url}}
            ]}
        ]
    }
    async with session.post(ENDPOINT, json=payload, headers={"Authorization": f"Bearer {API_KEY}"}) as resp:
        return await resp.json()

async def main(image_urls):
    async with ClientSession() as session:
        tasks = [tag_image(session, url) for url in image_urls]
        results = await asyncio.gather(*tasks, return_exceptions=True)
        # process results

# run with concurrency limit using asyncio.Semaphore

Adjust the semaphore value to control concurrency.

Monitoring and Optimization

• Track cost per image: Log token usage from responses to refine estimates.
• A/B test models: Different models may offer better accuracy or lower cost for your product types.
• Cache results: If images are re-processed, cache tags to avoid duplicate charges.
• Use batch inference: If the aggregator supports it, batch multiple images in one request (if the model allows) to reduce overhead.

By following these practices, you can build a scalable, cost-effective pipeline for tagging thousands of product photos.