How to Set a Custom Viewport Size in APITemplate.io Screenshots
APITemplate.io documents custom image-template dimensions, but that is different from setting a browser screenshot viewport. Here’s how to choose the right workflow.
To set custom dimensions in APITemplate.io, create an Image Template and choose a preset or enter custom dimensions in its editor. Those dimensions set the generated image canvas; they do not establish the browser viewport used to render a webpage screenshot. APITemplate.io’s documentation located for this guide describes the image-template workflow, but does not document a webpage screenshot viewport setting or its parameter names.
If you need a generated graphic at a particular width and height, use the image-template steps below. If you need to capture a live webpage at a particular browser viewport, the available APITemplate.io documentation does not confirm how to do that. See the [APITemplate.io Image Template Editor documentation](https://apitemplate.io/docs/image-template-editor/) and its [REST API guide](https://apitemplate.io/docs/).
Image canvas and browser viewport are different
| Setting | What it controls | Use it for |
|---|---|---|
| Image-template dimensions | The width and height of the generated image canvas | Generating a designed image at custom output dimensions |
| Browser viewport | The visible browser area used to render a webpage before capture | Capturing a page as it appears at a chosen screen size |
| PDF paper size and orientation | The dimensions and orientation of PDF pages | Generating paginated PDF output |
Changing an image template’s canvas size may change the dimensions of the generated file, but it is not evidence that the source webpage was rendered at a particular viewport. Likewise, PDF page-size settings apply to PDF output, not to a documented image screenshot viewport.
Set custom dimensions for an APITemplate.io image
- In APITemplate.io, open Manage Templates > New Template > Image Template.
- Choose a preset size or enter the custom dimensions you need, then launch the Image Editor. The editor documentation describes choosing a preset or setting custom dimensions.
- Build the image template. Give dynamic elements names if you want to supply or override their values when generating an image.
- Save the template and note its template ID.
- Generate an image from that template through the documented v2
/create-imageendpoint, passing the template ID and any supported element overrides. Check the current API reference for the exact request fields and authentication requirements.
The v2 guide gives https://rest.apitemplate.io/v2/ as the default API base URL and illustrates POST requests to /create-image and /create-pdf. The documentation surfaced for this article does not establish a safe, complete request body or a screenshot viewport parameter, so use the current APITemplate.io API reference for request syntax rather than guessing field names.
What to verify in the generated image
- Check the output file’s pixel dimensions to confirm the canvas size.
- Check that your template content fits the canvas; changing dimensions can require repositioning or resizing elements.
- If the source content is a live webpage and must be rendered at a specific screen size, verify that the service endpoint you plan to use explicitly supports viewport width and height. The Image Template Editor instructions alone do not show that capability.
If you meant a webpage screenshot viewport
A viewport is the browser’s visible layout area. It can affect responsive breakpoints, column layout, navigation, and which content is initially visible. To reproduce a page at a particular viewport, the capture service must set the browser viewport before loading or rendering the page. An output image’s dimensions alone do not tell you what viewport was used.
The official APITemplate.io sources found for this topic explain custom dimensions for image-template canvases and PDF page settings. They do not establish a webpage screenshot endpoint, viewport parameter names, defaults, or supported limits. Do not assume that a template width and height, PDF paper size, or similarly named output option emulates a browser viewport. Consult APITemplate.io’s current documentation or support for confirmation before building an integration around that behavior.
PDF page size is another separate setting
For PDF generation, APITemplate.io documents settings such as paper_size and orientation. Its documentation also describes preferCSSPageSize, which allows CSS @page rules to set page size and orientation, with rendering engine version 153 required for that feature. These settings concern PDF pages; they do not document a webpage screenshot viewport.
Choose the workflow based on the output you need:
- Designed image at exact pixel dimensions: set the Image Template canvas size.
- Paginated document: configure PDF paper size and orientation, or the documented CSS page-size behavior where applicable.
- Webpage rendered at a browser width and height: use a documented screenshot service viewport option. The APITemplate.io sources reviewed here do not confirm one.
Common problems and fixes
| Symptom | Likely cause | What to do |
|---|---|---|
| The output image has the desired dimensions, but the webpage layout is wrong. | Canvas dimensions were changed, but the browser viewport was not set. | Confirm that your endpoint renders webpages and documents viewport width and height controls. A template canvas setting is not a substitute. |
| You cannot find a viewport-width option in the Image Template Editor. | The editor configures image templates; the documentation found does not describe browser viewport emulation there. | Use the editor for generated image dimensions. Ask APITemplate.io whether a separate screenshot endpoint supports viewport control. |
| The API rejects a guessed field or request body. | The request uses an undocumented parameter or an outdated schema. | Check the current API reference for the endpoint, method, authentication, and field names. Avoid copying parameters from unrelated screenshot APIs. |
| Template content is clipped or poorly placed after resizing. | The canvas changed while element positions or sizes remained unsuitable for the new dimensions. | Reopen the template editor, adjust the layout, and generate again. |
| PDF page dimensions do not match the expected image or browser viewport. | PDF page size controls were applied to a different output type. | Choose image-template dimensions for generated images, or PDF page settings for PDFs. Neither establishes a webpage screenshot viewport. |
Performance, reliability, and cost considerations
The sources reviewed for this topic do not provide benchmark figures, screenshot viewport limits, or performance guarantees for a webpage screenshot workflow. For image templates, keep the template and its dynamic fields as simple as your output requires, and verify the generated dimensions and layout with representative data. For API usage, follow the current APITemplate.io documentation for rate limits, retries, and pricing; do not infer those details from the canvas editor.
If a webpage capture must be repeatable, record the target URL and requested viewport alongside the resulting file, and confirm that the chosen service actually accepts viewport settings. A successful image response only confirms an output was generated; it does not by itself prove a particular browser viewport was used.
Or skip the browser setup
If your goal is a live webpage screenshot at a chosen viewport, ScreenshotNeo is a website screenshot API with viewport options. Its clean-shot flow accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. ScreenshotNeo also has an MCP server for AI agents, including Claude, Cursor, and other MCP clients.
See the ScreenshotNeo API documentation for viewport and other capture options. Example request for a webpage:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo has a free plan with 1,000 screenshots a month and no card required. Paid plans start at $5 for 3,000 screenshots. Sign up for free and start with 1,000 screenshots a month, no card required.
FAQ
Does setting an Image Template size set the browser viewport?
No. It sets the generated image canvas dimensions. The APITemplate.io documentation found for this guide does not establish browser viewport emulation through that setting.
Can I use the custom canvas workflow to create a social image?
Yes. The Image Template Editor supports presets and custom dimensions for the image template. Check the generated output and adjust the template layout to fit.
Which APITemplate.io option controls PDF page dimensions?
The PDF workflow documents paper size and orientation, and describes CSS @page sizing with preferCSSPageSize when using rendering engine version 153. Those controls apply to PDFs.
