How to Use the APITemplate.io Screenshot API in a PHP Project

Direct answer: APITemplate.io’s documented image API generates an image from a saved APITemplate.io image template. In PHP, send a JSON POST request to https://rest.apitemplate.io/v2/create-image?template_id=YOUR_TEMPLATE_ID, authenticate with the X-API-KEY header, and put template element changes in an overrides array. A successful synchronous response contains a download URL. This is template-based image generation; the current sources reviewed do not establish an endpoint for capturing an arbitrary webpage as a screenshot image. APITemplate.io REST API reference, official PHP client.

If by “screenshot” you mean a screenshot of a live website, skip to the webpage screenshot section. A URL-to-PDF endpoint is documented, but that does not establish arbitrary webpage-to-image screenshot support.

What you need

An APITemplate.io account, an API key, and a saved image template.
PHP with the cURL extension enabled. The API key is sent in the request header; keep it server-side and out of source control. APITemplate.io describes the key as secret. Get Your API Key.
The exact names and properties of the template elements you plan to override. For example, a text element named title accepts a text override.

For a first template, create and save an image template in the APITemplate.io editor, then use its template ID and element names in the request. See Create Your First Template.

PHP example using cURL

This example reads credentials from environment variables, sends JSON, checks transport and HTTP/API errors, and prints the returned image URL. It is based on the documented v2 REST endpoint; it has not been run against a live account.

<?php
$templateId = getenv('APITEMPLATE_TEMPLATE_ID');
$apiKey = getenv('APITEMPLATE_API_KEY');

if (!$templateId || !$apiKey) {
    throw new RuntimeException('Set APITEMPLATE_TEMPLATE_ID and APITEMPLATE_API_KEY.');
}
if (!extension_loaded('curl')) {
    throw new RuntimeException('The PHP cURL extension is required.');
}

$endpoint = 'https://rest.apitemplate.io/v2/create-image?' . http_build_query([
    'template_id' => $templateId,
]);

$payload = [
    'overrides' => [
        ['name' => 'title', 'text' => 'Hello from PHP'],
    ],
];

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 90,
    CURLOPT_HTTPHEADER => [
        'X-API-KEY: ' . $apiKey,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
]);

$body = curl_exec($ch);
if ($body === false) {
    $error = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException('APITemplate.io transport error: ' . $error);
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

try {
    $response = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    throw new RuntimeException('APITemplate.io returned invalid JSON (HTTP ' . $statusCode . ').', 0, $e);
}

if ($statusCode < 200 || $statusCode >= 300 || ($response['status'] ?? null) !== 'success') {
    throw new RuntimeException('Image generation failed (HTTP ' . $statusCode . '): ' . $body);
}

$downloadUrl = $response['download_url'] ?? $response['download_url_png'] ?? null;
if (!$downloadUrl) {
    throw new RuntimeException('Successful response did not include a documented image download URL.');
}

echo $downloadUrl . PHP_EOL;

Endpoint, authentication header, JSON overrides, and response fields are documented in the REST reference. Use ScreenshotNeo’s API docs for its separate webpage capture API.

Download the generated file from PHP

The API response provides a URL; download the file separately if your application needs a local copy. Treat the returned URL as an external URL, handle download failures, and avoid exposing it if your use case considers generated assets private.

<?php
// $downloadUrl is the URL returned by the successful create-image response.
$download = curl_init($downloadUrl);
curl_setopt_array($download, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 60,
]);
$imageBytes = curl_exec($download);
$downloadStatus = curl_getinfo($download, CURLINFO_HTTP_CODE);
if ($imageBytes === false || $downloadStatus < 200 || $downloadStatus >= 300) {
    $error = curl_error($download);
    curl_close($download);
    throw new RuntimeException('Image download failed: ' . $error . ' (HTTP ' . $downloadStatus . ')');
}
curl_close($download);

if (file_put_contents(__DIR__ . '/generated-image.png', $imageBytes) === false) {
    throw new RuntimeException('Could not write generated-image.png');
}

