Delivery and embedding

After a screenshot is generated, you can either consume it as structured JSON or turn the API URL into a direct image. The right choice depends on where the screenshot is going next.

Two delivery models

When you need	Use	Result
Screenshot metadata inside an app or backend workflow	Default JSON response	Read the asset from `data.screenshot.url`
A direct image URL for HTML, CSS, Markdown, or social tags	`embed: 'screenshot.url'`	The API URL itself behaves like an image

JSON plus CDN URL

The default response gives you the screenshot metadata plus a CDN-hosted asset URL:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://github.com/microlinkhq' URL with 'screenshot' & 'meta' API parameters:

CLI Microlink API example

microlink https://github.com/microlinkhq&screenshot

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq" \
  -d "screenshot=true" \
  -d "meta=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://github.com/microlinkhq",
    "screenshot": "true",
    "meta": "false"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://github.com/microlinkhq",
  screenshot: "true",
  meta: "false"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://github.com/microlinkhq",
    "screenshot" => "true",
    "meta" => "false"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://github.com/microlinkhq")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false
})

Use data.screenshot.url when your application already expects JSON.

This is the best fit for server-side workflows, queues, automation jobs, and UI code that wants to keep the JSON response around.

Direct image with embed

Set embed=screenshot.url to return the image as the response body:

CLI Microlink API example

microlink https://github.com/microlinkhq&screenshot&embed=screenshot.url

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq" \
  -d "screenshot=true" \
  -d "meta=false" \
  -d "embed=screenshot.url"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false,
  embed: "screenshot.url"
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://github.com/microlinkhq",
    "screenshot": "true",
    "meta": "false",
    "embed": "screenshot.url"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://github.com/microlinkhq",
  screenshot: "true",
  meta: "false",
  embed: "screenshot.url"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://github.com/microlinkhq",
    "screenshot" => "true",
    "meta" => "false",
    "embed" => "screenshot.url"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://github.com/microlinkhq")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    q.Set("embed", "screenshot.url")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false,
  embed: "screenshot.url"
})

The API URL itself becomes the image. You can use dot notation to reference any nested field in the response payload.

The embed parameter uses dot notation to extract a specific field from the JSON response and return it directly. For screenshots, screenshot.url is the field you want. See the embed reference for all supported fields and advanced usage.

HTML

Use the API URL directly as an <img> src:

<img
  src="https://api.microlink.io?url=https://github.com/microlinkhq&screenshot&meta=false&embed=screenshot.url"
  alt="GitHub screenshot"
  loading="lazy"
/>

The image loads directly — no JavaScript needed, no parsing, no extra requests. This works in any HTML context, including emails and static sites.

CSS

Use it as a background-image:

