Layers

Layers are composable building blocks within a cell. A single video cell can have multiple layers — text overlays, sound tracks, video clips, captions — that get composed into the final rendered video.

Note

All layer endpoints require the agent_id query parameter.

Layer types

Type	Description	Key attributes
text	Text overlay with font, color, position, and animation	content, styles (fontSize, fontWeight, color, fontFamily, textAlign, animation)
clip	Video clip with trim, volume, and visual effects	src, volume, videoStartTime, styles (objectFit, filter, borderRadius)
sound	Audio track with volume and trim	src, volume, startFromSound
caption	Auto-generated captions with word-level timestamps	captions (array of timestamped words), styles, template
image	Static image overlay	src, styles (objectFit, borderRadius, filter)
shape	Geometric shape overlay	styles (fill, stroke, strokeWidth, borderRadius)

Layer schema

{
  "id": 4000,
  "name": "Background Music",
  "position": 1,
  "type": "sound",
  "additional_attributes": {
    "src": "https://cdn.gen.pro/outputs/audio_001.mp3",
    "from": 0,
    "durationInFrames": 300,
    "totalDuration": 300,
    "styles": { "volume": 0.8 },
    "startFromSound": 30
  },
  "created_at_ts": 1709294400000,
  "updated_at_ts": 1709380800000,
  "default_user_job": null,
  "user_jobs": [],
  "execution_cost": null
}

The additional_attributes object

This is a freeform JSON field that stores the layer’s composition settings. All timing values are in frames (30 fps).

Common fields (all layer types)

Field	Type	Description
from	integer	Start frame on the timeline (0 = beginning of video)
durationInFrames	integer	How many frames this layer is visible/audible
totalDuration	integer	Original duration before any trim
width	number	Width in pixels (for visual layers)
height	number	Height in pixels (for visual layers)
left	number	X position in pixels
top	number	Y position in pixels
rotation	number	Rotation in degrees

Clip (video) fields

Field	Type	Description
src	string	Video URL
videoStartTime	number	Trim start point in the source video (seconds)
styles.volume	number	Volume level: 0 (muted) to 1 (full). Default 1.
styles.objectFit	string	"cover", "contain", "fill", "none"
styles.filter	string	CSS filter (e.g., "brightness(1.2) contrast(1.1)")
styles.borderRadius	string	Corner rounding (e.g., "8px")
styles.animation	object	{ enter: "fadeIn", exit: "fadeOut" }

Sound (audio) fields

Field	Type	Description
src	string	Audio URL
startFromSound	number	Trim start point in the source audio (frames)
styles.volume	number	Volume level: 0 (muted) to 1 (full). Default 1.

Text fields

Field	Type	Description
content	string	The text to display
styles.fontSize	string	Font size (e.g., "48px")
styles.fontFamily	string	Font name
styles.fontWeight	string	"400", "700", etc.
styles.color	string	Text color (hex or CSS color)
styles.textAlign	string	"left", "center", "right"
styles.backgroundColor	string	Background behind text
styles.animation	object	{ enter: "fadeIn", exit: "fadeOut" }

Caption fields

Field	Type	Description
captions	array	Array of { text, startMs, endMs, words: [{ word, startMs, endMs }] }
template	string	Caption style template name
styles	object	Font, color, highlight styles for active words

Tip

To adjust volume, trim, or timing on an existing layer, use the Update layer endpoint and pass the new values inside additional_attributes.

---

Create layer

Adds a new layer to a cell.

POST /v1/autocontentengine/{id}/cells/{cell_id}/layers?agent_id={agent_id}

Path parameters

Parameter	Type	Description
id	integer	The sheet ID.
cell_id	integer	The cell ID.

Request body

Field	Type	Required	Description
video_layer.name	string	Yes	Layer name (e.g., "Sound Effect").
video_layer.type	string	Yes	Layer type.
video_layer.position	integer	No	Insert at a specific position. Appended to the end if omitted.

Response (201)

Returns the created layer.

Example

curl -X POST "https://api.gen.pro/v1/autocontentengine/101/cells/3000/layers?agent_id=42" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"video_layer": {"name": "Background Music", "type": "audio"}}'