Choose a filename and extension that match the actual output format configured or returned by your integration. Do not assume every generated image is PNG.

Equivalent cURL request

Use this to inspect the API independently of PHP. Substitute your credentials, template ID, and element names.

curl -X POST "https://rest.apitemplate.io/v2/create-image?template_id=YOUR_TEMPLATE_ID" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "overrides": [
      {"name": "title", "text": "Hello from cURL"}
    ]
  }'

Read the JSON response and use its returned download URL only after confirming that the response indicates success. Avoid putting a real API key in shell history, shared scripts, or logs.

Request structure and configuration

Part	Purpose	What to check
`POST /v2/create-image`	Creates an image from an image template.	Use the documented REST host and route.
`template_id`	Selects the saved template.	Use the image template ID, not an arbitrary webpage URL.
`X-API-KEY`	Authenticates the request.	Keep the key secret; do not place it in browser code or commit it.
`Content-Type: application/json`	Identifies the JSON request body.	Encode the payload as JSON.
`overrides`	Changes named template elements for this generation.	Names and property keys must match the saved template.
`async=true`	Requests asynchronous generation for larger or batch work.	The response includes a transaction reference; configure a webhook to learn when work completes.

The REST documentation describes synchronous generation as the default. It also documents asynchronous generation using async=true and a webhook. Use the current REST API reference for the full and current parameter set. Do not assume options from PDF endpoints apply to image creation.

Use the official PHP client

APITemplate.io publishes an official PHP client for API v2. It can be useful when a project already uses the generated client style or needs several API operations. Check its current installation instructions and PHP requirements before adding it; the repository lists PHP 7.4 and later and documents an APIIntegrationApi->createImage operation. Official PHP client repository.

<?php
require_once __DIR__ . '/vendor/autoload.php';

$config = OpenAPI\Client\Configuration::getDefaultConfiguration()
    ->setApiKey('X-API-KEY', getenv('APITEMPLATE_API_KEY'));

$api = new OpenAPI\Client\Api\APIIntegrationApi(
    new GuzzleHttp\Client(),
    $config
);

$templateId = getenv('APITEMPLATE_TEMPLATE_ID');
$body = [
    'overrides' => [
        ['name' => 'title', 'text' => 'Hello from the PHP client'],
    ],
];

try {
    $result = $api->createImage($templateId, $body);
    print_r($result);
} catch (Throwable $e) {
    error_log('APITemplate.io createImage failed: ' . $e->getMessage());
    throw $e;
}

Generated client method parameters may change with client releases. Refer to the repository’s current usage example for the method signature that matches the version you install.

Other integration options

Direct URL generation

APITemplate.io also documents a Direct URL feature for image templates, with a URL shaped like /v2/create-image-url/{template_id}?auth=...&element.property=value. It uses a configured auth code and element-property query parameters such as headline.text. The vendor describes cached results and use as an image source. This is a distinct workflow from a server-side POST with the API key. Check the Direct URL configuration, quota, expiration, and sharing implications before using it in a public page or email. Direct URL Image Generation docs.

Region and request limits

The official PHP repository lists regional REST hosts, with different documented timeout and payload limits by region. If processing location or request size matters, verify the current host and limits in the repository or REST documentation before choosing a regional endpoint. The repository also documents IP-based rate limiting of up to 100 requests per 10 seconds and HTTP 429 responses when exceeded. Do not hard-code a different region or retry limit based on an old copied example. Repository reference.

Webpage screenshots: choose an API for the actual task

If you need an image of an arbitrary live webpage, template image generation is the wrong mental model. The reviewed APITemplate.io sources document template-based image generation and PDF generation from a URL; they do not establish arbitrary webpage-to-screenshot image capture. A URL-to-PDF operation is not the same as returning a webpage screenshot as PNG, JPEG, or WebP.

For webpage capture in PHP, one option is to run a browser automation tool such as Playwright or Puppeteer in your own infrastructure and manage browser installation, navigation, waiting, output, and operational failures. The research dossier does not establish a specific PHP browser automation setup, so confirm the chosen tool’s official documentation before implementing it.

