Characters

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.

curl -X POST "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "[email protected]" \
  -F "name=Presenter"

{
  "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

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

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.

{
  "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.

curl "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"

{
  "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`.

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.

Get Started

Guides

Advanced

Reference

Create a Character

Example: create from a URL

Get a Character

List Characters

Delete a Character

Character response fields

Endpoint response rules

​Create a Character

​Example: create from a URL

​Get a Character

​List Characters

​Delete a Character

​Character response fields

​Endpoint response rules

Create a Character

Example: create from a URL

Get a Character

List Characters

Delete a Character

Character response fields

Endpoint response rules