Skip to main content
POST
/
api
/
characters
/
preprocess
Create Character
curl --request POST \
  --url https://apis.viggle.ai/api/characters/preprocess \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'name=My Character' \
  --form image='@example-file' \
  --form image_url=https://example.com/character.png
{
  "character_id": "550e8400-e29b-41d4-a716-446655440000",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "char_550e8400e29b",
  "name": "My Character",
  "status": "queued",
  "credits_reserved": 1,
  "enqueued_at": "2023-11-07T05:31:56Z"
}

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.

Upload a reference image to create a reusable character. Processing runs in background. Costs 1 credit. Characters are cross-model compatible — each character preprocess automatically generates embeddings for both V4 and V3 models (embedding_v4basesg.pkl + embedding_v3preview.pkl). You only pay 1 credit and can use the character with either model.
Best results with clear, front-facing subjects with good lighting and high resolution.

​
Example

import requests

url = "https://apis.viggle.ai/api/characters/preprocess"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}
files = {
    "image": ("character.png", open("character.png", "rb"), "image/png"),
}
data = {
    "name": "My Character",
}

response = requests.post(url, headers=headers, files=files, data=data)
response.raise_for_status()
result = response.json()

    print(f"Character ID: {result['character_id']}")
    print(f"Status: {result['status']}")

​
Next Steps

After creating a character, poll Get Character every 5 seconds until the status becomes ready. Then you can use it in render jobs.

Authorizations

​
Authorization
string
header
required

API key passed as Bearer token

Body

multipart/form-data
​
name
string
required

Display name for the character

Example:

"My Character"

​
image
file

Reference image file (PNG, JPG, WebP). Use this or image_url.

​
image_url
string<uri>

URL to a character image. Server fetches it. Use instead of image file upload.

Example:

"https://example.com/character.png"

Response

Character creation started

​
character_id
string
Example:

"550e8400-e29b-41d4-a716-446655440000"

​
id
string
Example:

"550e8400-e29b-41d4-a716-446655440000"

​
job_id
string
Example:

"char_550e8400e29b"

​
name
string
Example:

"My Character"

​
status
string
Example:

"queued"

​
credits_reserved
number
Example:

1

​
enqueued_at
string<date-time>