> For the complete documentation index, see [llms.txt](https://docs.projectsim.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.projectsim.ai/creating-assets/procedural-variation-set.md).

# Procedural variation set

`POST /v1/variation-sets/procedural`

Generate variations of **simple geometric objects**, such as boxes, desks, and cabinets. Use Procedural for changes to proportions and construction, including moving parts such as hinged doors and sliding drawers.

<figure><img src="https://70818391-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWnQtI3aVPkZHPVyrjjFG%2Fuploads%2Fgit-blob-60ea696248fcb75c3c6c2ea07463b9c6d3c79bf9%2Fprocedural-examples.png?alt=media" alt="Ten articulated desk variants with different dimensions, materials, and drawer configurations, including open drawers"><figcaption><p>Articulated desk variants for drawer-opening and manipulation tasks.</p></figcaption></figure>

## Use it when

* You need related boxes, containers, desks, or other objects built from **simple geometric shapes**.
* Your task needs changes to **size, proportions, or configuration**, such as different drawer layouts or handle shapes.
* You need **moving parts** for opening and closing tasks, or **jointless rigid objects** for picking and stacking.

## Don't use it when

* You need **realistic strawberries or other organic objects**. Use [High-fidelity](/creating-assets/high-fidelity-variation-set.md) for organic shapes and detailed appearance. Procedural can produce simplified, less faithful results for these subjects.
* **Fine visual detail** matters: fruit seeds, creases, crushed corners, labels, or surface wear. Use High-fidelity for these appearance variations; it does not create moving joints.
* You need **guaranteed dimensions, fit, or mechanism behaviour**. Prompts do not enforce exact clearances, motion limits, or joint counts. Validate outputs against your task. For one object's measured real-world scale, use [Measured](/creating-assets/assets-measured.md).
* You need **deformable bodies** or a **native output other than USD**. Procedural currently exports rigid-body USD. Check the [output settings](/creating-assets/parameters.md) for the other routes.

Provide **one image, a nonblank text brief, or both**. Both articulated and jointless objects use **rigid** bodies.

See the [desk example](/creating-assets/choosing-an-endpoint/worked-use-cases.md#articulated-desks-with-drawers) for an articulated generation workflow.

## Input

| Field                      | Notes                                                                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `count` (required)         | How many variants, `10`–`500`.                                                                                                                        |
| `seed` (required)          | Provide **`seed.text`, `seed.images`, or both**.                                                                                                      |
| `seed.text`                | A nonblank brief describing the object — its parts and how they move, materials, rough size (≤ 2000 chars).                                           |
| `seed.images`              | At most one PNG, JPEG or WebP image (≤ 100 MB), supplied as an HTTPS `url` or inline base64 `data`—exactly one source. Required when text is omitted. |
| `name`                     | Display label (≤ 100 chars).                                                                                                                          |
| `params`                   | Optional output settings; see [Parameters that apply](#parameters-that-apply).                                                                        |
| `Idempotency-Key` (header) | Optional, but recommended: without one, a timed-out retry duplicates the whole order.                                                                 |

For image-only seeds, the pipeline reads the reference image and creates the detailed object brief. It treats the image as one example of the product family, rather than restricting every variant to its exact configuration. With both inputs, the supplied text guides intake alongside the image.

Omitting both image and text returns `422`. Explicitly empty or whitespace-only text is rejected even when an image is supplied; omit `seed.text` for image-only requests (or set it to `null`).

## Image-only example

Send this body to `POST /v1/variation-sets/procedural`:

```json
{
  "name": "storage boxes",
  "count": 10,
  "seed": {
    "images": [{"url": "https://example.com/storage-box.png"}]
  },
  "params": {
    "physics": {"body": "rigid", "articulated": false}
  }
}
```

Add `seed.text` to guide construction or movement. Omit the image for a text-only request. The reference does not establish measured dimensions; use [Measured](/creating-assets/assets-measured.md) when measured real-world scale is required.

## Parameters that apply

Set body behavior and articulation under **`params.physics`**.

Set **`params.physics.body: rigid`** and choose **`params.physics.articulated`** independently. The articulation flag guides generation of moving parts. Mesh, texture, and variation settings are not forwarded by this endpoint, so they are hidden from its reference. See [Parameters](/creating-assets/parameters.md).

| Field                                  | Allowed values                                                                | Built-in default  |
| -------------------------------------- | ----------------------------------------------------------------------------- | ----------------- |
| `params.physics.body`                  | `rigid`                                                                       | `rigid`           |
| `params.physics.articulated`           | `true`, `false`                                                               | `true`            |
| `params.physics.collision_granularity` | `link`, `part`                                                                | `link`            |
| `params.physics.simulator`             | `isaac_sim_physx`, `isaac_sim_newton`, `genesis`                              | `isaac_sim_physx` |
| `params.physics.collision`             | `auto`, `convex_hull`, `convex_decomposition`, `coacd`, `bounding_box`, `sdf` | `auto`            |

`params` is optional. Every variant is delivered as USD authored for the chosen simulator, with the same files for each engine. `sdf` collision is accepted only with `isaac_sim_physx` or `isaac_sim_newton`; unsupported combinations return `422`.

See [Parameters](/creating-assets/parameters.md) for output settings and collision guidance.

## Writing a text prompt

Describe **one object and its construction**: the main body, attached parts, materials, and the proportions or features that may vary. For moving parts, name what moves, how it moves, and its starting position. “Articulated box” alone leaves the mechanism unclear; “four top flaps hinged along the upper rim, initially closed” gives a concrete construction brief.

Keep the prompt about one object per variant; avoid asking for a pile, a pair, or a scene containing several objects. If you supply an image, use a reference showing one object clearly. Background, lighting, camera, and image-layout instructions are unnecessary for describing the procedural object's construction.

Describe motion consistently. For opening lids, hinged doors, or sliding drawers, explain how they move and avoid conflicting phrases such as “no moving parts,” “fused shut,” or “sealed top.” For a fixed prop, describe its fixed construction without asking for functional hinges or sliding parts.

State task-critical requirements explicitly. For a hacksaw, describe the handle opening and required hand clearance rather than only saying “hacksaw.” Add a clear reference image when shape or construction matters. These details can improve the result, but verify the generated opening, collisions, and motion in your simulator; a plausible-looking tool may still be unusable for the intended task.

### Example procedural prompts

Use these examples as a starting point for describing the object you need.

| Asset                                  | Example prompt                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sealed parcel for picking and stacking | One closed corrugated cardboard shipping box with a taped, sealed top and bottom. Vary its width, depth, height, and cardboard colour within ordinary parcel proportions. All panels are fixed; no moving parts.                                                                                                                                            |
| Shipping box that opens                | One corrugated cardboard shipping box with a hollow interior, a permanently sealed bottom, and four independently opening top flaps. Each flap rotates about its attachment along the upper rim, from closed to approximately 120 degrees open. Start with the flaps closed and leave clearance for opening. Vary the box proportions and cardboard colour. |
| Desk with sliding drawers              | One freestanding desk with a fixed worktop, supporting legs, and drawers beneath the worktop. Each drawer slides outward horizontally and starts closed. Handles move with their drawers. Vary the desk proportions, drawer configuration, handle shape, and wood finish.                                                                                   |
| Roll cage with an opening gate         | One warehouse roll cage with a rectangular base, three fixed mesh sides, and one front mesh gate. The gate swings outward around a vertical hinge on its left edge and starts closed. Keep its handle attached to the gate. Vary cage height, width, and mesh spacing.                                                                                      |
| Drawer unit                            | One freestanding drawer unit with a fixed outer frame and three separate drawers. Each drawer slides straight forward from the frame and starts fully closed. Handles move with their drawers. Vary the frame proportions, drawer heights, and finish.                                                                                                      |

For detailed creases, crushed corners, printed labels, or surface wear from a photo, use the [High-fidelity prompt examples](/creating-assets/high-fidelity-variation-set.md#writing-a-text-prompt). That route varies appearance and geometry but does not create functional joints.

## Example

Set `PROJECTSIM_TOKEN` and install `httpx` as shown in the [Quickstart](/getting-started/quickstart.md).

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://api.projectsim.ai/v1/variation-sets/procedural" \
  -H "Authorization: Bearer $PROJECTSIM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '
{
  "name": "desk with drawers",
  "count": 50,
  "seed": {
    "text": "One freestanding desk with a fixed worktop, supporting legs, and drawers beneath the worktop. Each drawer slides outward horizontally and starts closed. Handles move with their drawers. Vary the desk proportions, drawer configuration, handle shape, and wood finish."
  },
  "params": {
    "physics": {
      "body": "rigid",
      "articulated": true,
      "simulator": "isaac_sim_physx",
      "collision": "auto",
      "collision_granularity": "part"
    }
  }
}'
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import uuid

import httpx

response = httpx.post(
    "https://api.projectsim.ai/v1/variation-sets/procedural",
    headers={
        "Authorization": f"Bearer {os.environ['PROJECTSIM_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "desk with drawers",
        "count": 50,
        "seed": {
            "text": (
                "One freestanding desk with a fixed worktop, supporting "
                "legs, and drawers beneath the worktop. Each drawer slides "
                "outward horizontally and starts closed. Handles move with "
                "their drawers. Vary the desk proportions, drawer "
                "configuration, handle shape, and wood finish."
            ),
        },
        "params": {
            "physics": {
                "body": "rigid",
                "articulated": True,
                "simulator": "isaac_sim_physx",
                "collision": "auto",
                "collision_granularity": "part",
            },
        },
    },
    timeout=30.0,
)
if response.status_code != 202:
    raise RuntimeError(response.text)
print(response.json()["job_id"])
```

{% endtab %}
{% endtabs %}

Creation returns `202` with the set's `id` and `job_id`. Exactly `count` member assets are created at once, each a full [`/v1/assets`](/guides/jobs-and-assets.md) citizen with a stable `variant_index` from 1 to `count`.

{% hint style="info" %}
Limits: `count` is 10–500, and at most **5 sets** may be queued or running at once (`409` `too-many-sets` beyond that). If the account has a lifetime [asset limit](/guides/jobs-and-assets.md#account-limit), every member counts toward it, so a set that would cross it returns `429` (`asset-limit-reached`).
{% endhint %}

For a jointless asset, change `params.physics.articulated` to `false` while keeping `params.physics.body` set to `rigid`.

## Pulling the set

* **Get the assets:** `GET /v1/variation-sets/{set_id}/assets` returns member assets with presigned download URLs (valid for 24 hours), ordered by `variant_index`. It is paginated: `limit` defaults to 50 (max 100); pass the returned `next_cursor` (the last `variant_index` on the page) as `cursor` until it is `null`. Filter by member job with `status`.
* **Check set status:** `GET /v1/variation-sets/{set_id}` returns status and member counts, derived from member jobs on every read, plus the manifest once terminal and the state of the set's [ZIP bundle](#downloading-the-set-as-one-zip).
* **Cancel the set:** `POST /v1/jobs/{job_id}/cancel` with the set's `job_id` cancels the set and its members until any member starts generating; after that, or once the set has finished, it returns `409` (`job-started` or `job-finished`). A member's own job cannot be canceled (`409` `variation-set-member`).

## Downloading the set as one ZIP

Once the set is `complete` or `partial`, you can ask for a single ZIP of all its files instead of downloading each member.

1. **Request it:** `POST /v1/variation-sets/{set_id}/bundle` with `{"format": "zip"}` returns `202` with `state` `pending` and the build's `job_id`. The ZIP is built in the background; a large set can take a few minutes.
2. **Wait for it:** subscribe to the `variation_set.bundle_ready` [webhook](/guides/webhooks.md), or poll `GET /v1/variation-sets/{set_id}` until `bundle.state` is `ready`.
3. **Download it:** `bundle.url` is a presigned URL valid for 24 hours. Read the set again for a fresh one.

Requesting the bundle again while it is `pending` or `ready` returns its current state rather than building another. If a build fails, you get `variation_set.bundle_failed`, `bundle.state` goes back to `none`, and you can request it again. A set that hasn't finished yet answers `409` `set-not-finished`; one that ended `failed` or `canceled` answers `409` `set-not-bundleable`.

The ZIP holds `manifest.json` at the root and one folder per member, named by its zero-padded `variant_index` (`001/`, `002/`, …). Each file sits at the `path` the manifest gives it, so every USD finds its textures. Members that failed have no folder, though the manifest still lists them. Files are stored uncompressed, since PNG, USD and GLB are already compressed. A bundle over 2 GiB, or one holding a file over about 1.9 GiB, is a ZIP64 archive, and a smaller one can be too; open bundles with a ZIP64-aware tool such as 7-Zip or `unzip` 6.0 or later.

See also: [High-fidelity variation set](/creating-assets/high-fidelity-variation-set.md).
