# Create a dynamic image by API

By sending a **POST** request to the `/designs/{designId}/dynamic-image-url` endpoint, you can generate a customized image URL based on your design and the parameters you specify.

{% hint style="info" %}
You can also use this endpoint to retrieve the dynamic image URLs for a design. If the dynamic image has already been created, it will simply return the existing URLs.
{% endhint %}

**Endpoint**

## Create a dynamic image

> Creates a dynamic image URL for a given design. Only one dynamic image is allowed per design. Subsequent calls return the existing dynamic image. Use \`enable\_rate\_limit\` in the request body to enable API rate limiting for this image & \`enable\_production\_mode\` to enable production mode (default is test mode).

```json
{"openapi":"3.0.3","info":{"title":"API Reference - Abyssale","version":"0.0.1"},"tags":[{"name":"Dynamic Images","description":"Dynamic images are customizable URLs with query parameters that allow you to instantly modify text, \ncolors, images, and more within a design.\n"}],"servers":[{"url":"https://api.abyssale.com","description":"Main Production Server"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"description":"All of your Abyssale requests must contain a `x-api-key header` with your API Key.","type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"DynamicImageResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the dynamic image"},"design_id":{"type":"string","description":"Design ID associated with this dynamic image"},"formats":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Format name"},"uid":{"type":"string","description":"Format unique identifier (UUID)"},"width":{"type":"integer","description":"Width of the format in pixels"},"unit":{"type":"string","description":"Unit of measurement for dimensions, e.g. px"},"height":{"type":"integer","description":"Height of the format in pixels"},"dynamic_image_url":{"type":"string","format":"uri","description":"URL to the dynamically generated image for this format"}},"required":["id","uid","width","unit","height","dynamic_image_url"]},"description":"List of formats available for this dynamic image"}},"required":["id","design_id","formats"]}}},"paths":{"/designs/{designId}/dynamic-image-url":{"post":{"tags":["Dynamic Images"],"summary":"Create a dynamic image","description":"Creates a dynamic image URL for a given design. Only one dynamic image is allowed per design. Subsequent calls return the existing dynamic image. Use `enable_rate_limit` in the request body to enable API rate limiting for this image & `enable_production_mode` to enable production mode (default is test mode).","parameters":[{"name":"designId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of the design"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enable_rate_limit":{"type":"boolean","default":false,"description":"Enable API rate limiting for this dynamic image"},"enable_production_mode":{"type":"boolean","default":false,"description":"Enable Production mode for this dynamic image"}},"required":["elements"]}}}},"responses":{"200":{"description":"Existing dynamic image retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DynamicImageResponse"}}}},"201":{"description":"Dynamic image successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DynamicImageResponse"}}}},"404":{"description":"Design Not found"}}}}}}
```

***

**Important Notes**

* **Uniqueness:** Only one dynamic image can be created per design.
* **Idempotency:** Calling this endpoint multiple times for the same design will return the already created dynamic image rather than creating a new one (and will not modify the existing one).
* **HTTP Status Codes:**
  * `201 Created` is returned when a new dynamic image is successfully created.
  * `200 OK` is returned if the dynamic image already exists and is returned again.

#### Side Notes

The dynamic image url for each format can also be retrieved in the [Get design details](/rest-api/designs/design-details.md) endpoint (if the dynamic image has already been created).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.abyssale.com/dynamic-images/create-a-dynamic-image-by-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.