Characters

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, or from your code by turning an image you generated into one. Listing 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.

List fields

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

referenceCount counts the photos or sheet panels you gave the character.

Create a character from an image

Generate a portrait, then make that hero a character so every later scene shows the same one.

curl https://pixloom.dev/api/v1/characters \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Nova", "imageId": "9b1e...", "characterType": "person" }'

{
  "character": {
    "id": "4d2f...",
    "name": "Nova",
    "description": null,
    "characterType": "person",
    "styleBehavior": "match",
    "createdAt": "2026-10-23T02:30:00Z",
    "referenceCount": 1
  }
}

The imageId is the one a completed job returns. Only images your account generated are accepted, and links to images elsewhere are not. Pass the new id as character on generate right away; give it a few seconds before the first scene, while we finish learning the character's look.

Secret keys only. Your copy of the image is kept with the character, so deleting the image later does not change the character.

Create responses

Cartoonify a photo

Turn one photo of a person into a few cartoon options in the look you describe, then save the one you like as a character. Built for "put me in the story" features.

curl https://pixloom.dev/api/v1/characters/cartoonify \
  -H "Authorization: Bearer sk_live_..." \
  -F photo=@me.jpg \
  -F prompt="Style: soft watercolor. Friendly and cheerful, upper body, centered." \
  -F count=2

{
  "cartoons": [
    { "imageId": "9b1e...", "imageUrl": "https://...", "width": 1024, "height": 1024 },
    { "imageId": "c07a...", "imageUrl": "https://...", "width": 1024, "height": 1024 }
  ]
}

Then pass the chosen imageId to create a character, with views: true for a stronger one, and delete the options you did not keep.

The photo is used for this one request and then dropped. We never store it, never log it and never run face recognition or an AI description on it. Only the cartoons are kept, as images in your account, and they never appear in the public library. Get consent from the person in the photo, and from a parent for anyone under 13.

Secret keys only. The call waits for the drawings, usually 10 to 30 seconds. Each option counts as one generation against your quota; options that fail are left out and not counted.

Send it as multipart/form-data.

Cartoonify responses

Delete a character

Delete one of your characters along with its reference photos and views. Images you already made with it stay.

curl -X DELETE https://pixloom.dev/api/v1/characters/4d2f... \
  -H "Authorization: Bearer sk_live_..."

# 200 { "id": "4d2f...", "deleted": true }

Secret keys only. A character that is not yours, or is already gone, answers 404.