# Meshy 7 - Image to 3D — API Reference

Model ID: `model_meshy-7-img23d`

---

## 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-img23d`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `image` | assetId[] | yes | - | Upload one image to convert into 3D, or up to four images from multiple angles for higher accuracy. |
| `ultraMode` | boolean | - | `false` | Enable Ultra generation for higher-fidelity geometry with finer surface detail. Adds cost. |
| `texturePrompt` | string | - | `` | Provide a text description to guide the texturing process. The Style Prompt is only used when no Style Image is provided. If you upload an image, this text prompt will be ignored. |
| `textureImage` | assetId | - | - | Upload a reference image to guide the visual style of the generated texture. This will override the Style Prompt. Requires the Texture setting to be enabled (toggle ON). |
| `shouldTexture` | boolean | - | `true` | Enable texture generation for a fully colored model. Disable to create a plain, untextured mesh. |
| `textureResolution` | string | - | `2k` | Base color texture resolution: 2K (2048), 4K (4096), or 8K (8192). Requires Texture to be enabled. At 8K, PBR maps are generated at 4K and no emission map is produced. 8K is only supported with triangle topology when remeshing. |
| `topology` | string | - | `triangle` | Choose the mesh structure type used for the generated model (e.g., triangles or quads). |
| `enablePbr` | boolean | - | `true` | Generate advanced PBR maps (metallic, roughness, normal) for more realistic materials. Meshy 7 does not produce an emission map. Requires the Texture setting to be enabled (toggle ON). |
| `poseMode` | string | - | `` | Specify the pose mode for the generated model. Accepts 'A-Pose', 'T-Pose', or empty string (default). |
| `shouldRemesh` | boolean | - | `false` | Enable remeshing to improve mesh quality and control polycount. Disable to keep the raw, unprocessed mesh (recommended for highest quality on Meshy 7). |
| `targetPolycount` | number | - | `30000` | Specify the target number of polygons in the generated model. The actual number of polygons may deviate from the target depending on the complexity of the geometry. Only applies when Remesh is enabled. |

### Example Requests

**cURL**

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

response = client.generate.run_model(
    model_id="model_meshy-7-img23d",
    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,
  "texturePrompt": "",
  "shouldTexture": true,
  "textureResolution": "2k",
  "topology": "triangle",
  "enablePbr": true,
  "poseMode": "",
  "shouldRemesh": false,
  "targetPolycount": 30000
};

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