API Documentation

Everything you need to integrate ProdVisual's image generation API into your application.

Introduction

The ProdVisual API is a RESTful service that generates AI-powered product visuals optimized for e-commerce platforms and digital marketplaces. Submit a product image via API and receive professionally styled output images within seconds.

All API requests and responses use JSON format. The API is designed to be simple to integrate — most developers are up and running within 15 minutes.

API Version: v1 (current) — All endpoints are stable and production-ready. Breaking changes will be introduced under a new version prefix.

Authentication

All API requests require authentication via a Bearer token in the Authorization header. You receive your API key after purchasing credits.

curl https://api.prodvisual.com/v1/account/credits \
  -H "Authorization: Bearer pv_live_a1b2c3d4e5f6..."

API keys are prefixed with pv_live_ for production and pv_test_ for sandbox mode. Keep your API key secure — do not expose it in client-side code or public repositories.

Security: Never embed your API key in frontend JavaScript, mobile apps, or public repositories. All API calls should be made from your backend server.

Base URL

All API requests should be made to the following base URL:

https://api.prodvisual.com/v1

The API is served over HTTPS only. HTTP requests will be rejected.

Rate Limits

To ensure fair usage and service stability, the following rate limits apply:

Requests / Minute

10K

Requests / Day

Images / Batch

Rate limit headers are included in every API response:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Exceeding rate limits returns a 429 Too Many Requests response. Need higher limits? Contact us at support@prodvisual.com for enterprise plans.

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has 0 credits remaining. Please purchase more credits to continue.",
    "status": 402
  }
}

Status	Code	Description
`400`	`invalid_request`	Missing or invalid parameters
`401`	`unauthorized`	Invalid or missing API key
`402`	`insufficient_credits`	No credits remaining
`404`	`not_found`	Resource not found
`413`	`file_too_large`	Uploaded image exceeds 10MB
`422`	`invalid_image`	Image format not supported
`429`	`rate_limited`	Too many requests
`500`	`server_error`	Internal server error

Generate Image

POST /v1/generate

Generate a single AI-powered product visual from a source image. Consumes 1 credit per successful generation.

Request Body

Parameter	Type	Required	Description
`image_url`	string	required	URL of the source product image (JPEG, PNG, WebP). Max 10MB.
`style`	string	required	Visual style to apply. See /v1/styles for available options.
`platform`	string	optional	Target platform preset (`amazon`, `ebay`, `etsy`, `shopify`, `generic`). Defaults to `generic`.
`dimensions`	string	optional	Output size in `WxH` format (e.g. `1500x1500`). Defaults to platform preset.
`background`	string	optional	Background color hex code (e.g. `#ffffff`) or `transparent`. Only applicable to certain styles.
`format`	string	optional	Output format: `png`, `jpeg`, or `webp`. Defaults to `png`.
`quality`	integer	optional	JPEG/WebP quality 1-100. Defaults to `90`.
`webhook_url`	string	optional	URL to receive a POST callback when generation completes (for async processing).

Example Request

curl -X POST https://api.prodvisual.com/v1/generate \
  -H "Authorization: Bearer pv_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/my-product.jpg",
    "style": "lifestyle",
    "platform": "amazon",
    "format": "png"
  }'

Response

{
  "id": "gen_7kX2mP9qR4",
  "status": "completed",
  "output_url": "https://cdn.prodvisual.com/output/gen_7kX2mP9qR4.png",
  "style": "lifestyle",
  "platform": "amazon",
  "dimensions": "1500x1500",
  "format": "png",
  "file_size": 847293,
  "credits_used": 1,
  "credits_remaining": 49,
  "generation_time_ms": 2340,
  "created_at": "2026-03-05T14:32:10Z",
  "expires_at": "2026-03-12T14:32:10Z"
}

Output URLs expire after 7 days. Download and store images on your own infrastructure for permanent access.

Batch Generate

POST /v1/generate/batch

Generate multiple product visuals in a single request. Consumes 1 credit per image. Maximum 50 images per batch.

Request Body

Parameter	Type	Required	Description
`items`	array	required	Array of generation objects (same schema as /v1/generate). Max 50 items.
`webhook_url`	string	optional	URL to receive a POST callback when the entire batch completes.

Example Request

curl -X POST https://api.prodvisual.com/v1/generate/batch \
  -H "Authorization: Bearer pv_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "image_url": "https://example.com/product1.jpg", "style": "lifestyle" },
      { "image_url": "https://example.com/product2.jpg", "style": "white_bg" },
      { "image_url": "https://example.com/product3.jpg", "style": "mockup" }
    ],
    "webhook_url": "https://yoursite.com/webhook/prodvisual"
  }'

