# Meshy 7 - Multi Image to 3D — API Reference

Model ID: `model_meshy-7-multi-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_meshy-7-multi-image-to-3d`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `image` | assetId[] | yes | - | Provide 1–4 images from multiple angles for higher-quality 3D. On Meshy 7 the first image is the primary (front) view; the order of the remaining views does not matter. |
| `ultraMode` | boolean | - | `false` | Enable Ultra generation for higher-fidelity geometry with finer surface detail, driven by all input views. Adds cost. |
| `shouldTexture` | boolean | - | `true` | Generate textures for a fully colored model. Disable for an untextured mesh (lower cost). |
| `enablePbr` | boolean | - | `false` | Generate PBR maps (metallic, roughness, normal) in addition to base color. Meshy 7 does not produce an emission map. Requires texture generation. |
| `textureResolution` | string | - | `2k` | Base color texture resolution: 2K (2048), 4K (4096), or 8K (8192). At 8K, PBR maps are generated at 4K and no emission map is produced. 8K is only supported with triangle topology when remeshing. |
| `texturePrompt` | string | - | `` | Optional text to guide texturing (max 600 characters). Cannot be combined with Multi-View Texture Images. |
| `textureImages` | assetId[] | - | - | Provide 1-4 images of the same object from different views to guide the texture only. The first image is the primary (front) view. Independent of the geometry Images in both content and count. Requires Texture enabled, and cannot be combined with Texture Prompt. |
| `topology` | string | - | `triangle` | Mesh topology for the generated model. |
| `targetPolycount` | number | - | `30000` | Target polygon count; actual count may vary with geometry complexity. |
| `savePreRemeshedModel` | boolean | - | `false` | Store the GLB before the remesh phase. |
| `poseMode` | string | - | `` | Pose for the generated model: A-Pose, T-Pose, or none. |
| `imageEnhancement` | boolean | - | `true` | Optimize input images for better results. |
| `removeLighting` | boolean | - | `true` | Remove highlights and shadows from input images. |
| `autoSize` | boolean | - | `false` | Estimate real-world scale for the generated model. |
| `originAt` | string | - | `bottom` | Place the model origin at the bottom or center. |

### Example Requests

**cURL**

```bash
curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_meshy-7-multi-image-to-3d" \
  -H "Authorization: Basic $(echo -n '<API_KEY>:<API_SECRET>' | base64)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "image": [
    "<asset_id>"
  ],
  "ultraMode": false,
  "shouldTexture": true,
  "enablePbr": false,
  "textureResolution": "2k",
  "texturePrompt": "",
  "topology": "triangle",
  "targetPolycount": 30000,
  "savePreRemeshedModel": false,
  "poseMode": "",
  "imageEnhancement": true,
  "removeLighting": true,
  "autoSize": false,
  "originAt": "bottom"
}
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 = {
    "image": [
        "<asset_id>"
    ],
    "ultraMode": False,
    "shouldTexture": True,
    "enablePbr": False,
    "textureResolution": "2k",
    "texturePrompt": "",
    "topology": "triangle",
    "targetPolycount": 30000,
    "savePreRemeshedModel": False,
    "poseMode": "",
    "imageEnhancement": True,
    "removeLighting": True,
    "autoSize": False,
    "originAt": "bottom"
}

response = client.generate.run_model(
    model_id="model_meshy-7-multi-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 = {
  "image": [
    "<asset_id>"
  ],
  "ultraMode": false,
  "shouldTexture": true,
  "enablePbr": false,
  "textureResolution": "2k",
  "texturePrompt": "",
  "topology": "triangle",
  "targetPolycount": 30000,
  "savePreRemeshedModel": false,
  "poseMode": "",
  "imageEnhancement": true,
  "removeLighting": true,
  "autoSize": false,
  "originAt": "bottom"
};

const response = await client.generate.runModel("model_meshy-7-multi-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)*