> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aigenstudio.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Product Photo job

> Creates an asynchronous Product Photo job. Live keys consume paid API credits. Sandbox keys validate the request and return simulated results without calling paid providers or consuming credits.



## OpenAPI

````yaml /openapi.yaml post /product-photo-jobs
openapi: 3.1.0
info:
  title: AI Gen Studio Product Photo API
  version: 1.0.0
  summary: Product Photo workflow API for commerce catalogs.
  description: >-
    The Product Photo API turns raw product photos into cleaner ecommerce
    visuals while preserving the real product, packaging, labels, logos,
    proportions, and color identity. Use sandbox keys for integration tests and
    live keys for paid catalog processing.
servers:
  - url: https://aigenstudio.app/api/v1
    description: Production
security:
  - bearerApiKey: []
tags:
  - name: Product Photo API
    description: Create Product Photo jobs and discover supported operations and presets.
paths:
  /product-photo-jobs:
    post:
      tags:
        - Product Photo API
      summary: Create a Product Photo job
      description: >-
        Creates an asynchronous Product Photo job. Live keys consume paid API
        credits. Sandbox keys validate the request and return simulated results
        without calling paid providers or consuming credits.
      operationId: createProductPhotoJob
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductPhotoJobCreateRequest'
            examples:
              live:
                summary: Live marketplace cleanup
                value:
                  operation: marketplace_clean
                  preset: marketplace_clean_catalog
                  preservation_level: strict
                  instructions: Keep the packaging, label, and product color unchanged.
                  webhook_url: https://client.example/webhooks/aigenstudio
                  images:
                    - source_url: https://client.example/images/yogurt-001.jpg
                      external_id: yogurt-001
              sandbox:
                summary: Sandbox integration test
                value:
                  operation: studio_packshot
                  preset: single_product_white_background
                  preservation_level: strict
                  images:
                    - source_url: https://example.com/product.jpg
                      external_id: local-test-001
      responses:
        '200':
          description: Existing idempotent Product Photo job returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductPhotoJobCreateResponse'
        '202':
          description: Product Photo job accepted and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductPhotoJobCreateResponse'
        '400':
          $ref: '#/components/responses/InvalidPayload'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '402':
          $ref: '#/components/responses/InsufficientApiCredits'
        '403':
          $ref: '#/components/responses/ApiAccessNotEnabled'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          $ref: '#/components/responses/ContentPolicyViolation'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 160
      description: Stable key for safely retrying one logical create request.
    RequestIdHeader:
      name: X-Request-Id
      in: header
      required: false
      schema:
        type: string
        maxLength: 160
      description: Optional client correlation id. AI Gen Studio also returns `request_id`.
  schemas:
    ProductPhotoJobCreateRequest:
      type: object
      required:
        - images
      properties:
        operation:
          $ref: '#/components/schemas/ProductPhotoOperationId'
        preset:
          type: string
          description: Preset id returned by `GET /product-photo-presets`.
        preservation_level:
          $ref: '#/components/schemas/PreservationLevel'
        instructions:
          type: string
          minLength: 1
          maxLength: 4000
        webhook_url:
          type: string
          format: uri
          maxLength: 2048
        images:
          type: array
          minItems: 1
          maxItems: 20
          items:
            $ref: '#/components/schemas/ProductPhotoSourceImage'
    ProductPhotoJobCreateResponse:
      type: object
      required:
        - job
        - remaining_paid_credits
        - request_id
      properties:
        job:
          $ref: '#/components/schemas/ProductPhotoJobSummary'
        remaining_paid_credits:
          type: integer
          minimum: 0
        request_id:
          type: string
    ProductPhotoOperationId:
      type: string
      enum:
        - product_photo_enhance
        - remove_background
        - studio_packshot
        - marketplace_clean
        - natural_lifestyle
        - premium_ad
    PreservationLevel:
      type: string
      default: strict
      enum:
        - strict
        - balanced
        - creative
    ProductPhotoSourceImage:
      type: object
      required:
        - source_url
      properties:
        source_url:
          type: string
          format: uri
          maxLength: 2048
        external_id:
          type: string
          minLength: 1
          maxLength: 160
          description: Your product, SKU, or catalog id.
    ProductPhotoJobSummary:
      type: object
      required:
        - credits_reserved
        - id
        - sandbox
        - status
        - total_items
      properties:
        id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/ProductPhotoJobStatus'
        total_items:
          type: integer
          minimum: 1
        credits_reserved:
          type: integer
          minimum: 0
        sandbox:
          type: boolean
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
    ProductPhotoJobStatus:
      type: string
      enum:
        - queued
        - processing
        - completed
        - partially_completed
        - failed
        - cancelled
  responses:
    InvalidPayload:
      description: Payload, query parameter, or idempotency header is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InvalidApiKey:
      description: API key is missing, invalid, expired, inactive, or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InsufficientApiCredits:
      description: The account does not have enough API-eligible paid credits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ApiAccessNotEnabled:
      description: Live API access requires eligible paid credits and an active account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    IdempotencyConflict:
      description: The idempotency key was already used with a different request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ContentPolicyViolation:
      description: The request violates the Product Photo content policy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimitExceeded:
      description: The request exceeded an API rate or concurrency limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: AI Gen Studio API key

````