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

# Get Character

> Get character details by ID

Pulls up everything about a single character — where it is in processing, and which model encodings are ready to use. This is the endpoint you'll poll after [creating a character](/api-reference/characters/create) to know when it's ready.

<Note>
  Check back every 5 seconds or so until `status` turns `ready` (then look at `has_v3_encoding` / `has_v4_encoding` to see which model is good to go) — or `failed`.
</Note>

## Path parameters

| Parameter      | Type   | Required | Description                                      |
| -------------- | ------ | :------: | ------------------------------------------------ |
| `character_id` | string |     ✅    | The character UUID returned when you created it. |

## Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Character",
  "status": "ready",
  "has_v3_encoding": true,
  "has_v4_encoding": false,
  "thumbnail_url": "https://cdn.viggle.ai/characters/....png",
  "credits_used": 1.0,
  "created_at": "2026-06-12T08:00:00Z",
  "completed_at": "2026-06-12T08:00:42Z"
}
```

| Field                                 | Description                                                                                                   |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `status`                              | `pending`, `processing`, `ready`, or `failed`. Only `ready` characters can be rendered.                       |
| `has_v3_encoding` / `has_v4_encoding` | Whether the character is ready for `V3_Preview` / `V4_Preview` renders. Must match the model you render with. |
| `thumbnail_url`                       | Preview image of the processed character, once available.                                                     |
| `error_message`                       | Why processing failed. Present only when `status` is `failed`.                                                |
| `credits_used`                        | Credits actually charged for preprocessing.                                                                   |

## Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  character_id = "YOUR_CHARACTER_ID"
  url = f"https://apis.viggle.ai/api/characters/{character_id}"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}

  response = requests.get(url, headers=headers)
  response.raise_for_status()
  result = response.json()

  print(f"Name: {result['name']}")
  print(f"Status: {result['status']}")
  ```

  ```javascript JavaScript theme={null}
  const characterId = "YOUR_CHARACTER_ID";

  const response = await fetch(`https://apis.viggle.ai/api/characters/${characterId}`, {
    headers: { "Authorization": "Bearer YOUR_API_KEY" },
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const result = await response.json();
  console.log(`Name: ${result.name}`);
  console.log(`Status: ${result.status}`);
  ```

  ```bash cURL theme={null}
  curl -X GET https://apis.viggle.ai/api/characters/YOUR_CHARACTER_ID \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

## Next steps

Once `status` is `ready` and the encoding you need is `true`, use the character's `id` as `character_id` in a [render job](/api-reference/render/create).


## OpenAPI

````yaml GET /api/characters/{character_id}
openapi: 3.0.3
info:
  title: Viggle API
  description: Generate AI-powered character animation videos
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: Production server
security: []
paths:
  /api/characters/{character_id}:
    get:
      tags:
        - Characters
      summary: Get Character
      description: Get full details of a specific character including processing status.
      operationId: getCharacter
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Character details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Character'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Character not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorStructured'
              example:
                detail:
                  error_code: CS-UORC01-003
                  message: Character not found. Double-check the character_id.
      security:
        - bearerAuth: []
components:
  schemas:
    Character:
      type: object
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: My Character
        status:
          type: string
          enum:
            - pending
            - processing
            - ready
            - failed
        has_v3_encoding:
          type: boolean
          description: Whether V3_Preview embedding is available for this character
          example: false
        has_v4_encoding:
          type: boolean
          description: Whether V4_Preview embedding is available for this character
          example: true
        job_id:
          type: string
          nullable: true
          example: char_550e8400e29b
        error:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
        thumbnail_url:
          type: string
          format: uri
          nullable: true
        credits_used:
          type: number
          nullable: true
          example: 1
        created_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
    ErrorStructured:
      type: object
      description: >-
        Structured error. `detail` carries a machine-readable `error_code` plus
        a human-readable `message`.
      properties:
        detail:
          type: object
          properties:
            error_code:
              type: string
              example: CS-UORC01-008
            message:
              type: string
              example: Insufficient credits. Top up your balance to continue.
    Error:
      type: object
      description: >-
        Simple error. `detail` is a human-readable message (used for auth
        errors).
      properties:
        detail:
          type: string
          example: 'API key required. Use Authorization: Bearer sk-xxx'
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              Invalid or missing API key. Pass it as Authorization: Bearer
              sk-...
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````