Images
Generating Images
Before generating an image, let's take a look at the options available for image generation.
Image Options
Each image route accepts the following form fields inside the options object:
| Key | Description | Default |
|---|---|---|
properties | The image properties. Please see the Image Properties section. | - |
emulatedMediaType | The emulated media type. | - |
waitDelay | The wait delay in milliseconds. | - |
waitForExpression | The wait for expression. | - |
extraHttpHeaders | The extra HTTP headers. | - |
failOnHttpStatusCodes | The HTTP status codes to fail on. | - |
failOnConsoleExceptions | Whether to fail on console exceptions. | false |
skipNetworkIdleEvent | Whether to skip the network idle event. | false |
optimizeForSpeed | Whether to optimize for speed. | false |
type ImageOptions = {
properties?: ImageProperties;
emulatedMediaType?: 'screen' | 'print';
waitDelay?: string;
waitForExpression?: string;
extraHttpHeaders?: Record<string, string>;
failOnHttpStatusCodes?: number[];
failOnConsoleExceptions?: boolean;
skipNetworkIdleEvent?: boolean;
optimizeForSpeed?: boolean;
}
Image Properties
The properties object contains the following fields:
| Key | Description | Default |
|---|---|---|
format | The image format. | png |
quality | The image quality. | 80 |
omitBackground | Whether to omit the background. | false |
width | The width of the image. | 800 |
height | The height of the image. | 600 |
clip | Whether to clip the image. | false |
Heads up!
For the URL source, the clip option will clip the image to the specified width and height. If false, the height will be ignored. For other conversion types, you don't need to set the clip option to force the image to be clipped.
type ImageProperties = {
format: 'png' | 'jpeg' | 'webp';
quality?: number;
omitBackground?: boolean;
width?: number;
height?: number;
clip?: boolean;
}
Example Options
const ExampleImageOptions = {
properties: {
format: 'png',
quality: 80,
omitBackground: false,
width: 800,
height: 600,
clip: false
},
emulatedMediaType: 'print',
waitDelay: '2s',
waitForExpression: 'document.querySelector("h1") !== null',
extraHttpHeaders: {
'X-My-Custom-Header': 'My custom value'
},
failOnHttpStatusCodes: [404, 500],
failOnConsoleExceptions: true,
skipNetworkIdleEvent: true,
optimizeForSpeed: true
};
Endpoint Structure
The /image endpoint generates an image from a URL, HTML, or a template. The endpoint accepts a JSON object with the source and options fields. The source field specifies the source of the document, and the options field specifies the image generation options. Please see the Image Options section for more information.
{
source: UrlSource | HtmlSource | TemplateSource,
options: ImageOptions
}
Getting buffer response
If you want to get the PDF as a buffer, you just need to put /buffer at the end of the URL.
fetch('/api/v1/image/buffer')
POST /image - From URL
The /image endpoint generates an image from a URL.
Request Body
The request body must contain a JSON object with the source field. Optionally, you can include the options field. Please see the Image Options section for more information and default values.
| Key | Description |
|---|---|
source.type | This should be set to url. |
source.url | The URL of the document. |
options | The image options. Please see the Image Options section. |
Response
The response contains a task object. Please see the tasks section for more information.
fetch('/api/v1/image', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
source: {
type: 'url',
data: 'https://example.com'
},
options: ImageOptions
})
})
{
"id": "36a4ebd91745f1755df615ba",
"url": "https://files.markupgo.com/66a4ebd91745f1755df615ba/1725057544064.png",
"format": "png",
"size": 1048576,
"width": 800,
"height": 600,
"createdAt": "2026-06-21T10:00:00Z",
"updatedAt": "2026-06-21T10:05:00Z"
}
POST /image - From HTML
The /image endpoint generates an image from HTML.
Request Body
The request body must contain a JSON object with the source field. Optionally, you can include the options field. Please see the Image Options section for more information and default values.
| Key | Description |
|---|---|
source.type | This should be set to html. |
source.html | The HTML content. |
options | The image options. Please see the Image Options section. |
Response
The response contains a task object. Please see the tasks section for more information.
fetch('/api/v1/image', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
source: {
type: 'html',
data: '<h1>Hello, World!</h1>'
},
options: ImageOptions
})
})
{
"id": "36a4ebd91745f1755df615ba",
"url": "https://files.markupgo.com/66a4ebd91745f1755df615ba/1725057544064.png",
"format": "png",
"size": 1048576,
"width": 800,
"height": 600,
"createdAt": "2026-06-21T10:00:00Z",
"updatedAt": "2026-06-21T10:05:00Z"
}
POST /image - From Template
Check out the editor
The /image endpoint generates an image from a template.
Request Body
The request body must contain a JSON object with the source field. Optionally, you can include the options field. Please see the Image Options section for more information and default values.
Heads up!
The template options will override original template options that you have configured in the dashboard.
If you want to use the original template options, you should only provide the id field in the source.data object.
How to get the template ID?
Visit the template list in the dashboard and click copy on the template you want to use.
| Key | Description |
|---|---|
source.type | This should be set to template. |
source.data | Template data. |
source.data.id | The template ID. |
source.data.context | The template context. |
source.data.html | The template HTML content. |
source.data.css | The template CSS content. |
source.data.libraries | The template libraries. |
source.data.libraries.js | The template JavaScript libraries. |
source.data.libraries.css | The template CSS libraries. |
options | The image options. Please see the Image Options section. |
Response
The response contains a task object. Please see the tasks section for more information.
fetch('/api/v1/image', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
source: {
type: 'template',
data: {
id: '666b3561fbaa04f6877e70b5',
context: {
name: 'John Doe'
}
}
},
options: ImageOptions
})
})
{
"id": "36a4ebd91745f1755df615ba",
"url": "https://files.markupgo.com/66a4ebd91745f1755df615ba/1725057544064.png",
"format": "png",
"size": 1048576,
"width": 800,
"height": 600,
"createdAt": "2026-06-21T10:00:00Z",
"updatedAt": "2026-06-21T10:05:00Z"
}
POST /image - From Markdown
The /image endpoint generates an image from a markdown content.
Request Body
The request body must contain a JSON object with the source field. Optionally, you can include the options field. Please see the Image Options section for more information and default values.
| Key | Description |
|---|---|
source.type | This should be set to markdown. |
source.data.markdown | The markdown content. |
source.data.padding | The padding of the image. |
source.data.css | The CSS content. |
source.data.dark | Whether to use dark mode. |
options | The image options. Please see the Image Options section. |
Response
The response contains a task object. Please see the tasks section for more information.
fetch('/api/v1/image', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
source: {
type: 'markdown',
data: {
markdown: '# Hello, World!',
padding: 20,
css: 'body { background-color: #f0f0f0; }',
dark: false
}
},
options: ImageOptions
})
})
{
"id": "36a4ebd91745f1755df615ba",
"url": "https://files.markupgo.com/66a4ebd91745f1755df615ba/1725057544064.png",
"format": "png",
"size": 1048576,
"width": 800,
"height": 600,
"createdAt": "2026-06-21T10:00:00Z",
"updatedAt": "2026-06-21T10:05:00Z"
}