# Meshy 7.1

> Detailed 3D assets from text, a single image, or up to four views, with geometry controls and optional textures, rigging and animation.

## Overview

- Submit: `https://api.poyo.ai/api/generate/submit`
- Status: `https://api.poyo.ai/api/generate/status/{task_id}`
- Page: https://poyo.ai/models/meshy-7-1
- Model page ID: `meshy-7-1`
- API model IDs: `meshy-7.1-image-to-3d`, `meshy-7.1-text-to-3d`, `meshy-7.1-multi-image-to-3d`
- Category: 3D
- Auth: `Authorization: Bearer $POYO_API_KEY`
- Create a key at https://poyo.ai/dashboard/api-key

This model uses PoYo's unified async API. POST the JSON body below, then poll status with the returned `task_id` or receive a webhook on `callback_url`. Failed tasks are not charged.

## Pricing

- Geometry only: 160 credits ($0.800) per generation
- Geometry + texture (default): 240 credits ($1.20) per generation
- Geometry + rigging: 200 credits ($1.00) per generation
- Geometry + texture + rigging: 280 credits ($1.40) per generation
- Geometry + rigging + animation: 224 credits ($1.12) per generation
- Geometry + texture + rigging + animation: 304 credits ($1.52) per generation
- Geometry only: 160 credits ($0.800) per generation
- Geometry + texture (default): 240 credits ($1.20) per generation
- Geometry + rigging: 200 credits ($1.00) per generation
- Geometry + texture + rigging: 280 credits ($1.40) per generation
- Geometry + rigging + animation: 224 credits ($1.12) per generation
- Geometry + texture + rigging + animation: 304 credits ($1.52) per generation
- Geometry only: 160 credits ($0.800) per generation
- Geometry + texture (default): 240 credits ($1.20) per generation
- Geometry + rigging: 200 credits ($1.00) per generation
- Geometry + texture + rigging: 280 credits ($1.40) per generation
- Plus 2 more pricing rows on the model page.

For more details, see https://poyo.ai/models/meshy-7-1.

## API Information

The request envelope is always `{ model, input, callback_url? }`. Input fields below are nested under `input`.

### Request envelope

- `model` (`ModelEnum`, required):
  Select meshy-7.1-text-to-3d for text, meshy-7.1-image-to-3d for exactly one image, or meshy-7.1-multi-image-to-3d for 1–4 images.
  - Options: `"meshy-7.1-text-to-3d"`, `"meshy-7.1-image-to-3d"`, `"meshy-7.1-multi-image-to-3d"`
- `callback_url` (`string`, optional):
  Optional completion or failure callback URL.

### Input Schema

Unified parameter list. Required fields, supported values, and defaults depend on model as described for each parameter.

The API accepts the following `input` parameters:

- `prompt` (`string`, optional):
  Required only for meshy-7.1-text-to-3d; omit for image models. Use 1–600 characters containing non-whitespace text.
  - Length: 1 to 600 characters
- `image_urls` (`list`, optional):
  Required for image models; omit for meshy-7.1-text-to-3d. meshy-7.1-image-to-3d requires exactly 1 image; meshy-7.1-multi-image-to-3d accepts 1–4 images of the same object from different angles. Each item accepts a public HTTP(S) image URL or image data URI.
  - Array of string
  - Length: 1 to 4
- `mode` (`ModeEnum`, optional):
  Only for meshy-7.1-text-to-3d. preview returns geometry only; full includes textures. Default: full.
  - Options: `"preview"`, `"full"`
- `model_type` (`ModelTypeEnum`, optional):
  Only for meshy-7.1-text-to-3d and meshy-7.1-image-to-3d; omit for meshy-7.1-multi-image-to-3d. Accepts standard (default) or smart-topology. Lowpoly is not supported.
  - Options: `"standard"`, `"smart-topology"`
