> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gizmo.antimlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variations

> Generate an asset plus extra versions of it, each saved as its own sim-ready asset.

Works with **Personal and Team keys**. Use variations to get several versions of one object (finishes, colors, sizes) for domain randomization without writing a prompt for each.

## Request variations

Variations keep your original asset and save extra versions of it as separate
assets in your library. Each variation is a full sim-ready asset with its own
collisions and exports. Turn them on with `appearance_variants`:

```json theme={null}
{
  "prompt": "A wooden cabinet with three sliding drawers",
  "appearance_variants": true,
  "variant_count": 4,
  "variant_mode": "appearance",
  "variant_guidance": "Painted finishes in muted colors, one with worn edges"
}
```

| Input | Type | Description |
| - | - | - |
| `appearance_variants` | boolean, optional | Defaults to `false`. Set `true` to save variations alongside the original. The other variant fields require it. |
| `variant_count` | integer, optional | How many variations to make, not counting the original. Defaults to `2`. Personal accepts 1 to 10; Teams accept 1 to 9. |
| `variant_mode` | string, optional | `appearance` (default) changes only materials, colors and surface finish, keeping the shape identical. `geometry` changes shape or size. `both` changes shape and surface together. |
| `variant_guidance` | string, optional | Up to 2,000 characters describing how the variations should differ. It applies to the variations only and never changes the original. Leave it out and Gizmo picks useful, visibly distinct variations itself. |

## Choose a mode

Set `variant_mode` yourself when calling the API. If your guidance asks for a
different size or shape, use `geometry` or `both`; in `appearance` mode, shape
requests in the guidance are ignored. The Gizmo home page does this for you: when
you type variation guidance there, it reads the guidance to choose the mode, and
falls back to a keyword check if that step is unavailable, so generation always
starts.

## Get the variations

Each variation is delivered on its own as soon as it is ready, so some can finish
before others. When the job is done, `job.variant_assets` lists each variation with
its `index`, `name`, `status` and `originalAssetId`. A ready variation also has an
`assetId` you can export like any other asset. The original stays at
`result.asset.id`. A variation that fails does not fail the original.

Batch items (Personal and Team) accept the same fields inside their `input` object.

## Pricing

On Personal accounts each delivered variation costs a flat $1, on top of the
original's metered price. Variations that fail are not charged. To start, a request
needs $1 plus $1 per requested variation available: an original with 4 variations
needs $5. Team variation pricing follows the Team's configured price. See
[Billing & limits](https://docs.gizmo.antimlabs.com/api-limits.md#personal-accounts) for details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.