-
-
Notifications
You must be signed in to change notification settings - Fork 132
Styles
The AI Horde provides the capability for you to create styles which is a preset of generation options, along with a prompt template. Styles can be created for both image and text generations and allows people to create and share, easy-to-use generation templates. For image generation styles can be used to generate images in a particular art style. For text generation, styles could be used to provide a good starting point for the template needed for the model. Styles can only be created by people with the customizer role which needs to be requested by the Horde mods, to prevent abuse.
The horde also adds collections, which allow anyone (not only those with the customizer role) to group multiple styles together under a name and then use the collection name to generate images with one random style of those cointained within.
Each style will provide a prompt as a template with a {p} and for image also an '{np}' replacement string. The actual prompt of the user will be inserted in the place of the {p} whereas any negative prompt during image generation will be inserted into {np}.
Furthermore each style will provide full parameters for how to generate the image. For example specifying the generated image width*height and steps, or pre-specifying LoRas and TIs to use. Likewise in text generations one could specify as well temperature, or all the sampler order etc.
Each style needs to select pre-specified models to use, to ensure that the author has created something that matches the specific model type.
A style can be specified as nsfw or not, which will set the relevant generation switch.
Finally each style can be public or private. A public style can be seen by anyone on the user's page and in the styles list. A private style cannot be seen in the generic list, but is visible by the owning user retrieving their own info, and anyone with the style name or ID can retrieve its details, so don't share you private style's name or ID with anyone you don't trust!
And last but not least, using a style gives the style owner 2 kudos from the requester. This is used as tiny "thank you" reward for crafting something popular. It's yet another way that someone can contribute to the health of the Horde without GPU or money.
To use a style or collection, one simply needs to use its UUID or name in the style key during /async. When a style is invoked, any parameters and models passed will be ignored in favour of the ones provided by the style.
Whenever a style or collection is used, it increments a "used_count" variable, which tracks how popular it is practically. This can be seen in its information.
The AI Horde API provides the following endpoints to manage styles. Remember that you can see full documentation in the API doc page.
for image
/v2/styles/image
/v2/styles/image/{style_id}
/v2/styles/image_by_name/{style_name}
/v2/styles/image/{style_id}/example
/v2/styles/image/{style_id}/example/{example_id}
for text
/v2/styles/text
/v2/styles/text/{style_id}
/v2/styles/text_by_name/{style_name}
The image and text styles work in an identical manner, other than having different generation parameters
To see all existing styles, one can simply call /v2/styles/image or /v2/styles/text and it will return all public styles available of that type, in a paginated format. You can further filter the returned style by model name or tag and change the sorting by age or popularity.
Another way to see styles is to retrieve a use details in api/v2/users. Any public styles for that user will appear under the styles header.
If you know a style ID you can use /v2/styles/image/{style_id} or /v2/styles/text/style_id} to see its full parameters.
If you know a style name, you can retrieve it in /v2/styles/image_by_name/{style_name} or /v2/styles/text_by_name/{style_name}. Note that multiple users can have a style with the same name. To retrieve a style with a name for one user, you can add the user alias in the style name like so db0#1::My Awesome Style.
Only users with the customizer role can create styles!
To create a style, you can send a POST to /v2/styles/image or /v2/styles/text. When doing so, you must pass a prompt, a list of models and the parameters you want the style to have. Any missing mandatory parameters will have the AI Horde defaults for that type (e.g. 512x512 size for images). So make sure you set every parameter you want. Because a style allow you to provide any and all parameters, you can go wild with pre-selecting LoRas and TIs to use, which can make life easier for people trying to use this style. Check the API doc for the exact parameters you can pass and the validation they have, but they are exactly the same as the async endpoints.
When creating a style, consider passing a number of tags, which can be used by others to lookup said style. Likewise you should also add a long-form info with details on what the style is attempting to achieve. Finally you can also add example images for image styles, which will be explained later.
A created style will return both an ID and its full alias. Any user can use either of these during an async generation to invoke that style.
Using PATCH on /v2/styles/image/{style_id} or /v2/styles/text/style_id} you can modify an existing style you created. You do not have to pass all parameters from scratch, just those you wish to change. Any parameter not passed, will remain as it was. This allows you to rename the style, change it's tags, or simply tweak its parameters. Note that if modifying the parameters, they are passed as a complete json, so you should pass all parameters the style should have, not only those changed.
Using DELETE on /v2/styles/image/{style_id} or /v2/styles/text/style_id} you can delete an existing style you created. This cannot be undone.
For image styles, one can optionally add up to 4 images which show sample results of that style. For now you can only link to images you hosted elsewhere, but we hope to allow to host these on the horde buckets in the future.
To add/modify/delete samples, please use the following endpoints
/v2/styles/image/{style_id}/example
/v2/styles/image/{style_id}/example/{example_id}
If a style has image examples, one of them will be marked as "primary" (the author can choose which), which doesn't have a functional effect, but frontends can use this info to know which image to show the user first.
Using a style consumes 2 extra kudos regardless of how many images are in the batch. This 2 extra kudos goes towards the style creator directly. The expectation is that people with great styles will get priority for their own generations from this.
A collection is a group of styles from one of more users. A collection name or id can be passed in place of a style in the /async endpoints and it will then use a random style from the ones contained within for the generation. Collection allow one to make a number of thematic groupings and provide a way to use a different one every time for versatility.
The collection endpoints are the following. As always the API doc provides the full information.
/v2/collections
/v2/collections/{collection_id}
/v2/collection_by_name/{collection_name}
A GET on /v2/collections will return all collections, text and image, but you can limit it to a specific type if you want.
a GET on /v2/collections/{collection_id} or /v2/collection_by_name/{collection_name} will return the details on that collection accordingly.
A POST on /v2/collections will create a new collection. A collection cannot contain both image and text styles, so choose one. You can add any number of existing styles in a collection. They do not have to belong to the same user! You also don't need to be a customizer to use a collection.
You can use a PATCH on /v2/collections/{collection_id} to modify a collection. Like styles, only passed fields are changed.
You can use a DELETE on /v2/collections/{collection_id} to delete a collection.