- `geometry_resolution` (`GeometryResolutionEnum`, optional):
  meshy-7.1-text-to-3d and meshy-7.1-image-to-3d accept standard, 2k, or 4k only when model_type is standard (the default); omit for smart-topology. meshy-7.1-multi-image-to-3d accepts only standard or 2k and does not support 4k.
  - Options: `"standard"`, `"2k"`, `"4k"`
- `topology` (`TopologyEnum`, optional):
  Output mesh topology for all models: triangle (default) or quad.
  - Default: `"triangle"`
  - Options: `"quad"`, `"triangle"`
- `target_polycount` (`integer`, optional):
  Target polygons for all models: 100–300000; default 30000. For meshy-7.1-text-to-3d and meshy-7.1-image-to-3d with model_type=smart-topology: 100–15000, default 4000 when omitted.
  - Range: `100` to `300000`
- `should_remesh` (`boolean`, optional):
  Enable remeshing for all models. Default: true.
  - Default: `true`
- `symmetry_mode` (`SymmetryModeEnum`, optional):
  Mesh symmetry behavior for all models: off, auto (default), or on.
  - Default: `"auto"`
  - Options: `"off"`, `"auto"`, `"on"`
- `should_texture` (`boolean`, optional):
  Only for meshy-7.1-image-to-3d and meshy-7.1-multi-image-to-3d; omit for meshy-7.1-text-to-3d. Generate textures; default true. For multi-image generation, must remain true when enable_pbr=true or texture guidance is supplied.
- `enable_pbr` (`boolean`, optional):
  Generate PBR texture maps for all models. Default: false. For meshy-7.1-multi-image-to-3d, requires should_texture=true.
  - Default: `false`
- `pose_mode` (`PoseModeEnum`, optional):
  Character pose for all models: a-pose, t-pose, or an empty string (default) for no specific pose.
  - Default: `""`
  - Options: `"a-pose"`, `"t-pose"`, `""`
- `seed` (`integer`, optional):
  Only for meshy-7.1-text-to-3d. Integer random seed; omit to select automatically.
- `enable_prompt_expansion` (`boolean`, optional):
  Only for meshy-7.1-text-to-3d. Expand the prompt before generation. Default: false.
  - Default: `false`
- `texture_prompt` (`string`, optional):
  Optional texture guidance for all models, at most 600 characters. For meshy-7.1-multi-image-to-3d, requires should_texture=true.
  - Length: 0 to 600 characters
- `texture_image_url` (`string`, optional):
  Optional texture guidance for all models; accepts a public HTTP(S) image URL or image data URI. For meshy-7.1-multi-image-to-3d, requires should_texture=true.
- `enable_rigging` (`boolean`, optional):
  Rig the generated humanoid character for all models. Default: false. Must be true when enable_animation=true.
  - Default: `false`
- `rigging_height_meters` (`float`, optional):
  Character height in meters for all models when rigging is enabled; must be greater than zero. Default: 1.7.
  - Default: `1.7`
- `enable_animation` (`boolean`, optional):
  Apply an animation for all models; requires enable_rigging=true. Default: false.
  - Default: `false`
- `animation_action_id` (`integer`, optional):
  Animation preset ID for all models: integer from 0 to 696. Default: 92.
  - Default: `92`
  - Range: `0` to `696`
- `enable_safety_checker` (`boolean`, optional):
  Enable input safety checking for all models. Default: true. Disabling requires account authorization when applicable.
  - Default: `true`

Required Parameters Example:

```json
{
  "model": "meshy-7.1-text-to-3d",
  "input": {
    "prompt": "A ceramic robot with a clean silhouette.",
    "enable_rigging": true,
    "enable_animation": true
  }
}
```

Full Example:

