# Images
## Create image synchronously
`POST` `https://api.usestencil.com/v1/images/sync`
Create image synchronously and get the result in within the same request.
#### Request Body
| Name | Type | Description |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| modifications | array | Array of modification objects |
| metadata | object | Extra metadata to be included together with the webhook |
| webhook\_url | string | URL of the webhook to be called when the image is done processing |
| template | string | The ID of the template |
| transparent | boolean | Set image background transparency |
| png\_multiplier | integer | Set the quality of PNG image. Must be greater or equal to 1. See [Image Quality](#undefined) section. |
| jpeg\_quality | float | Set the quality of JPEG image. Must be between 0 and 1 with 1 being the highest quality. See [Image Quality](#undefined) section. |
{% tabs %}
{% tab title="200 Image generated successfully " %}
```json
{
"id": "05e15531-b80d-4ca0-a658-203d68cd2216",
"status": "completed",
"self": "https://api.usestencil.com/v1/images/05e15531-b80d-4ca0-a658-203d68cd2216",
"log": "{}",
"metadata": {},
"template_id": "1688a5ed-ccdb-477d-a7d5-629a5d4d72ff",
"webhook_url": null,
"webhook_response_body": null,
"webhook_response_code": null,
"created_at": "2025-09-22T03:52:00.482Z",
"modifications": [
{
"name": "category",
"text": "1...2...3...Bougeons pour I.R.I.S.E"
},
{
"name": "distance",
"text": "10 KM"
},
{
"name": "logo",
"src": "https://i.ibb.co/wF2sybRX/Logo-IRISE-2.png"
},
{
"name": "name",
"text": "Malo J"
},
{
"name": "number",
"text": "00035"
},
{
"name": "qrcode",
"value": "https://usestencil.com",
"visible": false
}
],
"image_url": "https://cdn.usestencil.com/images/1688a5ed-ccdb-477d-a7d5-629a5d4d72ff/05e15531-b80d-4ca0-a658-203d68cd2216.png",
"image_url_jpg": "https://cdn.usestencil.com/images/1688a5ed-ccdb-477d-a7d5-629a5d4d72ff/05e15531-b80d-4ca0-a658-203d68cd2216.jpeg"
}
```
{% endtab %}
{% endtabs %}
## Create image asynchronously
`POST` `https://api.usestencil.com/v1/images`
Create image asynchronously. Once image is done processing, the specified webhook is called with the generated image.
#### Request Body
| Name | Type | Description |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| modifications | array | Array of modifications objects |
| metadta | object | Extra metadata to be included together with the webhook |
| webhook\_url | string | URL of the webhook to be called when the image is done processing |
| template | string | The ID of the template |
| transparent | boolean | Set image background transparency |
| png\_multiplier | integer | Set the quality of PNG image. Must be greater or equal to 1. See [Image Quality](#undefined) section. |
| jpeg\_quality | float | Set the quality of JPEG image. Must be between 0 and 1 with 1 being the highest quality. See [Image Quality](#undefined) section. |
{% tabs %}
{% tab title="201: Created Image is sent to processing" %}
```json
{
"id": "05e15531-b80d-4ca0-a658-203d68cd2216",
"status": "pending",
"self": "https://api.usestencil.com/v1/images/05e15531-b80d-4ca0-a658-203d68cd2216",
"log": "{}",
"metadata": {},
"template_id": "1688a5ed-ccdb-477d-a7d5-629a5d4d72ff",
"webhook_url": null,
"webhook_response_body": null,
"webhook_response_code": null,
"created_at": "2025-09-22T03:52:00.482Z",
"modifications": [
{
"name": "category",
"text": "1...2...3...Bougeons pour I.R.I.S.E"
},
{
"name": "distance",
"text": "10 KM"
},
{
"name": "logo",
"src": "https://i.ibb.co/wF2sybRX/Logo-IRISE-2.png"
},
{
"name": "name",
"text": "Malo J"
},
{
"name": "number",
"text": "00035"
},
{
"name": "qrcode",
"value": "https://usestencil.com",
"visible": false
}
],
"image_url": null,
"image_url_jpg": null
}
```
{% endtab %}
{% endtabs %}
### Modification object
Modification object generally follows the following pattern,
```javascript
"modifications": [
{
"name": "text_1",
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do..."
},
{
"name": "rating_3",
"rating": 3.5
}
]
```
`name` is a required property.
{% hint style="info" %}
The `name` is the field unique identifier in the template editor
{% endhint %}
The rest of the properties depend on the type of object. If you need full list of supported properties, you can view them in them in API Console.
### Image Quality
#### PNG
For PNG images, you can set `png_multiplier` to adjust the quality of generated images.
For example, if your template size is 800x800 then setting the `png_multiplier` to 2 will scale the image to 1600x1600 which creates a higher resolution image.
Please note that higher quality image will increase the image size and will also increase the image generation time.
#### JPEG
For JPEG images, you can set `jpeg_quality` to adjust the quality of generated images. JPEG is a lossy format, while it offers higher compression rate that could decrease the file size, it also degrades the image quality.
You can control this by setting `jpeg_quality` to a number between 0 and 1 with 1 being the highest quality.
Please note that higher quality image will increase the image size and will also increase the image generation time.
#### Default Settings
You can also set a default settings for all templates in your project. Go to your project's settings page and set the values accordingly.
You can always override these values in the API by following the instructions mentioned above.
## Search generated images
`POST` `/v1/images/search?q=`
Search for generated images based on your modification inputs. It searches for given query in your modification inputs. Query is case insensitive.
**Response**
{% tabs %}
{% tab title="200" %}
```json
{
"meta": {
"next": null,
"total_count": 2,
"previous": null
},
"results": [
{
"id": "4034dee3-039a-466e-b4ba-0c2fb721036a",
"status": "completed",
"self": "http://api.usestencil.com/v1/images/4034dee3-039a-466e-b4ba-0c2fb721036a",
"log": "{}",
"metadata": {},
"created_at": "2025-09-22T14:39:25.624Z",
"template_id": "8be62eca-72de-4f81-9edc-a4dbeee6986f",
"webhook_url": null,
"modifications": [
{
"name": "rect_4"
},
{
"name": "image",
"src": "https://images.unsplash.com/photo-1503327431567-3ab5e6e79140?q=80&w=3328&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
},
{
"name": "product",
"text": "JEANS"
},
{
"name": "price",
"text": "$49.99"
},
{
"name": "qrcode_5",
"value": "https://usestencil.com"
}
],
"image_url": "https://usestencil.s3.amazonaws.com/dev/images/8be62eca-72de-4f81-9edc-a4dbeee6986f/4034dee3-039a-466e-b4ba-0c2fb721036a.png",
"image_url_jpg": "https://usestencil.s3.amazonaws.com/dev/images/8be62eca-72de-4f81-9edc-a4dbeee6986f/4034dee3-039a-466e-b4ba-0c2fb721036a.jpeg",
"webhook_response_code": null,
"webhook_response_body": null
}
]
}
```
{% endtab %}
{% endtabs %}
---
# 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://docs.usestencil.com/api/endpoints/image.md?ask=
```
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.