# meshy/v7.1/text-to-3d

> Meshy 7.1 Text-to-3D turns a text description into a textured 3D model. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

## Overview

- **Endpoint**: `https://api.wavespeed.ai/api/v3/meshy/v7.1/text-to-3d`
- **Polling/result URL**: `https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result`
- **Model ID**: `meshy/v7.1/text-to-3d`
- **Category**: text-to-3d

## Pricing

Price per request, by model type (`model_type`), mode (`mode`) and texture resolution (`texture_resolution`):

| Generation option | Geometry only (`mode=preview`) | Textured, 2k (`mode=full`, `texture_resolution=2k`) | Textured, 4k (`mode=full`, `texture_resolution=4k`) | Textured, 8k (`mode=full`, `texture_resolution=8k`) |
|-------------------|------:|------:|------:|------:|
| Standard (`model_type=standard`) | $0.80 | $1.20 | $1.20 | $1.40 |
| Smart Topology (`model_type=smart-topology`) | $0.20 | $0.60 | $0.60 | $0.80 |

A request with default settings costs $1.20 per run.

Optional additions, shown as the extra charge of turning the option on compared with leaving it off:

| Optional addition | Extra charge |
|-------------------|-------------:|
| Ultra geometry in standard mode: `geometry_resolution=2k` or `4k` compared with `geometry_resolution=standard` | $0.20 |
| Rigging: `enable_rigging=true` compared with `enable_rigging=false` | $0.20 |
| Animation (includes rigging): `enable_animation=true` compared with `enable_animation=false` | $0.32 |
| Animation on top of rigging: `enable_animation=true` with `enable_rigging=true` compared with `enable_rigging=true` alone | $0.12 |

Enabling animation also includes rigging. Enabling both rigging and animation does not charge for rigging twice.

The total is the generation price plus the selected additions. Texture resolution does not add a charge when generating geometry only.

---

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
The API is asynchronous: submit a prediction, then poll its result URL until it completes.

### Input Schema

The API accepts the following input parameters:

- **`prompt`** (`string`, _required_):
  Description of the 3D object. Up to 600 characters.

- **`mode`** (`string`, _optional_):
  preview returns an untextured mesh; full also textures it.
  - Default: `"full"`
  - Options: "preview", "full"

- **`negative_prompt`** (`string`, _optional_):
  What the model should avoid.

- **`seed`** (`integer`, _optional_):
  Seed; the same seed and prompt give the same result.

- **`model_type`** (`string`, _optional_):
  smart-topology builds a clean low-poly mesh (Meshy T2.5); cheaper, no quad topology.
  - Default: `"standard"`
  - Options: "standard", "smart-topology"

- **`geometry_resolution`** (`string`, _optional_):
  Geometry detail: standard or Ultra (2k / 4k).
  - Default: `"standard"`
  - Options: "standard", "2k", "4k"

- **`texture_prompt`** (`string`, _optional_):
  Optional description of the texture.

- **`texture_image`** (`string`, _optional_):
  Optional reference image for the texture. Takes priority over texture_prompt.

- **`enable_pbr`** (`boolean`, _optional_):
  Generate PBR maps (metallic, roughness, normal).
  - Default: `false`

- **`texture_resolution`** (`string`, _optional_):
  Texture resolution: 2k, 4k or 8k (8k costs more).
  - Default: `"2k"`
  - Options: "2k", "4k", "8k"

- **`topology`** (`string`, _optional_):
  Mesh topology.
  - Default: `"triangle"`
  - Options: "triangle", "quad"

- **`target_polycount`** (`integer`, _optional_):
  Target number of polygons (used when should_remesh is on).
  - Default: `30000`
  - Range: `100` to `300000`

- **`should_remesh`** (`boolean`, _optional_):
  Remesh to the target polycount and topology.
  - Default: `true`

- **`symmetry_mode`** (`string`, _optional_):
  No longer has an effect; kept for compatibility.
  - Default: `"auto"`
  - Options: "off", "auto", "on"

- **`pose_mode`** (`string`, _optional_):
  Generate characters in an A-pose or T-pose (useful before rigging).
  - Options: "a-pose", "t-pose"

