Custom characters

A custom character is a portrait of a character of your own in 7 moods: neutral, happy, sad, angry, afraid, surprised, disgusted. You make the first portrait, called the reference, by describing the character or by uploading an image. A person checks that portrait and approves it, and then each mood image is generated from it or uploaded. Custom characters are kept in a library for the whole workspace.

A finished custom character can be the portrait of a simulation or a coach, and can stand beside a simulation on a journey's stage. See "Use a character as a portrait" and "Use a character in a journey" below. Custom characters are on the Core, Team, Enterprise plans.

Before you start

• Open the Characters tab of Brain. Custom characters are a section of that tab. If Brain has no Characters tab, or its Custom characters section is faded, your active workspace's plan does not include the feature. See "A workspace without the feature" below.
• Any member of a workspace that has the feature can create, edit and delete its custom characters, unless an organization's owners and admins have limited who can edit Characters to themselves. A member then sees the characters read only, with "An admin has limited who can edit Characters in this workspace.", and every change or new image is refused with the same message, before any credits are held. See Who can edit the Brain.
• Each generated image costs 165 credits, and up to 330 credits are set aside for it in case it has to be made a second time. Uploading images costs nothing. See "What it costs" below, and check the workspace's balance in Settings → Credits & Billing.
• If the section shows "Image generation is turned off for this workspace. You can still upload every image.", nothing can be generated and every generate button is replaced by upload. See "The image generation switch" below.
• To upload, have an image in PNG, JPEG or WebP format, no larger than 10 MB, that you have the right to use. See "Uploads and consent" below.

Steps

Describe the character or upload a portrait

1. In the Custom characters section, select Create character. The New custom character dialog opens on Describe the character.
2. Enter a Name of up to 120 characters. The name is for your library and for the default alt text.
3. If the dialog shows Persona (optional), you can link the character to one of the workspace's character personas. The field appears only when the workspace has personas to offer.
4. Under Portrait, choose how the reference is made:
   • Generate a portrait: fill in Age (up to 80 characters, for example "Mid 40s"), Appearance (up to 600 characters) and, if you want, Clothing (up to 300 characters). Under Framing, choose how much of the character is in the picture: Head and shoulders, Waist up or Full body. The dialog shows the credits the image can take above the buttons. Select Generate portrait.
   • Upload a portrait: choose or drag in an image, tick the consent statement, choose under Framing the framing your image has, and select Upload portrait. The button stays unavailable until the statement is ticked. An uploaded image is used as it is. The framing you choose is what mood images generated from it are held to.

A generated portrait shows the character facing the camera in the framing you chose, with the body and shoulders square to the camera and the arms relaxed, so the character faces the learner. It has a transparent background, and the app shows it over light grey.

The framing is fixed once the character has mood images, because every mood image keeps it. Until then, Upload a different one lets you choose the framing of the new image, and Regenerate keeps the framing the character has. The dialog shows the framing as text, for example "Framing: Waist up". To have the same character in another framing, select Copy with a different framing, choose the new framing and select Make a copy. That makes a new character from the same description, with its own portrait to approve and its own moods, and leaves this character as it is. The copy is named after the character with the new framing in brackets, for example "Maya (waist up)". The copy's portrait is charged as one image. Copy with a different framing is offered only for a character that was made from a description, and only while image generation is on.

Add a character from the library

devlin.ai keeps a library of ready-made characters. Each one is in all three framings, with a reference and all 7 moods. Adding one costs no credits and generates nothing, so it works while image generation is off.

1. In the Custom characters section, select Add from library. The button is there only when the library has characters to offer.
2. In the Add from library dialog, choose a character. Each one shows its age range, gender presentation, what they wear and where they would fit.
3. Under Framing, choose Head and shoulders, Waist up or Full body. The picture shows the character in that framing.
4. Select Add to my characters. The character is added to your list, ready, with its reference already approved.

The added character is your workspace's own: rename it, use it as a portrait, put it in a journey, regenerate or replace any of its mood images, or delete it, as with any other character. Its reference cannot be replaced, because it already has mood images. It keeps the library character's description, so Regenerate and Copy with a different framing work on it. If your workspace already has that character in that framing, the dialog says "This character is already in your library in this framing." and nothing is added twice.

