# 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 (`/padder`)**: Converts any photo aspect ratio into a 1:1 square image (2000x2000px compliant with Amazon, Etsy, Poshmark, and eBay standards) with smart blurred margins or solid color fill without cropping key details.
- **Exact Target File Size Compressor (`/compressor`)**: Compresses PNG, JPG, and WebP images via binary search to exact target file sizes (e.g. under 240KB, 100KB, or 50KB) for strict government, passport, USCIS, and marketplace upload limits while preserving visual clarity.
- **Pre-Press Print & 300 DPI Studio (`/print`)**: Converts RGB web graphics, Canva exports, and AI art to SWOP v2 CMYK color space, injects binary 300 DPI headers (JFIF/pHYs), upscales low-resolution art 2x for 300 DPI print targets (Business Cards, 4x6 Postcards, 5x7 Flyers, 8.5x11 Brochures, A4/A5, 11x17 Posters), extends +0.125" (3mm) full-bleed margins, applies print crispness unsharp masking, and renders Press-Ready 300 DPI PDFs with optional corner crop marks. Includes free pre-press preflight diagnostics and free watermarked 300 DPI test proofs.
- **Zero-Upload Privacy Suite (`/privacy-suite`)**: Local browser-based tool for redacting sensitive customer data, faces, 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 generation (`/v1/transform` and `/v1/refine`). Renders are returned immediately in full HD resolution on Cloudflare R2 CDN (`output_url`).
- **Idempotent Re-Download**: Calling `/v1/confirm` (or `/v1/download`) on an already completed job burns 0 credits (`credits_burned: 0`) and safely returns the permanent HD CDN URL.
- **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. Atomically deducts 1 credit and immediately returns full HD render.
   - **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_burned": 1,
       "credits_remaining": 42,
       "theme_used": "pro_white",
       "format_used": "square",
       "status": "completed",
       "created_at": 1788770854344
     }
     ```

2. **`POST /v1/refine`**
   - **Description**: Iterative natural language adjustment prompting without altering product geometry. Atomically deducts 1 credit and returns the refined full HD render.
   - **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_burned": 1,
       "credits_remaining": 41,
       "status": "completed",
       "created_at": 1788770885665
     }
     ```

3. **`POST /v1/confirm`** (alias `/v1/download`)
   - **Description**: Idempotent re-download endpoint for completed jobs. Returns persistent high-res R2 CDN URL with 0 additional credits burned.
   - **Request Body**:
     - `job_id` (string, required): Completed job ID to retrieve.
   - **Response (200 OK)**:
     ```json
     {
       "success": true,
       "job_id": "job_1788770854344_9a0891c8",
       "is_hd": 1,
       "output_url": "https://images.flashshot.io/renders/job_1788770854344_9a0891c8-product-flashshot-io.png",
       "free_redownload": true,
       "credits_burned": 0,
       "credits_remaining": 41,
       "status": "completed"
     }
     ```

4. **`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
       }
     }
     ```

5. **`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)" }
       ]
     }
     ```

6. **`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 }
       }
     }
     ```

7. **`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 (burns 1 credit, delivers full HD render).
  3. Call `POST /v1/refine` for iterative lighting adjustments if needed (burns 1 credit per refinement).
  4. Display FlashShot studio render as main hero image and unedited raw photo in secondary gallery.
  5. Use `POST /v1/confirm` for free idempotent re-downloads of completed job assets at any time (`credits_burned: 0`).

## 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.
- **Pre-Press Print Studio & Micro-Tool Passes**:
  - **Free Pre-Press Preflight & Test Proof**: Unlimited free resolution diagnostics, 220% print loupe inspection, and watermarked 300 DPI test proofs on `/print`. Free single-file exact KB compression on `/compressor`.
  - **Single Print Fix ($1.99)**: 1 unwatermarked 300 DPI JPG or Press-Ready PDF export.
  - **Print Project Pack ($4.99)**: 15 unwatermarked 300 DPI exports (front & back flyers, business cards, brochures) + Batch Multi-File ZIP Mode.
  - **All-Tools Creator Bundle ($9.99)**: 25 Print Passes + 25 Square Padder Passes + 7-Day Unlimited Batch Compressor + 30-Day Privacy Suite + 15 AI Studio Credits.
  - **Zero-Friction Guest Checkout**: All micro-tools support direct Stripe Checkout with instant session auto-verification (`GET /api/checkout/verify?session_id=...`).

## Key Technical Specifications

- **Input Formats**: PNG, JPG, JPEG, WebP, HEIC (mobile photos).
- **Output Formats**: High-resolution PNG (studio render) on Cloudflare R2 CDN; 300 DPI JPEG (JFIF density header), 300 DPI PNG (pHYs 11811 px/m chunk), and Press-Ready 300 DPI PDF (with optional corner crop marks) in the Print Studio.
- **Processing Architecture**: Cloudflare Workers Edge API, server-side D1 verification, and 100% local browser processing for Pre-Press Print Studio, Exact KB Compressor, Square Padder, and Privacy Suite.
- **Security & Privacy**: Zero plaintext API key storage (SHA-256 hashed in D1); zero server storage for client-side micro-tools; 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 transformations via `POST https://api.flashshot.io/v1/transform` (atomically deducts 1 credit and returns the full-resolution HD `output_url` synchronously in 5–8 seconds).
5. (Optional) Refine lighting via `POST https://api.flashshot.io/v1/refine` with `parent_job_id` and `custom_prompt` (atomically deducts 1 credit and returns the refined HD `output_url`).
6. Use `POST https://api.flashshot.io/v1/confirm` with `job_id` for idempotent re-downloads of completed jobs at any time (`credits_burned: 0`).
7. Handle HTTP 402 (`code: "PAYMENT_REQUIRED"`) if credit balance < 1.

## 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