Skip to content

Commit 9e6cf9a

Browse files
mscoutermarshmscoutermarsh
committed
improvements
1 parent 1c6c342 commit 9e6cf9a

File tree

2 files changed

+151
-17
lines changed

2 files changed

+151
-17
lines changed

‎parameters/device_scale.md‎

Lines changed: 75 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,26 +5,37 @@ permalink: /parameters/device_scale/
55
parent: Parameters
66
nav_order: 3
77
description: >-
8-
Adjust the pixel ratio of the screenshot. How it affects screensizes and its use in web development
8+
Control image resolution by adjusting the pixel ratio of screenshots
99
---
1010
# Using device_scale
1111
{: .no_toc }
1212
{: .fs-9 }
1313

14-
Learn how to adjust the pixel ratio of your images and why it matters
14+
Control image quality and size by adjusting the pixel ratio
1515
{: .fs-6 .fw-300 }
1616

1717
<hr>
1818

1919
## How it works
2020

21-
Use this parameter to adjust the pixel ratio of the generated image. Minimum: `1`, Maximum: `3`.
21+
The device_scale parameter controls the pixel ratio of generated images. Values range from `1` to `3`, where:
22+
- `1` = standard resolution (1:1 pixel ratio)
23+
- `2` = high resolution (2:1 pixel ratio, recommended for web)
24+
- `3` = maximum resolution (3:1 pixel ratio)
2225

2326
## Default values
24-
HTML images and URL images have different default values
27+
The default pixel ratio varies by image type:
2528

26-
1. HTML images: 2
27-
2. URL images: 1
29+
1. HTML images: `2` (recommended for web use)
30+
2. URL images: `1` (standard resolution)
31+
32+
## Common issues
33+
34+
### Blurry images
35+
If your image appears blurry, especially on high-DPI displays, try increasing the device_scale to `2`. This is particularly important for web usage.
36+
37+
### Oversized images
38+
If your image file size is larger than needed, consider reducing the device_scale. Remember that each increment doubles or triples the number of pixels.
2839

