# YVO3D Image to 3D — API Reference

Model ID: `model_yvo3d-image-to-3d`

---

## Authentication

- **API_KEY** and **API_SECRET** are found in your [Scenario Project Settings](https://app.scenario.com/team&tab=api_keys) under API Keys.
- Set them as environment variables `SCENARIO_SDK_API_KEY` and `SCENARIO_SDK_API_SECRET` — both SDKs pick them up by default.
- For raw HTTP (cURL), use Basic Auth: `Authorization: Basic base64("<API_KEY>:<API_SECRET>")`.

### Install the SDK

- JavaScript / TypeScript: `npm install @scenario-labs/sdk`
- Python: `pip install scenario-sdk`

---

## Generate

**Endpoint:** `POST https://api.cloud.scenario.com/v1/generate/custom/model_yvo3d-image-to-3d`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `images` | assetId[] | yes | - | Upload one image to build a 3D model from a single view, or 2–4 photos of the same subject from different angles for a more accurate shape. With several photos, put the front view first: it drives the texture. |
| `texture` | boolean | - | `true` | On, the model comes with surface color and material; off, you get the bare shape only. With several photos, the texture is painted from the first (front) view. |
| `modelGenerator` | string | - | `FAST_TRUE` | The shape quality level for single-image generation. Higher tiers produce better geometry but cost more. Multi-view uploads always use Ultima Prime. |
| `textureResolution` | string | - | `1K` | The detail level of the surface texture, for textured models. Higher resolutions look sharper but cost more. |
| `polycount` | number | - | `100000` | The target number of polygons in the model — more polygons mean finer detail and heavier files. Applies to shape-only and multi-view generation; ignored for textured single-image models. |
| `lowpoly` | boolean | - | `false` | Produces a simplified, low-polygon model for a lighter, stylized look. Applies to shape-only generation. |
| `highdetails` | boolean | - | `false` | Single image with the Ultima Prime generator only. Adds finer geometric detail for an extra cost. Can't be combined with Low Poly. |
| `autopoly` | boolean | - | `false` | Available with the Ultima Prime generator only. Lets the model pick the best polygon count for you. |
| `smartLowPoly` | number | - | - | Available with the Ultima Prime generator only, for an extra cost. Rebuilds the model as a clean low-poly mesh with about this many faces, overriding Polycount and Auto Polycount. Can't be combined with High Details. Aim for at least 150 faces on simple models and 250 on complex ones. |
| `realismLevel` | number | - | `0.85` | How photorealistic the texture looks, for textured models. Higher values are more realistic. |
| `creativity` | number | - | `3` | How much creative freedom the model takes. 0 stays faithful to your image; 5 allows more imaginative interpretation. |
| `generateUvs` | string | - | `ON` | Automatically creates UV maps — the layout that lets a texture wrap correctly onto the 3D surface — when they're missing. |
| `hyperMode` | string | - | `OFF` | Processes textures faster and at lower cost, with a small drop in quality. |
| `insideOut` | string | - | `OFF` | Textures the inside surfaces of the model as well as the outside, rather than just the outside. Adds cost. |
| `unlit` | string | - | `OFF` | Bakes the texture without any lighting or shadows, so the model looks the same under any lighting in your scene. |
| `textureSharpness` | number | - | `0.5` | How sharp and detailed the texture appears. Higher values enhance fine detail. |
| `textureAdherence` | string | - | `OFF` | When on, keeps the generated texture closer to the look of your source image. |
| `roughness` | number | - | `1.3` | How matte or glossy the surface looks. Higher values are more matte; lower values are shinier. |

### Example Requests

**cURL**

```bash
curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_yvo3d-image-to-3d" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "images": [
    "<asset_id>"
  ],
  "texture": true,
  "modelGenerator": "FAST_TRUE",
  "textureResolution": "1K",
  "polycount": 100000,
  "lowpoly": false,
  "highdetails": false,
  "autopoly": false,
  "realismLevel": 0.85,
  "creativity": 3,
  "generateUvs": "ON",
  "hyperMode": "OFF",
  "insideOut": "OFF",
  "unlit": "OFF",
  "textureSharpness": 0.5,
  "textureAdherence": "OFF",
  "roughness": 1.3
}
EOF
```

**Python**

```python
import os
from scenario_sdk import Scenario

client = Scenario(
    api_key=os.environ.get("SCENARIO_SDK_API_KEY"),
    api_secret=os.environ.get("SCENARIO_SDK_API_SECRET"),
)

body = {
    "images": [
        "<asset_id>"
    ],
    "texture": True,
    "modelGenerator": "FAST_TRUE",
    "textureResolution": "1K",
    "polycount": 100000,
    "lowpoly": False,
    "highdetails": False,
    "autopoly": False,
    "realismLevel": 0.85,
    "creativity": 3,
    "generateUvs": "ON",
    "hyperMode": "OFF",
    "insideOut": "OFF",
    "unlit": "OFF",
    "textureSharpness": 0.5,
    "textureAdherence": "OFF",
    "roughness": 1.3
}

response = client.generate.run_model(
    model_id="model_yvo3d-image-to-3d",
    body=body,
)
print(response)
```

**JavaScript**

```javascript
import Scenario from "@scenario-labs/sdk";

const client = new Scenario({
  apiKey: process.env["SCENARIO_SDK_API_KEY"],
  apiSecret: process.env["SCENARIO_SDK_API_SECRET"],
});

const body = {
  "images": [
    "<asset_id>"
  ],
  "texture": true,
  "modelGenerator": "FAST_TRUE",
  "textureResolution": "1K",
  "polycount": 100000,
  "lowpoly": false,
  "highdetails": false,
  "autopoly": false,
  "realismLevel": 0.85,
  "creativity": 3,
  "generateUvs": "ON",
  "hyperMode": "OFF",
  "insideOut": "OFF",
  "unlit": "OFF",
  "textureSharpness": 0.5,
  "textureAdherence": "OFF",
  "roughness": 1.3
};

const response = await client.generate.runModel("model_yvo3d-image-to-3d", { body });
console.info(response);
```

---

## Retrieve Results

After submitting a generation request, you receive a `jobId`. Poll the job until `job.status` is `"success"`. The generated asset IDs are in `job.metadata.assetIds`.

**Endpoint:** `GET https://api.cloud.scenario.com/v1/jobs/{jobId}`

### Example Requests

**cURL**

```bash
curl -X GET "https://api.cloud.scenario.com/v1/jobs/<JOB_ID>" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)"
```

**Python**

```python
job = client.jobs.retrieve(job_id="<JOB_ID>")
print(job.status)
print(job.metadata.asset_ids)
```

**JavaScript**

```javascript
// Option 1 — wait on the response from runModel using the SDK helper
const completed = await response.job.wait();
console.info(completed.status);
console.info(completed.metadata?.assetIds);

// Option 2 — retrieve a job by its ID
const job = await client.jobs.retrieve("<JOB_ID>");
console.info(job.status);
console.info(job.metadata?.assetIds);
```

**Example response:**

```json
{
  "job": {
    "jobId": "job_abc123",
    "status": "success",
    "metadata": {
      "assetIds": [
        "asset_abc123"
      ]
    }
  }
}
```

> **Important:** Generated asset URLs are **temporary** and expire after a short period. Download and store any images you wish to keep before the URL expires. More info: [Content Delivery Network (CDN)](https://docs.scenario.com/get-started/documentation/content-delivery-network-cdn).

---

*Generated by [Scenario](https://app.scenario.com)*