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

> Meshy v7 Text-to-3D generates a 3D mesh from a text prompt in two stages: a preview that produces the untextured geometry, and a refine that textures a preview you kept. Outputs GLB/OBJ/FBX/STL/USDZ/3MF with optional PBR maps up to 8K, a settable polygon budget, and A/T-pose output for characters.

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

- **Model ID**: `meshy-v7/text-to-3d`
- **Built by**: MESHY
- **Modality**: Image
- **Model page**: https://www.atlascloud.ai/models/meshy-v7/text-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/text-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/text-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/text-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/text-to-3d"`
  - Options: "meshy-v7/text-to-3d"

- **`mode`** (`string`, _optional_):
  How much of the pipeline to run. `full` generates the mesh and then textures it, returning a finished textured model from one request. `preview` stops after the mesh, for when you want to judge the shape before paying to texture it.
  - Default: `"full"`
  - Options: "full", "preview"

- **`prompt`** (`string`, _required_):
  What the object is. Up to 800 characters. Required when `mode` is `preview`.

- **`ultra_mode`** (`boolean`, _optional_):
  Higher-fidelity geometry with finer surface detail. Takes longer and costs 5 extra credits. Applies to the mesh, so it counts in both modes.
  - Default: `false`

- **`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

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

- **`enable_pbr`** (`boolean`, _optional_):
  Also generate PBR maps (metallic, roughness, normal) alongside the base colour. Applies to the texture stage, so only when `mode` is `full`.
  - Default: `false`

- **`texture_resolution`** (`string`, _optional_):
  Base colour texture resolution: 2k (2048²), 4k (4096²) or 8k (8192²). Applies to the texture stage, so only when `mode` is `full`. 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. Applies to the texture stage, so only when `mode` is `full`. 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. Applies to the texture stage, so only when `mode` is `full`.

- **`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`

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



**Required Parameters Example**:

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


**Full Example**:

```json
{
  "model": "meshy-v7/text-to-3d",
  "mode": "full",
  "prompt": "",
  "ultra_mode": false,
  "should_remesh": false,
  "topology": "triangle",
  "target_polycount": 30000,
  "decimation_mode": 0,
  "pose_mode": "",
  "enable_pbr": false,
  "texture_resolution": "2k",
  "texture_prompt": "",
  "texture_image": "",
  "target_formats": [
    "glb"
  ],
  "auto_size": false,
  "origin_at": "bottom",
  "alpha_thumbnail": 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/text-to-3d",
  "mode": "full",
  "prompt": "",
  "ultra_mode": false,
  "should_remesh": false,
  "topology": "triangle",
  "target_polycount": 30000,
  "decimation_mode": 0,
  "pose_mode": "",
  "enable_pbr": false,
  "texture_resolution": "2k",
  "texture_prompt": "",
  "texture_image": "",
  "target_formats": [
    "glb"
  ],
  "auto_size": false,
  "origin_at": "bottom",
  "alpha_thumbnail": 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/text-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 Text-to-3D

**Meshy 7 Text-to-3D** turns a written description into a production-ready 3D model. One request gives you a finished textured mesh — or, if you set `mode` to `preview`, just the geometry, so you can judge the shape before paying to texture it.

#### Why Choose This?

- **One request, a finished model** — `mode: "full"` generates the mesh and textures it in a single call.
- **Or stop at the shape** — `mode: "preview"` returns the bare mesh for a third of the price, for iterating on silhouettes.
- **Polygon budgets you control** — ask for an exact face count, an adaptive decimation level, or the raw high-detail mesh.
- **Rigging-ready output** — force an A-pose or T-pose so characters land in your animation pipeline without cleanup.
- **Real PBR textures** — base colour plus metallic, roughness and normal maps at up to 8K.
- **Every common format** — GLB, OBJ, FBX, STL, USDZ and 3MF.

#### The Two Modes

| `mode` | What runs | What you get |
| --- | --- | --- |
| `full` (default) | mesh generation, then texturing | A textured model, with PBR maps if you asked for them |
| `preview` | mesh generation only | An untextured mesh |

Both are one request and one poll. In `full` mode the two upstream stages are chained for you — the texture parameters (`enable_pbr`, `texture_resolution`, `texture_prompt`, `texture_image`) are read from the same request and applied to the texture stage, and the geometry parameters (including `ultra_mode`, which only affects geometry) apply to the mesh stage.

`preview` is for iteration, not for staging a later texture pass: there is no way to texture a preview afterwards, so run `full` when you want the finished asset.

#### Parameters

_(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/text-to-3d · Docs: https://www.atlascloud.ai/docs