API Reference

REST API v1

The ListingRVA AI REST API lets you generate product images, listing copy, manage products, and retrieve assets programmatically. Available on the Pro plan only.

Authentication

All API requests require a JWT Bearer token. Obtain one from your session after logging in — it's sent in the Authorization header of every request. API access is a Pro plan feature.

# Pass your JWT as a Bearer token curl https://api.listingrvaai.com/api/products \ -H "Authorization: Bearer <your-jwt-token>"

Tokens are workspace-scoped. All requests operate within your workspace's credit and rate limit budget. Never expose tokens in client-side code.

Errors

The API uses standard HTTP status codes. All error bodies follow a consistent structure:

{ "error": "error_code", "message": "Human-readable description" }

Code	Meaning
200	Success
400	Bad request — missing or invalid parameter
401	Unauthorized — invalid or missing API key
402	insufficient_credits — not enough credits to run the operation
403	Forbidden — feature not available on your plan
404	Resource not found
429	Rate limit exceeded
500	Internal server error — retry with exponential backoff

Rate Limits

Requests are rate-limited per workspace:

Route group	Limit
/api/ai/*	30 requests / minute
/api/products/*	120 requests / minute
/api/* (global)	200 requests / minute

Generate Image

POST/ai/image

Enqueue an AI image generation job. Credits are deducted atomically on request. Returns a jobId — poll GET /ai/jobs/:id for the result.

Request body

Parameter	Type	Description
productIdrequired	string	ID of the product to generate an image for
stylerequired	string	Image style key — see styles table
platformoptional	string	Target platform: amazon, shopify, flipkart, etc. Applies compliance rules. Default: general
outputSizeoptional	object	{"w":2000,"h":2000} — 1000/1200/1500/2000. Larger sizes add credit surcharge.
primaryImageUrloptional	string	URL of the product image to use as source. Defaults to first product image.
customPromptoptional	string	Additional scene instructions to guide the AI output.
contextoptional	string	Usage context for lifestyle scenes (e.g. kitchen counter)
seasonoptional	string	Seasonal theme for SEASONAL_VARIANT style
aiModeloptional	string	auto \| gemini \| openai. Default: auto

Example request

curl -X POST https://api.listingrvaai.com/api/ai/image \ -H "Authorization: Bearer <your-jwt-token>" \ -H "Content-Type: application/json" \ -d '{ "productId": "prod_abc123", "style": "LIFESTYLE_CONTEXTUAL", "platform": "shopify", "outputSize": { "w": 2000, "h": 2000 } }'

Response

{ "jobId": "job_789xyz", "status": "queued", "creditCost": 9 }

Image Styles

Style key	Credits	Best for
CLEAN_WHITE_BG	4	Amazon/Flipkart hero images, compliance
SHADOW_REFLECTION	4	Studio shadow reflection, premium product look
DIMENSION_SPEC	4	Size charts, reduces returns
INFOGRAPHIC_FEATURE	5	Feature callout overlays
COMPARISON_CHART	5	Amazon A+ side-by-side
FEATURE_CALLOUT_GRID	5	6-tile icon + description grid, Amazon secondary
INGREDIENT_SPEC_LIST	5	Ingredient / spec list panel, transparency plays
BEFORE_AFTER	5	Before/after split — problem to solution frame
SEASONAL_VARIANT	5	Diwali, Christmas, seasonal campaigns
LIFESTYLE_CONTEXTUAL	6	Product in realistic environment
PREMIUM_BRAND_STYLE	6	Dark studio, D2C editorial look
MODEL_LIFESTYLE	7	Model + lifestyle scene
MODEL_STUDIO	7	Model holding product, clean bg
LIFESTYLE_INFOGRAPHIC	7	Lifestyle scene + callout overlay
PACKAGING_DISPLAY	8	Unboxing, full kit in frame
MODEL_LIFESTYLE_INFOGRAPHIC	8	Model + scene + callouts

Size surcharges: 1200px +1cr, 1500px +2cr, 2000px +3cr per image. Amazon platform auto-sets 2000px.

Job Status

GET/ai/jobs/:jobId

Poll for the result of an image generation or listing copy job. Jobs typically complete in 20–60 seconds.

{ "id": "job_789xyz", "type": "image_generation", "status": "completed", // queued | processing | completed | failed "result": { "imageUrl": "https://cdn.listingrvaai.com/...", "imageUrls": ["..."] }, "created_at": "2026-05-18T10:00:00Z", "updated_at": "2026-05-18T10:00:38Z" }

Generate Listing Copy

POST/ai/listing

Generate SEO-optimized listing copy for a product on a specific platform. Returns a jobId.

Parameter	Type	Description
productIdrequired	string	Product ID
platformoptional	string	amazon \| flipkart \| shopify \| woocommerce \| etsy \| bigcommerce \| general
componentsoptional	array	Subset to generate: ["title","bullets","description","keywords"]
seedKeywordsoptional	string	Comma-separated keywords to incorporate
toneoptional	string	professional \| casual \| luxury
targetAudienceoptional	string	Buyer persona description

Listing Credit Costs by Platform

Platform	Credits	Notes
amazon	10	A9/A10 keyword-optimized, 200-char title
flipkart	9	Flipkart search-optimized
shopify / woocommerce / bigcommerce / etsy	8	HTML-friendly descriptions
general	6	Platform-agnostic copy

List Products

GET/products

{ "products": [ { "id": "prod_abc123", "title": "Organic Green Tea — 100g", "category": "Food & Beverage", "images": [{ "url": "https://..." }], "created_at": "2026-05-01T08:00:00Z" } ], "total": 42, "page": 1 }

Supports ?page= and ?limit= (default 20, max 100) query params.

Get Product

GET/products/:id

Create Product

POST/products

Parameter	Type	Description
titlerequired	string	Product name
descriptionoptional	string	Product description
categoryoptional	string	Product category for style recommendations
imageUrloptional	string	Public URL of product image to import

List Assets

GET/assets

Returns all generated and approved images. Filter by ?productId=, ?platform=, or ?style=.

Export ZIP

GET/export/:productId

Generates and returns a signed URL for a ZIP of all approved images for a product, organized by platform subfolder.

{ "downloadUrl": "https://cdn.listingrvaai.com/exports/prod_abc123_1716035200.zip", "expiresAt": "2026-05-18T11:00:00Z" }

Credit Balance

GET/billing/credits

{ "creditsRemaining": 342, "subscriptionCredits": 292, "topupCredits": 50, "plan": "growth", "renewsAt": "2026-06-01T00:00:00Z" }

Next: Webhooks Reference

Subscribe to real-time events for job completion, credit alerts, and billing changes.

Webhook Docs →