JavaScript SDK

The SDK is the recommended way to use the service from JavaScript. It takes care of the request, the headers and the answer for you, so a screenshot is one function call.

InstallationLink to this section

Add @url2image/sdk to your project with the package manager you use.

npm install @url2image/sdk

ImportingLink to this section

The SDK exports one function, Url2Image, both by name and as the default export.

import { Url2Image } from '@url2image/sdk'

// or, as the default export

import Url2Image from '@url2image/sdk'

UsageLink to this section

Call Url2Image with the page address, your token and any options. It resolves once the image is ready, and never throws: check success instead.

import { Url2Image } from '@url2image/sdk'

const { success, data, message } = await Url2Image({
    url: 'https://example.com',
    token: process.env.URL2IMAGE_TOKEN,
    options: {
        width: 1440,
        height: 900,
        fullPage: true
    }
})

if (success && data) {
    const { scrUrl, scrBase64 } = data

    // scrUrl is the hosted PNG, scrBase64 the same image as base64
}

else {
    // message says what went wrong and is safe to show to your users
    console.error(message)
}

RequestLink to this section

The function takes one object with these fields:

• urlstringRequired

  The page to capture, such as example.com/pricing. The protocol is optional, pages are always loaded over https.

• tokenstringRequired

  Your API token from the Account page. It identifies the account the credits are taken from.

• optionsobjectdefault {}

  Capture settings. Every one of them is optional, see the options reference.

ResponseLink to this section

It resolves with the same fields the REST API answers with:

• successbooleanAlways

  true when the screenshot was created, false for every error.

• messagestringAlways

  What happened, in plain words. Safe to show to your own users.

• dataobject | nullAlways

  The result on success. null on most errors, or the list of what is wrong when fields are missing.

• data.scrUrlstring | nullOn success

  The permanent link to the hosted PNG. It never expires. null when storage is false.

• data.scrBase64stringOn success

  The same PNG encoded as base64, without a data: prefix.

Framework examplesLink to this section

A route on your own server that takes a page address and answers with the hosted image link.

// app/api/screenshot/route.ts
import { Url2Image } from '@url2image/sdk'

export async function POST(request: Request) {
    const { url } = await request.json()

    const { success, data, message } = await Url2Image({
        url,
        token: process.env.URL2IMAGE_TOKEN,
        options: { width: 1280, height: 800 }
    })

    if (!success || !data) return Response.json({ message }, { status: 502 })

    return Response.json({ image: data.scrUrl })
}

Server environmentLink to this section

The SDK only works on a server, because your token goes with every request and must never reach a browser. In a browser it does not send anything and resolves with success set to false and a message saying so.