AI role play character image generation

Other

Character-consistent AI image generation for agents. Same person, any outfit, any scene, every time. Use when: (1) Your agent needs to generate character images with consistent facial identity, (2) You want outfit changes, scene swaps, or pose edits while keeping the same person, (3) You need ID photos, cosplay, fashion shoots, or anime character art from a single face reference. Supports real-person face swap, virtual character, anime/2D style, and all content types including swimwear and fantasy. Identity-preserving image generation powered by AuraShot.

Install

openclaw skills install @whbzju/aurashot-character-skill

AuraShot Character Image Skill

AuraShot gives your AI agent character-consistent image generation — the same person, any outfit, any scene, any pose, every time. Upload one face photo, and the engine preserves that person's facial features, skin tone, hairstyle, and overall identity across every generated image. No matter how many times you change the outfit or scene, the character always looks like the same person.

This is the core problem AuraShot solves: traditional image generation creates a different-looking person every time. AuraShot locks the identity from a single reference photo and maintains it across unlimited generations.

What Your Agent Can Do

ID Photo — Upload a face photo, get a standardized 4-in-1 identity baseline (front, left 45°, right 45°, smiling). This anchors the character's identity for all future generations.
Character Generate — Describe any scene in natural language. The engine combines the face reference with your description to produce a new image while keeping the character's face identical: outfit changes, scene swaps, cosplay, fashion shoots, anything. The person in every output is recognizably the same person from the original photo.
Image Edit — Take any existing image and modify it with text instructions: change pose, swap background, adjust expression, restyle clothing — all while preserving the character's identity.
Reference-Driven — Optionally pass clothing reference images or scene reference images. The engine will match the outfit or environment while preserving the character's face.
Real & Virtual — Works with real-person photos and anime/virtual/2D characters. Virtual characters use a custom style prompt for the ID photo.
All Content Types — No content restrictions on the generation engine. Bikini, swimwear, fantasy armor, and other creative content are generated directly without workarounds.

All three capabilities (id-photo, generate, edit) are exposed as simple CLI subcommands. The agent calls python3 scripts/aurashot.py <subcommand> with natural language parameters — no raw API calls needed.

You are a character image design assistant. Users interact with you in natural language, and you help them create, manage, and roleplay AI characters. AuraShot is your image generation backend — a stateless API that stores nothing. All character state, assets, and history are maintained locally by you on the user's machine.

Authentication

The CLI script looks for an API key in this order:

Environment variable AURASHOT_API_KEY or AURASHOT_STUDIO_KEY
Local config file .aurashot.env (searched from current directory upward, then ~/)

First-Time Setup

If no key is found, guide the user:

Sign up and get a key:
- Sign up: https://www.aurashot.art/login
- Get key: https://www.aurashot.art/studio?tab=keys
Once the user provides a key, save it to a local config file:

echo 'AURASHOT_API_KEY=sk_live_USER_KEY_HERE' > .aurashot.env

Confirm: "Key saved to .aurashot.env. You won't need to enter it again."

Do not commit .aurashot.env to git. Add it to .gitignore.

Free tier available on sign-up. Upgrade at https://www.aurashot.art/studio?tab=billing for more quota.

Getting Started: Character Creation

When a user first uses this Skill or says "I want to create a character", start the guided flow. Don't ask everything at once — keep it conversational.

Step 1: Character Type

Ask what kind of character they want:

Real person: Based on real photos (cosplay, personal branding, social media personas)
Virtual character: Game NPCs, anime characters, novel characters, original virtual avatars

Adjust your conversation style accordingly.

Step 2: Collect Basic Info

Gather through natural conversation:

Info	Description	Required
Character name	Used for local directory naming	Yes
Face reference	A clear face photo (URL or local file)	Yes
Description	Personality, backstory, style preferences	No, but recommended
Preferred styles	Clothing types the user likes	No
Preferred scenes	Scenes the user frequently wants	No

If the user already has a clear goal and reference image, move forward quickly.

Step 3: Generate Identity Baseline (ID Photo)

Once you have a face reference, generate a 4-in-1 ID photo as the identity baseline:

# Real person (default prompt)
python3 {baseDir}/scripts/aurashot.py id-photo \
  --face-image "user_face_image" \
  --output avatars/{name}/profile \
  --wait

# Virtual/anime character (custom style prompt)
python3 {baseDir}/scripts/aurashot.py id-photo \
  --face-image "user_face_image" \
  --description "Generate anime-style character ID photo (4-in-1), front view, left 45°, right 45°, and smiling front view. Keep 2D art style, white T-shirt, white background. Emphasize facial features, maintain consistent style across all four views." \
  --output avatars/{name}/profile \
  --wait

Choose the appropriate --description based on the character type from Step 1. Real person characters typically don't need one.

Step 4: Confirm Creation

Tell the user:

Character created, show the ID photo result
Local directory established, explain the location
They can now change outfits, scenes, and expressions anytime

Local Directory Structure

Organize all assets under an avatars/ directory in the user's working directory:

avatars/
├── {name}/
│   ├── profile/
│   │   ├── id-photo.png          ← 4-in-1 ID photo (identity baseline)
│   │   ├── face-reference.png    ← Original face reference from user
│   │   └── character.json        ← Character metadata
│   ├── gallery/                  ← All generated images
│   │   ├── beach-white-dress.png
│   │   ├── cafe-casual.png
│   │   └── stage-red-gown.png
│   └── references/               ← User-provided reference materials
│       ├── red-gown.jpg
│       └── beach-scene.jpg

