Characters

Create Character

Save a reusable identity from your own generated images, to get the same person again across images, edits and video.

A character is built only from images your account generated (the same provenance rule as every input), so a real photograph can never become one. Creation renders one neutral reference sheet and a short text descriptor; both are stored as ordinary assets in your library.

Billed as one spicy-image-edit-1 image. Up to 50 characters per account. Pass the returned id as character to /v1/images/generations, /v1/images/edits or /v1/videos/generations.

POST/v1/charactersTry it

Create Character

cURL

curl --request POST \
  --url https://api.spicyapi.com/v1/characters \
  --header 'Authorization: Bearer $SPICYAPI_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Mara",
    "image_urls": ["https://cdn.spicyapi.com/outputs/…/sj_2f1c…-0.png"]
  }'

200

JSON

{
  "id": "chr_9f2a1c3b7d4e5a60",
  "object": "character",
  "name": "Mara",
  "sheet_url": "https://cdn.spicyapi.com/outputs/a1b2/chr_9f2a1c3b7d4e5a60.png",
  "source_urls": ["https://cdn.spicyapi.com/outputs/a1b2/sj_2f1c…-0.png"],
  "description": "Adult woman in her late 20s, oval face, deep-set pale blue eyes, straight narrow nose, full lips, long straight ash-blonde hair parted in the centre, fair skin, slim build.",
  "created": 1758553200
}

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your SpicyAPI key (sk-spicy-…). Create one in the dashboard under API Keys.

Body

application/json

namestringrequired

A label, up to 60 characters.

image_urlsstring[]required

1 to 3 generated images of the same person, all from your account (GET /v1/images). More angles give a steadier identity.

Response

201 · application/json

Character

idstringrequired

Character id, chr_....

namestringrequired

The label you gave.

sheet_urlstringrequired

The rendered reference sheet (also listed in GET /v1/images).

source_urlsstring[]required

The images it was built from.

descriptionstringrequired

Text descriptor of the person, appended to prompts that use the character.

createdinteger | null

Unix timestamp.

Was this page helpful?

Suggest edits Raise issue

List Characters