How generated images are checked

Every generated image is checked automatically before you see it:

• The portrait is checked for its framing, for a background that could be removed cleanly, for a body clearly turned away from the camera, for white or light patches and halos that are not part of the person, and for visible defects such as malformed hands, text or a cropped head.
• A mood image is compared with the reference: the same person, the same framing, a clean background, the expression for the mood, a body that still faces the camera, no white or light patches that are not in the reference, and no visible defects. A small gesture of the hands or head is fine, and so is a happy smile with the mouth open or closed. A slight natural angle is fine; a torso in profile or an arm reaching toward the camera is not.
• The check sees a cut-out character over a dark backdrop as well as over light grey, so a pale glow around the hair or clothing shows up. Patches of background left around the character are found before the image is shown to anyone, and count as a failed check.
• An image that does not pass is made 1 more time, with what was wrong passed on. While that happens a mood image reads "Trying again: the first image did not match the reference." and the reference reads "Trying again: the first image did not pass the automatic check." You never see the first image.
• If the second image does not pass either, it is kept. A mood image is in use straight away like any other, and its tile says "May need a look:" followed by the reason, so you can regenerate or replace it if you agree. Nothing more is generated without you.
• If the check itself could not run, the image is kept and nothing more is generated. A mood image is in use with no note. A reference portrait is shown without a note, ready for you to review and approve.

The check does not try to work out who is in the picture, and it does not replace the description screen or the image service's own safety system.

Review and approve the reference

5. The dialog moves to Review the reference. While a portrait is being generated it reads "Generating your portrait. This is usually under a minute, and up to two or three when the image has to be made again or the image service is busy.", followed by how many images are ahead of yours when other images are being made first. You can close the dialog: the portrait keeps generating, and the character's row in the list shows Generating portrait and then Reference ready. Select the pencil icon on the row to open it again.

6. When it reads "Your portrait is ready to review.", check the face. If the automatic check found something on the portrait it kept, the dialog says so above the buttons, starting "Check before you approve:". You can still approve it. Every mood image is made from this portrait, and it cannot be replaced once the character has mood images. If it is not right, you have these choices:

   • Regenerate makes a new portrait from the same description. It is charged as another image. If the new portrait fails, the earlier portrait stays in place and can still be approved.
   • Change the description takes you back to the fields. A description belongs to its character for good, so generating from new words makes a new character, charged as another image, and the earlier draft is removed. If the earlier draft could not be removed, the list says "The earlier draft could not be removed. You can delete it from this list."
   • Upload a different one replaces the portrait with an image of your own, at no cost.

   Regenerate and Change the description are offered only for a character that was made from a description, and only while image generation is on.

7. Select Use this portrait. This is the approval. Only a person can give it, and no mood image can be generated or uploaded before it. A portrait that is replaced after approval needs approving again.

Make the moods

8. The dialog moves to Moods and shows the number of images still to make and the credits they can take. Select Generate all moods to generate every mood, or Upload them myself to open the grid and upload instead.
9. You can mix the two. If you upload some moods first, the button's label changes to say how many moods are left to generate, and only the missing moods are generated and charged.
10. The grid shows one tile for each mood, with a summary line such as how many are ready. Tiles read Queued, Generating or Waiting while images are made. Waiting means the image service is busy and the image is retried on its own. A full set of moods usually takes one to two minutes, longer when the image service is busy. A tile that says "Trying again: the first image did not match the reference." is having its image made a second time after the automatic check. You can close the dialog while this runs. The character's row shows how many images are ready. When other images are being made first, the summary line also says how many, for example "5 images are ahead of yours." The count includes images from other workspaces, and it never names them. Up to 4 of a workspace's images are made at the same time. When images from several workspaces are waiting, those of Enterprise workspaces are made first, then Team, then Core.
11. Check each image:
    • Every mood image that is made is kept. There is no step to accept it: an image is replaced only when you select Regenerate or Upload, and removed only when you delete the character.
    • A tile with a sentence in amber under its image, starting "May need a look:", holds an image that did not pass the automatic check after its second try. The sentence is the reason. The image is in use all the same. Select Regenerate to make that mood again, or Upload to use your own, if you agree with the check. Nothing more is regenerated automatically.
    • A tile marked Failed shows the reason under it. Select Regenerate to try again or Upload to use your own image.
    • Any tile with an image offers Upload to replace it, and Regenerate once the moods have been started and while image generation is on. The current image stays in place until the replacement arrives. If the replacement fails, the current image is kept as it was.
