# Meshy V7 Text to 3D API

> preview 또는 full 모드, 2k 기하, PBR, 리깅 및 애니메이션 옵션을 제공하는 Meshy 7 텍스트-3D

최대 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.com/v1/run/meshy/v7/text-to-3d`
- Quote: `POST https://api.doitong.com/v1/quote/meshy/v7/text-to-3d`
- Docs page: https://doitong.com/ko/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.com/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 메시 모드입니다. 더 깔끔한 폴리곤에 최적화된 low-poly 결과에는 'lowpoly'를 선택합니다. 이 모드에서 Meshy는 topology, target_polycount, should_remesh를 무시합니다. 일반적인 고해상도 결과에는 'standard'를, geometry (preview) 단계에서 Meshy-T2를 사용해 처음부터 별도로 생성된 깔끔한 부품을 얻으려면 'smart-topology'를 선택합니다. |
| `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` |  | 기본 색상과 함께 metallic, roughness, normal 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 |  |  | 'full' 모드에서만 적용되는 텍스처 생성용 2D 참조 이미지입니다. |
| `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.com/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.com/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.com/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.com/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.com/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.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `animation_glb` | object {url, content_type, file_name, file_size} \| null | 3D 모델이 GLB로 포함된 애니메이션 결과입니다. enable_animation이 true가 아니면 응답에서 생략됩니다. |
| `animation_fbx` | object {url, content_type, file_name, file_size} \| null | 3D 모델이 FBX로 포함된 애니메이션 결과입니다. 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.com/v1/models/meshy/v7/text-to-3d