For a hosted screenshot API, ScreenshotNeo is the first service to consider here: it removes consent banners, newsletter popups, and chat widgets before capture, and only clean shots are billed.

Or skip the browser setup

For a live webpage screenshot, make one GET request to ScreenshotNeo. Replace the target URL and API key. See the ScreenshotNeo API documentation for output and option details.

<?php
$query = http_build_query([
    'access_key' => getenv('SCREENSHOTNEO_API_KEY'),
    'url' => 'https://stripe.com',
]);
$url = 'https://api.screenshotneo.com/v1/shot?' . $query;

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 90,
]);
$image = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($image === false || $status < 200 || $status >= 300) {
    $error = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException('ScreenshotNeo request failed: ' . $error . ' (HTTP ' . $status . ')');
}
curl_close($ch);
file_put_contents(__DIR__ . '/shot.webp', $image);

Equivalent cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Equivalent Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Equivalent Node.js:

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

Cookie banners, newsletter popups, and chat widgets are removed before the shot; those cleanup steps can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status.
An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf.
1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.

Troubleshooting

Symptom	Likely cause	Fix
HTTP 401 or 403	Missing, invalid, or incorrect API key header.	Confirm the account key and send it as `X-API-KEY`. Keep it on the server.
HTTP 400 or API status is not success	Malformed JSON, missing template ID, or invalid request fields.	Inspect the response body, check JSON encoding, and compare the request with the current endpoint reference.
Generation succeeds but content is unchanged	Override name or property does not match a template element.	Check the saved template’s exact element name and supported property, then update the override.
Response has no usable image URL	Code assumed the wrong response field, or the request did not succeed.	Check HTTP status and API `status` first; inspect the documented response and use the image URL field returned for that operation.
cURL reports a transport error or timeout	Network connectivity, TLS, DNS, or generation duration.	Check server connectivity and cURL configuration. Set a reasonable timeout; avoid retrying indefinitely.
HTTP 429	IP-based rate limit exceeded.	Reduce request bursts, queue work, and retry after a delay with a bounded backoff.
Async call returns a transaction reference, not a completed asset	The request was explicitly made asynchronous.	Use the documented webhook completion flow; do not treat transaction reference as a download URL.
Local PHP says cURL function is missing	The PHP cURL extension is unavailable.	Enable/install the extension for the PHP runtime that runs the application, or use the official client and its HTTP dependencies.

Performance, reliability, and cost considerations

Latency: synchronous generation waits for the result in the request path. For larger or batch work, the vendor documents asynchronous generation and webhook notification. Avoid tying up a short-lived web request if the generation may outlast your application’s request budget.
Retries: retry transient network failures and rate limits with a bounded delay. Before retrying a timed-out generation, consider whether the original request may have completed; duplicate requests can create duplicate work.
Response handling: validate both HTTP status and API status, then consume the returned URL. Handle the download as another network request with its own timeout and error checks.
Secrets: store the API key in server-side environment or secret configuration. Do not expose it in client-side JavaScript, logs, or version control.
Regional processing: use the currently documented regional host when data location or proximity matters, and confirm its limits before deployment.
Cost: this dossier does not include APITemplate.io pricing, so check the vendor’s current plan and usage terms. This endpoint generates an image from a template; it is not evidence of arbitrary webpage screenshot billing.

FAQ

Can I pass any website URL to create-image?

The reviewed documentation describes an image template ID and template overrides. It does not establish arbitrary webpage-to-image capture for this endpoint.

Can APITemplate.io create a PDF from a URL?

The REST reference lists a separate create-pdf-from-url operation. That is PDF generation, not a documented arbitrary webpage screenshot image endpoint.

Do I need the PHP SDK?

No. The API is REST-based, so PHP cURL is sufficient. The official PHP client is an alternative if its abstraction fits the project.

Can generated images be used in a browser?

The documented response includes a download URL. For a browser-facing use, consider where the URL is exposed and whether the asset should be public; the Direct URL feature is a separate configured option.