Products API

Endpoints for managing product references and marketing image generation.

Overview

The Products API enables saving product images from URLs and generating consistent marketing images across multiple scenes. Product references ensure visual consistency for e-commerce campaigns, social media content, and promotional materials.

Save from URL, generate unlimited marketing scenes

List Products

Retrieve all saved product references.

GET /api/products

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
page_size	integer	20	Items per page (max: 100)
search	string	-	Search name/description/tags

Request

curl -X GET "https://gobananasai.com/api/products?page=1&page_size=20" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": [
    {
      "id": 3,
      "productName": "Premium Headphones",
      "productDescription": "Wireless over-ear headphones with noise cancellation",
      "productUrl": "https://example.com/products/headphones.jpg",
      "tags": "audio, electronics, premium",
      "timesUsed": 24,
      "lastUsedAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "fullUrl": "https://pub-xxx.r2.dev/acme-corp/2024-01-01/product-a1b2c3d4.jpg",
      "thumbnailUrl": "https://pub-xxx.r2.dev/acme-corp/2024-01-01/product-a1b2c3d4-thumb.jpg"
    },
    {
      "id": 7,
      "productName": "Ceramic Coffee Mug",
      "productDescription": "Handcrafted artisan coffee mug",
      "productUrl": "https://example.com/products/mug.jpg",
      "tags": "kitchenware, ceramic, handmade",
      "timesUsed": 18,
      "createdAt": "2024-01-05T00:00:00.000Z",
      "fullUrl": "https://pub-xxx.r2.dev/...",
      "thumbnailUrl": "https://pub-xxx.r2.dev/..."
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 15,
    "hasMore": false
  }
}

Get Product

Retrieve details for a specific product reference.

GET /api/products/:identifier

Request

curl -X GET "https://gobananasai.com/api/products/3" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": {
    "id": 3,
    "productName": "Premium Headphones",
    "productDescription": "Wireless over-ear headphones with noise cancellation",
    "productUrl": "https://example.com/products/headphones.jpg",
    "width": 1200,
    "height": 1200,
    "sizeBytes": 524288,
    "format": "jpeg",
    "mimeType": "image/jpeg",
    "tags": "audio, electronics, premium",
    "timesUsed": 24,
    "lastUsedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-14T15:00:00.000Z",
    "r2Key": "acme-corp/2024-01-01/product-a1b2c3d4.jpg",
    "r2ThumbnailKey": "acme-corp/2024-01-01/product-a1b2c3d4-thumb.jpg",
    "thumbnailUrl": "https://pub-xxx.r2.dev/...",
    "fullUrl": "https://pub-xxx.r2.dev/..."
  }
}

Create Product Reference

Save a product image from a URL.

POST /api/products

Request Body

Field	Type	Required	Description
product_name	string	Yes	Unique name (max: 100)
product_url	string	Yes	Public URL of product image
product_description	string	No	Description for context
tags	string	No	Comma-separated tags

Request

curl -X POST "https://gobananasai.com/api/products" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Wireless Speaker",
    "product_url": "https://example.com/products/speaker.png",
    "product_description": "Portable Bluetooth speaker with 360-degree sound",
    "tags": "audio, electronics, portable, bluetooth"
  }'

Response

{
  "data": {
    "id": 16,
    "productName": "Wireless Speaker",
    "productUrl": "https://example.com/products/speaker.png",
    "r2Key": "acme-corp/2024-01-15/product-e5f6g7h8.png",
    "r2ThumbnailKey": "acme-corp/2024-01-15/product-e5f6g7h8-thumb.jpg",
    "width": 1000,
    "height": 1000,
    "sizeBytes": 412672,
    "thumbnailSizeBytes": 65536,
    "format": "png",
    "message": "Product reference created successfully"
  }
}

Update Product

Modify product metadata.

PATCH /api/products/:id

Request Body

Field	Type	Description
product_name	string	New name
product_description	string	Updated description
tags	string	Updated tags

Request

curl -X PATCH "https://gobananasai.com/api/products/16" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_description": "Premium portable Bluetooth speaker with 360-degree immersive sound and 20-hour battery life",
    "tags": "audio, electronics, portable, bluetooth, premium"
  }'

Response

{
  "data": {
    "id": 16,
    "productName": "Wireless Speaker",
    "productDescription": "Premium portable Bluetooth speaker with 360-degree immersive sound and 20-hour battery life",
    "tags": "audio, electronics, portable, bluetooth, premium",
    "updatedAt": "2024-01-15T11:15:00.000Z"
  }
}

Delete Product

Remove a product reference.

DELETE /api/products/:id

Request

curl -X DELETE "https://gobananasai.com/api/products/16" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": { "deleted": true }
}

Note

Deleting a product reference also deletes the stored product image from R2. Images generated with the product are not deleted.

Generate with Product

Create marketing images featuring a saved product.

POST /api/products/:id/generate

Request Body

Field	Type	Required	Description
scene_prompt	string	Yes	Marketing scene description
additional_details	string	No	Extra styling instructions
aspect_ratio	string	No	1:1, 16:9, 9:16, 4:3, 3:4
negative_prompt	string	No	What to avoid
number_of_images	integer	No	1-4 images

Request

curl -X POST "https://gobananasai.com/api/products/3/generate" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "scene_prompt": "on a modern minimalist desk with a laptop and coffee cup, soft natural lighting from a window",
    "additional_details": "professional product photography style, clean background",
    "aspect_ratio": "16:9",
    "number_of_images": 2
  }'

Response

{
  "data": {
    "imageId": 157,
    "sessionId": "api-prod-1700000000",
    "fullUrl": "https://pub-xxx.r2.dev/acme-corp/2024-01-15/generate-i9j0k1l2.png",
    "thumbnailUrl": "https://pub-xxx.r2.dev/acme-corp/2024-01-15/generate-i9j0k1l2-thumb.jpg",
    "width": 1820,
    "height": 1024,
    "format": "png",
    "sizeBytes": 1572864,
    "prompt": "Create a product marketing image featuring the exact product from the reference image. Scene: on a modern minimalist desk with a laptop and coffee cup...",
    "productId": 3,
    "productName": "Premium Headphones",
    "scenePrompt": "on a modern minimalist desk with a laptop and coffee cup, soft natural lighting from a window",
    "images": [
      { "id": 157, "url": "https://pub-xxx.r2.dev/...", "thumbnail_url": "https://pub-xxx.r2.dev/..." },
      { "id": 158, "url": "https://pub-xxx.r2.dev/...", "thumbnail_url": "https://pub-xxx.r2.dev/..." }
    ],
    "message": "Product marketing images generated successfully"
  }
}

Error Responses

400 Invalid URL

{
  "error": "Product URL must be a valid HTTP or HTTPS URL"
}

400 Fetch Failed

{
  "error": "Failed to fetch image from URL: 404 Not Found"
}

400 Invalid Image

{
  "error": "URL does not point to an image. Content-Type: text/html"
}

404 Product Not Found

{
  "error": "Product not found"
}

409 Duplicate Name

{
  "error": "Product with name \"Premium Headphones\" already exists. Please use a different name or delete the existing product."
}

Next Steps

• Style Presets API →
• Usage API →
• Admin API →