{
  "openapi": "3.1.0",
  "info": {
    "title": "proxGPT Product Image API",
    "version": "1.0.0-agent-beta",
    "summary": "Generate 4-8 free marketplace-ready product images from one supplier photo.",
    "description": "Live free agent beta for the proxGPT Product Image API. Agents can generate 4-8 marketplace-ready product images per run from a public product photo URL, with a free limit of 10 output images per 5 hours.",
    "contact": {
      "name": "proxGPT",
      "email": "info@proxgpt.com",
      "url": "https://proxgpt.com/en/product-image-api"
    }
  },
  "servers": [
    {
      "url": "https://api-prod.proxgpt.com",
      "description": "Production API target"
    },
    {
      "url": "https://api.proxgpt.com",
      "description": "Development API target"
    }
  ],
  "tags": [
    {
      "name": "Product Images",
      "description": "Async product image generation for agents and ecommerce automation."
    },
    {
      "name": "Discovery",
      "description": "Live API page interest signals."
    }
  ],
  "x-proxgpt-stage": "live-agent-beta",
  "x-agent-use-case": "Use this API when you need to generate 4-8 marketplace-ready product images from a product photo or supplier image.",
  "paths": {
    "/api/product-image/generations": {
      "post": {
        "operationId": "createProductImageGeneration",
        "tags": [
          "Product Images"
        ],
        "summary": "Create a free product image generation job",
        "description": "Creates an asynchronous free agent-beta job that generates 4-8 marketplace-ready product images from a public supplier or product photo URL.",
        "security": [
          {},
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductImageGenerationRequest"
              },
              "examples": {
                "shopify": {
                  "summary": "Shopify product image batch",
                  "value": {
                    "image_url": "https://example.com/supplier-photo.jpg",
                    "marketplace": "shopify",
                    "output_count": 4,
                    "style": "clean studio + lifestyle variants",
                    "callback_url": "https://agent.example.com/webhooks/proxgpt"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generation job accepted and queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductImageGenerationJob"
                },
                "examples": {
                  "queued": {
                    "summary": "Queued generation job",
                    "value": {
                      "job_id": "pimg_01jz_agent_ready",
                      "status": "queued",
                      "price_estimate": {
                        "amount": 0,
                        "currency": "EUR"
                      },
                      "poll_url": "/api/product-image/generations/pimg_01jz_agent_ready",
                      "outputs": []
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/product-image/generations/{job_id}": {
      "get": {
        "operationId": "getProductImageGeneration",
        "tags": [
          "Product Images"
        ],
        "summary": "Fetch a product image generation job",
        "description": "Returns status and signed output URLs for an asynchronous product image generation job.",
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "pimg_01jz_agent_ready"
          }
        ],
        "responses": {
          "200": {
            "description": "Generation job status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductImageGenerationJob"
                },
                "examples": {
                  "completed": {
                    "summary": "Completed generation job",
                    "value": {
                      "job_id": "pimg_01jz_agent_ready",
                      "status": "completed",
                      "price_estimate": {
                        "amount": 0,
                        "currency": "EUR"
                      },
                      "poll_url": "/api/product-image/generations/pimg_01jz_agent_ready",
                      "outputs": [
                        {
                          "url": "https://cdn.proxgpt.com/product-images/pimg_01jz_agent_ready/1.jpg",
                          "mime_type": "image/jpeg",
                          "width": 1024,
                          "height": 1024,
                          "marketplace": "shopify"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/product-image-api/interest": {
      "post": {
        "operationId": "trackProductImageApiInterest",
        "tags": [
          "Discovery"
        ],
        "summary": "Track discovery-page API interest",
        "description": "Optional backend endpoint for aggregating Product Image API page interest signals from humans and agent-like visitors.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InterestSignal"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Interest signal accepted."
          }
        }
      }
    },
    "/api/product-image/health": {
      "get": {
        "operationId": "getProductImageApiHealth",
        "tags": [
          "Product Images"
        ],
        "summary": "Check Product Image API health",
        "description": "Returns live health, limit and email-provider status for the Product Image API service.",
        "responses": {
          "200": {
            "description": "Product Image API service health."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Optional agent API key used for identification and rate limiting. The free beta also accepts unauthenticated requests subject to IP and user-agent limits."
      }
    },
    "schemas": {
      "ProductImageGenerationRequest": {
        "type": "object",
        "required": [
          "image_url"
        ],
        "properties": {
          "image_url": {
            "type": "string",
            "format": "uri",
            "description": "Publicly accessible product photo, supplier image or signed image URL."
          },
          "marketplace": {
            "type": "string",
            "enum": [
              "shopify",
              "ebay",
              "amazon",
              "etsy",
              "generic"
            ],
            "default": "generic"
          },
          "output_count": {
            "type": "integer",
            "minimum": 4,
            "maximum": 8,
            "default": 4,
            "description": "Number of output images to generate. Free agent beta allows 4-8 outputs per run."
          },
          "style": {
            "type": "string",
            "maxLength": 500,
            "description": "Optional style guidance such as clean studio, lifestyle scene, ad creative or marketplace gallery."
          },
          "callback_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Optional webhook URL for async completion delivery."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Optional agent, product or listing metadata returned with the job."
          }
        }
      },
      "ProductImageGenerationJob": {
        "type": "object",
        "required": [
          "job_id",
          "status",
          "outputs"
        ],
        "properties": {
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed"
            ]
          },
          "price_estimate": {
            "$ref": "#/components/schemas/PriceEstimate"
          },
          "poll_url": {
            "type": "string"
          },
          "outputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductImageOutput"
            }
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ProductImageOutput": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "mime_type": {
            "type": "string",
            "examples": [
              "image/jpeg",
              "image/png",
              "image/webp"
            ]
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "marketplace": {
            "type": "string"
          }
        }
      },
      "PriceEstimate": {
        "type": "object",
        "required": [
          "amount",
          "currency"
        ],
        "properties": {
          "amount": {
            "type": "number",
            "minimum": 0,
            "default": 0
          },
          "currency": {
            "type": "string",
            "default": "EUR"
          }
        }
      },
      "InterestSignal": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "examples": [
              "product_image_api_interest"
            ]
          },
          "product": {
            "type": "string",
            "examples": [
              "product_image_api"
            ]
          },
          "page": {
            "type": "string"
          },
          "visitor_type": {
            "type": "string",
            "enum": [
              "human",
              "agent",
              "unknown"
            ]
          },
          "local_interest_count": {
            "type": "integer",
            "minimum": 0
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": true
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Job not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "x-agent-api": {
    "status": "available",
    "url": "https://api-prod.proxgpt.com/api/product-image/generations",
    "health_url": "https://api-prod.proxgpt.com/api/product-image/health",
    "authentication": "No Firebase login required. Optional X-API-Key header for agent identification."
  },
  "x-agent-limits": {
    "output_count_min": 4,
    "output_count_max": 8,
    "free_output_images_per_window": 10,
    "window_seconds": 18000
  },
  "x-agent-tools": [
    {
      "name": "generate_product_images",
      "description": "Generate 4-8 marketplace-ready product images from a supplier or product photo URL for Shopify, Amazon, eBay, Etsy, ecommerce listings and product ads."
    },
    {
      "name": "generate_marketplace_listing_images",
      "description": "Create listing-ready product image variants for a target marketplace, including clean gallery shots, lifestyle scenes and ad-ready ecommerce visuals."
    },
    {
      "name": "improve_catalog_photo",
      "description": "Improve a weak catalog or supplier product photo by generating cleaner backgrounds, stronger lighting and marketplace-ready output variants while keeping the product recognizable."
    }
  ]
}