PHP Screenshot API: End-to-End Example

When PHP is the right tool

PHP remains the backbone of countless CMS and billing stacks. Calling ScreenshotCenter from PHP is straightforward with the cURL extension (enabled by default in most distributions). The official PHP SDK wraps the same endpoints if you prefer an object-oriented client; this walkthrough uses raw HTTP so you can debug requests in any project.

Bookmark the developer hub for parameter names, limits, and automation command reference.

Flow overview

Phase	Endpoint	Output
Queue capture	GET /api/v1/screenshot/create	JSON with numeric id and status
Poll state	GET /api/v1/screenshot/info	Same shape until finished or error
Save file	GET /api/v1/screenshot/thumbnail	Raw PNG bytes

Runnable script

Save as screenshot.php, export SCREENSHOTCENTER_API_KEY, then run php screenshot.php https://example.com.

 true,
        CURLOPT_TIMEOUT => 120,
    ]);
    $body = curl_exec($ch);
    if ($body === false) {
        $err = curl_error($ch);
        curl_close($ch);
        throw new RuntimeException("cURL error: $err");
    }
    $code = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($code !== 200) {
        throw new RuntimeException("HTTP $code: $body");
    }
    /** @var array $json */
    $json = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    if (empty($json['success'])) {
        throw new RuntimeException("API success=false: $body");
    }
    if (!is_array($json['data'])) {
        throw new RuntimeException('Missing data object');
    }
    return $json['data'];
}

function http_download_file(string $url, string $path): void {
    $fp = fopen($path, 'wb');
    if ($fp === false) {
        throw new RuntimeException("Cannot open $path for write");
    }
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_FILE => $fp,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_TIMEOUT => 120,
    ]);
    $ok = curl_exec($ch);
    $code = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    fclose($fp);
    if ($ok === false || $code !== 200) {
        unlink($path);
        throw new RuntimeException("Download failed HTTP $code");
    }
}

function create_screenshot(string $base, string $key, string $pageUrl): int {
    $qs = http_build_query([
        'key' => $key,
        'url' => $pageUrl,
        'country' => 'us',
    ]);
    $data = http_get_json("$base/screenshot/create?$qs");
    if (!isset($data['id'])) {
        throw new RuntimeException('create: missing id');
    }
    return (int)$data['id'];
}

function screenshot_info(string $base, string $key, int $id): array {
    $qs = http_build_query(['key' => $key, 'id' => $id]);
    return http_get_json("$base/screenshot/info?$qs");
}

function wait_until_done(string $base, string $key, int $id, int $sleepSec = 2, int $maxWaitSec = 300): array {
    $deadline = time() + $maxWaitSec;
    while (time() < $deadline) {
        $info = screenshot_info($base, $key, $id);
        $status = $info['status'] ?? '';
        if ($status === 'finished') {
            return $info;
        }
        if ($status === 'error') {
            $msg = $info['error'] ?? 'unknown error';
            throw new RuntimeException("Screenshot error: $msg");
        }
        sleep($sleepSec);
    }
    throw new RuntimeException('Timeout waiting for screenshot');
}

$key = env_required('SCREENSHOTCENTER_API_KEY');
$base = 'https://api.screenshotcenter.com/api/v1';
$target = $argv[1] ?? 'https://example.com';

$id = create_screenshot($base, $key, $target);
fwrite(STDOUT, "Queued screenshot id=$id
");

wait_until_done($base, $key, $id);

$qs = http_build_query(['key' => $key, 'id' => $id]);
$imgUrl = "$base/screenshot/thumbnail?$qs";
$out = getcwd() . DIRECTORY_SEPARATOR . 'screenshot.png';
http_download_file($imgUrl, $out);
fwrite(STDOUT, "Wrote $out
");

Async jobs without blocking PHP-FPM

This script blocks until the capture completes — fine for CLI and queued workers. For web requests, enqueue a job (Redis, database) from your controller and let a background worker run the same logic, or call the API from a long-running php artisan queue:work process.

Explore the PHP library page for Composer installation and idiomatic client usage.