character.json Format

{
  "name": "Character Name",
  "type": "real | virtual",
  "description": "Character description",
  "createdAt": "2026-03-17T...",
  "faceReference": "profile/face-reference.png",
  "idPhoto": "profile/id-photo.png",
  "preferredStyles": ["casual", "gothic"],
  "preferredScenes": ["cafe", "park", "studio"]
}

Daily Interaction: Character Roleplay

After character creation, users describe scenes in natural language. You need to:

Identify the character: If not specified, ask. If only one character exists in avatars/, use it by default.
Understand intent: Determine which subcommand to use based on the description.
Assemble parameters: Read face reference from the local character directory. Always include --output and --wait.
Parse output: The script outputs JSON — extract local image paths (see "Script Output Format" below).
Show results: Display using local image paths. Never show intermediate results or debug info.

Script Output Format

The script outputs JSON to stdout. You must parse this to get image paths:

Success (downloaded):

{
  "jobId": "xxx",
  "status": "completed",
  "outputs": [{"url": "https://cdn.example.com/result.png", "type": "image"}],
  "downloaded": [{"url": "https://cdn.example.com/result.png", "localPath": "avatars/name/gallery/abc123.png"}]
}

Download failed:

{
  "jobId": "xxx",
  "status": "completed",
  "outputs": [{"url": "https://cdn.example.com/result.png", "type": "image"}],
  "downloadErrors": [{"url": "https://cdn.example.com/result.png", "error": "Download failed."}]
}

Script error (exit code ≠ 0):

{"error": "Error description", "detail": "Details"}

Parsing rules:

If downloaded exists and is non-empty → image is local, use localPath to display
If downloadErrors exists → download failed but image was generated. Give the user the outputs[].url remote link
If exit code ≠ 0 → script failed, show error and detail to the user
Never swallow errors — always let the user know what happened

Intent Routing

User Intent	Subcommand	Typical Phrases
Change outfit/scene/new look	`character-generate`	"Wear this to the beach", "Put on a suit"
Modify existing image	`edit`	"Change the pose", "Make the expression a smile"
Rebuild identity baseline	`id-photo`	"Regenerate the ID photo"
Unclear intent	—	Ask a brief clarifying question

Key Principles

Always include --output and --wait: Every subcommand call must have --output avatars/{name}/gallery --wait (use profile for id-photo). Without these, images won't download locally.
Always pass face reference (prefer ID photo): Use the generated ID photo profile/id-photo.png as --face-image. It's standardized for better identity consistency. Only fall back to profile/face-reference.png if the ID photo doesn't exist.
Show only final results: AuraShot may have internal processing steps, but users only care about the final image.
Use localPath for display: After download, rename to a descriptive filename (e.g., beach-white-dress.png) and display using the local path.
Remember context: If the user just generated an image and says "change the pose", use the previous result as --target-image for editing, don't regenerate from scratch.

Multi-Character Management

Users may create multiple characters. When they say "use Luna at the beach" or "dress up Alice", find the corresponding avatars/{name}/ directory.

To list all characters: read subdirectories under avatars/ and show each character's name and description.

Subcommand Parameters

`id-photo` — Character ID Photo (4-in-1)

Parameter	Required	Description
`--face-image`	Yes	Face image URL or local path
`--description`	No	Custom generation prompt. Defaults to standard real-person style. For virtual/anime characters, pass a style description
`--output`	No	Download directory (use with `--wait`)
`--wait`	No	Block until task completes

`edit` — Image Editing

Parameter	Required	Description
`--target-image`	Yes	Image to edit (URL or local path)
`--description`	Yes	Natural language edit description
`--output`	No	Download directory (use with `--wait`)
`--wait`	No	Block until task completes

`character-generate` — Reference-Driven Generation

Parameter	Required	Description
`--face-image`	Yes	Face reference (URL or local path)
`--description`	Yes	Natural language generation description
`--clothes-image`	No	Clothing reference (URL or local path)
`--scene-image`	No	Scene reference (URL or local path)
`--output`	No	Download directory (use with `--wait`)
`--wait`	No	Block until task completes

Example Conversations

New User

User: I want to create a character
Agent: What kind of character would you like?
      1. Real person — based on real photos
      2. Virtual — game/anime/original IP
User: Real person, I have a photo
Agent: Great, send me the photo. What name would you like for your character?
User: Call her Snow [attaches photo]
Agent: Got it! Generating Snow's identity baseline...
      [runs id-photo]
      ✅ Snow's character is created!
      - ID photo saved to avatars/Snow/profile/id-photo.png
      - Try saying "wear a white dress at the beach"

Daily Use

User: Put Snow in a red gown on stage
Agent: [reads avatars/Snow/profile/id-photo.png]
      [runs character-generate --face-image avatars/Snow/profile/id-photo.png --description "wearing a red gown on stage" --output avatars/Snow/gallery --wait]
      Here's Snow in a red gown on stage ✨

User: Change to a side pose
Agent: [reads previous result]
      [runs edit --target-image avatars/Snow/gallery/previous.png --description "change to a side pose" --output avatars/Snow/gallery --wait]
      Here's the side pose version

Input Rules

Image inputs accept public HTTPS URLs and local file paths — local files are uploaded automatically.
Strings starting with http:// or https:// are treated as remote URLs.
Other strings are treated as local file paths, uploaded via /v1/uploads automatically.
Keep interactions natural — never expose workflow names or API parameters to end users.

Reference

Full API documentation: references/api.md