Jewel-Byte AI API

Use these endpoints to integrate 3 product images + 1 product video generation into your app. All generation uses your own Google AI Studio API key; images and video are stored on S3.

Base URL

https://your-domain.com

Recommended flow (3 images + 1 video)

Verify API key — POST /api/verify-key
Select product type & generate prompts — In the app, Step 2 uses Male, Female, Unisex, Article radio buttons. Then POST /api/generate-prompt with productType (male | female | unisex | article) + optional productSummary or reference images.
Generate media — POST /api/stream/generate-media (SSE; 4 descriptions + reference images) → when reference images are sent, the stream first emits image_details (AI-generated title and description for the uploaded image), then 3 image URLs + 1 video URL. The app uses this stream endpoint for real-time progress.

Alternatively: use /api/generate-images or /api/stream/generate-images for 3 images only, then /api/generate or /api/stream/generate for video only.

REST vs stream: REST endpoints (/api/generate-media, /api/generate-images, /api/generate) return a single JSON response. Stream endpoints (/api/stream/*) return text/event-stream with events: start, image, video, done, error.

Endpoints

POST/api/verify-key

Validate a Google AI Studio API key before calling other endpoints. Call this first in your integration.

Request body (JSON)

Field	Type	Description
apiKey *	string	Google AI Studio API key

Response 200

{
  "valid": true,
  "message": "API key is valid and working!"
}

Error (4xx/5xx)

{ "valid": false, "error": "reason" }
// 400 if apiKey missing

Example (JavaScript)

const res = await fetch("https://your-domain.com/api/verify-key", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ apiKey: "AIzaSy..." }),
});
const { valid, error } = await res.json();
if (!valid) throw new Error(error);

POST/api/generate-prompt

Generate 4 prompts (3 image + 1 video) for a jewellery product. Uses Gemini to produce descriptions. In the app UI, product type is selected via Male / Female / Unisex / Article radio buttons. Use male, female, or unisex for the model gender in the wearing shot; use article for items like God structure, bangle, idol (displayed on stand, no model). Optionally send reference images so the model identifies the product (ring, earrings, etc.).

Request body (JSON)

Field	Type	Description
apiKey *	string	Google AI Studio API key
productType *	string	One of: male, female, unisex, article (matches app radio options; article = God structure, bangle, idol, etc.)
productSummary	string	Optional product style (e.g. Earring with Gold plated, Diamond ring)
referenceImages	string[]	Optional. Data URIs (data:image/...;base64,...) of product images so the model identifies product type and design

Response 200

{
  "imagePrompts": [
    "A straight-on front view of the ring...",
    "A slightly angled three-quarter view...",
    "A close-up of hand showing the ring..."
  ],
  "videoPrompt": "Silent video, no audio. Create a smooth 360-degree rotating..."
}

Error (4xx/5xx)

{ "error": "productType is required and must be one of: male, female, unisex, article" }
// 400/500 with error message

Example (JavaScript)

const { imagePrompts, videoPrompt } = await fetch("https://your-domain.com/api/generate-prompt", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    apiKey: "AIzaSy...",
    productType: "female",
    productSummary: "Diamond ring in Yellow gold",
    referenceImages: ["data:image/png;base64,..."], // optional
  }),
}).then(r => r.json());

POST/api/generate-media

Generate 3 product images + 1 product video in one call. Uses Gemini 3 Pro Image for images and Veo 3.1 for video. Pass reference images so generated images match your product (e.g. ring vs earrings). Video is silent (no audio). Long-running: allow 2–5 min timeout.

Request body (JSON)

Field	Type	Description
apiKey *	string	Google AI Studio API key
descriptions *	string[]	Array of exactly 4 strings: [imagePrompt1, imagePrompt2, imagePrompt3, videoPrompt]
referenceImages	string[]	Optional. Data URIs of product images; used so images and video match the product

Response 200

{
  "success": true,
  "media": [
    {
      "mediaUrl": "https://.../images/gen-xxx.png",
      "type": "image"
    },
    {
      "mediaUrl": "https://.../images/gen-yyy.png",
      "type": "image"
    },
    {
      "mediaUrl": "https://.../images/gen-zzz.png",
      "type": "image"
    },
    {
      "mediaUrl": "https://.../videos/veo-xxx.mp4",
      "type": "video"
    }
  ],
  "costUsed": 1.37,
  "durationMs": 120000
}

Error (4xx/5xx)

{ "error": "descriptions is required and must be an array of exactly 4 strings" }
// 400/500 with error message

Example (JavaScript)

const res = await fetch("https://your-domain.com/api/generate-media", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    apiKey: "AIzaSy...",
    descriptions: [imagePrompts[0], imagePrompts[1], imagePrompts[2], videoPrompt],
    referenceImages: refDataUris, // optional but recommended
  }),
});
const { media, costUsed, durationMs } = await res.json();
const imageUrls = media.filter(m => m.type === "image").map(m => m.mediaUrl);
const videoUrl = media.find(m => m.type === "video")?.mediaUrl;

POST/api/generate-images

Generate 3 product images from 3 text prompts. Uses Gemini 3 Pro Image (or Imagen if configured). Images are uploaded to S3 and returned as URLs. Allow ~1–2 min timeout.

Request body (JSON)

Field	Type	Description
apiKey *	string	Google AI Studio API key
prompts *	string[]	Array of exactly 3 image prompts

Response 200

{
  "success": true,
  "images": [
    {
      "url": "https://.../images/gen-xxx.png",
      "base64": "...",
      "mimeType": "image/png"
    },
    {
      "url": "https://.../images/gen-yyy.png",
      "base64": "...",
      "mimeType": "image/png"
    },
    {
      "url": "https://.../images/gen-zzz.png",
      "base64": "...",
      "mimeType": "image/png"
    }
  ]
}

Error (4xx/5xx)

{ "error": "prompts is required and must be an array of exactly 3 strings" }

POST/api/generate

Generate a single video from a text prompt. Optional reference image for image-to-video. Video is silent. Long-running: allow 2–5 min timeout.

Request body (JSON)

Field	Type	Description
apiKey *	string	Google AI Studio API key
prompt *	string	Video description (e.g. 360° rotating product)
referenceImages	string[]	Optional. Data URIs; first image used for image-to-video
imageUrls	string[]	Optional; for tracking only

Response 200

{
  "success": true,
  "videoBase64": "<base64 mp4>",
  "mimeType": "video/mp4",
  "videoUrl": "https://.../videos/veo-xxx.mp4"
}

Error (4xx/5xx)

{ "error": "Prompt is required" }
// 504 if video generation times out (5 min)

POST/api/upload

Upload one or more product images to S3. Request: multipart/form-data with field 'images' (File[]). Use the returned URLs or convert to data URIs for referenceImages in generate-prompt / generate-media.

Request body (JSON)

Field	Type	Description
images *	File[] (form)	One or more image files in multipart/form-data

Response 200

{
  "images": [
    {
      "id": "uuid",
      "filename": "uuid.png",
      "url": "https://.../uploads/uuid.png"
    }
  ]
}

Error (4xx/5xx)

{ "error": "No images provided" }
// 400 if form field 'images' is missing or empty

Example (JavaScript)

const form = new FormData();
form.append("images", file1);
form.append("images", file2);
const res = await fetch("https://your-domain.com/api/upload", { method: "POST", body: form });
const { images } = await res.json();
// Convert to data URI if needed for referenceImages:
// fetch(images[0].url).then(r=>r.blob()).then(blob=>{ ... readAsDataURL ... })

POST/api/videos

Save a video (base64) to S3 and return the public URL. Use if you receive video as base64 (e.g. from /api/generate) and need a persistent URL.

Request body (JSON)

Field	Type	Description
videoBase64 *	string	Base64-encoded video data
mimeType	string	e.g. video/mp4 (default)

Response 200

{
  "id": "uuid",
  "filename": "uuid.mp4",
  "url": "https://.../videos/uuid.mp4"
}

Error (4xx/5xx)

{ "error": "No video data provided" }

GET/api/history

Fetch recent generation history and aggregate stats (total generations, cost, tokens, image count). No auth required; useful for dashboards.

Response 200

{
  "stats": {
    "totalGenerations": 12,
    "totalCostUsd": 33.6,
    "totalTokens": 8200,
    "totalImages": 34
  },
  "history": [
    {
      "_id": "...",
      "apiKeyMasked": "AIzaSy......3GO",
      "type": "media",
      "descriptions": [
        "...",
        "...",
        "...",
        "..."
      ],
      "imageUrls": [
        "https://..."
      ],
      "videoUrl": "https://...",
      "durationMs": 120000,
      "estimatedCostUsd": 1.37,
      "createdAt": "2026-03-06T12:00:00.000Z"
    }
  ]
}

Notes for integration

Use the same apiKey for verify, generate-prompt, and generate-media.
Reference images must be data URIs: data:image/png;base64,<base64>. You can get these from upload URLs by fetching and using FileReader.readAsDataURL(blob).
Video is always generated without audio (silent).
Set HTTP timeouts: at least 2–3 minutes for image generation, 5 minutes for video or generate-media.
Image model defaults to Gemini 3 Pro Image (gemini-3-pro-image-preview). Override with env IMAGE_GENERATION_MODEL (e.g. imagen-4.0-generate-001).