- **`remove_lighting`** (`boolean`, _optional_):
  Remove baked-in lighting from the textures.

- **`auto_size`** (`boolean`, _optional_):
  Estimate the real-world size of the object and scale the model to it.
  - Default: `false`

- **`enable_rigging`** (`boolean`, _optional_):
  Rig the generated character (humanoids). The rigged model is returned after the model.
  - Default: `false`

- **`rigging_height_meters`** (`number`, _optional_):
  Character height in meters used for rigging.
  - Default: `1.7`

- **`enable_animation`** (`boolean`, _optional_):
  Rig and animate the character with animation_action_id. The animated model is returned last.
  - Default: `false`

- **`animation_action_id`** (`integer`, _optional_):
  Animation from the Meshy animation library (https://docs.meshy.ai/en/api/animation-library) applied when enable_animation is on.
  - Default: `92`



**Required Parameters Example**:

```json
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed"
}
```

**Full Example**:

```json
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "mode": "full",
  "negative_prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "seed": 0,
  "model_type": "standard",
  "geometry_resolution": "standard",
  "texture_prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "texture_image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "enable_pbr": false,
  "texture_resolution": "2k",
  "topology": "triangle",
  "target_polycount": 30000,
  "should_remesh": true,
  "symmetry_mode": "auto",
  "pose_mode": "a-pose",
  "remove_lighting": false,
  "auto_size": false,
  "enable_rigging": false,
  "rigging_height_meters": 1.7,
  "enable_animation": false,
  "animation_action_id": 92
}
```

### Result Data Schema

The `data` object returned by the API has the following fields:

- **`created_at`** (`string (date-time)`, _optional_):
  ISO timestamp of when the request was created (e.g., "2023-04-01T12:34:56.789Z").

- **`id`** (`string`, _optional_):
  Unique identifier for the prediction, the ID of the prediction to get.

- **`model`** (`string`, _optional_):
  Model ID used for the prediction.

- **`outputs`** (`array of string | object`, _optional_):
  Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.

- **`status`** (`string`, _optional_):
  Status of the task: created, processing, completed, or failed.

- **`urls`** (`object`, _optional_):
  Object containing related API endpoints.



**Example `data` Object**:

```json
{
  "created_at": "example",
  "id": "example",
  "model": "example",
  "outputs": [],
  "status": "example",
  "urls": {}
}
```

## Usage Examples

The examples use `jq` to read JSON. Set your API key first:

```bash
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
```

### 1. Submit a prediction

```bash
REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed"
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.wavespeed.ai/api/v3/meshy/v7.1/text-to-3d \
  --header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "${REQUEST_BODY}")

printf '%s\n' "${SUBMIT_RESPONSE}" | jq .
```

The response contains the prediction ID in `data.id`.

### 2. Poll until complete and read `outputs`

```bash
PREDICTION_ID=$(printf '%s' "${SUBMIT_RESPONSE}" | jq -r '.data.id')
if [ -z "${PREDICTION_ID}" ] || [ "${PREDICTION_ID}" = "null" ]; then
  printf 'Submission response did not contain data.id\n' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    --request GET \
    --url "${RESULT_URL}" \
    --header "Authorization: Bearer ${WAVESPEED_API_KEY}")

  RESULT=$(printf '%s' "${RESPONSE}" | jq -e '.data')
  STATUS=$(printf '%s' "${RESULT}" | jq -er '.status')
  case "${STATUS}" in
    completed)
      # Generated files are returned in the outputs array.
      printf '%s\n' "${RESULT}" | jq '.outputs'
      break
      ;;
    failed|cancelled|timeout|deleted)
      printf '%s\n' "${RESULT}" | jq '{status, error, code}'
      exit 1
      ;;
    *)
      sleep 2
      ;;
  esac
done
```

## Additional Resources

### Documentation

- [Model Playground](https://wavespeed.ai/models/meshy/v7.1/text-to-3d)
- [API Documentation](https://wavespeed.ai/docs/docs-api/meshy/meshy-v7.1-text-to-3d)
