AI Render (Kie.ai)

The AI Render feature allows users to generate photorealistic product mood shots from 3D screenshots using the Kie.ai API. It combines the original product photo (from AI Check API) with the 3D model screenshot (with logo) to produce high-quality renders.

Overview

The AI Render overlay is accessible from the Spranz Logo Modal (spranz-modal.magiceverse.online). It captures a screenshot of the current 3D product preview, fetches the original product photo, and sends both images to Kie.ai for AI-powered mood shot generation.

Architecture

Frontend (React Modal)          Backend (Express)              External APIs
┌─────────────────────┐   ┌──────────────────────┐   ┌─────────────────────┐
│ MagicLogoModal.tsx   │──▶│ /api/kie-ai/generate │──▶│ Kie.ai Upload       │
│ - Prompt input       │   │ - Upload original    │   │ Kie.ai createTask   │
│ - Polling for result │◀──│ /api/kie-ai/status   │◀──│ Kie.ai recordInfo   │
│                      │   │ - Upload 3D shot     │   │                     │
│                      │──▶│ /api/kie-ai/         │──▶│ AI Check API        │
│                      │   │   original-image     │   │ (port 11010)        │
└─────────────────────┘   └──────────────────────┘   └─────────────────────┘

Dual-Image Input

The feature sends two images to each AI model:

1. Original product photo — fetched from the AI Check API (aicheck-spranz.magiceverse.online, port 11010) via /api/products/image/:variantCode
2. 3D screenshot with logo — captured from the 3D canvas in the modal

The prompt instructs the AI to use the original photo as the base, take the logo/design placement from the 3D model, and create a mood shot combining both.

File Locations

Component	Path
Backend API	/mnt/data/magic_omniverse/magic_logo/spranz/backend/src/api/kieai.ts
Frontend Modal	/mnt/data/magic_omniverse/magic_modal/spranz/src/components/MagicLogoModal.tsx
CSS Styles	/mnt/data/magic_omniverse/magic_modal/spranz/src/styles/MagicLogoModal.css
Frontend Deploy	/mnt/data/htdocs/spranz-modal/

Services

Service	Details
Backend	Port 4055, pm2 process spranz-logo-backend (id 15), runs as adminwayne
Frontend	Static build served by nginx at spranz-modal.magiceverse.online
AI Check API	Port 11010, pm2 process magic-agent-spranz, provides original product images
Kie.ai API Base	https://api.kie.ai/api/v1/jobs
Kie.ai Upload	https://kieai.redpandaai.co/api/file-base64-upload

---

AI Models

Mood Shot (nano-banana-2)

Generates a photorealistic mood shot from the 3D screenshot and original product photo.

Parameter	Value
Model ID	nano-banana-2
Input field	image_input (array, up to 8 images)
Aspect ratios	1:1 (fixed)
Resolution	1K (default)
Output format	png

API payload example:

\{
  "model": "nano-banana-2",
  "input": \{
    "prompt": "The first image is the original product photo...",
    "image_input": ["https://tempfile.redpandaai.co/original.png", "https://tempfile.redpandaai.co/3d-screenshot.png"],
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "output_format": "png"
  \}
\}

---

Backend API Endpoints

POST /api/kie-ai/generate

Creates an AI render task. Uploads image(s) to Kie.ai file hosting, then calls createTask.

Request body:

{
  "base64Data": "iVBORw0KGgo...",
  "originalBase64Data": "iVBORw0KGgo...",
  "prompt": "The first image is the original product photo...",
  "model": "nano-banana-2",
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "quality": "basic"
}

Field	Required	Description
base64Data	Yes	Base64-encoded PNG of the 3D screenshot with logo
originalBase64Data	No	Base64-encoded original product photo (from AI Check API)
prompt	Yes	Text prompt describing desired output
model	No	Model ID (default: nano-banana-2)
aspect_ratio	No	Aspect ratio (uses model default if omitted)
resolution	No	1K, 2K, or 4K (only for nano-banana models)
quality	No	basic or high (only for seedream model)

When originalBase64Data is provided, both images are uploaded to Kie.ai and sent as an array: [originalUrl, screenshotUrl]. The original image is first so the AI uses it as the primary reference.

Response:

{
  "success": true,
  "data": {
    "taskId": "d98d6cba9ef8b49abad2f96dd7663fb7",
    "model": "nano-banana-2"
  }
}

GET /api/kie-ai/status/:taskId

Polls Kie.ai recordInfo for task status and result URLs.

Response:

