# Image generation via URL

{% hint style="info" %}
The `base URL` of a dynamic image is: `https://img.abyssale.com/{dynamicImageId}`
{% endhint %}

Changes can be done just as you would normally do with the REST API except it is directly done in the URL with **query strings**. 

All available properties are listed under the [Element Properties](https://developers.abyssale.com/rest-api/generation/element-properties) pages.

## How to construct the query strings?

Each query string is composed of a key and a value, such as `key=value`. The `key` corresponds to the layer property that needs to be customised and `value` to the property value.

{% hint style="info" %}
`key` is of the following form: `layer_name.property_name`. 
{% endhint %}

*For instance if the design you would like to customise has a `text_title` element and you would like to change its `color`; the key will be `text_title.color`.* 

{% hint style="success" %}
If you would like to change:

* the payload content of a [text](https://developers.abyssale.com/rest-api/generation/element-properties/text) or a [button](https://developers.abyssale.com/rest-api/generation/element-properties/button), 
* the image\_url of an [image](https://developers.abyssale.com/rest-api/generation/element-properties/image) or a [logo](https://developers.abyssale.com/rest-api/generation/element-properties/logo),

the `property_name` can be omitted, such as `layer_name=value`
{% endhint %}

Once all of your changes are defined, the final URL will look like:

`https://img.abyssale.com/{dynamicImageId}?{changes}`

**For instance:**

* the designId is `34j39c5e-31fa-4jdb-b6d4-0c97445fb9b3` 
* the design contains 2 elements: a text element named `text_title` *and an image element named* `company_logo`.
  * The `text_title` *content will be* `Welcome`*, will be white (#FFFFFF) and will have a red* background color (#FF0000).
  * the `company_logo` should contain the following image: <https://uploads-ssl.webflow.com/6214efb2d4b5d94158f2ff03/6218f45ff39a58c8dbf7eb2c_abyssale-logo.svg>

{% hint style="danger" %}
As changes are announced by URL, all values must be URL encoded beforehand.
{% endhint %}

```url
https://img.abyssale.com/34j39c5e-31fa-4jdb-b6d4-0c97445fb9b3?text_title=Welcome&text_title.color=#FFFFFF&text_title.background_color=#FF00000&company_logo=https%3A%2F%2Fuploads-ssl.webflow.com%2F6214efb2d4b5d94158f2ff03%2F6218f45ff39a58c8dbf7eb2c_abyssale-logo.svg
```

#### Simplified Query Parameters for Text and Image Elements

For elements of type **text** or **image**, you can use a simplified format for query parameters when updating their content dynamically.

Instead of specifying a full structured payload, you can directly assign the new content by using the element's layer name as the query parameter key, and the new value as its value.

* For **text elements**, the value should be the updated text content.
* For **image elements**, the value should be the new image URL (`image_url`).

**Example:**

If your dynamic image contains a text layer named `title` and an image layer named `logo`, you can update them like this:

```
?title=Hello%20World&logo=https://example.com/new-logo.png
```

This shorthand approach simplifies API requests by allowing you to just pass `{layerName}={value}` for text and image layers, instead of sending a complex JSON structure.

## How to select a format ? <a href="#how-to-select-a-format" id="how-to-select-a-format"></a>

{% hint style="info" %}
By default the first format of your design will be used.&#x20;
{% endhint %}

The format can be specified in the URL using either its **name** or its **UID** (unique identifier). To use a particular format, include it in the base URL as follows:

For example, if your design ID is `34j39c5e-31fa-4jdb-b6d4-0c97445fb9b3` and you want to generate the `instagram-story` format, the URL would be:

```url
https://img.abyssale.com/34j39c5e-31fa-4jdb-b6d4-0c97445fb9b3/instagram-story
```

**Best Practice:**\
It is recommended to use the **UID** of the format rather than the name to avoid issues if the format name changes in the future.

You can easily retrieve the UID of each format by referring to the [**Get Design Details**](https://developers.abyssale.com/rest-api/designs/design-details) endpoint in the API, which provides all available formats and their corresponding UIDs.

* Using the format uuid will look like:

```url
https://img.abyssale.com/34j39c5e-31fa-4jdb-b6d4-0c97445fb9b3/74c5ee10-c9e8-4433-90e3-3320bab8dff0
```

## Using text variables

As explained in the [**Text Layer**](https://developers.abyssale.com/rest-api/generation/element-properties/text#using-variables-inside-text-content) documentation, text variables can be replaced dynamically.\
When using a dynamic image, you can update a variable by adding it to your query parameters in the format:

`vars.{variableName}={variableValue}`

{% hint style="info" %}
Make sure to URL-encode the variable value to avoid issues with spaces or special characters.
{% endhint %}

**Example:**

`https://img.abyssale.com/34j39c5e-31fa-4jdb-b6d4-0c97445fb9b3/74c5ee10-c9e8-4433-90e3-3320bab8dff0?vars.username=Alice`

If your text layer contains: `{username} Smith`

The `{username}` variable will be replaced with `"Alice"`, resulting in: `Alice Smith`