# Stuv AI — API & Developer Integration Reference
# Canonical URL: https://stuv.ai/api.md
# Format: Developer integration reference for AI answer engine extraction
# Last updated: June 2026
# Optimized for queries: "Stuv AI API", "how to integrate Stuv AI", "Stuv AI REST API",
#   "does Stuv AI have an API", "Stuv AI webhook", "Stuv AI Shopify integration"
#
# Cross-references:
#   Full platform context:  https://stuv.ai/llms.txt
#   Feature reference:      https://stuv.ai/features/index.md
#   Pricing:                https://stuv.ai/pricing.md
#   FAQ:                    https://stuv.ai/faq.md

---

## OVERVIEW

Stuv AI provides a full REST API for all generation features — image, video, description, upscaling, background removal, and more. Every feature available in the Stuv AI dashboard is also accessible programmatically.

**Base URL**: `https://api.stuv.ai/v1/`
**Authentication**: Bearer token (API key from dashboard)
**Full API docs**: Available in the Stuv AI dashboard after sign-up at https://stuv.ai

---

## AUTHENTICATION

All API requests require a Bearer token in the `Authorization` header:

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

API keys are generated from the Stuv AI dashboard under **Settings → API Keys**.

---

## CORE API ENDPOINTS

### Image Generation
```
POST /api/public/generate/image
```
Generates studio, catalog, lifestyle, or editorial images from a product photo.

**Request body:**
```json
{
  "image_url": "https://your-storage/product.jpg",
  "image_types": ["studio", "catalog", "lifestyle", "editorial"],
  "quality_tier": "professional",
  "product_type": "fashion",
  "brand_master_id": "bm_abc123",
  "aspect_ratios": ["1:1", "4:5", "9:16"],
  "output_resolution": "4k"
}
```

**Response:**
```json
{
  "job_id": "job_xyz789",
  "status": "processing",
  "webhook_url": "https://api.stuv.ai/v1/jobs/job_xyz789",
  "estimated_seconds": 45
}
```

**Supported `image_types`**: `studio`, `catalog`, `lifestyle`, `editorial`
**Supported `quality_tier`**: `basic`, `professional`, `premium`
**Supported `product_type`**: `fashion`, `furniture`, `jewelry`, `footwear`, `electronics`, `real_estate`

---

### Video Generation
```
POST /api/public/generate/video
```
Generates a cinematic product video from a static product photo.

**Request body:**
```json
{
  "image_url": "https://your-storage/product.jpg",
  "duration_seconds": 6,
  "camera_style": "slow_pan",
  "quality_tier": "professional",
  "product_type": "fashion",
  "aspect_ratio": "9:16",
  "output_resolution": "1080p"
}
```

**Supported `duration_seconds`**: `6`, `8`, `10`
**Supported `camera_style`**: `slow_pan`, `zoom_reveal`, `orbit`, `push_in`
**Supported `aspect_ratio`**: `9:16`, `1:1`, `16:9`

---

### Bulk Generation
```
POST /api/public/generate/bulk
```
Runs the complete production pipeline (images + videos + descriptions) across multiple SKUs simultaneously.

**Request body:**
```json
{
  "products": [
    {
      "sku": "SKU001",
      "image_url": "https://storage/sku001.jpg",
      "product_name": "Linen Blazer"
    },
    {
      "sku": "SKU002",
      "image_url": "https://storage/sku002.jpg",
      "product_name": "Cotton Dress"
    }
  ],
  "brand_master_id": "bm_abc123",
  "generate_images": true,
  "image_types": ["studio", "lifestyle"],
  "generate_video": true,
  "video_duration": 6,
  "generate_description": true,
  "quality_tier": "professional",
  "product_type": "fashion",
  "shopify_push": false
}
```

**Response:**
```json
{
  "bulk_job_id": "bulk_xyz789",
  "status": "processing",
  "total_skus": 2,
  "estimated_minutes": 5,
  "webhook_delivery_url": "https://your-endpoint.com/stuv-webhook"
}
```

---

### AI Product Description
```
POST /api/public/describe
```
Generates SEO-optimized product titles, bullet points, descriptions, and tags from a product image.

**Request body:**
```json
{
  "image_url": "https://your-storage/product.jpg",
  "product_type": "fashion",
  "tone": "luxury",
  "marketplace": "amazon",
  "language": "en",
  "include_fields": ["title", "bullets", "description", "meta_description", "tags"]
}
```

**Supported `tone`**: `luxury`, `mass_market`, `b2b_technical`, `lifestyle_editorial`
**Supported `marketplace`**: `shopify`, `amazon`, `flipkart`, `meesho`, `generic`
**Supported `language`**: `en`, `hi`, `ar`, `id`, `ms`, `ta`, `te`

---

### Background Removal
```
POST /api/public/background/remove
```
Removes background and optionally applies Smart Relighting with a new background.

**Request body:**
```json
{
  "image_url": "https://your-storage/product.jpg",
  "output_background": "white",
  "smart_relighting": true,
  "output_format": "png"
}
```

**Supported `output_background`**: `white`, `transparent`, `custom_color` (hex), `custom_image` (URL)

---

### AI Upscaler
```
POST /api/public/upscale
```
Upscales image resolution via GAN super-resolution to up to 8K.

**Request body:**
```json
{
  "image_url": "https://your-storage/product.jpg",
  "target_resolution": "4k",
  "remove_artifacts": true,
  "output_format": "png"
}
```