{
  "success": true,
  "data": {
    "state": "success",
    "resultUrls": ["https://cdn.kie.ai/result/...png"],
    "failMsg": null,
    "raw": { }
  }
}

State	Meaning
processing / waiting	Task is being processed
success / completed	Result ready, check resultUrls
fail / failed / error	Generation failed, check failMsg

GET /api/kie-ai/original-image/:variantCode

Proxies the AI Check API (port 11010) to fetch the original product photo for a given variant code.

Response:

{
  "success": true,
  "base64": "/9j/4AAQ...",
  "mediaType": "image/jpeg",
  "variant_code": "376-00.005"
}

The AI Check API looks for images in /mnt/data/pim_data/spranz/ with these filename candidates:

• {variantCode}_Front.jpg
• {variantCode}.jpg
• {variantCode}_Front.png

GET /api/kie-ai/product-info/:sku

Returns product material and name from the product_physical_characteristics table in the magic_b2b_brinxx database. Used to auto-generate AI prompts with material context.

---

Image Upload Flow

All models require publicly accessible image URLs. The flow is:

1. Frontend captures 3D canvas as base64 PNG
2. Frontend fetches original product photo via /api/kie-ai/original-image/:variantCode
3. Backend receives both base64 images and uploads each to Kie.ai file hosting:
   • Endpoint: https://kieai.redpandaai.co/api/file-base64-upload
   • Upload path: magic-everse/screenshots
   • Files auto-delete after 3 days
4. Kie.ai returns downloadUrl for each image
5. Both URLs are passed as an array in image_input or image_urls in the createTask call

---

Default Prompt

When the original product image is available, the default prompt is:

The first image is the original product photo, made of {material}. The second image shows the same product as a 3D model with a branded logo/design printed on it. Create a high-end mood shot: take the logo/design placement from the 3D model and apply it to the original product photo. Place the product on a stylish modern office desk with warm wood tints. Clean, elegant minimalist setting with soft natural lighting, shallow depth of field. Photorealistic commercial photography.

When no original image is available (fallback):

High-end luxurious mood shot of this product, made of {material} with branded logo, placed on a stylish modern office desk with warm wood tints. Clean, elegant minimalist setting with soft natural lighting, shallow depth of field, premium lifestyle atmosphere. Photorealistic commercial photography.

---

Frontend UI

Image Display

The overlay shows:

• Original Photo (if available) — from AI Check API
• 3D + Logo — screenshot from 3D canvas
• Arrow →
• Result — AI-generated mood shot

State Machine

The mood shot generation goes through these states:

ready → generating → success
                   → error

Polling

• Poll every 3 seconds, 45-second progress timer
• Polling stops on success, fail, or overlay close

CSS Classes

Class	Purpose
.ai-render-overlay	Full-screen backdrop
.ai-render-modal	Modal container
.ai-render-images	Image display container
.ai-render-image-box	Individual image card
.ai-render-result-box	Result image container
.ai-render-prompt-area	Prompt input area
.ai-render-footer	Footer action buttons

---

Build & Deploy

Backend

cd /mnt/data/magic_omniverse/magic_logo/spranz/backend

# Compile TypeScript to dist/
npx tsc

# Restart pm2 (runs as adminwayne)
sudo -u adminwayne pm2 restart spranz-logo-backend

Important

The backend runs node dist/index.js (compiled JavaScript), NOT the TypeScript source directly. After editing any .ts file in src/, you must run npx tsc to compile before restarting pm2. Otherwise your changes won’t take effect.

Frontend

cd /mnt/data/magic_omniverse/magic_modal/spranz

# Build Vite app
npm run build

# Deploy to web root
cp -r dist/* /mnt/data/htdocs/spranz-modal/

---

Environment Variables

Variable	Description
KIE_AI_API_KEY	Kie.ai API key (set in pm2 ecosystem config)

---

Troubleshooting

Issue	Cause	Fix
All models return same result	Backend not compiled after TS changes	Run npx tsc then restart pm2
No original image shown	AI Check API down or no image for SKU	Check pm2 logs magic-agent-spranz and /mnt/data/pim_data/spranz/
Credits insufficient	Kie.ai account balance empty	Top up credits at kie.ai dashboard
No taskId returned	Various API errors	Check backend logs: sudo -u adminwayne pm2 logs spranz-logo-backend
Changes not visible in browser	Frontend not rebuilt/deployed	Run npm run build and copy dist/ to htdocs
Seedream returns error on aspect ratio	Invalid ratio for seedream model	Only use ratios from the supported list (no auto)