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

# Characters

> Create, retrieve, list, and delete reusable Character resources.

A Character is a reusable representation of the person in an image. Create it once, wait for it to become `ready`, and pass its `char_...` ID to a Render.

All endpoints in this page require `Authorization: Bearer YOUR_API_KEY`.

## Create a Character

`POST /v1/characters`

Creates an asynchronous Character resource. Send `multipart/form-data`.

| Field       | Type   | Required | Description                                                 |
| ----------- | ------ | :------: | ----------------------------------------------------------- |
| `image`     | file   |  One of  | Character image uploaded as a file.                         |
| `image_url` | string |  One of  | Publicly reachable URL for the character image.             |
| `name`      | string |    No    | Optional human-readable label. Defaults to an empty string. |

Provide exactly one image source: `image` or `image_url`.

Supported uploaded image types are PNG, JPEG, and WebP. V1 normalizes valid image input before processing.

```bash theme={null}
curl -X POST "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "image=@character.png" \
  -F "name=Presenter"
```

```json theme={null}
{
  "id": "char_123abc",
  "status": "queued",
  "name": "Presenter",
  "progress": 0,
  "capabilities": [],
  "created_at": "2026-07-17T10:00:00Z",
  "completed_at": null,
  "error": null
}
```

### Example: create from a URL

```bash theme={null}
curl -X POST "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "image_url=https://example.com/character.png" \
  -F "name=Remote presenter"
```

## Get a Character

`GET /v1/characters/{character_id}`

| Path parameter | Type   | Required | Description                                                                 |
| -------------- | ------ | :------: | --------------------------------------------------------------------------- |
| `character_id` | string |    Yes   | Full Character ID, for example `char_550e8400-e29b-41d4-a716-446655440000`. |

```bash theme={null}
curl "https://apis.viggle.ai/v1/characters/char_123abc" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

Poll this endpoint until `status` is `ready` before using the ID in a Render. A ready Character exposes `video_render` in `capabilities`.

```json theme={null}
{
  "id": "char_123abc",
  "status": "ready",
  "name": "Presenter",
  "progress": 100,
  "capabilities": ["video_render"],
  "created_at": "2026-07-17T10:00:00Z",
  "completed_at": "2026-07-17T10:00:12Z",
  "error": null
}
```

## List Characters

`GET /v1/characters`

This endpoint currently has no query parameters and returns all Characters available to the current account.

```bash theme={null}
curl "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "char_123abc",
      "status": "ready",
      "name": "Presenter",
      "progress": 100,
      "capabilities": ["video_render"],
      "created_at": "2026-07-17T10:00:00Z",
      "completed_at": "2026-07-17T10:00:12Z",
      "error": null
    }
  ]
}
```

## Delete a Character

`DELETE /v1/characters/{character_id}`

| Path parameter | Type   | Required | Description                                                                 |
| -------------- | ------ | :------: | --------------------------------------------------------------------------- |
| `character_id` | string |    Yes   | Full Character ID, for example `char_550e8400-e29b-41d4-a716-446655440000`. |

```bash theme={null}
curl -X DELETE "https://apis.viggle.ai/v1/characters/char_123abc" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

The underlying asset is soft-deleted. Do not assume a deleted Character can be used in future Renders.

Deletion returns the service's standard deletion result. A missing Character, an ID with the wrong prefix, or a Character owned by another account is returned as a V1 error.

## Character response fields

| Field                         | Type                    | Description                                                                                                            |
| ----------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `id`                          | string                  | Public Character ID, for example `char_550e8400-e29b-41d4-a716-446655440000`. Preserve it exactly for future requests. |
| `status`                      | string                  | `queued`, `processing`, `ready`, or `failed`.                                                                          |
| `name`                        | string                  | Label supplied when creating the resource.                                                                             |
| `progress`                    | integer or null         | Progress from 0 to 100 when available.                                                                                 |
| `capabilities`                | string\[]               | Public capabilities that are ready for use. Current ready assets expose `video_render`.                                |
| `created_at` / `completed_at` | ISO 8601 string or null | Resource timestamps.                                                                                                   |
| `error`                       | object or null          | Present when the resource has failed.                                                                                  |

## Endpoint response rules

| Endpoint                               | Success status | Response                  | Parameters                                     |
| -------------------------------------- | -------------- | ------------------------- | ---------------------------------------------- |
| `POST /v1/characters`                  | `200`          | Character object          | One required image source; `name` is optional. |
| `GET /v1/characters`                   | `200`          | `{ "data": [Character] }` | No parameters.                                 |
| `GET /v1/characters/{character_id}`    | `200`          | Character object          | `character_id` is required.                    |
| `DELETE /v1/characters/{character_id}` | `200`          | `{ "status": "deleted" }` | `character_id` is required.                    |