> ## 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. # Create from image > Generate a thumbnail from a reference image. Generated output URLs expire after 24 hours. ## OpenAPI ````yaml /openapi.json POST /v2/thumbnail/image 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/title URLs expire in 24 hours. Personas and styles are persisted. 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. servers: - url: https://api.pikzels.com security: [] paths: /v2/thumbnail/image: post: tags: - thumbnail summary: Create from image operationId: post_v2_thumbnail_image parameters: [] requestBody: required: true content: application/json: schema: type: object properties: prompt: type: string description: >- Optional instructions for the image. Ignored for pkz_2. Cannot contain URLs minLength: 1 maxLength: 3000 pattern: ^(?!.*[Hh][Tt][Tt][Pp]).+$ image_url: type: string description: HTTPS URL -- provide this or image_base64 pattern: ^https://\S+$ image_base64: type: string description: Base64 data URL -- provide this or image_url pattern: ^data:image/[a-zA-Z0-9.+-]+;base64, support_image_url: type: string description: >- Reference image (pkz_4 and pkz_4_5 only), HTTPS URL. If both support_image_url and support_image_base64 are provided, support_image_url is used. pattern: ^https://\S+$ support_image_base64: type: string description: >- Reference image (pkz_4 and pkz_4_5 only), base64 data URL. If both support_image_url and support_image_base64 are provided, support_image_url is used. pattern: ^data:image/[a-zA-Z0-9.+-]+;base64, image_weight: type: string description: >- Only applies to pkz_2 model Allowed values: "low", "medium", "high". default: medium enum: - low - medium - high model: type: string enum: - pkz_2 - pkz_3 - pkz_4 - pkz_4_5 description: 'Allowed values: "pkz_2", "pkz_3", "pkz_4", "pkz_4_5".' format: type: string enum: - '16:9' - '9:16' - '1:1' description: 'Allowed values: "16:9", "9:16", "1:1".' persona: type: string description: Persona ID style: type: string description: Style ID additionalProperties: false required: - model - format 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: {} - not: anyOf: - required: - support_image_url properties: model: enum: - pkz_2 - pkz_3 support_image_url: {} - required: - support_image_base64 properties: model: enum: - pkz_2 - pkz_3 support_image_base64: {} example: prompt: Make the cat fur white model: pkz_4 format: '16:9' image_url: https://example.com/reference.jpg responses: '200': description: Success content: application/json: schema: type: object properties: output: type: string description: URL to generated thumbnail (expires in 24h) request_id: type: string additionalProperties: false required: - output - request_id example: output: https://cdn.pikzels.com/example.png 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/image" \ -H "X-Api-Key: pkz_yourapikey" \ -H "Content-Type: application/json" \ --data-raw '{ "prompt": "Make the cat fur white", "model": "pkz_4", "format": "16:9", "image_url": "https://example.com/reference.jpg" }' - lang: python label: Python source: |- import requests url = "https://api.pikzels.com/v2/thumbnail/image" headers = { "X-Api-Key": "pkz_yourapikey", "Content-Type": "application/json", } payload = { "prompt": "Make the cat fur white", "model": "pkz_4", "format": "16:9", "image_url": "https://example.com/reference.jpg" } response = requests.post(url, headers=headers, json=payload) print(response.json()) - lang: javascript label: JavaScript source: |- const url = "https://api.pikzels.com/v2/thumbnail/image"; const body = { "prompt": "Make the cat fur white", "model": "pkz_4", "format": "16:9", "image_url": "https://example.com/reference.jpg" }; 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 - 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_)' ````