> ## Documentation Index
> Fetch the complete documentation index at: https://docs.animusai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Character Training

> Walk through the full pipeline for preparing LoRA models before you trigger generations.

Preparing production-ready characters requires a few coordinated steps: create the character container, collect clean reference photos, synthesize a curated dataset, and finally launch LoRA training. This guide documents the exact endpoints our production studio (`character-gen-app`) calls so your own tooling can mirror the workflow end to end.

All endpoints live under `https://api.animusai.co/v2` and accept the same bearer token you use for the rest of the Animus platform.

## 1. Create a Character Shell

Every pipeline starts with a character record:

```bash theme={null}
curl https://api.animusai.co/v2/characters \
  -H "Authorization: Bearer $ANIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Chloe",
    "description": "Lifestyle creator focusing on travel and wellness"
  }'
```

Response fields mirror the production schema and include counts for uploaded assets plus training status flags. Store the `character_id`; you will use it in every subsequent step.

To fetch or update characters later:

* `GET /characters` -- paginated list scoped to your organization
* `GET /characters/{character_id}` -- detailed record including wizard step progress
* `PUT /characters/{character_id}` -- rename or tweak the description

## 2. Upload Reference Photos

LoRA quality is driven by clean, high-resolution inputs. Submit photos with multipart uploads.

```bash theme={null}
curl https://api.animusai.co/v2/${CHARACTER_ID}/upload/face-image \
  -H "Authorization: Bearer $ANIMUS_API_KEY" \
  -F "file=@/path/to/headshot.jpg"
```

```bash theme={null}
curl https://api.animusai.co/v2/${CHARACTER_ID}/upload/body-image \
  -H "Authorization: Bearer $ANIMUS_API_KEY" \
  -F "file=@/path/to/full-body.jpg" \
  -F "image_type=body_image_front"
```

Key rules enforced by the API:

* Face images must be at least 512x512 and pass validation (sharpness, corruption checks, optional captioning).
* Default caps are 20 face images and 40 body images per character.
* HTTP `400` responses include a human-readable `detail` describing validation failures.

You can retrieve what has been uploaded at any point with `GET /{character_id}/assets` and filter client-side by `asset_type`.

## 3. (Optional) Auto-generate Face Variations

If you only have a handful of selfies, Seedream augmentation can bootstrap a larger face dataset:

```bash theme={null}
curl https://api.animusai.co/v2/characters/${CHARACTER_ID}/auto-generate-face-images \
  -H "Authorization: Bearer $ANIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_image_url": "https://cdn.animusai.co/samples/headshot.png"
  }'
```

* The backend queues a background job per prompt (defaults to our tuned list if you omit `prompts`).
* Credits are deducted up front (0.5 per synthesized face). Insufficient balances return HTTP `402` with `error`, `message`, and credit metadata.
* Track progress via `job_id` using `GET /upload-job/{job_id}/status` (the same endpoint the studio surfaces in the UI).

## 4. Build and Review the Training Dataset

Once front/back body references are in place you can ask ComfyDeploy to generate a curated dataset:

```bash theme={null}
curl https://api.animusai.co/v2/${CHARACTER_ID}/dataset/generate \
  -H "Authorization: Bearer $ANIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "use_default_prompts": true }'
```

The request returns immediately with a status message; background workers populate the dataset table as images land.

Use these endpoints to drive your review UI:

* `GET /{character_id}/dataset/status` -- overall counts (`total_images`, `approved_images`, `dataset_status`)
* `GET /{character_id}/dataset/images?approved_only=false` -- full list including prompts, seeds, and `view_url` links
* `PUT /{character_id}/dataset/images/{image_id}/approval` -- approve or reject
* `POST /{character_id}/dataset/images/{image_id}/regenerate` -- retry a single pose with a fresh prompt
* `DELETE /{character_id}/dataset/images/{image_id}` -- purge unsuitable renders

Approval responses include simple `{ success, message }` payloads so you can optimistically update your UI.

When everything looks good, call `POST /{character_id}/dataset/approve` to advance the character to the training step.

## 5. Launch LoRA Training

Two dedicated endpoints kick off the Replicate-backed training runs:

```bash theme={null}
curl https://api.animusai.co/v2/${CHARACTER_ID}/training/face-lora \
  -H "Authorization: Bearer $ANIMUS_API_KEY"
```

```bash theme={null}
curl https://api.animusai.co/v2/${CHARACTER_ID}/training/body-lora \
  -H "Authorization: Bearer $ANIMUS_API_KEY"
```

Each request validates the image counts, deducts the appropriate credits, and returns a `job_id` plus current balance snapshot. Use the monitoring endpoints for dashboards or Slack alerts:

* `GET /{character_id}/training/status` -- high-level face/body job summaries
* `GET /{character_id}/training/jobs` -- full job history with timestamps and statuses
* `GET /{character_id}/training/jobs/{job_id}/logs?lines=100` -- tail of the training logs (handy for surfacing ETA and phase changes)
* `GET /{character_id}/training/complete-status` -- convenience wrapper the studio uses to decide whether the user can proceed
* `POST /{character_id}/training/jobs/{job_id}/cancel` -- best-effort cancellation if a run stalls

All endpoints return HTTP `402` with contextual metadata when the requester lacks the credits required for the operation.

## 6. Verify Generation Readiness

Before exposing generations to the user, confirm both LoRAs are live:

```bash theme={null}
curl https://api.animusai.co/v2/${CHARACTER_ID}/generation/capabilities \
  -H "Authorization: Bearer $ANIMUS_API_KEY"
```

The response includes `face_lora.status`, `body_lora.status`, and a boolean `generation_ready` flag--the same signal the studio consumes.

## 7. Trigger Generations

With LoRAs in place you can use the unified media endpoints documented in the [Image Generation guide](/rest-api-integration/image-generation). That document covers job submission (`POST /generation/create`), status polling, gallery groups, and deletion tools. The production frontend uses those exact endpoints for every render, edit, and batch it ships today.

## Error Semantics & Credits

All routes share a consistent error contract:

* `402` -- insufficient credits or missing character subscription. The body carries `error`, `message`, `required_credits`, and `current_balance` fields.
* `404` -- the character or specific dataset/training record does not exist within your organization.
* `409` -- you attempted to advance the pipeline while prerequisite steps are unfinished (for example, approving a dataset with pending images).

Because the same credit middleware powers every stage, the `remaining_balance` returned from one step is immediately reusable in later surfaces.

***

Following this sequence mirrors exactly what the production `character-gen-app` Vercel deployment does today. When paired with the generation endpoints, you have everything needed to recreate the full Animus creator studio experience inside your own enterprise dashboards.