Visual Versioning

Visual Versioning lets you update a previously generated visual without changing its unique sharing_id. This keeps external links stable while tracking iterative changes internally.

How versioning works

1. Pass the id of an existing visual in the new generation request via original_visual_id
2. Abyssale creates a new visual with a new id but the same sharing_id
3. The version number increments by +1
4. The view_url associated with the sharing_id automatically points to the new version

API Configuration

Include original_visual_id in the request body:

Property	Type	Description
original_visual_id	string (UUID v4)	The id of the existing visual to create a new version for

Example

POST https://api.abyssale.com/banner-builder/{designId}/generate

{
  "original_visual_id": "a14e1d26-ff41-47cb-bbf9-8f2d777a5bd7",
  "elements": {
    "text_field": {
      "payload": "Updated Content for V2"
    }
  }
}

Constraints

Method	Constraint
Synchronous API	None
Asynchronous API	The request must target exactly one format (the original visual's format). Targeting more answers 400 with id: more_than_one_format.

Response properties

Property	Description
id	New UUID unique to this version
sharing_id	Shared identifier linking all versions of this visual. Preserved from the original visual across all new versions.
version	Incremented (e.g. 1 → 2)
view_url	When present (platform-tracked visuals), it points to the new latest version.

{
  "id": "9c31e7ba-52f0-4c8a-8f6e-2d5b0a1c4e77",
  "version": 2,
  "sharing_id": "5fcec999-2bfb-4dd7-ba38-2d9e16c49149",
  "file": { "type": "jpeg", "url": "…", "cdn_url": "…", "filename": "…" }
}

Errors

Status	id	When
404	visual_not_found	Unknown original_visual_id.
404	not_related_to_same_template	The visual belongs to another design.
404	not_related_to_same_format	The visual belongs to another format of the same design.
400	more_than_one_format	Async request targeting more than one format.

Related

• Generate Single Image — returns the id used for versioning
• Asynchronous Generation — versioning works there too, one format at a time