12. Each image has alt text, which starts as the character's name and the mood. Select Edit alt text under a tile to change it, up to 500 characters, and select Save.

Result

A character is ready when every mood has an image and no image is still being made or has failed. Its row in the list then shows Ready, and the summary line says the character is ready. A mood flagged "May need a look:" is ready and in use like the others. A row shows Needs attention while an image has failed, and the summary line then says how many need your attention.

• A ready character stays ready while you regenerate or replace one of its images. The image it has is used until the new one arrives.
• Once a character is ready, each of its mood images can be loaded by anyone who has that image's address, without signing in. The reference portrait is never available that way, and the mood images stop being available when the character is deleted.
• A ready character can be chosen as the portrait of a simulation or a coach, and can be shown beside a simulation in a journey. See "Use a character as a portrait" and "Use a character in a journey" below.
• You can rename a character or change its linked persona at any time: open it, edit Name or Persona (optional) at the bottom of the dialog, and select Save name and persona.
• To delete a character, select the trash icon on its row and confirm. Its portrait and every mood image are deleted, and this cannot be undone. Credits spent on its images are not returned. A character cannot be deleted while one of its images is still being generated, while it is the portrait of a simulation or a coach, or while a journey uses it. A journey counts whether the character is in its draft or only in the version learners see. See "Use a character as a portrait" and "Use a character in a journey" below.

Use a character as a portrait

A ready character can be the portrait learners see in a simulation or a coach, in place of a built-in portrait. To show one beside a simulation in a journey, see "Use a character in a journey" below.

1. Open the simulation or coach from Studio, and open its appearance controls: the Appearance controls of a simulation, or the Visual Editor of a coach.
2. In the portrait choices, select the tile with your character. Only a ready character of the same workspace is offered. Choosing a character replaces a built-in portrait, and choosing a built-in portrait replaces the character.
3. Under Portrait background, choose the color behind the character. It is light grey until you change it. Changing it costs no credits and generates nothing.
4. Save.

Below the portrait choices, Create a character opens the library. If your plan does not include custom characters, the portrait choices show Custom characters faded instead, with the plans that include them named.

• Learners see the face: a full body or waist up character is cropped to the face in the small portrait, and the portrait changes with the mood of the conversation, using the character's mood images. It shows wherever a built-in portrait would.
• Every mood image is shown to learners, including one flagged "May need a look:". To change what learners see for a mood, regenerate or replace that image.
• Attaching a character generates nothing and costs no credits, so it works while image generation is off. Clearing the portrait is always allowed.
• A workspace that later loses access to custom characters keeps the characters it attached in front of learners, and cannot attach another.
• Duplicating a simulation or a coach in the same workspace keeps its character.
• A character in use cannot be deleted. The refusal says where it is used, for example "Maya is the portrait of the simulation Angry customer and the coach Sales debrief. Choose a different portrait there, then delete the character." There is no option to delete it anyway.
• When a simulation is moved to another workspace, its character stays in the workspace that made it, because the images belong to that workspace. The move confirmation says so: "Its custom character stays in this workspace. Choose a portrait again after the move."

Use a character in a journey

A ready character can stand beside a simulation on a journey's stage, in place of a built-in character. Its picture changes with the mood of the conversation, using the character's mood images.

1. Open the journey in the journey editor and select the simulation block.
2. Set Beside the simulation to Character. In a simulation bank, set Beside the simulation to Character on the bank, then open Character under each simulation in the bank to choose its character.
3. Under Choose a character, the 6 built-in characters come first. Your characters lists the workspace's custom characters that are ready. Select one.
4. Create a character opens the character dialog over the journey editor, so you do not leave the journey. A character that is ready when you close the dialog is picked for the block. One still being made is not picked: once it is ready, close and reopen the simulation block's settings, and it is listed under Your characters.

Things to know:

