> 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/high-fidelity-variation-set.md). # High-fidelity variation set `POST /v1/variation-sets/high-fidelity` Order many variants of an object from an image, text, or both, with optional variation references. Use high-fidelity when you want the **highest photoreal fidelity** per variant. It does **not** articulate — for articulated objects use a [procedural set](/creating-assets/procedural-variation-set.md).
Strawberry variations in red, pale pink, and white, with different shapes and surface details

Strawberry variations showing differences in color, shape, and surface detail.

Generate object variants for visual domain randomization from one subject. ## Input Provide **an image, text, or both** to define the subject. You can add optional **variation reference images** with any of these input combinations to guide style, palette, or details. References alone do not define a valid seed. | Field | Notes | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `count` (required) | How many variants, `1`–`100`. | | `seed.images` | At most **one** reference image — the subject to vary. Provide an image, text, or both. | | `seed.text` | Text prompt (≤ 2,000 chars). Required and must be nonblank when no seed image is supplied; optional with an image. | | `seed.variation_references` | Optional list of up to **8** images for style, palette, or detail cues. Can accompany image-only, text-only, or combined input. | | `name` | Display label (≤ 100 chars); also grounds the generator's subject identification. | | `params` | Optional output settings; see [Parameters that apply](#parameters-that-apply). | | `Idempotency-Key` (header) | Without one, a timed-out retry duplicates the whole order. | Use `seed.images` for the subject image and `seed.variation_references` for additional visual guidance. Both lists use the same image input format as the examples below. Omitting both the subject image and nonblank text returns `422`, even if variation references are supplied. ## Parameters that apply Set **`params.physics.body`** to `rigid` (default) or `deformable`. Top-level `body` and `params.physics.articulated` are rejected (`422`). Deformable bodies require `collision: auto` and Isaac Sim (PhysX/Newton) or Genesis. High-fidelity uses **`mesh`, `texture`, and `physics`**, plus **`variation`**, which steers the image generator. See [Parameters](/creating-assets/parameters.md). ## Writing a text prompt Establish **one subject** with an image, a text description, or both, then describe the visual changes you want: shape, colour, material, wear, damage, or condition. This is an image-variation prompt. Functional hinges, joint axes, and opening-angle instructions belong in a [Procedural prompt](/creating-assets/procedural-variation-set.md#writing-a-text-prompt). An open lid visible in a High-fidelity result does not make it a moving part. When supplying a seed image, choose a photo containing one object. A pile of parcels or a photo with two boxes can lead to multiple objects being reconstructed as one asset. Crop or replace that reference before submitting it; text alone cannot ensure that the generator separates the subjects. Keep the prompt focused on one object rather than asking for multiple objects. The image generator already supplies background and isolation instructions. Focus your text on the subject and the changes; you do not need to repeat “isolated on a plain grey background,” camera setup, or render instructions. ### Example High-fidelity prompts The examples below describe changes to a single object in a reference image. | Goal | Example prompt | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Damaged parcel shapes | Vary the single cardboard parcel in the reference with lightly dented corners, shallow wall creases, and modest differences in rectangular proportions. Keep it recognisable as one closed shipping box. | | Tape and labels on the same box shape | Keep the reference box shape and proportions unchanged. Vary cardboard colour, packing-tape colour, shipping-label placement, and light surface scuffs. | | Strawberries at different stages of ripeness | Vary the single strawberry in the reference across pale, ripe red, and slightly overripe appearances, with modest changes in its plumpness and surface bruising. Keep each variant recognisable as one strawberry. | | Worn paint on a metal container | Preserve the reference container shape. Vary paint colour, faded patches, scratches, and small areas of surface rust without adding holes, dents, or extra parts. | Without a reference image, describe the subject directly, for example: “One strawberry with green leaves. Vary its ripeness from pale to deep red, its plumpness, and light surface bruising.” ## Example This request combines a subject image, text, and one optional variation reference. Omit `variation_references` when you do not need extra visual guidance. Install the generated Python SDK and set `PROJECTSIM_TOKEN` as shown in the [Quickstart](/getting-started/quickstart.md). {% tabs %} {% tab title="Python" %} ```python import os import uuid import httpx from projectsim import AuthenticatedClient from projectsim.api.variation_sets import create_high_fidelity_variation_set from projectsim.models import ( CreateHighFidelityVariationSetRequest, HighFidelitySeed, ImageInput, Params, PhysicsParams, TextureParams, VariationParams, ) client = AuthenticatedClient( base_url="https://api.projectsim.ai", token=os.environ["PROJECTSIM_TOKEN"], timeout=httpx.Timeout(30.0), raise_on_unexpected_status=True, ) body = CreateHighFidelityVariationSetRequest( name='strawberry', count=20, seed=HighFidelitySeed( text=( 'Vary the single strawberry in the reference across pale, ' 'ripe red, and slightly overripe appearances, with modest ' 'changes in its plumpness and surface bruising. Keep each ' 'variant recognisable as one strawberry.' ), images=[ImageInput( url='https://example.com/strawberry.png', )], variation_references=[ImageInput( url='https://example.com/strawberry-colour-reference.png', )], ), params=Params( physics=PhysicsParams(body='rigid'), variation=VariationParams( variation_type='general', wildness='moderate', ), texture=TextureParams( resolution=4096, ), ), ) with client: response = create_high_fidelity_variation_set.sync_detailed( client=client, body=body, idempotency_key=str(uuid.uuid4()), ) if response.status_code != 202: raise RuntimeError(response.content.decode("utf-8")) created = response.parsed if created is None: raise RuntimeError("The API returned an empty response") print(created.job_id) ``` {% endtab %} {% tab title="cURL" %} ```bash curl -X POST "https://api.projectsim.ai/v1/variation-sets/high-fidelity" \ -H "Authorization: Bearer $PROJECTSIM_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "name": "strawberry", "count": 20, "seed": { "images": [{ "url": "https://example.com/strawberry.png" }], "variation_references": [{ "url": "https://example.com/strawberry-colour-reference.png" }], "text": "Vary the single strawberry in the reference across pale, ripe red, and slightly overripe appearances, with modest changes in its plumpness and surface bruising. Keep each variant recognisable as one strawberry." }, "params": { "physics": { "body": "rigid" }, "variation": { "variation_type": "general", "wildness": "moderate" }, "texture": { "resolution": 4096 } } }' ``` {% endtab %} {% endtabs %} Returns `202` with the set's `id` and `job_id`; members are created at once, each with a stable `variant_index`. {% hint style="info" %} Limits: `count` is 1–100, 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`). Members can't be deleted individually — delete the set once it is no longer active; deleting an active set returns `409` (`job-in-progress`), so cancel it first. {% endhint %} ## 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, member counts, and the manifest once terminal. * **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`). A set may finish `partial`, meaning some members failed; indexes are never renumbered, so gaps stay legible.