Response

{
  "batch_id": "batch_Qx8mR2kP",
  "status": "processing",
  "total_items": 3,
  "credits_used": 3,
  "credits_remaining": 46,
  "estimated_time_ms": 8500,
  "results_url": "https://api.prodvisual.com/v1/generations/batch_Qx8mR2kP"
}

List Styles

GET /v1/styles

Returns all available visual generation styles. No authentication required.

Response (excerpt)

{
  "styles": [
    { "id": "lifestyle", "name": "Lifestyle Shot", "description": "Product in a natural setting" },
    { "id": "white_bg", "name": "Clean White Background", "description": "Studio-quality white background" },
    { "id": "mockup", "name": "Product Mockup", "description": "3D mockup on clean surface" },
    { "id": "infographic", "name": "Infographic", "description": "Feature callout layout" },
    { "id": "social_square", "name": "Social Media (1:1)", "description": "Square format for Instagram/Facebook" },
    { "id": "social_story", "name": "Social Media (9:16)", "description": "Vertical format for Stories/Reels" },
    { "id": "hero_banner", "name": "Hero Banner", "description": "Wide banner for storefront headers" },
    { "id": "comparison", "name": "Before/After", "description": "Side-by-side comparison layout" },
    // ... 14 more styles
  ],
  "total": 22
}

Check Credits

GET /v1/account/credits

Returns your current credit balance and usage statistics.

Response

{
  "credits_remaining": 142,
  "credits_used_total": 858,
  "credits_used_today": 23,
  "last_purchase": {
    "amount": 100,
    "date": "2026-03-01T09:15:00Z"
  }
}

Generation Status

GET /v1/generations/{id}

Retrieve the status and result of a generation or batch request. Useful for polling async requests.

Response

{
  "id": "gen_7kX2mP9qR4",
  "status": "completed",  // pending | processing | completed | failed
  "output_url": "https://cdn.prodvisual.com/output/gen_7kX2mP9qR4.png",
  "generation_time_ms": 2340,
  "created_at": "2026-03-05T14:32:10Z",
  "expires_at": "2026-03-12T14:32:10Z"
}

Webhooks

For async processing (especially batch requests), you can provide a webhook_url parameter. When the generation completes, we'll send a POST request to your URL with the result payload.

Webhook Payload

{
  "event": "generation.completed",
  "data": {
    "id": "gen_7kX2mP9qR4",
    "status": "completed",
    "output_url": "https://cdn.prodvisual.com/output/gen_7kX2mP9qR4.png",
    "credits_used": 1
  },
  "timestamp": "2026-03-05T14:32:12Z"
}

Webhook requests include a X-ProdVisual-Signature header for verification. Compute HMAC-SHA256 of the raw request body using your API key as the secret, and compare with the signature header.

SDKs & Libraries

Official SDKs are available for popular languages:

Language	Package	Install
Python	`prodvisual`	`pip install prodvisual`
Node.js	`prodvisual`	`npm install prodvisual`
PHP	`prodvisual/sdk`	`composer require prodvisual/sdk`
Go	`prodvisual-go`	`go get github.com/prodvisual/prodvisual-go`

Python Example

from prodvisual import ProdVisual

client = ProdVisual(api_key="pv_live_a1b2c3d4...")

result = client.generate(
    image_url="https://example.com/product.jpg",
    style="lifestyle",
    platform="amazon"
)

print(result.output_url)  # https://cdn.prodvisual.com/output/...
print(result.credits_remaining)  # 49

Node.js Example

const { ProdVisual } = require('prodvisual');

const client = new ProdVisual('pv_live_a1b2c3d4...');

const result = await client.generate({
  imageUrl: 'https://example.com/product.jpg',
  style: 'lifestyle',
  platform: 'amazon'
});

console.log(result.outputUrl);

Changelog

v1.2.0 — March 1, 2026

Added hero_banner and comparison styles
Batch endpoint now supports up to 50 images (was 20)
Improved generation speed by ~30%

v1.1.0 — January 15, 2026

Added webhook support for async processing
Added format and quality parameters
New platform presets: WooCommerce, Mercado Libre

v1.0.0 — November 6, 2025

Initial API release
Core endpoints: generate, batch, styles, credits, status
15 visual styles, 5 platform presets