---

Get layer

Returns a single layer with its generation history.

GET /v1/autocontentengine/{id}/cells/{cell_id}/layers/{layer_id}?agent_id={agent_id}

Path parameters

Parameter	Type	Description
id	integer	The sheet ID.
cell_id	integer	The cell ID.
layer_id	integer	The layer ID.

Response

Returns the full layer object.

Example

curl "https://api.gen.pro/v1/autocontentengine/101/cells/3000/layers/4000?agent_id=42" \
  -H "X-API-Key: your-api-key"

---

Update layer

Updates a layer’s name, type, or composition attributes (volume, trim, position, styles, etc.).

PATCH /v1/autocontentengine/{id}/cells/{cell_id}/layers/{layer_id}?agent_id={agent_id}

Path parameters

Parameter	Type	Description
id	integer	The sheet ID.
cell_id	integer	The cell ID.
layer_id	integer	The layer ID.

Request body

Field	Type	Required	Description
video_layer.name	string	No	Rename the layer.
video_layer.type	string	No	Change layer type.
video_layer.additional_attributes	object	No	Update composition settings (volume, trim, position, styles).

Examples

Rename a layer:

curl -X PATCH "https://api.gen.pro/v1/autocontentengine/101/cells/3000/layers/4000?agent_id=42" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"video_layer": {"name": "Intro Music"}}'

Set volume to 50%:

curl -X PATCH "https://api.gen.pro/v1/autocontentengine/101/cells/3000/layers/4000?agent_id=42" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"video_layer": {"additional_attributes": {"styles": {"volume": 0.5}}}}'

Trim a clip (start at frame 60, show for 150 frames):

curl -X PATCH "https://api.gen.pro/v1/autocontentengine/101/cells/3000/layers/4001?agent_id=42" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"video_layer": {"additional_attributes": {"from": 60, "durationInFrames": 150}}}'

Move a text overlay and change its style:

curl -X PATCH "https://api.gen.pro/v1/autocontentengine/101/cells/3000/layers/4002?agent_id=42" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"video_layer": {"additional_attributes": {"left": 50, "top": 400, "styles": {"fontSize": "64px", "color": "#ffffff", "fontWeight": "700"}}}}'

Response

Returns the updated layer.

---

Delete layer

Removes a layer from a cell.

DELETE /v1/autocontentengine/{id}/cells/{cell_id}/layers/{layer_id}?agent_id={agent_id}

Path parameters

Parameter	Type	Description
id	integer	The sheet ID.
cell_id	integer	The cell ID.
layer_id	integer	The layer ID.

Response (204)

No content.

Example

curl -X DELETE "https://api.gen.pro/v1/autocontentengine/101/cells/3000/layers/4000?agent_id=42" \
  -H "X-API-Key: your-api-key"

---

Duplicate layer

Creates a copy of a layer.

POST /v1/autocontentengine/{id}/cells/{cell_id}/layers/{layer_id}/duplicate?agent_id={agent_id}

Path parameters

Parameter	Type	Description
id	integer	The sheet ID.
cell_id	integer	The cell ID.
layer_id	integer	The layer ID to duplicate.

Response (201)

Returns the newly created layer.

Example

curl -X POST "https://api.gen.pro/v1/autocontentengine/101/cells/3000/layers/4000/duplicate?agent_id=42" \
  -H "X-API-Key: your-api-key"

---

Update layer positions

Reorders layers within a cell.

PUT /v1/autocontentengine/{id}/cells/{cell_id}/layers/update_positions?agent_id={agent_id}

Request body

Field	Type	Required	Description
layers	array	Yes	Array of {id, position} objects.

Example

curl -X PUT "https://api.gen.pro/v1/autocontentengine/101/cells/3000/layers/update_positions?agent_id=42" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"layers": [{"id": 4000, "position": 2}, {"id": 4001, "position": 1}]}'

Response

Returns the updated layers.

Errors

Status	Error code	Description
404	not_found	Sheet, cell, or layer not found.
422	validation_error	Invalid layer data.