• Only a ready character of the same workspace is listed. If none is ready yet, the list says "No custom character is ready yet."
• The journey stores which character it uses, not the images. If you regenerate or replace one of the character's images later, the journey shows the new image with no edit.
• If one of the character's mood images was flagged "May need a look", the journey still uses it. Regenerate or replace it if you do not like it, and the journey shows the new image with no edit.
• Choosing a custom character replaces a built-in character, and choosing a built-in character replaces the custom one. While a custom character is chosen, the block says "This simulation uses a custom character. Choosing a library character or entering portrait addresses replaces it."
• If the journey uses a character that is not ready, the block says "This simulation uses a custom character that is not ready. The journey cannot be published until it is, or until you pick another."
• The character's row in the Custom characters list names the journey under Used by, for example "Used by 2: Angry customer (simulation), Returns desk (journey)".
• A character a journey uses cannot be deleted. The refusal names the journey, for example "Maya is the portrait of the journey Returns desk. Choose a different portrait there, then delete the character." This holds whether the character is in the journey's draft or only in the version learners see.
• Attaching a character to a journey generates nothing and costs no credits.
• A workspace that does not have custom characters sees only the built-in characters. A workspace on another plan sees Your characters faded, with Not on this plan and a See plans link.
• devlin can also make a new character for a journey it builds. See Building and managing content with devlin.

See Building a journey for the rest of the simulation block.

What it costs

• Each generated image costs 165 credits, which covers making the image and checking it. The reference portrait is one image, and each mood is one image. A full set of 7 moods that each pass the check the first time costs 1,155 credits.
• An image that is made a second time after the automatic check is charged as a second image, because two images were made. No image is made again more than 1 time by one request.
• For that reason a request sets aside up to 330 credits for each image, 2,310 credits for a full set of 7 moods. The dialog shows this before you start anything, as "Up to" that many credits, with "You are only charged for images that are made." What was set aside and not used comes back when the image is finished.
• A request starts only if the workspace has enough credits to set aside the full amount for every image in it. Otherwise nothing is started and the dialog says how many credits the request needs, with a link to add credits.
• An image is charged when it is made. An image that fails before it is made, or that the image service declines, is not charged. An image that was made and then replaced by its second try is charged, and so is a second try that fails after the first image was made.
• Regenerating an image yourself is charged as one more image, and sets aside the same amount as any other image.
• Once a character has cost anything, its dialog shows the credits spent on it, and how many retries that includes.
• Uploading an image, approving the reference, adding a character from the library, editing a name or alt text, and deleting a character cost no credits.
• Each member can start only so many image requests in a minute. Above that, the request is refused with "You are generating images too quickly. Wait a minute and try again." and nothing is charged.

See Credits, usage and low-credit alerts for how credits work in general.

What is sent to the image service

Images are generated by an external image service. It receives only what an image needs:

• For a reference portrait: the Age, Appearance and Clothing text you typed, inside a fixed instruction that asks for a portrait in the framing you chose on a flat coloured background. The background is removed before the image is stored. The character's name is not sent.
• For a mood image: the reference portrait itself, the same fixed instruction and a fixed description of the facial expression. If the reference is an image you uploaded, that uploaded image is what is sent, and it may be a photo of a real person. Your description text is not sent again.
• For a second try: exactly what the first try sent, with one instruction from the automatic check saying what the image must show. Every mood prompt also says the image must match the reference exactly.
• Nothing about learners is ever sent: no conversations, results or learner identity.

An image that you upload for a mood is not sent to the image service at all. If you upload every image, or image generation is turned off, nothing goes to the image service.

Separately, before anything is generated, the description and the name are screened by a language model, and every uploaded image is checked by a language model before it is kept. See "What gets refused" below.

The automatic check of a generated image is also made by a language model, not by the image service. It is shown the generated image and, for a mood, the reference portrait it was made from. If that reference is an image you uploaded, the uploaded image is what it is shown. See "How generated images are checked" above.

The image generation switch

Each workspace has a switch that decides whether its text and images may be sent to the image service. It is on by default.

1. Open Settings → Data & privacy as an owner or admin of the workspace.
2. In the Image generation card, select Turn off, or Turn on to allow it again.

The Image generation card is on the page only in a workspace that has custom characters. While it is on, the card reads "On: custom characters can have their images generated." While it is off, it reads "Off: nothing from this workspace is sent to the image service." No learner data is sent to the image service in either state.

