> ## 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. # Score thumbnail > Score a thumbnail and get a main score with subscores. ## OpenAPI ````yaml /openapi.json POST /v2/thumbnail/score 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/score: post: tags: - thumbnail summary: Score thumbnail operationId: post_v2_thumbnail_score parameters: [] requestBody: required: true content: application/json: schema: type: object properties: 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, title: type: string description: Optional title for context maxLength: 200 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: main_score: type: number description: Overall score 0-100 request_id: type: string subscores: type: object properties: clarity: type: number curiosity: type: number emotion: type: number idea: type: number virality: type: number additionalProperties: false required: - clarity - curiosity - emotion - idea - virality suggestion: type: string nullable: true additionalProperties: false required: - main_score - request_id - subscores - suggestion example: main_score: 84 request_id: 18b2ad5e-2a9e-4d3f-b9a8-9f2a1e0b1234 subscores: clarity: 82 curiosity: 85 emotion: 76 idea: 79 virality: 88 suggestion: >- Increase contrast and tighten composition in the center section. '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/score" \ -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/score" 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/score"; 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 - 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_)' ````