Shotify API Integration Guide

Integrate Shotify's screenshot API into your application with minimal effort. This guide provides detailed information on how to use our API, available parameters, and integration examples in various programming languages.

GET https://us-api.shotify.dev/?url=[https://yahoo.com]&format=[png]&res=[fhd]&token=[YOUR_TOKEN_KEY]

Shotify's API is designed for simplicity. Just make a GET request to our endpoint with the required parameters, and you'll receive a screenshot of the specified webpage in response. No SDK required - it works with any HTTP client.

API Parameters

The Shotify API accepts the following parameters to customize your screenshot requests:

Parameter	Required	Available Values	Description
url	Yes	Any valid URL	The webpage URL you want to capture. Must be URL-encoded.
format	Optional Default: png	png, pdf	Output format for the screenshot. Use 'png' for images or 'pdf' for document format.
res	Optional Default: fhd	hd, fhd, 2k, 4k, android, ios	Resolution preset for the screenshot. See the resolution details table below.
token	Yes	Your API token	Authentication token for accessing the API. Get this from your account dashboard.

Resolution Details

The res parameter accepts the following values, each representing a specific resolution configuration:

Resolution Value	Width	Height	Device Type	Notes
hd	1280	720	Desktop	Standard HD resolution
fhd	1920	1080	Desktop	Full HD resolution (default)
2k	2560	1440	Desktop	QHD/2K resolution
4k	3840	2160	Desktop	UHD/4K resolution
android	412	915	Mobile	Samsung Galaxy S25 Ultra with mobile user agent
ios	430	932	Mobile	iPhone 16 Pro Max with mobile user agent

Note

When using android or ios resolution options, the API automatically applies the appropriate mobile user agent strings to ensure proper rendering of mobile versions of websites:

Android: Mozilla/5.0 (Linux; Android 14; SM-S928U) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Mobile Safari/537.36
iOS: Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1

Integration Examples

Below are examples of how to integrate Shotify's API in various programming languages and environments.

cURL Integration

Use cURL to download screenshots directly from the command line or in shell scripts.

curl "https://us-api.shotify.dev/?url=https://yahoo.com&format=png&res=fhd&token=YOUR_TOKEN_KEY" --output screenshot.png

Use Cases

Automated screenshot capture in CI/CD pipelines
Batch processing of multiple URLs
Integration with shell scripts

Node.js Integration

For Node.js applications, use the fetch API or a similar HTTP client to download and save screenshots.

const fetch = require('node-fetch');
fetch('https://us-api.shotify.dev/?url=https://yahoo.com&format=png&res=fhd&token=YOUR_TOKEN_KEY')
  .then(res => res.buffer())
  .then(buffer => {
    require('fs').writeFileSync('screenshot.png', buffer);
  });

For modern Node.js versions using ESM imports:

import fetch from 'node-fetch';
import { writeFile } from 'fs/promises';

const response = await fetch('https://us-api.shotify.dev/?url=https://yahoo.com&format=png&res=fhd&token=YOUR_TOKEN_KEY');
const buffer = await response.buffer();
await writeFile('screenshot.png', buffer);

Python Integration

Python applications can use the requests library to easily download screenshots.

import requests
url = "https://us-api.shotify.dev/?url=https://yahoo.com&format=png&res=fhd&token=YOUR_TOKEN_KEY"
response = requests.get(url)
with open("screenshot.png", "wb") as f:
    f.write(response.content)

Error Handling Example

import requests
url = "https://us-api.shotify.dev/?url=https://yahoo.com&format=png&res=fhd&token=YOUR_TOKEN_KEY"
try:
    response = requests.get(url)
    response.raise_for_status()  # Raise exception for 4XX/5XX responses
    with open("screenshot.png", "wb") as f:
        f.write(response.content)
    print("Screenshot saved successfully")
except requests.exceptions.RequestException as e:
    print(f"Error capturing screenshot: {e}")

PHP Integration

PHP applications can use cURL to reliably download screenshots, which is more robust than file_get_contents.

$url = "https://us-api.shotify.dev/?url=https://yahoo.com&format=png&res=fhd&token=YOUR_TOKEN_KEY";

// Using cURL which is more reliable than file_get_contents
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30); // Set timeout to 30 seconds
$response = curl_exec($ch);

if(curl_errno($ch)) {
    echo 'Error: ' . curl_error($ch);
} else {
    file_put_contents("screenshot.png", $response);
    echo "Screenshot saved successfully.";
}

curl_close($ch);

Java Integration

Java applications can use standard java.net classes to download and save screenshots.

import java.io.*;
import java.net.*;
import java.nio.file.*;

public class ShotifyExample {
    public static void main(String[] args) throws Exception {
        String url = "https://us-api.shotify.dev/?url=https://yahoo.com&format=png&res=fhd&token=YOUR_TOKEN_KEY";
        InputStream in = new URL(url).openStream();
        Files.copy(in, new File("screenshot.png").toPath(), StandardCopyOption.REPLACE_EXISTING);
        in.close();
        System.out.println("Screenshot saved successfully.");
    }
}

Best Practices

Token Security: Never expose your API token in client-side code. For browser-based applications, proxy requests through your server.
Error Handling: Always implement proper error handling to gracefully manage API failures or timeouts.
URL Encoding: Ensure that URLs passed to the API are properly URL-encoded to handle special characters.
Caching: Implement caching mechanisms for frequently accessed screenshots to reduce API usage and improve performance.
Quota Management: Monitor your API usage to avoid exceeding your plan's quota. Consider implementing fallback mechanisms for quota exhaustion.

Optimizing Performance

For pages that rarely change, consider implementing a caching strategy to reduce API calls:

Store screenshots with a timestamp
Only request new screenshots after a certain time interval
Implement a refresh mechanism for users to manually update screenshots when needed