Characters

Characters belong to a project and can be referenced in scene dialog blocks. Each character can have an AI-generated or manually uploaded portrait image.

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/characters	authenticated	List all characters
GET	/api/characters/project/:projectId	authenticated	List characters by project
GET	/api/characters/:id	authenticated	Get character by ID
GET	/api/characters/file/*	—	Serve character file (public)
POST	/api/characters	character:create	Create a character
PUT / PATCH	/api/characters/:id	character:edit	Update a character
POST	/api/characters/:id/generate-image	character:image:generate	Generate character image (AI)
POST	/api/characters/:id/upload-image	character:image:upload	Upload character image
DELETE	/api/characters/:id/generated-image	character:image:delete	Delete generated character image
DELETE	/api/characters/:id	character:delete	Delete a character

Endpoints

List all characters

GET /api/characters — Auth required

Response — 200

{
  "characters": [
    {
      "id": "char-uuid-001",
      "name": "Mia",
      "age": 8,
      "gender": "female",
      "traits": ["curious", "brave"],
      "fears": ["darkness"],
      "phrases": ["Let's explore!"],
      "skills": ["climbing"],
      "role": "protagonist",
      "icon": null,
      "species": "human",
      "voiceId": "voice-id-xyz",
      "generatedImageUrl": "/api/characters/file/portraits/mia.png",
      "imageGenerationParams": {
        "prompt": "An 8-year-old girl with red hair",
        "width": 1024,
        "height": 1024,
        "steps": 28,
        "guidanceScale": 3.5,
        "noiseLevel": 0.35,
        "seed": 42
      },
      "createdAt": "2025-01-12T10:00:00.000Z",
      "updatedAt": "2025-02-01T08:00:00.000Z",
      "nameI18n": { "uk": "Міа", "en": "Mia", "es": "Mia" },
      "speciesI18n": { "uk": "людина", "en": "human", "es": "humano" },
      "roleI18n": { "uk": "протагоніст", "en": "protagonist", "es": "protagonista" },
      "traitsI18n": { "uk": ["допитлива", "смілива"], "en": ["curious", "brave"], "es": ["curiosa", "valiente"] },
      "fearsI18n": { "uk": ["темрява"], "en": ["darkness"], "es": ["oscuridad"] },
      "phrasesI18n": { "uk": ["Давайте досліджуємо!"], "en": ["Let's explore!"], "es": ["¡Exploremos!"] },
      "skillsI18n": { "uk": ["скелелазіння"], "en": ["climbing"], "es": ["escalada"] }
    }
  ],
  "total": 1
}

---

List characters by project

GET /api/characters/project/:projectId — Auth required

Response — 200

{
  "characters": [ /* same shape as above */ ],
  "total": 5,
  "filtered": 5
}

---

Get character by ID

GET /api/characters/:id — Auth required

Response — 200 — single character object (same shape as list item)

---

Serve character file (public)

GET /api/characters/file/*

No authentication required. Used by the frontend to load character images via <img> tags.

---

Create character

POST /api/characters — Auth required, Permission: character:create

Request body

{
  "projectId": "proj-uuid-001",
  "name": "Mia",
  "age": 8,
  "gender": "female",
  "traits": ["curious", "brave"],
  "fears": ["darkness"],
  "phrases": ["Let's explore!"],
  "skills": ["climbing"],
  "role": "protagonist",
  "icon": null,
  "species": "human",
  "voiceId": "voice-id-xyz"
}

Field	Required	Notes
projectId	yes	UUID of the parent project
name	yes	Auto-translated
age	yes	Integer
traits	yes	Non-empty string array; auto-translated
gender	no
fears	no	String array; auto-translated
phrases	no	String array; auto-translated
skills	no	String array; auto-translated
role	no	Auto-translated
icon	no
species	no	Auto-translated
voiceId	no	ElevenLabs voice ID

Response — 201 — created character object

---

Update character

PUT /api/characters/:id or PATCH /api/characters/:id — Auth required, Permission: character:edit

Request body (all fields optional)

{
  "name": "Mia",
  "age": 9,
  "gender": "female",
  "traits": ["curious", "brave", "stubborn"],
  "fears": ["darkness", "spiders"],
  "phrases": ["Let's explore!", "I can do it!"],
  "skills": ["climbing", "swimming"],
  "role": "protagonist",
  "icon": null,
  "species": "human",
  "voiceId": "voice-id-xyz"
}

Response — 200 — updated character object

---

Generate character image (AI)

POST /api/characters/:id/generate-image — Auth required, Rate limited, Permission: character:image:generate

Request body (all fields optional)

{
  "prompt": "An 8-year-old girl with red hair and green eyes",
  "width": 1024,
  "height": 1024,
  "steps": 28,
  "guidanceScale": 3.5,
  "noiseLevel": 0.35,
  "seed": 42
}

Field	Default
width	1024
height	1024
steps	28
guidanceScale	3.5
noiseLevel	0.35
seed	random

Response — 200 — updated character object with generatedImageUrl and imageGenerationParams

---

Upload character image

POST /api/characters/:id/upload-image — Auth required, Rate limited, multipart/form-data, Permission: character:image:upload

Form field: file — JPEG or PNG image

Response — 200 — updated character object with generatedImageUrl set

---

Delete generated character image

DELETE /api/characters/:id/generated-image — Auth required, Permission: character:image:delete

Response — 200 — updated character object with generatedImageUrl: null

---

Delete character

DELETE /api/characters/:id — Auth required, Permission: character:delete

Response — 204