> ## Documentation Index > Fetch the complete documentation index at: https://docs.pikzels.com/llms.txt > Use this file to discover all available pages before exploring further. # Upscale thumbnail > Upscale a thumbnail to 4K. Generated output URLs expire after 24 hours. ## OpenAPI ````yaml openapi.json POST /v2/thumbnail/upscale openapi: 3.0.3 info: title: Pikzels Public API version: v2 description: >- Public REST API for external developers (v2). Synchronous processing for thumbnails/titles (waits for result). Async for persona/style creation. Thumbnail output URLs expire in 24 hours. Personas and styles are persisted. Image inputs must be JPEG, PNG or WebP, at most 10 MB and 25 megapixels, and not animated; the whole request body is limited to 15 MB. V2 assigns a request_id at request start, returns it on error responses, and also sends it as the X-Request-Id header. V2 error messages are safe public summaries; use error.code and request_id for programmatic handling and support. Requests that cannot be processed return GENERATION_REJECTED. Smart Balance recovery only charges when the configured top-up can cover the failed request. When Smart Balance recovery is blocked by a failed or unpaid auto top-up invoice, V2 returns SMART_BALANCE_PAYMENT_FAILED. Each account has a limit on requests in flight at once (GET requests are not counted); it starts at 10 and grows with API top-ups in the last 28 days. A request beyond it is rejected immediately with TOO_MANY_REQUESTS and is not charged. Generated images carry embedded machine-readable AI-provenance metadata (EXIF and XMP, including the IPTC digital source type) identifying them as AI-generated. servers: - url: https://api.pikzels.com security: [] paths: /v2/thumbnail/upscale: post: tags: - thumbnail summary: Upscale thumbnail description: >- Upscale an image to 4K as a PNG: 3840x2160 for landscape, 2160x3840 for portrait and 1920x1920 for square. Accepts square images and landscape or portrait images from 16:9 to 3:1 that are smaller than the output size; any other image returns VALIDATION_ERROR before a charge. Upscaling is generative enhancement: it keeps the composition and may refine fine detail. operationId: post_v2_thumbnail_upscale parameters: [] requestBody: required: true content: application/json: schema: type: object properties: image_url: type: string description: >- HTTPS URL -- provide this or image_base64. A YouTube watch URL resolves to that video's current thumbnail pattern: ^https://\S+$ image_base64: type: string description: Base64 data URL -- provide this or image_url pattern: ^data:image/[a-zA-Z0-9.+-]+;base64, additionalProperties: false allOf: - oneOf: - required: - image_url properties: image_url: {} not: required: - image_base64 properties: image_base64: {} - required: - image_base64 properties: image_base64: {} not: required: - image_url properties: image_url: {} example: image_url: https://cdn.pikzels.com/example.png responses: '200': description: Success content: application/json: schema: type: object properties: model: type: string description: The model that upscaled this thumbnail output: type: string description: URL to upscaled thumbnail (expires in 24h) prompt_compacted: type: boolean description: 'Always false: upscale takes no prompt' request_id: type: string additionalProperties: false required: - model - output - prompt_compacted - request_id example: model: pkz_upscale output: https://cdn.pikzels.com/example.png prompt_compacted: false request_id: 18b2ad5e-2a9e-4d3f-b9a8-9f2a1e0b1234 '400': description: Error content: application/json: schema: anyOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/ValidationErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '499': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '504': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyAuth: [] x-codeSamples: - lang: bash label: cURL source: |- curl -X POST "https://api.pikzels.com/v2/thumbnail/upscale" \ -H "X-Api-Key: pkz_yourapikey" \ -H "Content-Type: application/json" \ --data-raw '{ "image_url": "https://cdn.pikzels.com/example.png" }' - lang: python label: Python source: |- import requests url = "https://api.pikzels.com/v2/thumbnail/upscale" headers = { "X-Api-Key": "pkz_yourapikey", "Content-Type": "application/json", } payload = { "image_url": "https://cdn.pikzels.com/example.png" } response = requests.post(url, headers=headers, json=payload) print(response.json()) - lang: javascript label: JavaScript source: |- const url = "https://api.pikzels.com/v2/thumbnail/upscale"; const body = { "image_url": "https://cdn.pikzels.com/example.png" }; const options = { method: "POST", headers: { "X-Api-Key": "pkz_yourapikey", "Content-Type": "application/json", }, body: JSON.stringify(body), }; const response = await fetch(url, options); const data = await response.json(); console.log(data); components: schemas: ErrorResponse: type: object additionalProperties: false required: - error - request_id properties: error: type: object additionalProperties: false required: - code - message properties: code: type: string enum: - VALIDATION_ERROR - INVALID_PERSONA - INVALID_STYLE - INVALID_AMOUNT - CONTENT_POLICY - CANNOT_DELETE_PROCESSING - SUPPORT_IMAGE_NOT_SUPPORTED - MODEL_UNAVAILABLE - PERSONA_NOT_SUPPORTED - STYLE_NOT_SUPPORTED - PERSONA_NOT_FOUND - STYLE_NOT_FOUND - PERSONA_NOT_READY - STYLE_NOT_READY - IMAGE_TOO_LARGE - MISSING_API_KEY - INVALID_API_KEY_FORMAT - INVALID_API_KEY - API_KEY_INACTIVE - API_KEY_DELETED - INSUFFICIENT_CREDITS - SMART_BALANCE_PAYMENT_FAILED - API_ACCESS_NOT_ENABLED - ACCOUNT_SUSPENDED - NOT_FOUND - NAME_RESERVED - NAME_ALREADY_EXISTS - CONFLICT - GENERATION_REJECTED - CANCELLED - GENERATION_FAILED - INVALID_IMAGE - INTERNAL_ERROR - SERVICE_UNDER_MAINTENANCE - GENERATION_TIMEOUT - SCORING_TIMEOUT - TITLE_TIMEOUT - TOO_MANY_REQUESTS message: type: string request_id: type: string ValidationErrorResponse: type: object additionalProperties: false required: - error - request_id properties: error: type: object additionalProperties: false required: - code - message properties: code: type: string enum: - VALIDATION_ERROR message: type: string details: type: array items: type: object additionalProperties: false required: - message properties: field: type: string message: type: string request_id: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: 'Your Pikzels API key (prefix: pkz_)' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.