# Meshy V7 Text to 3D API

> Meshy 7 文字轉 3D：預覽或完整模式、2k 幾何，以及 PBR、綁定骨架和動畫選項

從最長 600 個字元的 `prompt` 產生 3D 模型，並可選用 `enable_prompt_expansion`。`mode` 回傳無貼圖幾何或有貼圖模型。透過 `model_type` 選擇 standard、lowpoly 或 smart-topology，將 `target_polycount` 設為 100 至 300000，並選擇 standard 或 2k 的 `geometry_resolution`。人形角色可加入綁定骨架和動畫預設。

- Model id: `meshy/v7/text-to-3d`
- Made by: Meshy
- Category: Text to 3D
- Output: 3d
- Price per run: from $0.80 / run (cheapest run $0.80 (800 API credits))
- Run: `POST https://api.doitong.ru/v1/run/meshy/v7/text-to-3d`
- Quote: `POST https://api.doitong.ru/v1/quote/meshy/v7/text-to-3d`
- Docs page: https://doitong.com/zh-TW/developers/models/meshy/v7/text-to-3d

## Pricing

Price: **from $0.80 / run** (the lowest tier; the quote prices your exact input). Price per run: the input files are measured before the run (length, resolution, frame rate). The quote measures the same files and is exactly what the run charges.

The full example input below costs $1.20 = 1200 API credits (1 run × $1.20).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.ru/v1/quote/meshy/v7/text-to-3d` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `prompt` |  | string | yes |  | ≤ 600 characters | 要表示為 3D 模型的物件描述，限制為 600 個字元。 |
| `mode` |  | enum (string) | no | `full` | `preview`, `full` | 生成模式：'preview' 輸出沒有紋理的幾何體，而 'full' 會結合 preview 和 refine 輸出有紋理的模型。 |
| `seed` |  | integer \| null | no |  |  | 將此種子與未變更的提示詞一起重複使用，通常可重現先前的結果。 |
| `model_type` |  | enum (string) | no | `standard` | `standard`, `lowpoly`, `smart-topology` | 3D 網格模式：選擇 'lowpoly' 以取得針對更乾淨多邊形最佳化的低多邊形結果；在此模式中 Meshy 會忽略 topology、target_polycount 和 should_remesh。若要取得傳統的高細節結果，請選擇 'standard'；或選擇 'smart-topology'，在幾何體（preview）步驟使用 Meshy-T2，並從一開始分別生成乾淨部件。 |
| `topology` |  | enum (string) | no | `triangle` | `quad`, `triangle` | 模型拓撲選項：Triangle 提供幾何細節，Quad 提供表面平滑度。 |
| `target_polycount` |  | integer | no | `30000` | 100 – 300,000 | 多邊形數量目標；當 model_type 為 'smart-topology' 時上限為 15,000。在該模式中省略目標值會選取 Meshy 較低的預設值 4,000。 |
| `should_remesh` |  | boolean | no | `true` |  | 將此值設為 false 可略過重新網格化並取得原始三角網格；否則啟用重新網格化階段。 |
| `symmetry_mode` |  | enum (string) | no | `auto` | `off`, `auto`, `on` | 生成模型時套用的對稱設定。 |
| `enable_pbr` |  | boolean | no | `false` |  | 控制是否在基礎色旁生成金屬、粗糙度和法線 PBR 貼圖。 |
| `is_a_t_pose` |  | boolean | no | `false` |  | 由 true 啟用的 T-pose 生成開關；已棄用，請改用 pose_mode。 |
| `pose_mode` |  | enum (string) | no | `` | `a-pose`, `t-pose`, `` | 將字串留空以不指定生成模型的姿勢，或使用 'a-pose' 要求 A-pose，使用 't-pose' 要求 T-pose。 |
| `enable_prompt_expansion` |  | boolean | no | `false` |  | 允許大型語言模型以詳細資訊豐富提示詞。啟用此擴展不會改變提示詞的含義。 |
| `texture_prompt` |  | string \| null | no |  | ≤ 600 characters | 在 'full' 模式中使用額外文字提示詞引導紋理；其他模式不使用此項。 |
| `texture_image_url` |  | string (image URL) \| null | no |  |  | 用於紋理生成的 2D 參考圖像，僅套用於 'full' 模式。 |
| `enable_rigging` |  | boolean | no | `false` |  | 自動人形骨架套用，最適合四肢清楚可辨的人形模型。啟用後會為生成模型套用骨架，並提供走路和跑步的基本動畫。 |
| `rigging_height_meters` |  | number | no | `1.7` | > 0 | 當 enable_rigging 為 true 時，提供以公尺為單位的預估角色高度；否則此值不會產生作用。 |
| `enable_animation` |  | boolean | no | `false` |  | 是否為已套用骨架的模型加入預設動畫；需要 enable_rigging 為 true。 |
| `animation_action_id` |  | integer | no | `92` |  | Meshy 程式庫動畫預設值 ID，可用動作列於 https://docs.meshy.ai/en/api/animation-library。僅在 enable_animation 為 true 時驗證並使用：超出 [0, 696] 的值會以 422 拒絕，且 "Idle" 對應 `0`。 |
| `enable_safety_checker` |  | boolean | no | `true` |  | 前處理安全檢查開關：true 會將輸入安全檢查設為處理的必要條件。 |
| `geometry_resolution` |  | enum (string) \| null | no |  | `standard`, `2k` | 網格幾何體解析度；支援的 Meshy-7 選項為 standard 和 2k。 |
| `ultra_mode` |  | boolean | no | `false` |  | 已棄用的選項，由 geometry_resolution 取代；若兩者皆提供，geometry_resolution 優先。請改用 geometry_resolution='2k'。 |

File parameters (`texture_image_url`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
}
```

