# FlashShot.io — AI Product Photography & E-Commerce Visual Asset Suite

> FlashShot (https://flashshot.io) transforms raw phone photos into studio-quality e-commerce product listings instantly using AI Relighting, automatic background generation, and privacy-first image utilities. Built for Etsy sellers, Amazon FBA merchants, eBay stores, Shopify brands, Poshmark resellers, and programmatic API integrations.

## Overview & Core Capabilities

- **AI Studio Relighting**: Replaces harsh shadows, bad indoor lighting, and glares with soft, realistic studio lighting tailored to product materials (apparel, jewelry, footwear, skincare, home decor, electronics).
- **Background Replacement & Scene Generation**: Instantly extracts subjects and places products into professional, high-converting environments (minimalist studio, marble countertops, podiums, natural sunlight, lifestyle settings).
- **Edge Subject Protection**: Uses advanced background isolation to ensure sharp product contours without artificial clipping or distorted branding.
- **Smart E-Commerce Square Padder**: Converts any photo aspect ratio into a 1:1 square image (2000x2000px compliant with Amazon, Etsy, and eBay standards) with smart blurred margins or solid color fill without cropping key details.
- **Target File Compressor**: Compresses PNG, JPG, and WebP images to exact target file sizes (e.g. under 5MB or 2MB) for strict marketplace upload limits while preserving visual clarity.
- **Print-Ready Converter**: Converts web images to 300 DPI high-resolution print files with custom margins and Bleed guidelines for packaging, inserts, and print materials.
- **Zero-Upload Privacy Suite**: Local browser-based tool for redacting sensitive customer data, invoice numbers, and watermarks before publishing or sharing assets.
- **Public Developer API (v1)**: Production REST API under `https://api.flashshot.io/v1` for automated catalog relighting, prompt refinement, and synchronous image delivery.

## Developer API (v1) & Programmatic Integration

- **Base URL**: `https://api.flashshot.io/v1`
- **Interactive Documentation**: `https://flashshot.io/docs`
- **OpenAPI 3.1.0 Specification**: `https://api.flashshot.io/v1/openapi.json`
- **CORS Support**: Universal Cross-Origin Resource Sharing (`Access-Control-Allow-Origin: *`) enabled for all developer origins.
- **Synchronous Delivery**: Renders complete in 5–8 seconds synchronously; no webhook receiver or polling required.

### Authentication & Keys
- **Header**: `Authorization: Bearer <api_key>` OR `x-api-key: <api_key>`
- **Format**: `fs_live_[32_hex_chars]` (e.g. `fs_live_a1b2c3d4e5f67890123456789abcdef0`)
- **Key Lifecycle**: Self-service creation, regeneration, and revocation in the Customer Account Modal under "API Keys & Integrations" on `https://flashshot.io`.
- **Security Standard**: Keys are hashed with SHA-256 before storage in Cloudflare D1. Zero plain-text secret persistence.

### Credit Engine & Fail-Fast 402
- **Deduction Rate**: Exactly 1 credit is atomically deducted per `/v1/transform` or `/v1/refine` call.
- **Fail-Fast**: If balance < 1, requests fail fast with `HTTP 402 Payment Required` (`code: "PAYMENT_REQUIRED"`) in <400ms without calling external AI models.
- **Compensatory Rollback**: If upstream Google Gemini inference models fail across the cascade, the deducted credit is automatically refunded in the same lifecycle.

### Endpoint Catalog

1. **`POST /v1/transform`**
   - **Description**: Synchronous AI studio relighting from Base64 or public image URL.
   - **Request Body**:
     - `image` (string, required): Base64 data URI (`data:image/png;base64,...`), raw Base64 string, or public HTTPS URL. Max ~4.5MB.
     - `theme_key` (string, required): Active lighting preset (e.g. `pro_white`, `the_clean_marble`, `natural_wood`).
     - `format_key` (string, optional): Target aspect ratio e.g. `square` (1:1), `portrait` (4:5), `story` (9:16), or keys `portrait_4_5`, `square_1_1`, `story_9_16`. Default `square`.
     - `custom_prompt` (string, optional): Natural language prompt adjustments.
     - `original_filename` (string, optional): Semantic filename for R2 CDN slugging.
   - **Response (200 OK)**:
     ```json
     {
       "success": true,
       "job_id": "job_1788770854344_9a0891c8",
       "output_url": "https://images.flashshot.io/renders/job_1788770854344_9a0891c8-product-flashshot-io.png",
       "credits_remaining": 42,
       "theme_used": "pro_white",
       "format_used": "square",
       "created_at": 1788770854344
     }
     ```

2. **`POST /v1/refine`**
   - **Description**: Iterative natural language adjustment prompting without altering product geometry.
   - **Request Body**:
     - `parent_job_id` (string, required): Prior transformation job ID belonging to authenticated account.
     - `custom_prompt` (string, required): Natural language instructions (e.g. "Soften the specular glare on the bezel and warm up the rim light").
   - **Response (200 OK)**:
     ```json
     {
       "success": true,
       "job_id": "job_1788770885665_94ba9a49",
       "parent_job_id": "job_1788770854344_9a0891c8",
       "output_url": "https://images.flashshot.io/renders/job_1788770885665_94ba9a49-refine-flashshot-io.png",
       "credits_remaining": 41,
       "created_at": 1788770885665
     }
     ```

3. **`GET /v1/jobs/:id`**
   - **Description**: Query metadata, status, theme used, format, and output URL of a prior job.
   - **Response (200 OK)**:
     ```json
     {
       "success": true,
       "job": {
         "id": "job_1788770854344_9a0891c8",
         "status": "completed",
         "theme_used": "pro_white",
         "format_used": "square",
         "output_url": "https://images.flashshot.io/renders/...",
         "parent_job_id": null,
         "created_at": 1788770854344
       }
     }
     ```

4. **`GET /v1/themes`**
   - **Description**: Public discovery of available studio lighting presets and aspect ratios.
   - **Response (200 OK)**:
     ```json
     {
       "success": true,
       "themes": [
         { "key": "pro_white", "name": "The Studio White", "color": "bg-white", "reference_image_url": "..." },
         { "key": "natural_wood", "name": "The Oak Collection", "color": "bg-amber-800", "reference_image_url": "..." }
       ],
       "formats": [
         { "key": "square", "label": "Square (1:1)" },
         { "key": "portrait", "label": "Portrait (4:5)" },
         { "key": "story", "label": "Story (9:16)" }
       ]
     }
     ```

5. **`GET /v1/account`**
   - **Description**: Authenticated account details, credit balance, lifetime usage, and rate limits.
   - **Response (200 OK)**:
     ```json
     {
       "success": true,
       "account": {
         "user_id": "usr_...",
         "email": "developer@example.com",
         "tier": "enterprise",
         "credits": { "balance": 100, "total_used": 50 },
         "rate_limits": { "requests_per_minute": 60, "max_concurrent_jobs": 10 }
       }
     }
     ```

6. **`GET /v1/openapi.json`**
   - **Description**: Full OpenAPI 3.1.0 JSON document for SDK generation and schema validation.

### E-Commerce Dual-Image Workflow (JRG Electronics Guide)
- **Concept**: Maintain customer trust by presenting authentic condition photos alongside high-converting studio renders.
- **Workflow**:
  1. Capture raw phone photo of product and store on seller CDN.
  2. Call `POST /v1/transform` with `theme_key: "pro_white"` to create primary catalog listing image.
  3. Call `POST /v1/refine` for iterative lighting adjustments.
  4. Display FlashShot studio render as main hero image and unedited raw photo in secondary gallery.

## Target Use Cases & E-Commerce Platforms

- **Amazon FBA & Merchant Listings**: Pure white background generation and exact 1:1 square 2000x2000px asset preparation compliant with Amazon seller guidelines.
- **Etsy & Handmade Shops**: Warm, organic lifestyle scenes that highlight crafted textures and boost buyer engagement.
- **Poshmark & eBay Resellers**: Quick smartphone photo cleanup into professional flat-lays and clean studio shots.
- **Shopify & Direct-to-Consumer (D2C) Brands**: Consistent catalog product photo background styling across entire product collections.
- **Instagram & TikTok Shop**: Vertical 9:16 story-ready product showcases and high-impact visual banners.

## Tools & Features Ecosystem

- [Main AI Studio](https://flashshot.io/): Generate studio product photos with AI relighting and environment selection.
- [Developer API Documentation](https://flashshot.io/docs): Complete REST API reference, code snippets, and interactive live console.
- [Smart E-Commerce Square Padder](https://flashshot.io/padder): Resize product photos to 1:1 square with smart blurred or solid background padding without cropping.
- [Target File Compressor](https://flashshot.io/compressor): Reduce image size to exact megabyte or kilobyte limits in browser.
- [Print-Ready Converter](https://flashshot.io/print): Prepare 300 DPI print files and product packaging inserts.
- [Zero-Upload Privacy Suite](https://flashshot.io/privacy-suite): Redact documents and redact sensitive photo elements entirely client-side.
- [All Tools Directory](https://flashshot.io/tools): Index of all free and single-pass visual compliance utilities.
- [E-Commerce & Photography Guides](https://flashshot.io/blog): Detailed tutorials on seller compliance, lighting setups, and AI workflow optimization.

## Pricing & Credit System

- **Free Trial**: New users receive starter credits upon initial registration.
- **HD Download & Developer API Credits**: 1 credit is consumed per high-definition (HD) image download and per `/v1/transform` or `/v1/refine` API call.
- **Single Pass Utility Access**: Utility tools (Square Padder, Target Compressor, Privacy Suite) are available via single-pass passes or bundled credits.

## Key Technical Specifications

- **Input Formats**: PNG, JPG, JPEG, WebP, HEIC (mobile photos).
- **Output Formats**: High-resolution PNG (studio render) on Cloudflare R2 CDN.
- **Processing Architecture**: Cloudflare Workers Edge API, server-side D1 verification, and local browser processing for privacy tools.
- **Security & Privacy**: Zero plaintext API key storage (SHA-256 hashed in D1); zero server storage for Privacy Suite files; ephemeral processing for AI studio passes.

## Autonomous AI Agent Guidance (Cursor, Claude Code, Windsurf)

Autonomous AI agents integrating FlashShot should:
1. Obtain API key with `fs_live_` prefix from user or environment variable `FLASHSHOT_API_KEY`.
2. Inspect account credit balance via `GET https://api.flashshot.io/v1/account`.
3. Discover available lighting themes via `GET https://api.flashshot.io/v1/themes`.
4. Submit image transformation via `POST https://api.flashshot.io/v1/transform`.
5. Check for HTTP 402 if credits are exhausted.
6. Refine lighting using `POST https://api.flashshot.io/v1/refine` with `parent_job_id` (the returned `job_id`) and `custom_prompt`.

## Contact & Legal

- Website: https://flashshot.io
- Developer Docs: https://flashshot.io/docs
- OpenAPI Spec: https://api.flashshot.io/v1/openapi.json
- Terms of Service: https://flashshot.io/terms
- Privacy Policy: https://flashshot.io/privacy
- Refund Policy: https://flashshot.io/legal-refund