Cactal Media generation API
Generate reference-guided website images that are stored as ordinary Cactal CDN assets.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cactal-ai:cactal-ai-media-generation-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Cactal Ai Media generation API
version: 1.0.0
description: 'Operations tagged Media generation across 2 of this provider''s published API definitions: openapi.json, cactal-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cactal.ai/v1
security:
- apiKey: []
tags:
- name: Media generation
description: Generate reference-guided website images that are stored as ordinary Cactal CDN assets.
paths:
/mediaGeneration/profiles:
get:
operationId: mediaGeneration.catalog
summary: List image-generation profiles
description: Lists stable Cactal image profiles and their supported controls. Provider and model identities are intentionally private.
tags:
- Media generation
parameters:
- name: websiteId
in: query
required: true
schema:
type: string
minLength: 1
responses:
'200':
description: The current image profile catalog.
content:
application/json:
schema:
type: object
properties:
version:
type: string
profiles:
type: array
items:
type: object
properties:
id:
type: string
label:
type: string
description:
type: string
maxReferences:
type: integer
maxOutputs:
type: integer
aspectRatios:
type: array
items:
type: string
required:
- id
- label
- description
- maxReferences
- maxOutputs
- aspectRatios
additionalProperties: false
required:
- version
- profiles
additionalProperties: false
'400':
description: Validation failed. The response `message` names the first invalid field.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'403':
description: The authenticated principal lacks the required capability.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'404':
description: The resource does not exist or is outside the principal’s access scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'429':
description: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
x-cactal-required-capability: mediaGeneration.catalog
x-cactal-read-only: true
x-cactal-destructive: false
x-cactal-idempotent: true
servers:
- url: https://api.cactal.ai/v1
/mediaGeneration:
post:
operationId: mediaGeneration.generate
summary: Generate website images
description: '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.'
tags:
- Media generation
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
websiteId:
type: string
minLength: 1
idempotencyKey:
description: Send the same key when retrying one request so it never generates or bills twice. Omit for a new request.
type: string
minLength: 1
maxLength: 200
items:
minItems: 1
maxItems: 8
type: array
items:
type: object
properties:
prompt:
type: string
minLength: 1
maxLength: 20000
category:
description: Category stored on each generated asset (what it is, not where it is used).
type: string
enum:
- logo
- icon
- photo
- illustration
- screenshot
- graphic
- background
- other
profile:
default: website-image
description: 'Stable Cactal image profile: `website-image` for general imagery, `logo` for flat logos, marks, and icons.'
type: string
enum:
- website-image
- logo
aspectRatio:
default: auto
type: string
enum:
- auto
- '1:1'
- '3:2'
- '2:3'
- '4:3'
- '3:4'
- '16:9'
- '9:16'
- '21:9'
background:
default: opaque
description: '`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.'
type: string
enum:
- opaque
- transparent
outputs:
default: 1
type: integer
minimum: 1
maximum: 8
referenceAssetIds:
default: []
maxItems: 4
type: array
items:
type: string
minLength: 1
required:
- prompt
additionalProperties: false
required:
- websiteId
- items
responses:
'200':
description: The completed image-generation result.
content:
application/json:
schema:
type: object
properties:
version:
type: number
const: 1
kind:
type: string
const: image_generation
websiteId:
type: string
status:
type: string
enum:
- ready
- partial
- failed
items:
type: array
items:
type: object
properties:
status:
type: string
enum:
- ready
- failed
assets:
type: array
items:
type: object
properties:
id:
type: string
filename:
type: string
mimeType:
type: string
byteSize:
type: integer
width:
anyOf:
- type: integer
- type: 'null'
height:
anyOf:
- type: integer
- type: 'null'
colors:
anyOf:
- maxItems: 8
type: array
items:
type: object
properties:
hex:
type: string
description: Uppercase sRGB hex, exact for flat colors.
share:
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
description: 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:
type: boolean
description: Saturated enough to matter as an accent even at a small share.
required:
- hex
- share
- accent
additionalProperties: false
description: Up to 8 representative colors sorted by share. `null` for files and for images that could not be analyzed.
- type: 'null'
transparentShare:
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
description: '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:
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
description: Fraction of pixels with partial alpha (soft shadows, glows, fades, glass), excluding fully transparent and fully opaque pixels. `null` when unknown.
sourceAssetId:
type:
- string
- 'null'
url:
type: string
description: Optimized public CDN URL for display, the same `url` websiteAssets returns.
originalUrl:
type: string
description: Stable public CDN URL for the original bytes. It never expires.
srcSet:
description: Ready-to-use responsive image srcset. `null` when image transformation is unavailable.
type:
- string
- 'null'
required:
- id
- filename
- mimeType
- byteSize
- width
- height
- colors
- transparentShare
- translucentShare
- sourceAssetId
- url
- originalUrl
- srcSet
additionalProperties: false
error:
anyOf:
- type: object
properties:
code:
type: string
message:
type: string
retryable:
type: boolean
required:
- code
- message
- retryable
additionalProperties: false
- type: 'null'
referenceCount:
type: integer
description: Reference images the model received for this item.
required:
- status
- assets
- error
- referenceCount
additionalProperties: false
creditsCharged:
type: number
required:
- version
- kind
- websiteId
- status
- items
- creditsCharged
additionalProperties: false
'400':
description: Validation failed. The response `message` names the first invalid field.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'403':
description: The authenticated principal lacks the required capability.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'404':
description: The resource does not exist or is outside the principal’s access scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'429':
description: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
x-cactal-required-capability: mediaGeneration.generate
x-cactal-read-only: false
x-cactal-destructive: false
x-cactal-idempotent: false
servers:
- url: https://api.cactal.ai/v1
components:
schemas:
ServiceError:
type: object
required:
- kind
- message
description: Canonical error body returned by every non-2xx response. Extra fields carry error-specific details.
properties:
kind:
type: string
enum:
- validation
- unauthorized
- forbidden
- not_found
- conflict
- rate_limited
- internal
description: Stable, machine-readable error category.
message:
type: string
description: Human-readable explanation of the failure.
suggestion:
type: string
description: What to do next when the failure has a known fix; may name the exact operation to call.
validValues:
type: array
items:
type: string
description: The acceptable values for the failing field, when the set is closed.
additionalProperties: true
securitySchemes:
apiKey:
type: http
scheme: bearer
description: Cactal API key. Create one in the dashboard or via `POST /apiKeys`. The plaintext key is shown once at creation.
x-refined-from:
- openapi.json
- cactal-ai-openapi.json