---
title: "Generate Thumbnail (JSON)"
method: POST
path: "/api/v1/thumbnails/generate/json"
tags: ["thumbnails"]
---

# Generate Thumbnail (JSON)

`POST /api/v1/thumbnails/generate/json`

## Request

- Base URL: `https://docs.thedrive.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.thedrive.ai/api/v1/thumbnails/generate/json`
- Auth: none declared

Generate a thumbnail from a URL using JSON request body.

## Headers

- `X-API-Key` string

## Request body

- ThumbnailRequest: Request model for thumbnail generation. Either `url` must be provided (for URL-based fetching) or a file must be uploaded via multipart form data. When using the JSON body, only `url` is supported.
  - `url` string, uri, nullable: URL to fetch the file from
  - `url_headers` object, nullable: Custom headers for URL fetching (e.g., Authorization)
  - `width` integer: Maximum thumbnail width
  - `height` integer: Maximum thumbnail height
  - `quality` integer: JPEG quality (1-100)
  - `sync` boolean: If true, wait for result. If false, return job_id immediately.
  - `webhook_url` string, uri, nullable: URL to POST the result when processing completes (for async requests)
  - `response_type` 'url' | 'base64': Response format for thumbnail delivery.

## Response `200`

Successful Response

- ThumbnailResponse: Response for a completed thumbnail generation.
  - `success` boolean
  - `job_id` string, required: Unique job identifier
  - `status` 'pending' | 'processing' | 'completed' | 'failed': Job processing status.
  - `thumbnail_url` string, nullable: URL to the thumbnail image
  - `thumbnail_base64` string, nullable: Base64-encoded thumbnail (if response_type='base64')
  - `metadata` ThumbnailMetadata, required: Metadata about the generated thumbnail.
    - `original_filename` string, required: Original filename
    - `file_type` string, required: File extension (e.g., 'pdf', 'png')
    - `file_category` 'image' | 'video' | 'pdf' | 'document' | 'spreadsheet' | 'presentation' | 'markdown' | 'code' | 'text' | 'ebook' | 'unsupported', required: Supported file categories for thumbnail generation.
    - `file_size` integer, required: Original file size in bytes
    - `mime_type` string, required: MIME type of the original file
    - `thumbnail_width` integer, required: Thumbnail width in pixels
    - `thumbnail_height` integer, required: Thumbnail height in pixels
    - `created_at` string, date-time, required: When the thumbnail was created

## Other responses

- `202`: Async job created
- `400`: Invalid request
- `422`: Validation Error

---

[API](https://skmtc.dev/thedrive/apis/the-drive-ai-api.md) · [All operations](https://skmtc.dev/thedrive/apis/the-drive-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thedrive/apis/the-drive-ai-api/revisions/ee4e32647ebf?raw)