> 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/getting-started/quickstart.md).

# Quickstart

<a href="https://dashboard.projectsim.ai/?utm_source=docs&#x26;utm_medium=hero&#x26;utm_content=quickstart" class="button primary">Get an API token</a> <a href="https://www.projectsim.ai/access?utm_source=docs&#x26;utm_medium=hero&#x26;utm_content=quickstart" class="button secondary">Request a custom dataset</a>

Create an asset from one image, poll until it finishes, and download the result. The walkthrough uses Python with the [`httpx`](https://www.python-httpx.org/) HTTP client; any HTTP client works, and the creation guides also show cURL.

This uses `POST /v1/assets/standard`, a single-asset creation endpoint. If you need measured real-world scale or many variants at once, see [Choose a creation endpoint](/creating-assets/choosing-an-endpoint.md) first.

{% hint style="info" %}
The API base URL is `https://api.projectsim.ai`. Every request needs a bearer token; see [Authentication](/getting-started/authentication.md).
{% endhint %}

## Before you start

{% hint style="info" %}
**Sign-up is self-serve.** Create an account at [dashboard.projectsim.ai](https://dashboard.projectsim.ai/?utm_source=docs\&utm_medium=hint\&utm_content=quickstart), add a payment method on the **Billing** page to start the free trial (your first 40 credits are free), then create your token on the **API token** page. See [Authentication](/getting-started/authentication.md#getting-a-token) for details.

Need a custom dataset built for you — thousands of assets, or millions? [**Request a dataset →**](https://www.projectsim.ai/access?utm_source=docs\&utm_medium=hint\&utm_content=quickstart)
{% endhint %}

Already have a token? Follow the [authentication instructions](/getting-started/authentication.md#use-your-api-token), then continue below.

Use Python 3.11 or later and install `httpx`:

```bash
python -m pip install httpx
```

Set `PROJECTSIM_TOKEN` to your API token in your environment. Run the Python snippets below in order in the same script or session. Replace the example image URL with a publicly reachable HTTPS URL for your image.

The API is JSON over HTTPS: send your token in the `Authorization` header and JSON request bodies. The examples check the HTTP status before reading the JSON response; API errors return a [Problem Details](/getting-started/authentication.md#errors) body, which the examples raise as the error message.

## 1. Create the asset

This example sends one image (an HTTPS URL we fetch, inline base64, or an [uploaded file](/guides/uploads.md)) to `POST /v1/assets/standard`. The endpoint also accepts a text description, or an image plus `inputs.subject_name` with `inputs.multi_subject_image: true` — see [Standard asset](/creating-assets/assets-standard.md). It returns `202` immediately; the asset is not ready yet.

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

```python
import os
import uuid

import httpx

client = httpx.Client(
    base_url="https://api.projectsim.ai",
    headers={"Authorization": f"Bearer {os.environ['PROJECTSIM_TOKEN']}"},
    timeout=30.0,
)

response = client.post(
    "/v1/assets/standard",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={
        "name": "office chair",
        "inputs": {"images": [{"url": "https://example.com/chair.png"}]},
    },
)
if response.status_code != 202:
    raise RuntimeError(response.text)
created = response.json()
asset_id = created["id"]
job_id = created["job_id"]
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X POST "https://api.projectsim.ai/v1/assets/standard" \
  -H "Authorization: Bearer $PROJECTSIM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "office chair",
    "inputs": { "images": [{ "url": "https://example.com/chair.png" }] }
  }'
```

{% endtab %}
{% endtabs %}

The response carries `id` (the asset), `job_id`, `status`, and `effective_params` — the resolved parameters used for this asset.

## 2. Poll the job

`GET /v1/jobs/{job_id}` is the single polling surface. `status` moves `queued → running → complete`, or to `failed`. A job that is still `queued` or `running` when its time budget runs out moves to `failed`, so it cannot poll forever.

```python
import time

while True:
    response = client.get(f"/v1/jobs/{job_id}")
    if response.status_code != 200:
        raise RuntimeError(response.text)
    job = response.json()
    if job["status"] == "complete":
        break
    if job["status"] in {"failed", "canceled", "partial"}:
        raise RuntimeError(f"Job ended with {job['status']}: {job['error']}")
    time.sleep(5)
```

## 3. Download

`GET /v1/assets/{asset_id}` is both the record and the download surface: every entry in `files` carries a presigned URL valid for one hour. Don't cache the URLs — call again to mint fresh ones. Files appear only once the asset completes; there are no partial downloads. Download each file from its URL without your API token.

```python
from pathlib import Path

response = client.get(f"/v1/assets/{asset_id}")
if response.status_code != 200:
    raise RuntimeError(response.text)
asset = response.json()
output_dir = Path("downloads").resolve()

for file in asset["files"]:
    # Preserve relative paths so models can find their textures.
    destination = (output_dir / file["path"]).resolve()
    if not destination.is_relative_to(output_dir):
        raise ValueError("Unexpected download path")
    destination.parent.mkdir(parents=True, exist_ok=True)
    # Storage URLs are signed; use a separate client without your API token.
    with httpx.stream("GET", file["url"], timeout=60, follow_redirects=True) as download:
        download.raise_for_status()
        with destination.open("wb") as target:
            for chunk in download.iter_bytes(chunk_size=1024 * 1024):
                target.write(chunk)
    print(destination)

client.close()
```

## Where to go next

* Not sure which endpoint fits? See [Choose a creation endpoint](/creating-assets/choosing-an-endpoint.md).
* Steer mesh, texture, and simulation-ready physics with [Parameters](/creating-assets/parameters.md).
* Need measured real-world scale? See [Measured asset](/creating-assets/assets-measured.md). Need many variants at once? See [High-fidelity](/creating-assets/high-fidelity-variation-set.md) or [Procedural](/creating-assets/procedural-variation-set.md) variation sets.
* Receive completion and failure notifications with [Webhooks](/guides/webhooks.md).