> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get an Avatar

> Returns a single Studio Avatar owned by the authenticated account.



## OpenAPI

````yaml /openapi/avatar-open-api.json get /avatars/{avatarId}
openapi: 3.0.3
info:
  title: Spatius API
  version: 1.0.0
  description: >-
    The Spatius API lets you create and manage avatars programmatically. Submit
    a source image, poll the asynchronous creation job, and use the resulting
    avatar ID anywhere an avatar ID is accepted in your SDK integration.


    All endpoints require the `X-App-ID` and `X-API-Key` headers. See
    [Authentication](/api-reference/authentication) and [Errors and
    Limits](/api-reference/errors).
servers:
  - url: https://console.spatius.ai/v1/open
    description: Spatius Console API (global)
security:
  - AppId: []
    ApiKey: []
tags:
  - name: Avatars
    description: >-
      Create Avatars and read the canonical Studio Avatar resources owned by
      your account.
  - name: Avatar Jobs
    description: Track asynchronous Avatar creation jobs.
paths:
  /avatars/{avatarId}:
    get:
      tags:
        - Avatars
      summary: Get an Avatar
      description: Returns a single Studio Avatar owned by the authenticated account.
      operationId: getAvatar
      parameters:
        - name: avatarId
          in: path
          required: true
          description: Avatar ID (UUID).
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The requested Avatar.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAvatarResponse'
              example:
                avatar:
                  id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  name: Support Agent
                  coverUrl: https://cdn.spatius.ai/avatars/a1b2c3d4/cover.png
                  backgroundImageUrl: https://cdn.spatius.ai/avatars/a1b2c3d4/background.png
                  createdAt: '2026-07-25T09:47:12Z'
                  updatedAt: '2026-07-25T09:47:12Z'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    GetAvatarResponse:
      type: object
      properties:
        avatar:
          $ref: '#/components/schemas/Avatar'
    Avatar:
      type: object
      description: A canonical Studio Avatar resource.
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Avatar ID usable anywhere an Avatar ID is accepted (for example
            `SPATIUS_AVATAR_ID`).
        name:
          type: string
        coverUrl:
          type: string
          format: uri
          description: Avatar cover image.
        backgroundImageUrl:
          type: string
          format: uri
          description: Default background image, when one is configured.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      description: The single public error envelope returned by every Spatius API endpoint.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
              enum:
                - unauthorized
                - forbidden
                - invalid_request
                - not_found
                - insufficient_avatar_units
                - rate_limit_exceeded
                - concurrency_limit_exceeded
                - service_unavailable
                - unsupported_input
                - internal_error
            message:
              type: string
              description: Human-readable explanation specific to this occurrence.
            requestId:
              type: string
              description: >-
                Unique identifier for this request. Quote it when contacting
                support.
  responses:
    InvalidRequest:
      description: >-
        The request is malformed or violates a precondition, such as a missing
        `imageUrl` or an invalid ID in the path.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_request
              message: imageUrl is required
              requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f
    Unauthorized:
      description: >-
        The `X-App-ID` / `X-API-Key` pair is missing, does not match, or belongs
        to an inactive account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Unauthorized.
              requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f
    Forbidden:
      description: >-
        API access is not configured for the account, or avatar creation is
        disabled.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: API Avatar creation is disabled
              requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f
    NotFound:
      description: The requested resource does not exist or belongs to another account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Avatar job not found
              requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f
    RateLimited:
      description: >-
        A rate limit, rolling 24-hour quota, or concurrency limit was exceeded.
        Back off and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limit_exceeded
              message: Open API rate limit exceeded
              requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f
    InternalError:
      description: An unexpected server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: internal_error
              message: An internal error occurred.
              requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f
  securitySchemes:
    AppId:
      type: apiKey
      in: header
      name: X-App-ID
      description: Your Spatius App ID.
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: The API key bound to the App ID.

````