A fuller example:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.ru/v1/run/meshy/v7/text-to-3d?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.ru/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.ru/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/meshy/v7/text-to-3d?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.ru/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/meshy/v7/text-to-3d", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.ru/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "meshy/v7/text-to-3d",
      "input": {
        "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "meshy/v7/text-to-3d",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 1200,
    "usd": "1.20",
    "charged": 1200,
    "refunded": 0
  },
  "input": {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  },
  "output": {
    "animation_glb": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "animation_fbx": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "model_glb": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "thumbnail": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "model_urls": {
      "glb": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      },
      "fbx": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      },
      "obj": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      },
      "usdz": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      },
      "blend": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      },
      "stl": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      }
    },
    "texture_urls": [
      {
        "base_color": {
          "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
          "content_type": "image/jpeg",
          "file_name": "0-output.jpeg",
          "file_size": 1843200
        },
        "metallic": {
          "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
          "content_type": "image/jpeg",
          "file_name": "0-output.jpeg",
          "file_size": 1843200
        },
        "normal": {
          "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
          "content_type": "image/jpeg",
          "file_name": "0-output.jpeg",
          "file_size": 1843200
        },
        "roughness": {
          "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
          "content_type": "image/jpeg",
          "file_name": "0-output.jpeg",
          "file_size": 1843200
        }
      }
    ],
    "seed": 42,
    "prompt": "A rustic, antique wooden treasure chest with a curved, domed lid, constructed from weathered, dark brown planks exhibiting prominent wood grain and subtle distress. It's heavily reinforced with broad, dark grey, oxidized metal bands secured by numerous circular rivets. Ornate, dark iron decorative elements featuring swirling foliate patterns and dragon motifs adorn the corners and lid. A prominent, circular, intricately carved metal lock plate with a central keyhole dominates the front, flanked by two large, dark metallic pull rings.",
    "actual_prompt": "string",
    "rigged_character_glb": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "rigged_character_fbx": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "basic_animations": {
      "walking_glb": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      },
      "walking_fbx": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      },
      "walking_armature_glb": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      },
      "running_glb": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      },
      "running_fbx": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      },
      "running_armature_glb": {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      }
    },
    "rig_task_id": "string"
  },
  "outputs": [
    {
      "type": "file",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_size": 1843200,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `animation_glb` | object {url, content_type, file_name, file_size} \| null | 包含 GLB 3D 模型的動畫結果；除非 enable_animation 為 true，否則回應會省略此結果。 |
| `animation_fbx` | object {url, content_type, file_name, file_size} \| null | 包含 FBX 3D 模型的動畫結果；除非 enable_animation 為 true，否則回應會省略此結果。 |
| `model_glb` | object {url, content_type, file_name, file_size} | 包含生成 3D 物件的 GLB 檔案。 |
| `thumbnail` | object {url, content_type, file_name, file_size} \| null | 顯示生成模型預覽的縮圖。 |
| `model_urls` | object {glb, fbx, obj, usdz, blend, stl} | 各種格式的 3D 模型連結。 |
| `texture_urls` | array of object {base_color, metallic, normal, roughness} | 以物件陣列表示的紋理檔案。 |
| `seed` | integer \| null | 生成期間使用的種子值。 |
| `prompt` | string | 提供給生成使用的文字提示詞。 |
| `actual_prompt` | string \| null | 啟用提示詞擴充時實際套用於生成的提示詞。 |
| `rigged_character_glb` | object {url, content_type, file_name, file_size} \| null | 以 GLB 角色檔案提供的骨架套用結果；除非 enable_rigging 為 true，否則不會出現在回應中。 |
| `rigged_character_fbx` | object {url, content_type, file_name, file_size} \| null | 以 FBX 角色檔案提供的骨架套用結果；除非 enable_rigging 為 true，否則不會出現在回應中。 |
| `basic_animations` | object {walking_glb, walking_fbx, walking_armature_glb, running_glb, running_fbx, running_armature_glb} \| null | 基本走路和跑步動畫，僅在 enable_rigging 為 true 時包含。 |
| `rig_task_id` | string \| null | 骨架套用工作的識別碼；僅在 enable_rigging 為 true 時包含。 |

## Related models

- [Meshy V7 Image to 3D](https://doitong.com/developers/models/meshy/v7/image-to-3d.md) (`meshy/v7/image-to-3d`): from $0.80 / run
- [Meshy V7 Multi Image to 3D](https://doitong.com/developers/models/meshy/v7/multi-image-to-3d.md) (`meshy/v7/multi-image-to-3d`): from $0.80 / run
- [Meshy 7 Retexture](https://doitong.com/developers/models/meshy/v7/retexture.md) (`meshy/v7/retexture`): from $0.30 / request
- [Meshy 6 Preview · Text to 3D](https://doitong.com/developers/models/meshy/v6-preview/text-to-3d.md) (`meshy/v6-preview/text-to-3d`): $0.80 / request
- [Meshy 6 · Text to 3D](https://doitong.com/developers/models/meshy/v6/text-to-3d.md) (`meshy/v6/text-to-3d`): $0.80 / request
- [Meshy 7.1 Text to 3D](https://doitong.com/developers/models/meshy/v7.1/text-to-3d.md) (`meshy/v7.1/text-to-3d`): from $0.80 / run
- [Hunyuan 3d](https://doitong.com/developers/models/hunyuan-3d/v3.1/rapid/text-to-3d.md) (`hunyuan-3d/v3.1/rapid/text-to-3d`): from $0.225 / request
- [Hunyuan 3D Pro Text to 3D](https://doitong.com/developers/models/hunyuan-3d/v3.1/pro/text-to-3d.md) (`hunyuan-3d/v3.1/pro/text-to-3d`): $0.375 / run

## Links

- HTML page: https://doitong.com/developers/models/meshy/v7/text-to-3d
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=meshy/v7/text-to-3d
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.ru/v1/models/meshy/v7/text-to-3d