# Thumbnails

> Render the pages of documents and stored templates as PNG, JPG, GIF or BMP images with the two thumbnails endpoints: zoom factor, page range, curl and .NET.

- **Product:** ReportingCloud
- **Section:** Documentation
- **Kind:** Topic
- **Path:** ReportingCloud > Document Processing > Thumbnails
- **2464 words**
- **Web URL:** https://docs.textcontrol.com/reporting-cloud/document-processing/thumbnails/
- **LLMs URL:** https://docs.textcontrol.com/reporting-cloud/document-processing/thumbnails/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/reporting-cloud/document-processing/thumbnails/llms-full.txt

---

How do you show users what a template or a created document looks like before they download it? ReportingCloud renders the pages as images: a preview of every template in a template picker, the first page of each invoice in a list, a page overview before a document is sent. Two endpoints do this, one for a document you send with the request and one for a template in your template storage, and both return one image per page in the size and format you choose.

### How Thumbnails Work

The two endpoints take the same options and differ in where the document comes from:

| Endpoint | Source of the pages |
|---|---|
| [POST /v1/document/thumbnails](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/thumbnails/post/llms-full.txt) | A document in the body, as a Base64 string in a JSON string. The formats are DOC, DOCX, PDF, TX, XLSX, RTF and HTML |
| [GET /v1/templates/thumbnails](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/thumbnails/get/llms-full.txt) | A template in your template storage, named in the required query parameter `templateName`, which is matched regardless of letter case |

Both take these optional query parameters:

| Parameter | Content |
|---|---|
| `zoomFactor` | The size of the images in percent of the page size, from 10 to 400. The default is `100` |
| `fromPage` | The first page to render, from 1 to the number of pages. The default is the first page |
| `toPage` | The last page to render, up to the number of pages. The default is the last page, and so is `0` |
| `imageFormat` | The image format: `PNG`, `JPG`, `GIF` or `BMP`, in upper or lower case. The default is `PNG` |

The response is a JSON array of Base64 strings, one image per page, in page order. If `fromPage` is greater than `toPage`, the response is `null` instead of an array.

A request is refused with `400 Bad Request` and a plain-text message in these cases:

- "Template not valid": `zoomFactor` is not between 10 and 400, or `fromPage` is less than 1.
- "Page numbers not valid": `fromPage` or `toPage` is greater than the number of pages.
- "The image format is not supported": `imageFormat` is not one of the four formats.
- "No merge data found in body": the body of `document/thumbnails` is empty or is not a JSON string.
- "Template doesn't exist in storage": the template name of `templates/thumbnails` is not in the storage.

A `zoomFactor`, `fromPage` or `toPage` that is not an integer is ignored, and its default is used, but one given without a value is refused with 400 and the JSON body `{"Message":"The request is invalid."}`. An empty `imageFormat` gets `500 Internal Server Error`, and so does a body of `document/thumbnails` whose JSON string is not Base64. Data in a format that `document/thumbnails` doesn't support is not refused: it is rendered as plain text.

