> ## Documentation Index > Fetch the complete documentation index at: https://cactal.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Generate website images > Generate up to eight website images in parallel over REST or MCP, guide them with existing assets, and use the CDN-hosted results immediately. Cactal can generate new images or edit from existing website images. Every successful result is stored as an ordinary image asset on the same website, so it appears in the asset library and uses the same permanent CDN URLs and image transformations as an upload. When the Cactal agent generates images, the completed turn keeps the thumbnails directly beneath its final response. Select a thumbnail to review the full-size result. If a preview is briefly unavailable, it retries quietly behind its loading state instead of showing a broken image. The same images remain available in the turn's expandable activity. Image generation spends AI credits from the website's organization. Cactal uses the completed provider cost to price images stored successfully. Failed, interrupted, and unstored outputs do not consume credits. Partial batches are capped by the number of delivered images. Images requested by the Cactal agent draw from the credits already reserved for the run instead of reserving separately. If a batch does not fit in the remaining run budget, request fewer images. Direct REST and MCP requests reserve credits for their own batch. ## Choose a profile Call `GET /v1/mediaGeneration/profiles?websiteId=...` before composing a request. Profiles are stable Cactal ids with supported aspect ratios and reference limits. Cactal can improve the provider or model behind a profile without changing your integration. Two profiles are available today. Both support text-to-image generation and reference-guided edits with up to four ready PNG, JPEG, or WebP assets from the same website: * `website-image` for photographs, illustrations, backgrounds, and images where fine detail or demanding composition matters. It prioritizes quality. * `logo` for flat logos, marks, and icons. It prioritizes speed and low cost for complete lockups with the wordmark drawn in, text-only wordmarks, and reference-guided edits, such as extracting a symbol for a favicon. Set `"background": "transparent"` to generate a native transparent PNG. Describe isolated artwork without a surface or shadow. Inspect it on the intended page background for edge residue or missing white details before using it. ## Use image references The Cactal agent is guided to use relevant references for image edits, likeness, style matching, and related variants. It can use images attached to your message even before they appear in the asset library. Tell it which details to preserve and what to change; an existing asset can be reused directly when it already meets the request. The image generator receives only the references explicitly supplied in each item's `referenceAssetIds`. Viewing an image in the conversation does not attach it to a generation request. Use ready PNG, JPEG, or WebP asset ids from the same website, importing public images first when needed. State each reference's role, such as subject identity, illustration style, or composition, in the prompt. For revisions, reference the selected output again. When creating a coordinated set without an existing reference, generate and inspect an initial image before using its asset id in subsequent items. Items within one batch run concurrently and cannot reference outputs from their siblings. Check each result's `referenceCount` and inspect the image to confirm the intended continuity. ## Generate a batch `POST /v1/mediaGeneration` accepts up to 8 items and 8 total outputs. Items run concurrently, so put independent images in one request instead of waiting for serial calls. Each generated asset stores its prompt as the asset `description`; add an optional `category` per item (`logo`, `icon`, `photo`, `illustration`, `screenshot`, `graphic`, `background`, or `other`) so the results stay findable. Set `"background": "transparent"` on an item to receive a native transparent PNG for each output, with its own `colors` and `transparentShare`. The result has `sourceAssetId: null`; no separate opaque copy or background-removal pass is created. See [Transparency and background removal](/docs/concepts/assets#transparency-and-background-removal). ```bash theme={null} curl -X POST "https://api.cactal.ai/v1/mediaGeneration" \ -H "Authorization: Bearer $CACTAL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "websiteId": "V1StGXR8_Z5jdHi6B-myT", "idempotencyKey": "homepage-images-2026-08-28", "items": [ { "prompt": "Editorial photograph of a modern garden studio at dawn", "profile": "website-image", "aspectRatio": "16:9", "outputs": 2, "referenceAssetIds": [] }, { "prompt": "Keep the product unchanged and replace the background with warm limestone", "profile": "website-image", "aspectRatio": "1:1", "outputs": 1, "referenceAssetIds": ["aB3xK9mQpR7sTn2vWc5Yd"] } ] }' ``` `idempotencyKey` is required and is scoped to the website. It identifies one paid attempt but does not cache the response. Reusing it can return a conflict; use a new key only when you intentionally want another generation. The request waits for the batch to complete. Individual items can succeed or fail independently. The result status is `ready` when every item succeeds, `partial` when only some succeed, and `failed` when none succeed. Each item reports `referenceCount`, the number of reference images the model received. Unknown request fields are rejected rather than ignored, so a `referenceAssetIds` placed outside an item fails validation instead of generating without references. ```json theme={null} { "version": 1, "kind": "image_generation", "websiteId": "V1StGXR8_Z5jdHi6B-myT", "status": "ready", "items": [ { "status": "ready", "assets": [ { "id": "generated-asset-id", "filename": "image-1-1.png", "mimeType": "image/png", "byteSize": 1842011, "width": 1536, "height": 1024, "url": "https://cdn.cactal.app/website-assets/generated-asset-id" } ], "error": null, "referenceCount": 0 } ], "creditsCharged": 3.61 } ``` Generation has no separate job history. Successful images persist in the asset library, and credits are charged only for images stored successfully. Failed, interrupted, and unstored outputs do not consume credits. If only part of a multi-image request can be stored, the charge is capped to the delivered images. ## Generate over MCP The same operations appear as `mediaGeneration_catalog` and `mediaGeneration_generate` tools. Tool availability follows website access, and content editors can generate images without a separate approval. Generated images are returned as visual content to compatible agents as well as structured asset metadata. ## Next steps Add generated images to source code or CMS fields through their asset ids and CDN URLs. Give an outside agent access to the same generation operations.