> ## 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.

# Get persona or style

> Retrieve a persona or style by ID, including built-in ones.



## OpenAPI

````yaml openapi.json GET /v2/pikzonality/{id}
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) by default; send async: true to get a
    request_id, status_url and response_url at once, poll GET
    /v2/requests/:request_id/status until the status is COMPLETED, then fetch
    the result from GET /v2/requests/:request_id. Async for persona/style
    creation. Thumbnail output URLs stay available, and every request with its
    input and output is listed under Requests in the API dashboard. 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; an
    async request counts from submit until it completes or fails); 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/pikzonality/{id}:
    get:
      tags:
        - pikzonality
      summary: Get persona or style
      description: >-
        Works for your own personas and styles and for built-in ones. Built-in
        personas and styles are read-only: reference and special_instructions
        are always null, and updating or deleting one returns BUILTIN_READ_ONLY.
      operationId: get_v2_pikzonality_id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  failure_code:
                    type: string
                    nullable: true
                    description: >-
                      Why processing failed: SUBJECT_NOT_SUPPORTED,
                      SUBJECT_INCONSISTENT, CONTENT_POLICY, GENERATION_REJECTED,
                      or PROCESSING_FAILED for anything else. Null unless status
                      is failed.
                  failure_message:
                    type: string
                    nullable: true
                    description: >-
                      The user-facing message for failure_code. Null unless
                      status is failed.
                  id:
                    type: string
                  is_builtin:
                    type: boolean
                    description: >-
                      True for a built-in persona or style from Pikzels, false
                      for one you created.
                  mode:
                    type: string
                    enum:
                      - persona
                      - style
                  portrait_url:
                    type: string
                    nullable: true
                    description: Portrait image URL (null until completed).
                  progress:
                    type: number
                    description: From 0 to 100.
                  reference:
                    type: array
                    items:
                      type: string
                    nullable: true
                    description: >-
                      Reference image URLs. Null until completed, and always for
                      built-in ones.
                  special_instructions:
                    type: string
                    nullable: true
                    description: Always null for built-in ones.
                  status:
                    type: string
                    enum:
                      - processing
                      - completed
                      - failed
                  subject_kind:
                    type: string
                    nullable: true
                    description: >-
                      Personas only: what the images show; object means the
                      persona was refused. Null for styles and until classified.
                    enum:
                      - human
                      - animal
                      - character
                      - object
                  subject_medium:
                    type: string
                    nullable: true
                    description: >-
                      Personas only: the medium of the reference images. Null
                      for styles and until classified.
                    enum:
                      - photo
                      - drawn
                      - 3d
                additionalProperties: false
                required:
                  - name
                  - failure_code
                  - failure_message
                  - id
                  - is_builtin
                  - mode
                  - portrait_url
                  - progress
                  - reference
                  - special_instructions
                  - status
                  - subject_kind
                  - subject_medium
              example:
                name: Creator Studio
                failure_code: null
                failure_message: null
                id: 18b2ad5e-2a9e-4d3f-b9a8-9f2a1e0b1234
                is_builtin: false
                mode: persona
                portrait_url: https://cdn.pikzels.com/example.png
                progress: 100
                reference:
                  - https://cdn.pikzels.com/example.png
                special_instructions: Use cinematic colors and stronger contrast.
                status: completed
                subject_kind: human
                subject_medium: photo
        '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 GET
            "https://api.pikzels.com/v2/pikzonality/18b2ad5e-2a9e-4d3f-b9a8-9f2a1e0b1234"
            \
              -H "X-Api-Key: pkz_yourapikey"
        - lang: python
          label: Python
          source: >-
            import requests


            url =
            "https://api.pikzels.com/v2/pikzonality/18b2ad5e-2a9e-4d3f-b9a8-9f2a1e0b1234"

            headers = {
                "X-Api-Key": "pkz_yourapikey",
            }

            response = requests.get(url, headers=headers)

            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const url =
            "https://api.pikzels.com/v2/pikzonality/18b2ad5e-2a9e-4d3f-b9a8-9f2a1e0b1234";


            const options = {
              method: "GET",
              headers: {
                "X-Api-Key": "pkz_yourapikey",
              },
            };


            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_IMAGE
                - INVALID_PERSONA
                - INVALID_STYLE
                - INVALID_AMOUNT
                - CONTENT_POLICY
                - CANNOT_DELETE_PROCESSING
                - SUPPORT_IMAGE_NOT_SUPPORTED
                - MODEL_UNAVAILABLE
                - PERSONA_NOT_SUPPORTED
                - STYLE_NOT_SUPPORTED
                - REQUEST_IN_PROGRESS
                - 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
                - BUILTIN_READ_ONLY
                - PERSONA_NOT_FOUND
                - STYLE_NOT_FOUND
                - NOT_FOUND
                - PERSONA_NOT_READY
                - STYLE_NOT_READY
                - NAME_RESERVED
                - NAME_ALREADY_EXISTS
                - CONFLICT
                - IMAGE_TOO_LARGE
                - GENERATION_REJECTED
                - TOO_MANY_REQUESTS
                - CANCELLED
                - GENERATION_FAILED
                - INTERNAL_ERROR
                - SERVICE_UNDER_MAINTENANCE
                - GENERATION_TIMEOUT
                - SCORING_TIMEOUT
                - TITLE_TIMEOUT
            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.