.hero {
  background-image: url(https://api.microlink.io?url=https://github.com/microlinkhq&screenshot&meta=false&embed=screenshot.url);
  background-size: cover;
  background-position: center;
}

Markdown

Standard Markdown image syntax works:

![GitHub](https://api.microlink.io?url=https://github.com/microlinkhq&screenshot&meta=false&embed=screenshot.url)

This is useful for documentation, README files, and any Markdown-based CMS.

One of the most powerful use cases — generate dynamic social preview images for any page:

<meta property="og:image" content="https://api.microlink.io?url=https://your-site.com/blog/post&screenshot&meta=false&embed=screenshot.url">
<meta name="twitter:image" content="https://api.microlink.io?url=https://your-site.com/blog/post&screenshot&meta=false&embed=screenshot.url">

Every time someone shares your link on Twitter, Slack, Discord, or LinkedIn, they can receive an up-to-date screenshot of the page. Combined with caching, these images are served quickly from cache whenever possible.

Embedding with customization

All screenshot parameters work with embed. For example, a mobile screenshot with a browser overlay:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://microlink.io' URL with 'screenshot', 'device', 'meta' & 'embed' API parameters:

CLI Microlink API example

microlink https://microlink.io&screenshot.overlay.background='linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)'&screenshot.overlay.browser=dark&device='iPhone 15 Pro'&embed=screenshot.url

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://microlink.io" \
  -d "screenshot.overlay.background=linear-gradient(225deg%2C%20%23FF057C%200%25%2C%20%238D0B93%2050%25%2C%20%23321575%20100%25)" \
  -d "screenshot.overlay.browser=dark" \
  -d "device=iPhone%2015%20Pro" \
  -d "meta=false" \
  -d "embed=screenshot.url"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://microlink.io', {
  screenshot: {
    overlay: {
      background: "linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)",
      browser: "dark"
    }
  },
  device: "iPhone 15 Pro",
  meta: false,
  embed: "screenshot.url"
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://microlink.io",
    "screenshot.overlay.background": "linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)",
    "screenshot.overlay.browser": "dark",
    "device": "iPhone 15 Pro",
    "meta": "false",
    "embed": "screenshot.url"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://microlink.io",
  screenshot.overlay.background: "linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)",
  screenshot.overlay.browser: "dark",
  device: "iPhone 15 Pro",
  meta: "false",
  embed: "screenshot.url"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://microlink.io",
    "screenshot.overlay.background" => "linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)",
    "screenshot.overlay.browser" => "dark",
    "device" => "iPhone 15 Pro",
    "meta" => "false",
    "embed" => "screenshot.url"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://microlink.io")
    q.Set("screenshot.overlay.background", "linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)")
    q.Set("screenshot.overlay.browser", "dark")
    q.Set("device", "iPhone 15 Pro")
    q.Set("meta", "false")
    q.Set("embed", "screenshot.url")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://microlink.io', {
  screenshot: {
    overlay: {
      background: "linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)",
      browser: "dark"
    }
  },
  device: "iPhone 15 Pro",
  meta: false,
  embed: "screenshot.url"
})

Generate and embed a mobile screenshot with a browser overlay in a single URL.

The equivalent URL:

https://api.microlink.io?url=https://microlink.io&screenshot.overlay.background=linear-gradient(225deg,%20%23FF057C%200%25,%20%238D0B93%2050%25,%20%23321575%20100%25)&screenshot.overlay.browser=dark&device=iPhone%2015%20Pro&meta=false&embed=screenshot.url

Filtering JSON responses

If you still want JSON but only need the screenshot field, use filter:

CLI Microlink API example

microlink https://github.com/microlinkhq&screenshot&filter=screenshot

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq" \
  -d "screenshot=true" \
  -d "meta=false" \
  -d "filter=screenshot"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false,
  filter: "screenshot"
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://github.com/microlinkhq",
    "screenshot": "true",
    "meta": "false",
    "filter": "screenshot"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://github.com/microlinkhq",
  screenshot: "true",
  meta: "false",
  filter: "screenshot"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://github.com/microlinkhq",
    "screenshot" => "true",
    "meta" => "false",
    "filter" => "screenshot"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://github.com/microlinkhq")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    q.Set("filter", "screenshot")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false,
  filter: "screenshot"
})

The response only includes the screenshot field. This is useful for JSON workflows, but unnecessary when you already use embed.

See the filter reference for dot notation and multiple fields.

Custom filename
PRO

The filename parameter lets you assign a meaningful name to the generated screenshot asset:

CLI Microlink API example

microlink https://github.com/microlinkhq&screenshot&filename=github-microlink

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq" \
  -d "screenshot=true" \
  -d "meta=false" \
  -d "filename=github-microlink"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false,
  filename: "github-microlink"
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://github.com/microlinkhq",
    "screenshot": "true",
    "meta": "false",
    "filename": "github-microlink"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://github.com/microlinkhq",
  screenshot: "true",
  meta: "false",
  filename: "github-microlink"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://github.com/microlinkhq",
    "screenshot" => "true",
    "meta" => "false",
    "filename" => "github-microlink"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://github.com/microlinkhq")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    q.Set("filename", "github-microlink")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  screenshot: true,
  meta: false,
  filename: "github-microlink"
})

Helpful when you are downloading assets, organizing archives, or generating user-facing files with readable names.

Security considerations

If the request needs an API key, cookies, or authorization headers, do not expose those values in client-side code or public embed URLs. Keep the request on the server side or protect it with a proxy:

Use
@microlink/proxy
for self-hosted protection.
Use
@microlink/edge-proxy
for edge-deployed protection.

Read more in the authentication docs and the private pages guide.

Next step

Learn how to optimize screenshot requests for speed and cost in caching and performance.