```json
{
  "model": "meshy-7.1-text-to-3d",
  "input": {
    "prompt": "A ceramic robot with a clean silhouette.",
    "enable_rigging": true,
    "enable_animation": true,
    "topology": "triangle",
    "should_remesh": true,
    "symmetry_mode": "auto",
    "rigging_height_meters": 1.7,
    "animation_action_id": 92,
    "enable_safety_checker": true
  }
}
```

Text to 3D — Smart Topology Preview:

```json
{
  "model": "meshy-7.1-text-to-3d",
  "input": {
    "prompt": "A ceramic robot.",
    "mode": "preview",
    "model_type": "smart-topology"
  }
}
```

Image to 3D:

```json
{
  "model": "meshy-7.1-image-to-3d",
  "input": {
    "image_urls": [
      "https://example.com/front.png"
    ],
    "enable_rigging": true,
    "enable_animation": true
  }
}
```

### Output Schema

Submit returns a `task_id`. Poll `GET /api/generate/status/{task_id}` until `status` is `finished` or `failed`. Completed media is in `data.files`.

Response fields:

- `code` (`integer`, required):
  - Examples: `200`
- `data` (`object`, required):

Example Response:

```json
{
  "code": 200,
  "data": {
    "task_id": "task_example",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.poyo.ai/models/meshy-7-1/examples/meshy-7-1-default-output-1-25f174f1eda76073.glb",
        "file_type": "3d"
      }
    ]
  }
}
```

## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"meshy-7.1-text-to-3d","input":{"prompt":"A ceramic robot with a clean silhouette.","enable_rigging":true,"enable_animation":true}}'
```

### Python

```python
import json
import os
import time
import requests

API = "https://api.poyo.ai"
headers = {
    "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
    "Content-Type": "application/json",
}
payload = json.loads("{\n  \"model\": \"meshy-7.1-text-to-3d\",\n  \"input\": {\n    \"prompt\": \"A ceramic robot with a clean silhouette.\",\n    \"enable_rigging\": true,\n    \"enable_animation\": true\n  }\n}")

submit = requests.post(f"{API}/api/generate/submit", headers=headers, json=payload)
submit.raise_for_status()
task_id = submit.json()["data"]["task_id"]

while True:
    status = requests.get(f"{API}/api/generate/status/{task_id}", headers=headers)
    status.raise_for_status()
    data = status.json()["data"]
    if data["status"] in ("finished", "failed"):
        print(data)
        break
    time.sleep(2)
```

### JavaScript

```javascript
const headers = {
  Authorization: `Bearer ${process.env.POYO_API_KEY}`,
  "Content-Type": "application/json",
};

const submit = await fetch("https://api.poyo.ai/api/generate/submit", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "meshy-7.1-text-to-3d",
  "input": {
    "prompt": "A ceramic robot with a clean silhouette.",
    "enable_rigging": true,
    "enable_animation": true
  }
}),
});

const submitted = await submit.json();
const taskId = submitted.data.task_id;

while (true) {
  const statusResponse = await fetch(`https://api.poyo.ai/api/generate/status/${taskId}`, { headers });
  const status = await statusResponse.json();
  if (["finished", "failed"].includes(status.data.status)) {
    console.log(status.data);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 2000));
}
```

## Additional Resources

### Documentation

- [Model Playground](https://poyo.ai/models/meshy-7-1)
- [API Documentation](https://docs.poyo.ai/api-manual/3d-series/meshy-7-1-3d)
- [API Documentation (Markdown)](https://docs.poyo.ai/api-manual/3d-series/meshy-7-1-3d.md)
- [Task status](https://docs.poyo.ai/api-manual/task-management/query-task-status)
- [Webhooks](https://docs.poyo.ai/api-manual/task-management/webhooks)

### Other agent-readable surfaces

- [Platform overview](https://poyo.ai/llms.txt)
- [Documentation index](https://docs.poyo.ai/llms.txt)
- [Full documentation text](https://docs.poyo.ai/llms-full.txt)
- Any other model: `https://poyo.ai/models/<model-id>/llms.txt`