File Type & Quality

The format you choose for your screenshot affects file size, image quality, and where you can use it. A PNG gives you pixel-perfect sharpness but weighs more; a WebP delivers similar quality at half the size. This page covers all output formats, quality settings, resizing, and transparent backgrounds.

Choosing a format

The format parameter controls the output file type. The default is png.

PNG

PNG is lossless — every pixel is preserved exactly as rendered. Text stays crisp, edges stay sharp, and there are no compression artifacts. The trade-off is larger file sizes. Use PNG when quality matters more than size: documentation screenshots, UI comparisons, bug reports, or any image where you need to zoom in and read text clearly.

JPEG

JPEG compresses aggressively by discarding visual detail that the human eye is less likely to notice. This works well for photographs and pages with lots of images, but it introduces visible artifacts around sharp edges and text. You can control how much detail is discarded with the quality parameter. Use JPEG when file size is a priority and the content is mostly photographic.

WebP

WebP is the best all-around choice for most use cases. It delivers image quality comparable to PNG but at 30–50% smaller file sizes. All modern browsers support WebP. If you're unsure which format to pick, go with WebP.

AVIF

AVIF offers the best compression ratio of any image format — files are even smaller than WebP at similar quality. The downside is that encoding is slower and not all browsers or image viewers support it yet. Use AVIF when you're serving images to modern browsers and want the smallest possible files.

TIFF

TIFF is a lossless archival format that produces very large files. It's rarely used on the web, but it's the standard for print production and long-term archival. Use TIFF only when you need maximum quality for print or archival purposes.

PDF

PDF output generates a document rather than an image. Text in the PDF is vector-based, so it stays sharp at any zoom level. For PDF-specific settings (page size, orientation, margins), see PDF Rendering.

Quality control

The quality parameter controls how much compression is applied. It only affects lossy formats: JPEG, WebP, and AVIF. PNG and TIFF are always lossless, so this parameter has no effect on them.

Higher values mean better quality but larger files. Lower values mean smaller files but more visible artifacts. Here are some practical guidelines:

• 90–100 — High fidelity. Use for hero images, portfolios, or when quality is critical.
• 75–85 — Good balance. The default of 80 works well for most screenshots.
• 50–70 — Lightweight. Good for thumbnails, previews, and email images where small size matters.
• Below 50 — Noticeable artifacts. Only use when you need the absolute smallest files.

Example: High-quality WebP

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=webp&quality=90" \
  -o high-quality.webp

Example: Lightweight JPEG thumbnail

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=jpeg&quality=60" \
  -o thumbnail.jpg

Resizing output images

Sometimes you need a smaller version of the screenshot — a thumbnail for a link preview, a card image for social media, or a preview in an email. Instead of capturing at full size and resizing in your application, you can let the API do it.

The image is always resized proportionally — it will never be stretched or distorted. If you provide both width and height, the image fits inside that box while keeping its original proportions. The image will not be enlarged beyond its original size.

Example: 320px wide thumbnail

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=webp&quality=70&resize_width=320" \
  -o thumb.webp

Example: Fit within a 400×300 box

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&resize_width=400&resize_height=300" \
  -o preview.png

Transparent backgrounds

When you capture a specific element — a logo, an icon, or a UI component — the page background often gets in the way. The omit_background parameter removes it, giving you a transparent PNG or WebP.

Example: Logo with transparent background

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&selector=.logo&omit_background=true&format=png" \
  -o logo.png

Practical recipes

Social card image

Open Graph and Twitter Card images look best at 1200×630 pixels in WebP or JPEG.

JavaScript Copy

const response = await fetch('https://api.screenshotrun.com/v1/screenshots', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/blog/post',
    width: 1200,
    height: 630,
    format: 'webp',
    quality: 80,
  }),
});

const { data } = await response.json();
console.log(data.links.image);

Python Copy

import requests

response = requests.post(
    "https://api.screenshotrun.com/v1/screenshots",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "url": "https://example.com/blog/post",
        "width": 1200,
        "height": 630,
        "format": "webp",
        "quality": 80,
    },
)

data = response.json()["data"]
print(data["links"]["image"])

PHP Copy

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://api.screenshotrun.com/v1/screenshots', [
        'url' => 'https://example.com/blog/post',
        'width' => 1200,
        'height' => 630,
        'format' => 'webp',
        'quality' => 80,
    ]);

$data = $response->json('data');

cURL Copy

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/post",
    "width": 1200,
    "height": 630,
    "format": "webp",
    "quality": 80
  }'

Ruby Copy

require "net/http"
require "json"

uri = URI("https://api.screenshotrun.com/v1/screenshots")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  url: "https://example.com/blog/post",
  width: 1200,
  height: 630,
  format: "webp",
  quality: 80,
}.to_json

response = http.request(request)
data = JSON.parse(response.body)["data"]

Go Copy

body, _ := json.Marshal(map[string]any{
        "url": "https://example.com/blog/post",
        "width": 1200,
        "height": 630,
        "format": "webp",
        "quality": 80,
    })

req, _ := http.NewRequest("POST",
    "https://api.screenshotrun.com/v1/screenshots",
    bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]any
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

Java Copy

var client = HttpClient.newHttpClient();

var body = """
    {
        "url": "https://example.com/blog/post",
        "width": 1200,
        "height": 630,
        "format": "webp",
        "quality": 80
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.screenshotrun.com/v1/screenshots"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

High-resolution archival screenshot

For archival, use PNG at retina resolution with full page enabled. The file will be large, but every detail is preserved.

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "full_page": true,
    "retina": true,
    "format": "png"
  }'

Email-friendly lightweight preview

Emails have strict size limits. Use JPEG with moderate quality and resize to keep it under 100 KB.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=jpeg&quality=50&resize_width=320" \
  -o email-preview.jpg