Skip to main content
POST
/
api
/
v1
/
thumbnails
/
generate
Generate Thumbnail
curl --request POST \
  --url https://api.example.com/api/v1/thumbnails/generate \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=<string>' \
  --form 'url=<string>' \
  --form 'url_headers=<string>' \
  --form width=600 \
  --form height=400 \
  --form quality=95 \
  --form sync=true \
  --form 'webhook_url=<string>' \
  --form response_type=url
import requests

url = "https://api.example.com/api/v1/thumbnails/generate"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url_headers\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"width\"\r\n\r\n600\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"height\"\r\n\r\n400\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\n95\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"sync\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"response_type\"\r\n\r\nurl\r\n-----011000010111000001101001--"
headers = {"Content-Type": "multipart/form-data"}

response = requests.post(url, data=payload, headers=headers)

print(response.text)
const form = new FormData();
form.append('file', '<string>');
form.append('url', '<string>');
form.append('url_headers', '<string>');
form.append('width', '600');
form.append('height', '400');
form.append('quality', '95');
form.append('sync', 'true');
form.append('webhook_url', '<string>');
form.append('response_type', 'url');

const options = {method: 'POST'};

options.body = form;

fetch('https://api.example.com/api/v1/thumbnails/generate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/thumbnails/generate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url_headers\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"width\"\r\n\r\n600\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"height\"\r\n\r\n400\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\n95\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"sync\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"response_type\"\r\n\r\nurl\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Content-Type: multipart/form-data"
],
]);

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

curl_close($curl);

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

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

func main() {

url := "https://api.example.com/api/v1/thumbnails/generate"

payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url_headers\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"width\"\r\n\r\n600\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"height\"\r\n\r\n400\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\n95\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"sync\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"response_type\"\r\n\r\nurl\r\n-----011000010111000001101001--")

req, _ := http.NewRequest("POST", url, payload)

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/thumbnails/generate")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url_headers\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"width\"\r\n\r\n600\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"height\"\r\n\r\n400\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\n95\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"sync\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"response_type\"\r\n\r\nurl\r\n-----011000010111000001101001--")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/thumbnails/generate")

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

request = Net::HTTP::Post.new(url)
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url_headers\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"width\"\r\n\r\n600\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"height\"\r\n\r\n400\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\n95\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"sync\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"response_type\"\r\n\r\nurl\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body
{
  "job_id": "job_abc123",
  "metadata": {
    "created_at": "2024-01-15T10:30:00Z",
    "file_category": "pdf",
    "file_size": 102400,
    "file_type": "pdf",
    "mime_type": "application/pdf",
    "original_filename": "document.pdf",
    "thumbnail_height": 400,
    "thumbnail_width": 600
  },
  "status": "completed",
  "success": true,
  "thumbnail_url": "https://storage.example.com/thumbnails/thumb_abc123.jpg"
}
{
"job_id": "job_abc123",
"message": "Job created. Poll /api/v1/thumbnails/jobs/{job_id} for status.",
"status": "pending",
"success": true
}
{
"detail": "File size exceeds maximum allowed (50MB)",
"error": "validation_error",
"success": false
}
{
"detail": "File size exceeds maximum allowed (50MB)",
"error": "validation_error",
"success": false
}
{
"detail": "File size exceeds maximum allowed (50MB)",
"error": "validation_error",
"success": false
}
{
"detail": "File size exceeds maximum allowed (50MB)",
"error": "validation_error",
"success": false
}

Headers

X-API-Key
string

Body

multipart/form-data
file
string | null

File to generate thumbnail from

url
string | null

URL to fetch file from

url_headers
string | null

JSON-encoded headers for URL auth

width
integer
default:600

Max thumbnail width

Required range: 50 <= x <= 2000
height
integer
default:400

Max thumbnail height

Required range: 50 <= x <= 2000
quality
integer
default:95

JPEG quality

Required range: 1 <= x <= 100
sync
boolean
default:true

Wait for result or return job ID

webhook_url
string | null

Webhook URL for async completion

response_type
string
default:url

Response type: 'url' or 'base64'

Response

Successful Response

Response for a completed thumbnail generation.

job_id
string
required

Unique job identifier

metadata
ThumbnailMetadata · object
required

Thumbnail metadata

success
boolean
default:true
status
enum<string>
default:completed

Job processing status.

Available options:
pending,
processing,
completed,
failed
thumbnail_url
string | null

URL to the thumbnail image

thumbnail_base64
string | null

Base64-encoded thumbnail (if response_type='base64')