List characters
GET /api/v1/characters returns the characters you can put in an image.
A character is a person, mascot, creature or object you have added from photos or a spec sheet, so the same one can appear across many images. You create them in the dashboard, where you also choose whether it adapts to each style or keeps one look. This endpoint is how your code finds their ids.
curl https://pixloom.dev/api/v1/characters \
-H "Authorization: Bearer sk_live_..."{
"characters": [
{ "id": "4d2f...", "name": "Ada", "description": "Founder headshots", "referenceCount": 1 }
]
}Pass an id as the character field on generate or the character parameter on render.
Secret keys only. Publishable keys get a 403, because a page's source should not list who you have on file.
Fields
| Field | Type | Notes |
|---|---|---|
id | uuid | What you pass as character. |
name | string | |
description | string or null | |
referenceCount | integer | How many reference images back this character. |
The reference photos themselves are never returned. Only our servers resolve them, so a character id in your front end cannot be turned back into someone's face.
Caching
Cacheable for five minutes, and stale copies stay usable for an hour.
Responses
| Status | Body |
|---|---|
200 | The list above. |
401 | Missing or invalid key. |
403 | Account not approved, or you used a publishable key. |
500 | { "error": "Failed to fetch characters" }. Retry. |
referenceCount counts the character’s original source images. Internally prepared style variants do not increase this count.