# Meshy v7 Image-to 3D — Atlas Cloud API

> Meshy v7 Image-to-3D reconstructs a textured 3D model from a single image in one request. Outputs GLB/OBJ/FBX/STL/USDZ/3MF with optional PBR maps up to 8K, a settable polygon budget, and optional four-angle preview renders.

This is the machine-readable API reference for **Meshy v7 Image-to 3D** on Atlas Cloud,
a unified API platform for 400+ AI models across text, image, video, audio and 3D.

- **Model ID**: `meshy-v7/image-to-3d`
- **Built by**: MESHY
- **Modality**: Image
- **Model page**: https://www.atlascloud.ai/models/meshy-v7/image-to-3d
- **API key**: https://www.atlascloud.ai/console/api-keys
- **Docs**: https://www.atlascloud.ai/docs

## Pricing on Atlas Cloud

- $0.02 per image
- Pay-as-you-go. No minimum spend, no subscription required.

> **These are the authoritative Atlas Cloud rates for this model.** Any price that
> appears in the vendor description further down refers to a different platform or
> a different model variant and does not apply here.

## Use this model from an AI agent

Atlas Cloud ships three first-party integration surfaces. All three authenticate
with the same API key via the `ATLASCLOUD_API_KEY` environment variable.

### MCP server

The official MCP server (`atlascloud-mcp`) exposes this model to any
MCP-compatible host — Claude Code, OpenAI Codex, Cursor, Gemini CLI, Goose,
Claude Desktop. One-line install:

```bash
# Claude Code
claude mcp add atlascloud -- npx -y atlascloud-mcp

# OpenAI Codex CLI
codex mcp add atlascloud -- npx -y atlascloud-mcp

# Gemini CLI
gemini mcp add atlascloud -- npx -y atlascloud-mcp

export ATLASCLOUD_API_KEY="your-api-key"
```

Then ask in plain English; the agent calls `atlas_generate_image` with `model: "meshy-v7/image-to-3d"`.
The server fetches each model's schema and validates parameters before submitting,
so invalid requests fail fast without spending credits.

MCP docs: https://www.atlascloud.ai/docs/mcp-server

### Agent Skills

`atlas-cloud-skills` is a portable skill package (API reference, code templates in
Python / Node.js / cURL, model IDs with pricing) for Claude Code, Cursor, Codex and
12+ other agents:

```bash
npx skills add AtlasCloudAI/atlas-cloud-skills
export ATLASCLOUD_API_KEY="your-api-key"
```

Skills docs: https://www.atlascloud.ai/docs/skills

### CLI

The `atlas` binary runs Atlas Cloud from a terminal or CI script. Async media jobs
are polled and downloaded automatically (use `--no-download` when a script only
needs the output URLs):

```bash
# Install (Homebrew, npm, or shell installer)
brew install AtlasCloudAI/tap/atlascloud
# npm install -g atlascloud-cli
# curl -fsSL https://raw.githubusercontent.com/AtlasCloudAI/cli/main/install.sh | sh

atlas auth login
atlas generate image meshy-v7/image-to-3d -p "Your prompt here"
```

CLI docs: https://www.atlascloud.ai/docs/cli

## HTTP API reference

- **Submit endpoint (POST)**: `https://api.atlascloud.ai/api/v1/model/generateImage` — start an async generation; returns a `prediction_id`
- **Poll endpoint (GET)**: `https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}` — poll this until the prediction finishes
- **Model ID**: `meshy-v7/image-to-3d`


## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
See the input and output schema below, as well as the usage examples.


### Input Schema

The API accepts the following input parameters:

- **`model`** (`string`, _required_):
  Model name.
  - Default: `"meshy-v7/image-to-3d"`
  - Options: "meshy-v7/image-to-3d"

