> For the complete documentation index, see [llms.txt](https://umber.gitbook.io/umber/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://umber.gitbook.io/umber/guides/creating-a-virtual-asset.md).

# Creating a Virtual Asset

This walks through the dashboard's asset creation wizard in detail — what each step asks for, what's optional, and what happens if something goes wrong. For the shortest path to your first asset, see the [Quickstart](/umber/getting-started/quickstart.md); come here when you want the full picture, or when a field or error message on screen isn't obvious.

Start from **Assets → Single → +**. The wizard adapts based on whether you upload a file up front:

1. Upload a File (optional)
2. Check for Duplicates (only if you uploaded a file)
3. Define the Asset

## Step 1 — Upload a File

Drag a file onto the drop zone, or click to browse. This step is optional — you can skip it and create an empty asset definition now, then add a file later (see **Empty virtual assets** in [Virtual Assets](/umber/concepts/virtual-assets.md)).

Supported formats:

| Category  | Formats                                    |
| --------- | ------------------------------------------ |
| Images    | JPG, PNG, WebP, SVG                        |
| Video     | MP4, WebM, OGG                             |
| Audio     | MP3, WAV, OGG                              |
| Documents | PDF, JSON, XML, Word (DOC/DOCX), Excel/CSV |
| 3D Models | GLB, GLTF, OBJ, STL, PLY, FBX              |

See [Asset Types](/umber/concepts/asset-types.md) for how these map to Umber's type system.

{% hint style="info" %}
Maximum file size depends on your plan and is shown on screen (e.g. "Max file size: 100MB"). A file that's too large, or in an unsupported format, is rejected with an inline error before you can continue.
{% endhint %}

Images and videos get a live preview; audio shows a placeholder icon. To skip this step entirely, click **Skip and Create Definition Only**.

## Step 2 — Check for Duplicates

Shown only if you uploaded a file. Umber detects the asset type from the file and searches your existing assets for similar names, so you don't accidentally create a duplicate when you meant to add a new version of something that already exists. Matching is typo-tolerant, not just exact-substring, so near-misses (reordered words, small spelling differences) still surface as candidates.

* If matches are found, they're listed alongside your uploaded file (name, ID, version count) with a link to open each in a new tab. Choose:
  * **Create New Asset** — proceed to Step 3 as a brand-new asset.
  * Select a match, then **Add as New Version** — you're redirected to that asset's version upload page (the same form used in [Adding a Version to an Existing Asset](/umber/guides/adding-a-version.md)), and your file carries over so you don't need to re-select it.
* If nothing similar is found, you'll see a note confirming this looks like a new asset — click **Continue to Asset Details** to proceed to Step 3.
* If the similarity check itself fails (a transient server issue), Umber fails open: you'll see a note that it couldn't check for similar assets right now, but you're never blocked from continuing to Step 3.

## Step 3 — Define the Asset

| Field       | Required | Notes                                                                                                                                                                                                                                            |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Asset ID    | Yes      | Unique slug — letters, numbers, hyphens, underscores. Minimum 3 characters. Auto-suggested from the filename but editable; checked live against existing IDs. Two words are reserved and can't be used on their own: `actions` and `time-range`. |
| Asset Name  | Yes      | Human-readable display name, minimum 3 characters. Auto-suggested (Title Case) from the filename.                                                                                                                                                |
| Asset Type  | Yes      | Pre-selected from the uploaded file's detected type; change it if needed. See [Asset Types](/umber/concepts/asset-types.md).                                                                                                                     |
| Description | No       | Free text.                                                                                                                                                                                                                                       |

**Advanced Options** (collapsed by default):

| Field                    | Default | Notes                                                                                              |
| ------------------------ | ------- | -------------------------------------------------------------------------------------------------- |
| Require API Key          | Off     | Marks the asset **Secured** — it can't be requested from the delivery URL without a valid API key. |
| Active                   | On      | Inactive assets aren't served.                                                                     |
| Enable Browser Cache     | On      | Controls whether delivered responses are cache-control'd for the browser.                          |
| Cache Duration (minutes) | 5       | Only shown when browser cache is enabled. Accepts 1 to 525,600 (one year).                         |

If you uploaded a file in Step 1, this screen also collects the first **version**, so the asset and its version are created together:

| Field           | Required | Notes                                                                                             |
| --------------- | -------- | ------------------------------------------------------------------------------------------------- |
| Version Name    | Yes      | Minimum 3 characters. Auto-filled as "*Asset Name* v1".                                           |
| Target Platform | Yes      | The platform this version targets (use **Generic** if you don't need platform-specific variants). |

The submit button reads **Create Asset & Version** when a file is attached, or **Create Asset** if you skipped upload.

{% hint style="info" %}
Larger files upload directly to the asset service with a live progress bar. Smaller files show a brief "Creating…" state instead.
{% endhint %}

## After creation

Either way — whether you uploaded a file (and its version was created alongside the asset) or clicked **Skip and Create Definition Only** — you land on the same success screen, offering **View Asset** (go straight to the asset's detail page) and **Create Another Asset** (start the wizard over). If you skipped upload, the description reminds you that you can add a version anytime from the asset's detail page (see [Adding a Version to an Existing Asset](/umber/guides/adding-a-version.md)) — there's no forced "add a version now" step, since skipping means you explicitly don't want to deal with a file yet.

* **Asset created, version upload failed:** treated as a partial success rather than a hard error — you'll see a note that the asset was created and can add a version afterward from the asset's detail page, since retrying the same submission would fail on the now-existing Asset ID.
* **Creation failed:** a dialog shows the server's error — most commonly a duplicate Asset ID (*"Asset Container Already Exists with this Id! Please try again"*). Pick a different Asset ID and resubmit.
* **Storage limit exceeded:** if uploading the version would put you over your plan's storage limit, you'll see a dedicated dialog rather than a generic error. Check `umber billing` (see [Umber CLI](/umber/cli-tools/umber-cli.md)) or your plan page to confirm usage before retrying.

## Already have assets in a codebase?

The steps above are for creating one asset by hand. If you're onboarding a project with many existing assets, use the [Umber CLI](/umber/cli-tools/umber-cli.md) instead — see [Migrating Assets with the CLI](/umber/guides/migrating-assets-with-cli.md).

## Made a mistake?

To remove a version or an asset you created, see [Deleting Assets and Versions](/umber/guides/deleting-assets-and-versions.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://umber.gitbook.io/umber/guides/creating-a-virtual-asset.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.