How to Call the APITemplate.io Screenshot API from Node.js

To call APITemplate.io’s current template-based image API from Node.js, send a JSON POST request to https://rest.apitemplate.io/v2/create-image, pass your template ID in the query string, authenticate with the X-API-KEY header, and provide an overrides array in the request body. A successful response includes a download_url.

Scope check: APITemplate.io’s documented image endpoint renders an image from a saved template and overridden properties. The reviewed docs do not establish that it captures an arbitrary webpage URL as an image. If you need a PDF generated from a URL, APITemplate.io documents that separately; do not treat that PDF endpoint as an image screenshot API.

1. Create a template and get credentials

Create and save an image template in APITemplate.io.
Note the template ID and the names of the elements you want to customize. Overrides address template elements by name.
Get an API key from your account. Keep it server-side, such as in an environment variable; do not put it in browser code or a client-visible URL.

For the request shape and available template properties, see the APITemplate.io REST API documentation and its image quickstart.

2. Call the v2 image endpoint with Node.js

This example uses the built-in fetch available in current Node.js releases. Set the two environment variables before running it.

const templateId = process.env.APITEMPLATE_TEMPLATE_ID;
const apiKey = process.env.APITEMPLATE_API_KEY;

if (!templateId || !apiKey) {
  throw new Error('Set APITEMPLATE_TEMPLATE_ID and APITEMPLATE_API_KEY');
}

const endpoint = new URL('https://rest.apitemplate.io/v2/create-image');
endpoint.searchParams.set('template_id', templateId);

const response = await fetch(endpoint, {
  method: 'POST',
  headers: {
    'X-API-KEY': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    overrides: [
      { name: 'headline', text: 'Hello from Node.js' },
    ],
  }),
});

if (!response.ok) {
  const detail = await response.text();
  throw new Error(`APITemplate.io returned HTTP ${response.status}: ${detail}`);
}

const result = await response.json();
if (!result.download_url) {
  throw new Error('The response did not include download_url');
}

console.log(result.download_url);

Save this as an ES module, for example create-image.mjs, then run it with APITEMPLATE_TEMPLATE_ID=your_id APITEMPLATE_API_KEY=your_key node create-image.mjs. The example uses a text override. Use the property names and override fields supported by your template for other element types.

3. Understand the request and response

Part	Purpose
`POST /v2/create-image`	Requests an image generated from a template.
`template_id` query parameter	Selects the saved image template.
`X-API-KEY` header	Authenticates the REST request.
`Content-Type: application/json`	Declares that the body contains JSON.
`overrides`	Provides replacement properties for named template elements.
`download_url` in response	URL for retrieving the generated image, as described by the quickstart.

The image quickstart documents download_url. Check the full current API reference for response details and error formats before building production-specific parsing around other fields.

4. Send the same request with cURL or Python

cURL

curl --fail-with-body \
  --request POST \
  'https://rest.apitemplate.io/v2/create-image?template_id=YOUR_TEMPLATE_ID' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"overrides":[{"name":"headline","text":"Hello from Node.js"}]}'

This prints the JSON response. Read its download_url to retrieve the image.

Python

import os
import requests

endpoint = 'https://rest.apitemplate.io/v2/create-image'
response = requests.post(
    endpoint,
    params={'template_id': os.environ['APITEMPLATE_TEMPLATE_ID']},
    headers={
        'X-API-KEY': os.environ['APITEMPLATE_API_KEY'],
        'Content-Type': 'application/json',
    },
    json={'overrides': [{'name': 'headline', 'text': 'Hello from Node.js'}]},
    timeout=90,
)
response.raise_for_status()
result = response.json()
print(result['download_url'])

5. Handle failures and operational edge cases

Symptom	Likely cause	What to check
HTTP 401 or 403	Missing, invalid, or unauthorized API key.	Confirm the key is present, current, and sent in `X-API-KEY`.
HTTP 400 or validation error	Invalid template ID, malformed JSON, or an override that does not match a template element.	Check the saved template ID, element name spelling, and property shape in the current docs.
HTTP 404	Wrong route or resource identifier.	Use the v2 `/create-image` route and verify the template ID. Do not copy legacy v1 `/v1/create` examples.
Non-JSON response or JSON parse error	The request failed and the server returned an error body in another format.	Check `response.ok` before parsing JSON; log the response text for diagnosis without logging secrets.
Response has no `download_url`	Unexpected response shape or an error object was treated as success.	Inspect the status and response body, then compare with the current API reference.
Node reports `fetch is not defined`	The runtime does not provide global fetch.	Use a current Node.js version with built-in fetch or an HTTP client supported by your project.

Keep credentials in environment variables or a secret manager. Avoid printing the API key or placing it in logs. For transient network failures, apply bounded retries only when appropriate for your application; avoid retry loops that can multiply requests. The reviewed docs do not establish a specific latency, rate limit, or retry guarantee, so consult the current API reference and your account terms for those details.

6. Choose REST, the JavaScript client, or Direct URL mode

REST from Node.js: A direct authenticated request is straightforward when your server constructs template overrides and needs the generated response data.
JavaScript client: APITemplate.io lists an official JavaScript client library. Use its current documentation for installation and supported methods; the direct REST call above makes the HTTP request explicit.
Direct URL: APITemplate.io also documents a URL mode using a template ID, an auth code, and query parameters shaped like element_name.property=value. Its docs say generated images are cached and a new image is generated when query parameters or the template change. This can fit URL embedding, while the authenticated POST is easier to construct server-side when overrides are more involved.

For high-volume or asynchronous workflows, verify the current service behavior and account limits in APITemplate.io’s documentation. The reviewed sources do not support specific performance comparisons or service-level guarantees.

7. If you need an actual webpage screenshot

A template renderer and a webpage screenshot service solve different tasks. If your input is an arbitrary public webpage URL and your desired output is a rendered capture, use a browser-based capture method or a screenshot API that accepts URLs. ScreenshotNeo is a website screenshot API and MCP server for developers: one GET request takes a URL and returns a PNG, JPEG, WebP, or PDF. Its cookie-banner cleanup and billing verdict headers are relevant when captures need to exclude consent overlays or you need to distinguish clean captures from failed pages. See ScreenshotNeo and its API documentation.

Or skip the browser setup

If you mean a webpage screenshot rather than an APITemplate.io template image, ScreenshotNeo accepts a URL in one GET request. See the ScreenshotNeo API docs for the available capture options.

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed, and response headers say the page verdict and billing status. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for free ScreenshotNeo screenshots.

FAQ

Does this API screenshot any webpage URL?

The reviewed APITemplate.io image documentation describes rendering images from templates with overridden properties. It does not establish arbitrary webpage URL capture through this endpoint.

Can I call it from browser-side JavaScript?

The documented REST request uses an API key in a request header. Keep that secret on a server and call the API from your backend rather than exposing the key in a browser bundle.

Should I use the v1 endpoint?

No. The legacy reference labels v1 as no longer supported and recommends v2. Use the v2 image endpoint described here.

Can I use the generated image in an HTML image tag?

APITemplate.io documents Direct URL mode for image URLs. Review its current authentication and caching requirements before embedding such a URL in a public page.