Both endpoints count against the document quota: each successful request adds one document, however many pages it renders, and a response of `null` counts as well. They have no `test` parameter. [Plans and Licensing](https://docs.textcontrol.com/reporting-cloud/overview/licensing/llms-full.txt) lists the quota of each plan, and every request needs the `Authorization` header that [Authentication](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt) describes.

### Create Thumbnails of a Document With curl

The following commands render the first three pages of *invoice.docx* at half their size and save each image as a file:

```bash
# Wrap the Base64 string of the document in a JSON string
base64 -w 0 invoice.docx | jq -Rs . > document.json

curl "https://api.reporting.cloud/v1/document/thumbnails?zoomFactor=50&fromPage=1&toPage=3&imageFormat=PNG" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @document.json \
  --output thumbnails.json

# Decode each Base64 string of the array into page-1.png, page-2.png ...
count=$(jq length thumbnails.json)
for i in $(seq 0 $((count - 1))); do
  jq -r ".[$i]" thumbnails.json | base64 -d > "page-$((i + 1)).png"
done
```

The commands work as follows:

- `base64 -w 0` encodes the file on one line, and `jq -Rs .` makes a JSON string of it, which is the whole body.
- The query parameters select the pages, the size and the format. Keep the URL in quotes: the shell would otherwise treat each `&` as the end of a command.
- The response is an array with one Base64 string per page. `jq -r ".[$i]"` takes one element without quotes, and `base64 -d` decodes it into an image file.

### Create Thumbnails of a Stored Template With curl

A template in the storage needs no body. The following request renders the first page of the demo template *sample\_invoice.tx*, which every trial account has in its storage, as a JPG image at 50 percent:

```bash
curl "https://api.reporting.cloud/v1/templates/thumbnails?templateName=sample_invoice.tx&zoomFactor=50&fromPage=1&toPage=1&imageFormat=JPG" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  --output thumbnails.json

jq -r ".[0]" thumbnails.json | base64 -d > sample-invoice.jpg
```

A document that you have created with the merge or the convert endpoint doesn't have to be uploaded to the storage first: send it to `POST /v1/document/thumbnails`.

### Create Thumbnails With .NET

The .NET SDK, the NuGet package `TXTextControl.ReportingCloud`, has a method for each endpoint, among them the two thumbnail endpoints. The following console application renders three pages of a document and the first page of a stored template:

```csharp
using TXTextControl.ReportingCloud;

ReportingCloud rc = new ReportingCloud(
    Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY"));

byte[] document = File.ReadAllBytes("invoice.docx");

// Pages 1 to 3 at a zoom factor of 50 percent
List<string> pages = rc.GetDocumentThumbnails(document, 50, 1, 3, ImageFormat.PNG);

for (int i = 0; i < pages.Count; i++)
{
    // Each element is a Base64 string: decode it into the image file
    File.WriteAllBytes($"page-{i + 1}.png", Convert.FromBase64String(pages[i]));
}

// The first page of a template in the storage
List<string> preview = rc.GetTemplateThumbnails("sample_invoice.tx", 50, 1, 1, ImageFormat.PNG);
File.WriteAllBytes("sample-invoice.png", Convert.FromBase64String(preview[0]));
```

The code works as follows:

- `GetDocumentThumbnails` takes the document as a byte array, then the zoom factor, the first and the last page and an `ImageFormat` value: `PNG`, `JPG`, `GIF` or `BMP`. All arguments after the document are optional, with the defaults `100`, `1`, `0` and `ImageFormat.PNG`; a last page of `0` renders up to the end of the document.
- `GetTemplateThumbnails` takes the template name and the zoom factor, followed by the same optional arguments.
- In an application for .NET or .NET Core, both methods return a `List<string>` of Base64 strings, which `Convert.FromBase64String` decodes. In an application for .NET Framework, the package returns a `List<System.Drawing.Image>` instead, with images you can save with `Image.Save`.
- A refused request throws an `ArgumentException` whose message is the response body.

In the PHP SDK, the methods are `getDocumentThumbnails($documentFilename, $zoomFactor, $fromPage, $toPage, $imageFormat)` and `getTemplateThumbnails($templateName, $zoomFactor, $fromPage, $toPage, $imageFormat)`. All five arguments are required, page numbers start at `1`, and each element of the returned array is the binary data of one image. The Java and Ruby SDKs offer template thumbnails only.

### Choose the Size and the Pages

- **Size.** `zoomFactor` is a percentage of the page size, from 10 to 400. A value of 100, the default, renders the page at its full size at 96 dpi, 816 by 1056 pixels for a Letter page; smaller values give smaller images for a preview list.
- **First page only.** For a single preview image, set `fromPage=1&toPage=1`, or pass `1, 1` as the page arguments in the SDKs.
- **Every page.** Leave out `fromPage` and `toPage`, or set `toPage=0`, and the array has one image for every page. Every request counts as one document, so rendering all pages at once uses less quota than one request per page.
- **Page count first.** To know how many pages a stored template has before you render it, ask the pagecount endpoint that [Managing Templates](https://docs.textcontrol.com/reporting-cloud/document-processing/templates/llms-full.txt) describes.

### Next Steps

- [Converting Documents](https://docs.textcontrol.com/reporting-cloud/document-processing/converting/llms-full.txt): convert the document itself into another format.
- [Managing Templates](https://docs.textcontrol.com/reporting-cloud/document-processing/templates/llms-full.txt): upload templates, list them and read their page count.
- [Supported File Formats](https://docs.textcontrol.com/reporting-cloud/overview/file-formats/llms-full.txt): the formats of each endpoint.
- [Errors and Status Codes](https://docs.textcontrol.com/reporting-cloud/document-processing/errors/llms-full.txt): what a refused request means.

---

## Nearby

- **Previous:** [Find and Replace](https://docs.textcontrol.com/reporting-cloud/document-processing/find-replace/llms-full.txt)
- **Next:** [Managing Templates](https://docs.textcontrol.com/reporting-cloud/document-processing/templates/llms-full.txt)