# Meshy V7 Text to 3D API

> تحويل النص إلى ثلاثي الأبعاد مع Meshy 7: وضع المعاينة أو الخامات، وهندسة 2k، وخيارات PBR والتحريك والرسوم المتحركة

ينشئ نموذجًا ثلاثي الأبعاد من `prompt` تصل إلى 600 حرف، مع `enable_prompt_expansion` اختياريًا. تعيد `mode` إما هندسة بلا خامات أو نموذجًا مزوّدًا بالخامات. اختر standard أو lowpoly أو smart-topology عبر `model_type`، واضبط `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/ar/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 | وصف للكائن المراد تمثيله كنموذج ثلاثي الأبعاد، محدود بـ600 حرف. |
| `mode` |  | enum (string) | no | `full` | `preview`, `full` | وضع التوليد: ينتج 'preview' هندسة بلا خامات، بينما ينتج 'full' نموذجًا مزودًا بالخامات عبر الجمع بين المعاينة والتحسين. |
| `seed` |  | integer \| null | no |  |  | أعد استخدام هذه البذرة مع موجّه لم يتغير لإعادة إنتاج نتيجة سابقة عادةً. |
| `model_type` |  | enum (string) | no | `standard` | `standard`, `lowpoly`, `smart-topology` | وضع الشبكة الثلاثية الأبعاد: اختر 'lowpoly' لنتيجة منخفضة المضلعات محسّنة لمضلعات أنظف؛ في هذا الوضع يتجاهل Meshy كلًا من topology وtarget_polycount وshould_remesh. للحصول على نتيجة تقليدية عالية التفاصيل اختر 'standard'، أو اختر 'smart-topology' لاستخدام Meshy-T2 أثناء خطوة الهندسة (المعاينة) والحصول على أجزاء نظيفة تُولَّد منفصلة منذ البداية. |
| `topology` |  | enum (string) | no | `triangle` | `quad`, `triangle` | اختيار طوبولوجيا النموذج بين Triangle للتفاصيل الهندسية وQuad لنعومة السطح. |
| `target_polycount` |  | integer | no | `30000` | 100 – 300,000 | العدد المستهدف للمضلعات، ويُحد بـ15,000 عندما تكون model_type تساوي 'smart-topology'. يؤدي حذف الهدف في ذلك الوضع إلى اختيار القيمة الافتراضية الأقل في 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` |  | مفتاح توليد وضعية T، يُفعّل بالقيمة true؛ وهو مهجور لصالح pose_mode. |
| `pose_mode` |  | enum (string) | no | `` | `a-pose`, `t-pose`, `` | اترك السلسلة فارغة لتجنب تحديد وضعية النموذج المُولَّد، أو اطلب وضعية A باستخدام 'a-pose' أو وضعية T باستخدام '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'. |
| `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، مع إدراج الحركات المتاحة في 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='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 | نتيجة الحركة التي تحتوي على النموذج الثلاثي الأبعاد بصيغة GLB؛ يحذف الرد هذه النتيجة ما لم تكن enable_animation تساوي true. |
| `animation_fbx` | object {url, content_type, file_name, file_size} \| null | نتيجة الحركة التي تحتوي على النموذج الثلاثي الأبعاد بصيغة FBX؛ يحذف الرد هذه النتيجة ما لم تكن enable_animation تساوي true. |
| `model_glb` | object {url, content_type, file_name, file_size} | ملف GLB يحتوي على الكائن ثلاثي الأبعاد المُولَّد. |
| `thumbnail` | object {url, content_type, file_name, file_size} \| null | صورة مصغرة تعرض معاينة للنموذج المُولَّد. |
| `model_urls` | object {glb, fbx, obj, usdz, blend, stl} | روابط إلى النموذج ثلاثي الأبعاد بتنسيقات مختلفة. |
| `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