2940
## Blurry URL images
3041
If you have an image that looks blurry on your monitor, this often means it could be improved by increasing the pixel ratio.
@@ -83,3 +94,61 @@ To address the challenges posed by varying pixel ratios, web developers often us
8394
```
8495

8596
Understanding and accommodating pixel ratio is crucial for delivering a consistent and visually appealing experience across a diverse range of devices in modern web development.
97+
98+
## Using device_scale effectively
99+
100+
### For web usage
101+
If you plan to use images on a website, use device_scale `2` to ensure crisp display on high-resolution screens. For example:
102+
- Source image: `800x800` (device_scale: 2)
103+
- Display size: `400x400` on webpage
104+
- Result: Sharp image on both standard and high-DPI displays
105+
106+
### For print usage
107+
For print materials, consider using device_scale `3` to ensure maximum quality. Note that this will significantly increase file size.
108+
109+
## Technical details
110+
111+
### Pixel ratio explained
112+
Pixel ratio (or device pixel ratio/DPR) represents the relationship between physical pixels and CSS pixels:
113+
```
114+
Pixel Ratio = Physical Pixels / CSS Pixels
115+
```
116+
117+
For example:
118+
- Standard display: 1 physical pixel = 1 CSS pixel (ratio 1:1)
119+
- Retina display: 2 physical pixels = 1 CSS pixel (ratio 2:1)
120+
- High-DPI display: 3 physical pixels = 1 CSS pixel (ratio 3:1)
121+
122+
### Impact on file size
123+
Each increment of device_scale significantly affects the total number of pixels:
124+
- device_scale `1`: Base size (1x pixels)
125+
- device_scale `2`: 4x total pixels
126+
- device_scale `3`: 9x total pixels
127+
128+
### Best practices
129+
1. For web usage:
130+
- Use device_scale `2` as default
131+
- Test images on both standard and high-DPI displays
132+
- Consider bandwidth constraints
133+
134+
2. For print usage:
135+
- Use device_scale `3` for highest quality
136+
- Verify final output resolution meets your needs
137+
- Account for larger file sizes
138+
139+
3. For standard resolution:
140+
- Use device_scale `1` when high resolution isn't needed
141+
- Ideal for thumbnails or preview images
142+
- Best for bandwidth-constrained situations
143+
144+
## Example usage
145+
146+
### In API requests
147+
```javascript
148+
{
149+
"html": "<div>Your content</div>",
150+
"device_scale": 2
151+
}
152+
```
153+
154+
{% include hint.md title="Performance tip" text="Higher device_scale values increase both rendering time and file size. Use the lowest value that meets your quality requirements." %}

‎parameters/ms_delay.md‎

Lines changed: 76 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,31 +5,96 @@ permalink: /parameters/ms_delay/
55
parent: Parameters
66
nav_order: 2
77
description: >-
8-
The number of milliseconds the API should delay before generating the image. This is useful when waiting for JavaScript. We recommend starting with `500`. Large values slow down the initial render time.
8+
Control the delay before screenshot capture when needed for dynamic content
99
---
10+
1011
# Using ms_delay
1112
{: .no_toc }
1213
{: .fs-9 }
1314

14-
Learn how to adjust the delay time in your image rendering
15+
Adjust rendering delay to capture dynamic content
1516
{: .fs-6 .fw-300 }
1617

18+
Table of contents
19+
{: .text-delta }
20+
1. TOC
21+
{:toc}
22+
1723
<hr>
1824

25+
## When to use ms_delay
26+
27+
{% include hint.md title="Important" text="Most users don't need ms_delay. Only use this parameter if you notice missing content in your screenshots." %}
28+
29+
The `ms_delay` parameter should only be used when:
30+
1. Your screenshots are missing expected content
31+
2. Dynamic content isn't appearing in the final image
32+
3. Custom fonts or images aren't loading properly
33+
1934
## How it works
2035

21-
The `ms_delay` parameter can be used to increase the time that the API waits for the page
22-
to render before generating the screenshot.
36+
When content is missing from your screenshots, the `ms_delay` parameter lets you add a delay before capture. This can help with:
37+
- JavaScript that needs time to execute
38+
- Assets (images, fonts) still loading
39+
- Animations not completing
40+
- Dynamic content not appearing
2341

24-
This is useful for pages that load a lot of assets such as JavaScript, or in general are slow to load.
42+
## Default behavior
2543

26-
By default the API will wait `500` milliseconds for each external asset to load before triggering
27-
the screenshot. If assets are taking longer than `500` milliseconds, the API will stop waiting for them.
44+
By default, the API intelligently handles most loading scenarios:
45+
- Waits for the page to fully load
46+
- Detects when assets finish loading
47+
- Automatically manages common JavaScript frameworks
2848

29-
If you are having issues with white or blank images, we recommend adjusting this parameter first to see if it helps.
30-
Start with a fairly low value, such as `1500`.
49+
Only add `ms_delay` if you notice issues with the default behavior.
3150

3251
## Image credits and billing
3352

34-
The maximum value for `ms_delay` is 20 seconds (20,000ms). Usage above `5000` will use an additional image render credit for every 5000ms above.
35-
For example, using `ms_delay` of 10000ms on an image will count as 2 images towards your monthly quota. 15000ms will use 3 image credits.
53+
### Credit usage
54+
The `ms_delay` parameter can affect how many image credits are consumed per request:
55+
56+
| Delay Range (ms) | Credits Used | Example Usage |
57+
|:----------------|:-------------|:--------------|
58+
| 0-5000 | 1 credit | Standard usage, suitable for most cases |
59+
| 5001-10000 | 2 credits | Complex pages with many assets |
60+
| 10001-15000 | 3 credits | Heavy JavaScript applications |
61+
| 15001-20000 | 4 credits | Maximum delay scenarios |
62+
63+
### Important notes
64+
- Maximum allowed value is 20,000ms (20 seconds)
65+
- Values are rounded up to the nearest credit tier
66+
- Credits are calculated before the request is processed
67+
68+
{% include hint.md title="Cost optimization" text="To minimize credit usage, try optimizing your page load time before increasing ms_delay. Consider using render_when_ready for precise timing control." %}
69+
70+
### Examples
71+
72+
```javascript
73+
// Standard usage (1 credit)
74+
{
75+
"html": "<div>Your content</div>",
76+
"ms_delay": 3000
77+
}
78+
79+
// 2 credits used
80+
{
81+
"html": "<div>Your content</div>",
82+
"ms_delay": 8000
83+
}
84+
85+
// 4 credits used (maximum)
86+
{
87+
"html": "<div>Your content</div>",
88+
"ms_delay": 20000
89+
}
90+
```
91+
92+
### Alternatives to high ms_delay values
93+
94+
Instead of using high `ms_delay` values, consider:
95+
1. Using the `render_when_ready` parameter
96+
2. Optimizing your page load time
97+
3. Preloading assets
98+
4. Reducing JavaScript execution time
99+
100+
This can help reduce both credit usage and overall processing time.

0 commit comments

Comments
 (0)