Skip to main content
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: 
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. 
curl https://api.animusai.co/v2/${CHARACTER_ID}/upload/face-image \
  -H "Authorization: Bearer $ANIMUS_API_KEY" \
  -F "file=@/path/to/headshot.jpg"

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: 
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: 
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: 
curl https://api.animusai.co/v2/${CHARACTER_ID}/training/face-lora \
  -H "Authorization: Bearer $ANIMUS_API_KEY"

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: 
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. 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.
⌘I