# Create Character

`POST /v1/characters`

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`.
Moving to SpicyAPI with characters you already generated on another platform? Email contact@spicyapi.com and we can enable `POST /v1/characters/import` on your account for a limited window.

Base URL: `https://api.spicyapi.com`

## Authorizations

- `Authorization` (string, header, required): 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)

- `name` (string, required): A label, up to 60 characters.
- `image_urls` (string[], required): 1 to 3 generated images of the same person, all from your account (`GET /v1/images`). More angles give a steadier identity.

## Request

```bash
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"]
  }'
```

## Response: 201 application/json

Character

- `id` (string, required): Character id, `chr_...`.
- `name` (string, required): The label you gave.
- `sheet_url` (string, required): The rendered reference sheet (also listed in `GET /v1/images` once the character is active).
- `source_urls` (string[], required): The images it was built from.
- `description` (string, required): Text descriptor of the person, appended to prompts that use the character.
- `imported` (boolean, required): `true` for a character brought in with `POST /v1/characters/import`.
- `status` (string, required): `active`, or `under_review` for an import a person has to approve first. Using an `under_review` character returns 409.
- `created` (integer | null, optional): Unix timestamp.

```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.",
  "imported": false,
  "status": "active",
  "created": 1758553200
}
```