Members can open the page and see whether the switch is on, with "This setting is managed by your workspace owner and admins." They cannot change it.

While the switch is off:

• No new image can be generated. The Custom characters section says "Image generation is turned off for this workspace. You can still upload every image." and every generate control is replaced by upload.
• Images that were already requested and had not been made yet are stopped as well. Each ends with "Image generation was turned off for this workspace before this image was made." and is not charged.
• An image waiting for its second try is stopped in the same way. Its second image is not made, and the first one, which was made, is charged.
• Uploading still works for the reference and for every mood, so a character can be completed without the image service.
• Images that were already made are kept. Turning the switch off does not remove them.

Turning the switch back on does not restart the images that were stopped. Regenerate them, or upload them. Turning it on does not give a workspace custom characters either: access to the feature is decided separately.

devlin.ai can also turn image generation off for the whole service. The section then shows the same message, and uploading works in the same way.

Uploads and consent

You can upload the reference, any mood, or every image. Uploading costs no credits and works while image generation is off.

• An upload must be a PNG, JPEG or WebP image of 10 MB or less. Other files are refused with "That file cannot be used." or "That image is too large." and the accepted formats or size.
• Before an image is uploaded, the uploader has to agree to this statement: "I have the right to use this image and, where it shows a real person, that person's permission to use their likeness in training simulations. The image does not show a child." The agreement is recorded with the character, along with who gave it and when. Once it is recorded for a character, the statement is not shown again when you upload that character's mood images. Uploading a new reference always asks for it again.
• Every uploaded image is checked before it is kept, and one that looks sexually explicit or appears to show a child is refused. The check does not try to work out who is in the picture. Whether you may use a real person's likeness is covered by the statement you agree to, not by the check.
• Uploaded images are not checked against the reference and keep the background they have. Use the same framing as the reference yourself so the character does not appear to move when the mood changes.
• An uploaded reference still has to be approved with Use this portrait before moods can be added.
• A character that was created by uploading its reference has no description, so its reference cannot be regenerated. Replace it with Upload a different one. A character made from a description keeps that description when you upload a different reference, so its reference can still be regenerated. Either way, its moods can be generated from the reference when image generation is on.

What gets refused

Before any image is generated, the description is screened. Nothing is generated or charged when it is refused.

• A description is refused when it includes sexual content or nudity, a real named person or public figure, graphic injury, hateful imagery, or text that tries to override the screen's rules or to get around the fixed portrait to produce one of those. Harmless notes about pose, framing, setting or picture style, such as "full body, standing", are accepted; the framing you chose and the plain background stay as they are. The message is "This description cannot be used to generate a character. Remove any real people, sexual content or graphic detail and try again."
• If the screen itself cannot run, the request is refused with "We could not check this description just now. Nothing was generated or charged. Try again in a moment."
• The image service has its own safety system and can decline an image that passed the screen. That image ends with "The image generator's safety system declined this image. Try again, or upload your own image." and is not charged.
• Generating a character who is a child is not guaranteed. The description screen accepts a child described in ordinary terms for a professional scenario, but the image service may still decline the image. An uploaded image that appears to show a child is always refused.

Uploaded images are refused as described under "Uploads and consent". An image that appears to contain nudity or sexual content gets "This image cannot be used for a character because it appears to contain nudity or sexual content." If the check cannot run, the upload is refused with "We could not check this image just now. Nothing was saved. Upload it again in a moment."

Other messages you may see on a tile:

• "The image generator was too busy to finish this image. Try again in a few minutes."
• "This image could not be generated. Try again."
• "This image is still being generated. Wait for it to finish, then try again.", when you act on an image that is already being made.
• "The reference image cannot be replaced once the character has mood images. Create a new character to start from a different image."

Using it from an AI tool

The same actions are available to devlin, the in-app agent, and to an AI tool connected through the MCP server. Every rule on this page applies to them in the same way: access, the image generation switch, screening, consent and credits.

devlin looks in the character library first when a simulation needs a face, and generates a character only when nothing in the library fits. Matches are ranked on what the person looks like, their age range, what they wear and where they work; a role only nudges the order, so a character is never left out for a role it does not list.

What an AI tool cannot do, and what it has to ask first:

