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. type additionally selects whether a 3D vsplat is extracted from the same image. All endpoints on this page require Authorization: Bearer YOUR_API_KEY. Field-by-field detail lives on the split reference pages: Create, List, Get, Delete, Export.

Create a Character

POST /v1/characters Creates an asynchronous Character resource. Send multipart/form-data.

Pricing (1 credit = $0.01): type=render is 1 credit. type=vsplat is 25 credits (30 with enhance=true, which replaces the price rather than adding to it — enhance has no effect and isn’t billed for type=render). type=all bills for both: 26 or 31 credits. See Pricing and retention.

Field	Type	Required	Default	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.
`type`	string	No	`render`	`render` (1 credit), `vsplat` (25 credits, 30 with `enhance`), or `all` (billed for both).
`enhance`	boolean	No	`false`	Runs an additional AI enhancement pass over the vsplat extraction only — no effect for `type=render`. Raises the vsplat cost from 25 to 30 credits flat.

Provide exactly one image source: image or image_url. Supported uploaded image types are PNG, JPEG, and WebP. For type=vsplat or all, the request also accepts model_precision, filter_low_quality, joint_set, render_thumbnail, and task_id. joint_set (full, expression, or body; defaults to body) selects the rig the vsplat is skinned to — a Motion used to drive the Character must be extracted on the same joint_set. The caller only decides whether a thumbnail is needed; its source and pose are internal implementation details. See Create Character (from Image) for constraints and defaults.

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:00+00:00",
  "completed_at": null,
  "error": null,
  "type": "render",
  "vsplat": null,
  "glb": null
}

To also extract a 3D vsplat, add type=vsplat (or all to keep the render too — see Create Character (from Image) for the extraction-only fields).

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. On a vsplat/all Character, check vsplat.status for the extraction’s own progress.

List Characters

GET /v1/characters This endpoint has no query parameters. It returns the most recently created active Characters for the current account, newest first, capped at 100 with no cursor.

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

Delete a Character

DELETE /v1/characters/{character_id}

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

Returns {"status": "deleted"}. A missing Character, an ID with the wrong prefix, or a Character owned by another account returns 404.

Export a Character’s vsplat

GET /v1/characters/{character_id}/export Only meaningful for a vsplat/all Character. Add download_type=vsplat to populate the vsplat URL — that’s the only accepted value; there is no glb output for Characters (that’s a Motion-only extraction). thumbnail_url populates on its own, independent of download_type, whenever the Character was created with render_thumbnail=true.

curl "https://apis.viggle.ai/v1/characters/char_123abc/export?download_type=vsplat" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"

Character response fields

Field	Type	Description
`id`	string	Public Character ID. Preserve it exactly for future requests.
`status`	string	`queued`, `processing`, `ready`, or `failed`. On an `all` Character, only reaches `ready` once both the render and vsplat extraction have.
`name`	string	Label supplied when creating the resource.
`progress`	integer or null	Progress from 0 to 100 when available; always `null` in list responses.
`capabilities`	string[]	`video_render` once ready.
`type`	string	`render`, `vsplat`, or `all`.
`vsplat`	object or null	`{status, error}` when `type` requested a vsplat extraction, otherwise `null`. Never carries a download URL — use Export for that.
`glb`	null	Always `null` for a Character.
`created_at` / `completed_at`	ISO 8601 string or null	Resource timestamps.
`error`	object or null	Always `null` — read `status` (and `vsplat.error`) to detect failure.

Endpoint response rules

Endpoint	Success status	Response	Parameters
`POST /v1/characters`	`200`	Character object	One image source; optional 3D vsplat controls depend on `type`.
`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 /v1/characters/{character_id}/export`	`200`	CharacterExport object	`character_id` required; `download_type` optional.

Account

Motions

Video

Characters

Create a Character

Get a Character

List Characters

Delete a Character

Export a Character’s vsplat

Character response fields

Endpoint response rules

​Create a Character

​Get a Character

​List Characters

​Delete a Character

​Export a Character’s vsplat

​Character response fields

​Endpoint response rules

Create a Character

Get a Character

List Characters

Delete a Character

Export a Character’s vsplat

Character response fields

Endpoint response rules