Choose a profile
CallGET /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-imagefor photographs, illustrations, backgrounds, and images where fine detail or demanding composition matters. It prioritizes quality.logofor 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’sreferenceAssetIds. 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.
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.
Generate over MCP
The same operations appear asmediaGeneration_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
Use generated assets
Add generated images to source code or CMS fields through their asset ids and CDN URLs.
Connect over MCP
Give an outside agent access to the same generation operations.