• No tool approves the reference. A person approves it in the app. generate_character_moods is refused until that has happened.
• The tools that spend credits start at once when the credits the call sets aside are within the plan's approval limit, and the AI tool is told to say what it cost afterwards. Over the limit the call starts nothing and answers that it needs your agreement first, naming the amount it would set aside. The approval limit for one call is 200 credits on Free, 1,500 on Starter, 7,500 on Core, and 75,000 on Team and Enterprise. One image sets aside 330 credits, so on Free every generated image asks first. A full set of moods sets aside 2,310 credits, so it asks first on Free and Starter and starts without asking on the other plans. In Ask devlin, with Review all chosen under Edits, every one of these calls asks first, whatever its cost.
• An image the automatic check flagged is kept and in use like any other. The AI tool can see what the check said, and regenerates it only if you ask.
• set_character_reference needs the consent statement agreed to by a person. The AI tool is told to show you the statement word for word and to pass the confirmation only after you have agreed in that conversation.
• Over MCP, a result never includes the reference portrait. It includes the address of a mood image only once the whole character is ready.

In a workspace that requires approval for changes made over MCP:

• generate_character_reference, generate_character_moods, regenerate_character_image and copy_character_with_framing start nothing and spend nothing. They answer that a workspace member has to start the image in the app, with the credits it would set aside.
• delete_custom_character records a change request for an owner or admin to approve in the app, and deletes nothing until then.
• update_custom_character, create_character_upload, set_character_reference and use_library_character still apply at once and cost nothing. create_character_upload, set_character_reference and use_library_character change nothing learners see. update_custom_character can: when the character is the portrait of a simulation or coach, a new alt text, or a new name used in the default alt text, reaches learners.

Over MCP, delete_custom_character always asks for an explicit confirmation before it does anything.

With devlin:

• Attach a PNG, JPEG or WebP image in the chat to use it as a character's reference. devlin has no upload tool of its own and uses the image you attached. The chat takes images this way only in a workspace that has custom characters. It does so whether or not image generation is on, because uploading does not use the image service.
• A result about one character puts a character card in the chat. The chat shows one full card for each character, the latest one. Earlier mentions read ": see the latest card below." When the reference is ready and not yet approved, the card has an Approve reference button. Selecting it is the same approval as Use this portrait. devlin is told when you approve and goes on to generate the moods. It asks first when the credits they set aside are over the plan's approval limit (a full set sets aside 2,310 credits), or always if you chose Review all under Edits. It is also told when images finish.
• Select the reference portrait or a mood image, on the card or in a character's dialog in the library, to see it larger. Close or Escape closes the preview. A preview opened on a card stays open when devlin's reply draws a newer card for the same character, until you close it. The small picture on a character's row in the library list does not open.
• Deleting a character is a proposal that you apply yourself. Nothing is deleted until you do.

To use a character as a portrait, devlin and an AI tool set the portrait on a simulation with update_simulation, or on a coach with update_coach, naming the character or clearing it. The same rules apply: a ready character of the workspace, no credits. When you ask devlin to put a finished character on a simulation or a coach, it does so. No tool approves a character's reference.

To show a character beside a simulation in a journey, devlin and an AI tool use update_journey_content and name a ready character of this workspace on the simulation block. As in the editor, a character that is not ready saves in the draft but blocks publishing, and attaching costs no credits.

An AI tool can also change the image generation switch with update_workspace_settings, when the person using it is an owner or admin of the workspace. It is treated as a live change, like the other workspace settings that tool can change: see "AI tools over MCP" in Collecting learner identity.

A workspace without the feature

A workspace on a plan without custom characters sees the feature without being able to use it:

• Where Brain already has a Characters tab, the Custom characters section is faded, with a Not on this plan tag, a message that starts "Custom characters are not included on this workspace's plan." and names the plans that include them, and a See plans link. Being offered custom characters does not add a Characters tab by itself.
• The Image generation card is faded in the same way, with the same tag, message and link. An owner or admin can still use its switch.
• A request to the feature is refused with that same message.

Related

• Brain: audience profiles and organization context
• Credits, usage and low-credit alerts
• Data privacy, retention and learner data requests
• MCP server and AI tool connectors
• Building and managing content with devlin