Integrate Vetrinà's Image API in 5 Steps

This prompt is pre-filled with your current configuration. Paste it into Claude (or any AI assistant) and it will generate production-ready integration code for your codebase.

You are implementing an integration with the Vetrinà Image Generation API in our codebase.

## API Overview
- **Endpoint**: POST https://vetrina.stocka.it/api/v1/generate
- **Auth**: Header "x-api-key: YOUR_API_KEY" (create at https://vetrina.stocka.it/settings/api — requires Creator or Agency plan)
- **Content-Type**: application/json
- **Response time**: ~2-5 seconds (synchronous)

## Request Body
```json
{
  "templateKey": "super-prezzo",
  "formatKey": "ig-45",
  "product": {
    "imageUrl": "https://example.com/product.jpg",
    "name": "Wireless Headphones"
  },
  "pricing": {
    "price": 49.9,
    "originalPrice": 89.9
  },
  "mode": "final",
  "delivery": "signed_url",
  "market": "IT",
  "adLanguage": "it"
}
```

## Field Reference
- **templateKey** (required): One of "super-prezzo", "sconto-barrato", "nuovo-arrivo" (predefined templates) or "tpl_<uuid>" (marketplace template)
- **formatKey** (default: "ig-45"): One of "ig-45" (1080×1350, Instagram 4:5), "ig-story" (1080×1920, Story 9:16), "square" (1080×1080, 1:1), "pinterest" (1080×1620, 2:3)
- **mode** (default: "final"): "preview" returns a low quality inline base64 PNG with Vetrinà watermark and does not create generations, consume quota, or debit wallet. "final" generates the high quality output.
- **product.imageUrl** (required): Public HTTPS URL of the product photo, or an asset path returned by POST /api/v1/upload
- **removeBg** (optional): best-effort AI background removal. If it fails, the original photo is used and the response includes warnings.
- **product.name** (optional, max 60 chars): Product display name
- **pricing.price** (required, positive number): Current price
- **pricing.originalPrice** (optional, must be > price): Strikethrough price — activates discount % and Omnibus legal text
- **pricing.lowestPrice30d** (optional, requires originalPrice): Lowest price in last 30 days (EU Omnibus directive)
- **pricing.unitPrice** + **pricing.unitPriceUnit** (optional, both required together): Unit price for food products (e.g. 9.98, "kg")
- **pricing.currency** (default: "EUR"): ISO 4217 currency code
- **badgeText** (optional, max 24 chars): Custom badge text (e.g. "ULTIMI PEZZI")
- **validUntil** (optional, "YYYY-MM-DD"): Offer expiry date — printed on image and in caption
- **delivery** (default: "signed_url"): "signed_url" (24h temporary URL), "inline_base64" (base64 PNG in response), "both"
- **market** (default: "IT"): ISO 3166-1 alpha-2 market code — determines legal regime, currency, date/number formats
- **adLanguage** (default: "it"): Language for legal text and caption — one of: it, en, de, fr, es, nl, pt, pl
- **formats** (optional, array): Kit Social — generate multiple formats in one request (e.g. ["ig-45","ig-story","square"]). Each format consumes 1 quota in mode="final" and 0 quota in mode="preview". Response shape changes to { kit: true, images: [...], caption, durationMs }
- **layoutChoices** (optional): { badgePos: "tr"|"tl", logoPos: "left"|"right" }
- **colorOverrides** (optional): Override brand colors for this image only (primary, primaryDark, accent, badge, ink, paper, paperSoft as hex)

## Response (single format, HTTP 200)
```json
{
  "id": "uuid",
  "url": "https://...signed-url...",
  "asset": {
    "signedUrl": "https://...signed-url...",
    "expiresAt": "2026-06-28T12:00:00Z",
    "contentType": "image/png",
    "width": 1080,
    "height": 1350
  },
  "caption": "🔥 Friggitrice ad aria 5,5 L — 49,90€ invece di 89,90€...",
  "width": 1080,
  "height": 1350,
  "durationMs": 2100
}
```

## Response (Kit Social with formats[], HTTP 200)
```json
{
  "kit": true,
  "images": [
    { "id": "uuid", "formatKey": "ig-45", "url": "...", "asset": {...}, "width": 1080, "height": 1350, "durationMs": 2100 },
    { "id": "uuid", "formatKey": "ig-story", "url": "...", "asset": {...}, "width": 1080, "height": 1920, "durationMs": 1800 }
  ],
  "caption": "...",
  "durationMs": 3900
}
```

## Error Codes
- **401**: Unauthorized — missing or invalid API key
- **402**: Quota exceeded (free plan = 10 images per month) or insufficient wallet balance (marketplace templates). Code: "upgrade_required" or "insufficient_wallet_balance"
- **403**: Forbidden — e.g. Agency plan required for brandKitId, or template agreement required for marketplace templates
- **422**: Validation error — details in response body
- **429**: Rate limited — respect the "Retry-After" header (seconds). Limits: 30 generate/min, 3 batch/min, 60 upload/min per organization
- **500**: Generation failed — error message in response body

## Rate Limits
- 30 generate requests / minute (per organization)
- 3 batch requests / minute
- 60 upload requests / minute
- On 429: wait "Retry-After" seconds, then retry

## Quota
- Free plan: 10 images per month (then 402 upgrade_required)
- Creator (€9.90/mo) or Agency (€39/mo): unlimited
- Each format in a Kit Social request consumes 1 generation

## Batch (for catalogs)
- POST /api/v1/batch with { items: [...], webhookUrl?, webhookSecret? }
- Returns 202 with { batchId, total, statusUrl }
- Poll GET /api/v1/batch/{id} or receive webhook POST with header "x-vetrina-signature: sha256=<HMAC-SHA256 of body with webhookSecret>"
- Max 50 items per batch. Requires Creator plan.

## Upload (for binary images)
- POST /api/v1/upload (multipart/form-data, field: "file")
- Accepts PNG, JPG, WEBP up to 10MB
- Optional: removeBg=true for AI background removal. If removal fails, the API still returns 200, uses the original photo, and includes a non-blocking warning.
- Returns { id, url, width, height, bgRemoved, warning?, warnings? } — use the "url" as product.imageUrl

## Task
Implement a function/module that:
1. Takes product data (name, price, optional original price, image URL or file path) as input
2. Calls POST /api/v1/generate with the request body shown above
3. Handles all error codes with appropriate exceptions/messages
4. Retries on 429 with exponential backoff (respecting Retry-After header)
5. Returns the generated image URL (signedUrl) and caption
6. If the image is a local file, upload it first via POST /api/v1/upload, then use the returned URL

Use the configuration values from the request body above as defaults. Make the code production-ready with proper error handling, logging, and type safety.