- **`image`** (`string`, _required_):
  The source image, as a public URL, base64 data URI, or asset reference (asset://<ASSET_ID>). Formats: jpg/jpeg/png. A single, well-lit object on a clean background reconstructs best.

- **`ultra_mode`** (`boolean`, _optional_):
  Higher-fidelity geometry with finer surface detail. Takes longer and costs 5 extra credits.
  - Default: `false`

- **`should_texture`** (`boolean`, _optional_):
  Generate textures. Turn it off for an untextured mesh — faster and cheaper.
  - Default: `true`

- **`enable_pbr`** (`boolean`, _optional_):
  Also generate PBR maps (metallic, roughness, normal) alongside the base colour. Requires `should_texture`.
  - Default: `false`

- **`texture_resolution`** (`string`, _optional_):
  Base colour texture resolution: 2k (2048²), 4k (4096²) or 8k (8192²). 8k costs 5 extra credits.
  - Default: `"2k"`
  - Options: "2k", "4k", "8k"

- **`texture_prompt`** (`string`, _optional_):
  Extra prompt describing the surface material. Up to 800 characters. Takes priority over `texture_image` when both are given.

- **`texture_image`** (`string`, _optional_):
  Reference image guiding the texture, as a public URL, base64 data URI, or asset reference (asset://<ASSET_ID>). Formats: jpg/jpeg/png. Works best when its geometry is close to the source image's.

- **`image_enhancement`** (`boolean`, _optional_):
  Pre-process the source image for a better reconstruction. Turn it off to preserve the input's exact appearance with no style processing.
  - Default: `true`

- **`should_remesh`** (`boolean`, _optional_):
  Run the remesh phase. Leave off for the highest-quality mesh; turn it on when you need a specific polygon budget via `target_polycount` or `decimation_mode`.
  - Default: `false`

- **`topology`** (`string`, _optional_):
  Topology of the remeshed output. `quad` produces a quad-dominant mesh, `triangle` a decimated triangle mesh. Requires `should_remesh`.
  - Default: `"triangle"`
  - Options: "triangle", "quad"

- **`target_polycount`** (`integer`, _optional_):
  Target face count for the remesh phase: 100-300000, default 30000. Requires `should_remesh`, and is ignored when `decimation_mode` is set.
  - Default: `30000`
  - Min: 100
  - Max: 300000

- **`decimation_mode`** (`integer`, _optional_):
  Adaptive decimation level, used instead of an exact `target_polycount`. 1 = ultra, 2 = high, 3 = medium, 4 = low polycount. Requires `should_remesh`, and takes priority over `target_polycount`.
  - Options: 1, 2, 3, 4

- **`save_pre_remeshed_model`** (`boolean`, _optional_):
  Also return the GLB as it was before the remesh phase, so you can compare the two. Requires `should_remesh`.
  - Default: `false`

- **`pose_mode`** (`string`, _optional_):
  Force a rest pose for character meshes. Empty applies no specific pose.
  - Default: `""`
  - Options: "", "a-pose", "t-pose"

- **`target_formats`** (`array[string]`, _optional_):
  Which 3D file formats to return. Defaults to GLB alone; ask for more only when you need them, since each extra format adds generation and transfer time.
  - Default: `["glb"]`
  - Min items: 1
  - Max items: 6

- **`auto_size`** (`boolean`, _optional_):
  Estimate the object's real-world height with AI vision and scale the model accordingly.
  - Default: `false`

- **`origin_at`** (`string`, _optional_):
  Where the model origin sits when `auto_size` is on.
  - Default: `"bottom"`
  - Options: "bottom", "center"

- **`alpha_thumbnail`** (`boolean`, _optional_):
  Also render a transparent-background (RGBA) preview image alongside the normal thumbnail.
  - Default: `false`

- **`multi_view_thumbnails`** (`boolean`, _optional_):
  Also render right / back / left preview images so the model can be reviewed from four angles without downloading the mesh. Adds roughly 3 seconds.
  - Default: `false`

- **`moderation`** (`boolean`, _optional_):
  Screen the input image, texture image and texture prompt for harmful content before generating. A flagged request does not proceed to generation.
  - Default: `false`



**Required Parameters Example**:

```json
{
  "model": "meshy-v7/image-to-3d",
  "image": ""
}
```


**Full Example**:

```json
{
  "model": "meshy-v7/image-to-3d",
  "image": "",
  "ultra_mode": false,
  "should_texture": true,
  "enable_pbr": false,
  "texture_resolution": "2k",
  "texture_prompt": "",
  "texture_image": "",
  "image_enhancement": true,
  "should_remesh": false,
  "topology": "triangle",
  "target_polycount": 30000,
  "decimation_mode": 0,
  "save_pre_remeshed_model": false,
  "pose_mode": "",
  "target_formats": [
    "glb"
  ],
  "auto_size": false,
  "origin_at": "bottom",
  "alpha_thumbnail": false,
  "multi_view_thumbnails": false,
  "moderation": false
}
```


### Output Schema

The API returns the following output format:


- **`code`** (`integer`, _optional_):

- **`message`** (`string`, _optional_):

- **`data`** (`string`, _optional_):



**Example Response**:

```json
{
  "code": 0,
  "message": "",
  "data": null
}
```


## Usage Examples

### cURL

```bash
# Step 1: Start generation (async)
curl -X POST "https://api.atlascloud.ai/api/v1/model/generateImage" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "meshy-v7/image-to-3d",
  "image": "",
  "ultra_mode": false,
  "should_texture": true,
  "enable_pbr": false,
  "texture_resolution": "2k",
  "texture_prompt": "",
  "texture_image": "",
  "image_enhancement": true,
  "should_remesh": false,
  "topology": "triangle",
  "target_polycount": 30000,
  "decimation_mode": 0,
  "save_pre_remeshed_model": false,
  "pose_mode": "",
  "target_formats": [
    "glb"
  ],
  "auto_size": false,
  "origin_at": "bottom",
  "alpha_thumbnail": false,
  "multi_view_thumbnails": false,
  "moderation": false
}'

# Response will contain: {"code": 200, "data": {"id": "prediction_id", "status": "processing"}}

# Step 2: Poll for result (replace {prediction_id} with the id returned above)
curl -X GET "https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

# Keep polling until status is "completed", "succeeded" or "failed"
# When completed, outputs will contain the generated content URL(s)
```

## Additional Resources

### Documentation

- [Model Playground](https://www.atlascloud.ai/models/meshy-v7/image-to-3d)

## About this model

_Vendor-supplied description. Any pricing or endpoint mentioned below refers to_
_other platforms — use the Atlas Cloud values above._

### Meshy 7 Image-to-3D

**Meshy 7 Image-to-3D** reconstructs a textured 3D model from a single photograph or render. One request in, a mesh with PBR textures out — no preview stage, no second call.

#### Why Choose This?

- **One call, one model** — geometry and textures are generated in the same task.
- **Faithful to your image** — turn `image_enhancement` off to keep the input's exact look instead of a stylised interpretation.
- **Polygon budgets you control** — an exact face count, an adaptive decimation level, or the raw high-detail mesh.
- **PBR textures up to 8K** — base colour plus metallic, roughness and normal maps.
- **Review before you download** — optional four-angle preview renders and a transparent-background thumbnail.

#### Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `model` | Yes | `meshy-v7/image-to-3d` |
| `image` | Yes | Source image: public URL, base64 data URI, or `asset://<ASSET_ID>`. jpg/jpeg/png. |
| `ultra_mode` | No | Finer surface detail. Slower, +5 credits. Default: `false` |
| `should_texture` | No | Generate textures. Default: `true`; `false` returns a bare mesh for less. |
| `enable_pbr` | No | Also produce metallic / roughness / normal maps. Default: `false` |
| `texture_resolution` | No | `2k` (default), `4k`, or `8k`. |
| `texture_prompt` | No | Describe the surface material, up to 800 characters. |
| `texture_image` | No | A separate reference image for the texture (URL, data URI, or `asset://<ID>`). |
| `image_enhancement` | No | Pre-process the input for a better reconstruction. Default: `true` |
| `should_remesh` | No | Run the remesh phase. Default: `false` — leave it off for the best mesh. |
| `topology` | No | `triangle` (default) or `quad`. Requires `should_remesh`. |
| `target_polycount` | No | Face count, 100–300000. Default: `30000`. Requires `should_remesh`. |
| `decimation_mode` | No | Adaptive polycount level `1`–`4` (ultra → low). Requires `should_remesh`; overrides `target_polycount`. |

_(Description truncated. Full text on the model page.)_

---

Atlas Cloud — one API for 400+ AI models. Model page: https://www.atlascloud.ai/models/meshy-v7/image-to-3d · Docs: https://www.atlascloud.ai/docs