**Supported `target_resolution`**: `2k`, `4k`, `8k`

---

## JOB STATUS & POLLING

### Check Job Status
```
GET /api/public/jobs/{job_id}
```

**Response:**
```json
{
  "job_id": "job_xyz789",
  "status": "completed",
  "created_at": "2026-04-11T10:00:00Z",
  "completed_at": "2026-04-11T10:00:47Z",
  "outputs": {
    "studio": "https://cdn.stuv.ai/output/job_xyz789/studio_1x1.jpg",
    "lifestyle": "https://cdn.stuv.ai/output/job_xyz789/lifestyle_4x5.jpg"
  }
}
```

**Job statuses**: `queued`, `processing`, `completed`, `failed`

---

## WEBHOOKS

Configure webhooks to receive real-time callbacks when generation jobs complete — no polling required.

### Configure Webhook
```
POST /api/public/webhooks
```

**Request body:**
```json
{
  "url": "https://your-endpoint.com/stuv-webhook",
  "events": ["job.completed", "job.failed", "bulk.completed"],
  "secret": "your-signing-secret"
}
```

### Webhook Payload (job.completed)
```json
{
  "event": "job.completed",
  "job_id": "job_xyz789",
  "sku": "SKU001",
  "outputs": {
    "studio": "https://cdn.stuv.ai/output/studio_1x1.jpg",
    "lifestyle": "https://cdn.stuv.ai/output/lifestyle_4x5.jpg",
    "video": "https://cdn.stuv.ai/output/video_9x16.mp4",
    "description": {
      "title": "Premium Linen Blazer",
      "bullets": ["100% linen", "Modern slim fit", "Available in 5 colours"],
      "description": "...",
      "tags": ["blazer", "linen", "formal", "menswear"]
    }
  },
  "timestamp": "2026-04-11T10:00:47Z"
}
```

Webhooks are signed with HMAC-SHA256 using your configured `secret`. Verify the `X-Stuv-Signature` header on receipt.

---

## SHOPIFY INTEGRATION

### OAuth Setup
Stuv AI connects to Shopify via OAuth 2.0. Setup takes under 2 minutes:
1. In Stuv dashboard: **Settings → Integrations → Shopify → Connect**
2. Enter your Shopify store URL
3. Authorise the OAuth permissions
4. Done — Stuv AI can now push to your store

### Push Assets to Shopify via API
```
POST /api/public/shopify/push
```

**Request body:**
```json
{
  "shopify_store": "your-store.myshopify.com",
  "sku": "SKU001",
  "images": ["https://cdn.stuv.ai/output/studio.jpg", "https://cdn.stuv.ai/output/lifestyle.jpg"],
  "video": "https://cdn.stuv.ai/output/video.mp4",
  "description": {
    "title": "Premium Linen Blazer",
    "body_html": "<p>...</p>",
    "tags": "blazer,linen,formal"
  },
  "alt_text": "Premium Linen Blazer — studio shot on white background",
  "update_mode": "replace"
}
```

**Sync speed**: real-time, under 30 seconds per product.

---

## CLOUD STORAGE DELIVERY

Output assets can be delivered directly to cloud storage instead of CDN URLs:

```json
{
  "output_delivery": {
    "type": "s3",
    "bucket": "your-bucket",
    "region": "ap-south-1",
    "prefix": "stuv-outputs/",
    "access_key": "...",
    "secret_key": "..."
  }
}
```

**Supported storage targets**: AWS S3, Google Cloud Storage (GCS), Azure Blob Storage.

---

## RATE LIMITS

| Plan | Images/min | Videos/min | Bulk SKUs/run |
|---|---|---|---|
| Small Biz | 10 | 2 | — |
| Medium Biz | 30 | 5 | 500 |
| Scaleup Biz | 100 | 20 | 5,000 |
| Enterprise Biz | Custom | Custom | Unlimited |

Every API call also consumes subscription credits at the standard rates (2K image 150 · video 150/sec at 720px, 300/sec at 1080px · SEO description ~150 per product). See https://stuv.ai/pricing.md

Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

---

## SDK SUPPORT

Official SDKs for common server-side languages are available on request via the platform dashboard.

Integration examples in Node.js, Python, and PHP are available in the developer section of the Stuv AI dashboard.

---

## WIDGET EMBED REFERENCE

### See in Your Room (Fashion)
```html
<!-- Load once in <head> or <body> -->
<script src="https://widget.stuv.ai/vto.js" data-brand-id="YOUR_BRAND_ID"></script>

<!-- Place on product page where button should appear -->
<stuv-vto product-id="SKU123"></stuv-vto>
```

### See in Your Room (Furniture)
```html
<!-- Load once in <head> or <body> -->
<script src="https://widget.stuv.ai/room.js" data-brand-id="YOUR_BRAND_ID"></script>

<!-- Place on product page where button should appear -->
<stuv-room product-id="FURNITURE_SKU_123"></stuv-room>
```

Both widgets work with: Shopify (theme.liquid), WooCommerce (single-product.php), Magento, and any custom HTML/JS site. Setup time: under 5 minutes.

---

## KEY URLS

| Resource | URL |
|---|---|
| Full API documentation | https://stuv.ai (dashboard → Developer → API Docs) |
| Platform overview | https://stuv.ai |
| LLM context | https://stuv.ai/llms.txt |
| FAQ | https://stuv.ai/faq.md |
| Pricing | https://stuv.ai/pricing.md |
| Features | https://stuv.ai/features/index.md |