Getting Started
Your first Unprompted template. It's a big step, I know. You feeling nervous? A sense of tremendous pressure maybe? Don't worry, it's not that hard to set this thing up.
For the purposes of this guide, we will construct a basic "human generator" similar to the one that is included with the repo download.
Step 1: Create the entry point
In the root directory of the WebUI app, navigate to extensions/unprompted/templates. This is where all your templates belong - you can organize the files here in any way you like.
Create a blank text file called example.txt. This will serve as the "entry point" for our new template.
Open up your new file and enter the following text:
Photo of a man
Save the file and boot up your Unprompted interface. I will be using Automatic's repo for this guide, but you can follow along with the standalone unprompted_dry.py if you prefer.
Now enter the following as your prompt and press generate:
[call example]
You can check the information underneath the resulting picture to confirm that Stable Diffusion received the correct prompt ("Photo of a man").
Cool! Now let's proceed to the good stuff...
Step 2: Using the [choose] shortcode
Let's ask Unprompted to choose between a man and a woman. This is easy to do:
Photo of a [choose]man|woman[/choose]
💡 Tip: All of the code in this guide refers to our example.txt file unless otherwise noted. Remember to save your file with each change!
💡 Tip: You do NOT need to restart the web UI when making changes to your text files.
We can use the vertical pipe (i.e. |) to separate our options.
Now, what if we want to specify the hair color for our subject? We could do something like this...
Photo of a [choose]red|blue|yellow|green[/choose]-haired [choose]man|woman[/choose]
...but as you can imagine, the list of options can become quite lengthy and difficult to manage. There's a better way. We will create a separate file called color.txt and put our colors there. In programming, this is akin to an "object-oriented approach."
To make our life even easier, we can put our options on individual lines instead of relying on the vertical pipe.
So here's our new color.txt:
[choose]
red
blue
yellow
green
pink
[/choose]
Feel free to add a bunch of other colors - I'm keeping things brief for the guide.
Now, we can reference our new file in example.txt like this:
Photo of a [call color]-haired [choose]man|woman[/choose]
Yes, we are using a [call] shortcode inside of another file. This is perhaps one of the most powerful things about Unprompted!
Next, let's check out some other shortcodes we can use.
Step 3: Managing Stable Diffusion options with [set]
Unprompted has the ability to manage variables using [set] and [get]. You can create your own variables or even adjust the system variables used by the image generator.
At the bottom of example.txt, let's force a seed value of "1" to help with later debugging:
[set seed]1[/set]
For improved image quality, we can also force a CFG scale of 7 and turn on the "Restore Faces" option:
[set cfg_scale]7[/set]
[set restore_faces]1[/set]
Now no matter how we change the UI, our template will continue using these optimized values.
Step 4: Overriding parts of the template
Imagine a situation where you want the randomness a template offers, but you need to lock in a certain word or phrase of your choosing.
For example, maybe we want to generate a "panda" instead of a "man" or "woman." Do we have to destructively edit our template file? No! We can use the [overrides] shortcode for this. Here's how:
In example.txt, we need to wrap the man/woman phrase with a variable that will act like a category:
[set subject _out][choose]man|woman[/choose][/set]
I'm calling this variable subject but you can name it anything you like.
The _out argument indicates to Unprompted that we want to print this variable immediately for use in our prompt. Sometimes you don't want to do this, like when we set the CFG scale and Restore Faces earlier.
Now, inside of our web UI, we can change the prompt to this:
[overrides subject="panda"][call example]
That's it, now you've got pandas!
In the final section, we will learn about some more advanced functions.
Step 5: Conditional shortcodes
The last subject I want to discuss are the conditional shortcodes [if] and [chance]. These will evaluate given variable(s) in deciding what to output.
For our demo, we will run a check on the subject variable, and if it's set to man, we will make him wear a business suit 75% of the time. Here's how we can do this:
On a new line, we will write wearing a business suit inside of a conditional check...
[if subject="man"]wearing a business suit[/if]
💡 Tip: Unprompted will automatically convert any linebreaks in our template to spaces, and it will also remove unnecessary/double spaces at the end of the processing chain.
Finally, if we want to make this occur only 75% of the time, we introduce [chance]:
[if subject="man"][chance 75]wearing a business suit[/chance][/if]
He'd like to congratulate you on making it this far.
GG no RE
I hope you found this starter guide useful and now have a better idea of what Unprompted brings to the table!
We have only scratched the surface here - when you're ready to do a deeper dive, please check out the full documentation here (or simply click on the Manual tab if you're inside of the app itself):
Good luck!
Setting up Replacement Terms
Do you regularly use LORA files or other embeddings in your Stable Diffusion prompts? If so, you probably know that it can be a challenge to keep track of all the different filenames, trigger words, and optimal weights to use in your prompts.
You can solve this by setting up replacement terms with Unprompted.
Let's say you have the following prompt with a couple LORA tags:
an amazing illustration of pepe_frog<lora:pepeFrog_v20:0.8> bloodstainai<lora:bloodstainedVector_v10:0.75>
You can use the [replace] shortcode to perform find-and-replace operations on the inner content. So if we specify [replace red=blue], then all instances of "red" will be swapped to "blue."
Here's where it gets interesting: we can load our replacement strings from external files.
In your unprompted folder, create a subdirectory called user and make a file called replacements.json inside of that (i.e. unprompted/user/replacements.json).
Open replacements.json in your text editor of choice.
Let's write our new dictionary with "from":"to" replacement pairings:
{
"from something":"to something else"
}
In place of from something, we want to insert an easy-to-remember shorthand for the complicated LORA tag.
Looking at the example prompt, we'll use pepe the frog for the first tag. Here is our updated dictionary:
{
"pepe the frog":"pepe_frog<lora:pepeFrog_v20:0.8>"
}
Now, let's add a comma and a linebreak for the next entry.
We don't want to use bloodstained as our shorthand because it's too generic - sometimes you may want to include "bloodstained" in your prompts without invoking the LORA embedding. So we'll use in the style of bloodstained instead. We can also add an alternative replacement such as bloodstained style with a vertical pipe delimiter.
Here is our dictionary with both entries:
{
"pepe the frog":"pepe_frog<lora:pepeFrog_v20:0.8>",
"in the style of bloodstained|bloodstained style":"bloodstainai<lora:bloodstainedVector_v10:0.75>"
}
Save the file. To use it in your prompts, you must set it to the _load value of your [replace] block as shown below:
[replace _load="user/replacements.json"]an amazing illustration of pepe the frog in the style of bloodstained[/replace]
And you're done!
If you're happy with your dictionary, you probably don't want to manually write [replace] all the time. Luckily, you don't have to.
Create or open a file called config_user.json in the root of unprompted.
Add an entry called templates as shown below:
{
"templates":
{
"default":"[replace _load='user/replace.json']*[/replace]"
}
}
The asterisk wildcard represents any prompt. Restart the WebUI and you're all set!
I would like to bring a couple pargs (positional arguments) available in [replace] that may improve your workflow:
This will prevent [replace] from processing the shortcodes in your JSON values unless the key matches a string in your content. In other words, you need to use this if you wish to add shortcodes to your dictionary values.
Runs the [replace] operations before executing any shortcodes in the content. For example, let's say you have a replacement query that includes the setting of a variable:
"char_john_smith" : "male, brown hair[set name='John']"
And you have a prompt like this:
char_john_smith, [get name]
The [get name] will return an empty string because it runs before [replace] sets the variable.
So you must add _now to avoid this.
Putting both options together, your config setting may look like this:
{
"templates":
{
"default":"[replace _load='user/replace.json' _now _strict]*[/replace]"
}
}
Using Metatags with Your [choose] Blocks
In this guide, we will utilize the [tags] and [filter_tags] shortcodes to create a more dynamic [choose] block.
Let's say we want to generate a random animal. We can use the following prompt:
[choose]
dog
cat
lion
tiger
wolf
lizard
turtle
crocodile
newt
salamander
frog
[/choose]
But what if we want to generate a random animal that is also a reptile? We could create a separate [choose] block for reptiles, but that would be time-consuming and redundant. Instead, we can use the [tags] shortcode to filter our options.
We can sort our animals into three categories: mammal, reptile, and amphibian. Here's how we can do this:
[choose]
[tags mammal]
dog
cat
lion
tiger
wolf
[/tags]
[tags reptile]
lizard
turtle
crocodile
[/tags]
[tags amphibian]
newt
salamander
frog
[/tags]
[/choose]
Now we can simply write [filter_tags reptile] before our [choose] block to select a random reptile.
Note that the [tags] shortcode is not limited to use with [choose] blocks. You can use it anywhere in your template to create grouped content that can be filtered by [filter_tags].
We can also write multiple tags in a single [tags] block. Both reptiles and amphibians are known for laying eggs, so we can add a lays_eggs tag to both of those categories and use it as our filter criteria:
[filter_tags lays_eggs]
[choose]
[tags mammal]
dog
cat
lion
tiger
wolf
[/tags]
[tags reptile lays_eggs]
lizard
turtle
crocodile
[/tags]
[tags amphibian lays_eggs]
newt
salamander
frog
[/tags]
[/choose]
Now it will only select animals that lay eggs - either a reptile or an amphibian.
For our final example, let's say we want to generate a mammal that is not a feline. To achieve this, we will first create feline and canine genus tags within the mammal category (yes, we can use nested [tags]!):
[choose]
[tags mammal]
[tags genus="feline"]
cat
lion
tiger
[/tags]
[tags genus="canine"]
dog
wolf
[/tags]
[/tags]
[tags reptile lays_eggs]
lizard
turtle
crocodile
[/tags]
[tags amphibian lays_eggs]
newt
salamander
frog
[/tags]
[/choose]
Then we update our filter to exclude the feline genus using the ! operator:
[filter_tags mammal genus="!feline"]
With this setup, we will only get dog or wolf as a result.
As you can see, [tags] and [filter_tags] are very flexible - you can use them to create complex, multi-layered prompts that are easy to maintain.
For more information on these shortcodes, please consult the Unprompted Manual.