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

# Generate Thumbnail

`POST /api/v1/thumbnails/generate`

## 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`
- Auth: none declared

Generate a thumbnail from a file upload or URL.

**File Upload**: Use multipart/form-data with a `file` field.

**URL Fetch**: Use JSON body with `url` field. Optionally include `url_headers` for authenticated URLs.

**Options**:
- `width`, `height`: Max dimensions (default 600x400)
- `quality`: JPEG quality 1-100 (default 95)
- `sync`: Wait for result (true) or return job ID (false)
- `webhook_url`: URL to POST result when complete (async only)
- `response_type`: "url" returns storage URL, "base64" returns encoded image

## Headers

- `X-API-Key` string

## 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
- `413`: File too large
- `415`: Unsupported file type
- `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)