---
title: "Generate website images"
method: POST
path: "/mediaGeneration"
tags: ["Media generation"]
---

# Generate website images

`POST /mediaGeneration`

## Request

- Base URL: `https://api.cactal.ai/v1`
- URL: `https://api.cactal.ai/v1/mediaGeneration`
- Auth: HTTP bearer

Generates up to eight images in one batch. Items run concurrently, may use same-website image references, and successful outputs become ordinary website assets. An item with `background: "transparent"` stores each output as a native transparent PNG without a separate opaque copy.

## Request body

- object
  - `websiteId` string, required
  - `idempotencyKey` string: Send the same key when retrying one request so it never generates or bills twice. Omit for a new request.
  - `items` object[], required
    - `prompt` string, required
    - `category` 'logo' | 'icon' | 'photo' | 'illustration' | 'screenshot' | 'graphic' | 'background' | 'other': Category stored on each generated asset (what it is, not where it is used).
    - `profile` 'website-image' | 'logo': Stable Cactal image profile: `website-image` for general imagery, `logo` for flat logos, marks, and icons.
    - `aspectRatio` 'auto' | '1:1' | '3:2' | '2:3' | '4:3' | '3:4' | '16:9' | '9:16' | '21:9'
    - `background` 'opaque' | 'transparent': `transparent` generates and stores a native transparent PNG for each output, with its own `colors` and `transparentShare`; no separate opaque copy or background-removal pass is created.
    - `outputs` integer
    - `referenceAssetIds` string[]

## Response `200`

The completed image-generation result.

- object
  - `version` 1, required
  - `kind` 'image_generation', required
  - `websiteId` string, required
  - `status` 'ready' | 'partial' | 'failed', required
  - `items` object[], required
    - `status` 'ready' | 'failed', required
    - `assets` object[], required
      - `id` string, required
      - `filename` string, required
      - `mimeType` string, required
      - `byteSize` integer, required
      - `width` integer, nullable, required
      - `height` integer, nullable, required
      - `colors` object[], nullable, required: Up to 8 representative colors sorted by share. `null` for files and for images that could not be analyzed.
        - `hex` string, required: Uppercase sRGB hex, exact for flat colors.
        - `share` number, nullable, required: Fraction of opaque pixels this color and its anti-aliasing cover. `null` for SVG, whose colors are read from the source instead of rendered.
        - `accent` boolean, required: Saturated enough to matter as an accent even at a small share.
      - `transparentShare` number, nullable, required: Fraction of the backdrop that shows through, weighting each pixel by its transparency: 0 for an opaque image, roughly the background area for a cutout, 0.5 for a uniform 50% overlay. `null` when unknown.
      - `translucentShare` number, nullable, required: Fraction of pixels with partial alpha (soft shadows, glows, fades, glass), excluding fully transparent and fully opaque pixels. `null` when unknown.
      - `sourceAssetId` string, nullable, required
      - `url` string, required: Optimized public CDN URL for display, the same `url` websiteAssets returns.
      - `originalUrl` string, required: Stable public CDN URL for the original bytes. It never expires.
      - `srcSet` string, nullable, required: Ready-to-use responsive image srcset. `null` when image transformation is unavailable.
    - `error` object, nullable, required
      - `code` string, required
      - `message` string, required
      - `retryable` boolean, required
    - `referenceCount` integer, required: Reference images the model received for this item.
  - `creditsCharged` number, required

## Other responses

- `400`: Validation failed. The response `message` names the first invalid field.
- `401`: Missing, invalid, expired, or revoked API key.
- `403`: The authenticated principal lacks the required capability.
- `404`: The resource does not exist or is outside the principal’s access scope.
- `429`: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.

---

[API](https://skmtc.dev/cactal/apis/cactal-api.md) · [All operations](https://skmtc.dev/cactal/apis/cactal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cactal/apis/cactal-api/revisions/9cd0fb5eacdd?raw)