Meshy

https://docs.meshy.ai
Admin
Meshy is a RESTful API platform that enables developers to programmatically interact with Meshy...
Tokens:233,699
Snippets:2,090
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Create a Figure Build Task

Source: https://docs.meshy.ai/llms-full.txt

Examples for initiating a build task using cURL, JavaScript, and Python.

```bash
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'
```

```javascript
import axios from 'axios'

const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

// Stage 2: chain build off a succeeded prototype task
const payload = {
  input_task_id: "018a210d-8ba4-705c-b111-1f1776f7f578",
};

try {
  const response = await axios.post(
    'https://api.meshy.ai/openapi/creative-lab/figure/v1/build',
    payload,
    { headers }
  );
  console.log(response.data);
} catch (error) {
  console.error(error);
}
```

```python
import requests

headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

// Stage 2: chain build off a succeeded prototype task
payload = {
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
}

response = requests.post(
    "https://api.meshy.ai/openapi/creative-lab/figure/v1/build",
    headers=headers,
    json=payload,
)
response.raise_for_status()
print(response.json())
```

--------------------------------

### Install smee-client for Local Testing

Source: https://docs.meshy.ai/en/api/webhooks

Install the smee-client globally using npm to forward webhooks to your local development environment. This is necessary for testing webhook functionality without deploying to a public server.

```bash
npm install --global smee-client
```

--------------------------------

### Create a Text to Image Task

Source: https://docs.meshy.ai/llms-full.txt

Examples for initiating an image generation task using different programming languages.

```bash
# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'
```

```javascript
import axios from 'axios'

// Generate an image from a text prompt
const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };
const payload = {
  ai_model: "nano-banana",
  prompt: "A majestic dragon soaring through clouds at sunset",
  aspect_ratio: "16:9"
};

try {
  const response = await axios.post(
    'https://api.meshy.ai/openapi/v1/text-to-image',
    payload,
    { headers }
  );
  console.log(response.data);
} catch (error) {
  console.error(error);
}
```

```python
import requests

# Generate an image from a text prompt
payload = {
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
}
headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

response = requests.post(
    "https://api.meshy.ai/openapi/v1/text-to-image",
    headers=headers,
    json=payload,
)
response.raise_for_status()
print(response.json())
```

--------------------------------

### Prompt Structure Example

Source: https://docs.meshy.ai/llms-full.txt

A breakdown of the prompt formula applied to a specific asset.

```text
A medieval knight's helmet          ← Subject
with scratched iron surface         ← Material
in dark fantasy art style           ← Style
low-poly, game-ready asset          ← Technical constraints
```

--------------------------------

### Analyze Printability Response Stream Examples

Source: https://docs.meshy.ai/llms-full.txt

Sample event stream data showing error handling and task progress updates.

```javascript
// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}
```

--------------------------------

### Stream Multi-Color 3D Print Task

Source: https://docs.meshy.ai/llms-full.txt

Examples for consuming the SSE stream using cURL, JavaScript, and Python.

```bash
curl -N https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
```

```javascript
const response = await fetch(
  'https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream',
  {
    headers: { Authorization: `Bearer ${YOUR_API_KEY}` }
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop();

  for (const line of lines) {
    if (line.startsWith('data:')) {
      const data = JSON.parse(line.slice(5));
      console.log(data);

      if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(data.status)) {
        reader.cancel();
      }
    }
  }
}
```

```python
import requests
import json

headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}",
    "Accept": "text/event-stream"
}

response = requests.get(
    'https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream',
    headers=headers,
    stream=True
)

for line in response.iter_lines():
    if line:
        if line.startswith(b'data:'):
            data = json.loads(line.decode('utf-8')[5:])
            print(data)

            if data['status'] in ['SUCCEEDED', 'FAILED', 'CANCELED']:
                break

response.close()
```

--------------------------------

### Retrieve Lamp Task via API

Source: https://docs.meshy.ai/llms-full.txt

Examples for fetching lamp task data using cURL, JavaScript, and Python. Ensure the correct path is used based on whether the task is a prototype or a build.

```bash
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

```javascript
import axios from 'axios'

const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

// Prototype
const prototypeId = '018a210d-8ba4-705c-b111-1f1776f7f578';
const proto = await axios.get(
  `https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/${prototypeId}`,
  { headers }
);
console.log(proto.data);

// Build
const buildId = '019c320e-9a8f-7a1c-9c11-2a1876f8a9bb';
const build = await axios.get(
  `https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/${buildId}`,
  { headers }
);
console.log(build.data);
```

```python
import requests

headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

# Prototype
prototype_id = "018a210d-8ba4-705c-b111-1f1776f7f578"
proto = requests.get(
    f"https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/{prototype_id}",
    headers=headers,
)
proto.raise_for_status()
print(proto.json())

# Build
build_id = "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
build = requests.get(
    f"https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/{build_id}",
    headers=headers,
)
build.raise_for_status()
print(build.json())
```

--------------------------------

### Stream Image to Image Task via SSE

Source: https://docs.meshy.ai/llms-full.txt

Examples for consuming the SSE stream using cURL, JavaScript Fetch API, and Python requests.

```bash
curl -N https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
```

```javascript
const response = await fetch(
  'https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream',
  {
    headers: { Authorization: `Bearer ${YOUR_API_KEY}` }
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop();

  for (const line of lines) {
    if (line.startsWith('data:')) {
      const data = JSON.parse(line.slice(5));
      console.log(data);

      if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(data.status)) {
        reader.cancel();
      }
    }
  }
}
```

```python
import requests
import json

headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}",
    "Accept": "text/event-stream"
}

response = requests.get(
    'https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream',
    headers=headers,
    stream=True
)

for line in response.iter_lines():
    if line:
        if line.startswith(b'data:'):
            data = json.loads(line.decode('utf-8')[5:])
            print(data)

            if data['status'] in ['SUCCEEDED', 'FAILED', 'CANCELED']:
                break

response.close()
```

--------------------------------

### Stream Fridge Magnet Task Updates

Source: https://docs.meshy.ai/llms-full.txt

Examples for connecting to the SSE stream to receive real-time task progress and status updates.

```bash
curl -N https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
```

```javascript
const response = await fetch(
    'https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream',
    {
      headers: { Authorization: `Bearer ${YOUR_API_KEY}` }
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop();

    for (const line of lines) {
      if (line.startsWith('data:')) {
        const data = JSON.parse(line.slice(5));
        console.log(data);

        if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(data.status)) {
          reader.cancel();
        }
      }
    }
  }
```

```python
import requests
  import json

  headers = {
      "Authorization": f"Bearer {YOUR_API_KEY}",
      "Accept": "text/event-stream"
  }

  response = requests.get(
      'https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream',
      headers=headers,
      stream=True
  )

  for line in response.iter_lines():
      if line:
          if line.startswith(b'data:'):
              data = json.loads(line.decode('utf-8')[5:])
              print(data)

              if data['status'] in ['SUCCEEDED', 'FAILED', 'CANCELED']:
                  break

  response.close()
```

--------------------------------

### GET /openapi/v1/print/analyze/:id/stream

Source: https://docs.meshy.ai/llms-full.txt

Streams real-time updates for an analyze-printability task using Server-Sent Events (SSE).

```APIDOC
## GET /openapi/v1/print/analyze/:id/stream

### Description
This endpoint streams real-time updates for an analyze-printability task using Server-Sent Events (SSE). For PENDING or IN_PROGRESS tasks, the stream provides progress and status updates, while the full printability block is sent upon task completion.

### Method
GET

### Endpoint
/openapi/v1/print/analyze/:id/stream

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique identifier for the analyze-printability task to stream.

### Response
#### Success Response (200)
- **Stream** (SSE) - A stream of Analyze Printability Task Objects.
```

--------------------------------

### Stream Figure Task Updates via SSE

Source: https://docs.meshy.ai/llms-full.txt

Examples for consuming the figure task stream using cURL, JavaScript Fetch API, and Python requests.

```bash
curl -N https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
```

```javascript
const response = await fetch(
    'https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream',
    {
        headers: { Authorization: `Bearer ${YOUR_API_KEY}` }
    }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop();

    for (const line of lines) {
        if (line.startsWith('data:')) {
            const data = JSON.parse(line.slice(5));
            console.log(data);

            if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(data.status)) {
                reader.cancel();
            }
        }
    }
}
```

```python
import requests
import json

headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}",
    "Accept": "text/event-stream"
}

response = requests.get(
    'https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream',
    headers=headers,
    stream=True
)

for line in response.iter_lines():
    if line:
        if line.startswith(b'data:'):
            data = json.loads(line.decode('utf-8')[5:])
            print(data)

            if data['status'] in ['SUCCEEDED', 'FAILED', 'CANCELED']:
                break

response.close()
```

--------------------------------

### Retrieve Convert Task using Python (Requests)

Source: https://docs.meshy.ai/en/api/convert

This Python example shows how to get a convert task's details using the Requests library. Remember to substitute YOUR_API_KEY.

```python
import requests

task_id = "a43b5c6d-7e8f-901a-234b-567c890d1e2f"
headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

response = requests.get(
    f"https://api.meshy.ai/openapi/v1/convert/{task_id}",
    headers=headers,
)
response.raise_for_status()
print(response.json())
```

--------------------------------

### Response Stream Example

Source: https://docs.meshy.ai/llms-full.txt

Example of the message events received during a task stream.

```javascript
// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}
```

--------------------------------

### List and Download Tasks Prompt

Source: https://docs.meshy.ai/llms-full.txt

Example prompt to list recent tasks and download top results.

```text
List my last 10 successful text-to-3d tasks and download the top 3 as GLB
into ./downloads/.
```

--------------------------------

### Task status response example

Source: https://docs.meshy.ai/en/api/quick-start

Example JSON response returned when a task has successfully completed.

```json
{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "task_error": {
    "message": ""
  }
}
```

--------------------------------

### Create a Fridge Magnet Prototype Task

Source: https://docs.meshy.ai/en/api/creative-lab-fridge-magnet

Examples for initiating the prototype generation process using various programming environments.

```bash
# Stage 1: generate a colorized fridge magnet concept image
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'
```

```javascript
import axios from 'axios'

const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

// Stage 1: generate a colorized fridge magnet concept image
const payload = {
  image_url: "<your publicly accessible image url or base64-encoded data URI>",
};

try {
  const response = await axios.post(
    'https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype',
    payload,
    { headers }
  );
  console.log(response.data);
} catch (error) {
  console.error(error);
}
```

```python
import requests

headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

# Stage 1: generate a colorized fridge magnet concept image
payload = {
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
}

response = requests.post(
    "https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype",
    headers=headers,
    json=payload,
)
response.raise_for_status()
print(response.json())
```

--------------------------------

### Create a Convert Task

Source: https://docs.meshy.ai/llms-full.txt

Examples for initiating a 3D model conversion task using different programming languages and tools.

```bash
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'
```

```javascript
import axios from 'axios'

const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

const payload = {
    input_task_id: "018a210d-8ba4-705c-b111-1f1776f7f578",
    target_formats: ["fbx", "stl"]
};

try {
    const response = await axios.post(
    'https://api.meshy.ai/openapi/v1/convert',
    payload,
  { headers }
);
    console.log(response.data);
} catch (error) {
    console.error(error);
}
```

```python
import requests

headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

payload = {
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
}

response = requests.post(
    "https://api.meshy.ai/openapi/v1/convert",
    headers=headers,
    json=payload,
)
response.raise_for_status()
print(response.json())
```

--------------------------------

### Keychain Task Response Stream Examples

Source: https://docs.meshy.ai/en/api/creative-lab-keychain

Examples of error and message events received through the SSE stream.

```javascript
// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}
```

--------------------------------

### Create a Keychain Prototype Task

Source: https://docs.meshy.ai/en/api/creative-lab-keychain

Examples for initiating a prototype generation task using various programming languages.

```bash
# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'
```

```javascript
import axios from 'axios'

const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

// Stage 1: generate a colorized keychain concept image
const payload = {
  image_url: "<your publicly accessible image url or base64-encoded data URI>",
};

try {
  const response = await axios.post(
    'https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype',
    payload,
    { headers }
  );
  console.log(response.data);
} catch (error) {
  console.error(error);
}
```

```python
import requests

headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

# Stage 1: generate a colorized keychain concept image
payload = {
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
}

response = requests.post(
    "https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype",
    headers=headers,
    json=payload,
)
response.raise_for_status()
print(response.json())
```

--------------------------------

### Animation Task Response Stream Examples

Source: https://docs.meshy.ai/en/api/animation

Example payloads for error events and task progress updates.

```javascript
// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Animation Task Object structure
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}
```

--------------------------------

### SSE Response Stream Example

Source: https://docs.meshy.ai/llms-full.txt

Example of the event stream format containing task progress and completion data.

```javascript
// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}
```

--------------------------------

### Chain build task using API

Source: https://docs.meshy.ai/en/api/creative-lab-lamp

Examples for initiating a build task based on a previously succeeded prototype task using cURL, JavaScript, and Python.

```bash
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "diameter_mm": 120,
      "thickness_mm": 2,
      "light_source_preset": "bambu_mh001_60mm",
      "cut_amount_percent": 30
    },
    "output": {
      "format": "stl"
    }
  }'
```

```javascript
import axios from 'axios'

const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

// Stage 2: chain build off a succeeded prototype task
const payload = {
  input_task_id: "018a210d-8ba4-705c-b111-1f1776f7f578",
  options: {
    diameter_mm: 120,
    thickness_mm: 2,
    light_source_preset: "bambu_mh001_60mm",
    cut_amount_percent: 30,
  },
  output: { format: "stl" },
};

try {
  const response = await axios.post(
    'https://api.meshy.ai/openapi/creative-lab/lamp/v1/build',
    payload,
    { headers }
  );
  console.log(response.data);
} catch (error) {
  console.error(error);
}
```

```python
import requests

headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

# Stage 2: chain build off a succeeded prototype task
payload = {
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
        "diameter_mm": 120,
        "thickness_mm": 2,
        "light_source_preset": "bambu_mh001_60mm",
        "cut_amount_percent": 30,
    },
    "output": {"format": "stl"},
}

response = requests.post(
    "https://api.meshy.ai/openapi/creative-lab/lamp/v1/build",
    headers=headers,
    json=payload,
)
response.raise_for_status()
print(response.json())
```

--------------------------------

### Create a Text to Image Task

Source: https://docs.meshy.ai/en/api/text-to-image

Examples of how to initiate an image generation task using the POST endpoint with different programming languages.

```bash
# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'
```

```javascript
import axios from 'axios'

// Generate an image from a text prompt
const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };
const payload = {
  ai_model: "nano-banana",
  prompt: "A majestic dragon soaring through clouds at sunset",
  aspect_ratio: "16:9"
};

try {
  const response = await axios.post(
    'https://api.meshy.ai/openapi/v1/text-to-image',
    payload,
    { headers }
  );
  console.log(response.data);
} catch (error) {
  console.error(error);
}
```

```python
import requests

// Generate an image from a text prompt
payload = {
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
}
headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

response = requests.post(
    "https://api.meshy.ai/openapi/v1/text-to-image",
    headers=headers,
    json=payload,
)
response.raise_for_status()
print(response.json())
```

--------------------------------

### Response Stream Examples

Source: https://docs.meshy.ai/en/api/multi-color-print

Example payloads for error events and task progress messages received via the stream.

```json
// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}
```

--------------------------------

### Response Stream Examples

Source: https://docs.meshy.ai/en/api/image-to-image

Example payloads for error events and task progress messages received via the SSE stream.

```text
// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "expires_at": 1692771679037,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ]
}
```

--------------------------------

### Fridge Magnet Build Task Object Example

Source: https://docs.meshy.ai/en/api/creative-lab-fridge-magnet

A JSON representation of a successful fridge magnet build task, showing the structure of the task object and its model URLs.

```json
{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}
```

--------------------------------

### POST /openapi/creative-lab/lamp/v1/build

Source: https://docs.meshy.ai/en/api/creative-lab-lamp

Initiates a build task that converts a selected prototype image into a printable lampshade model.

```APIDOC
## POST /openapi/creative-lab/lamp/v1/build

### Description
This endpoint chains a build process off a succeeded prototype task to generate a printable lampshade model.

### Method
POST

### Endpoint
https://api.meshy.ai/openapi/creative-lab/lamp/v1/build

### Request Body
- **input_task_id** (string) - Required - The UUID of the succeeded prototype task.
- **options** (object) - Required - Configuration for the lamp build.
  - **diameter_mm** (number) - Optional - Diameter of the lamp in millimeters.
  - **thickness_mm** (number) - Optional - Thickness of the lamp in millimeters.
  - **light_source_preset** (string) - Optional - Preset identifier for the light source.
  - **cut_amount_percent** (number) - Optional - Percentage for the cut amount.
- **output** (object) - Required - Output configuration.
  - **format** (string) - Required - The file format (e.g., "stl").

### Response
#### Success Response (200)
- **result** (string) - The ID of the created build task.

#### Response Example
{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
```

--------------------------------

### Task Error Response Examples

Source: https://docs.meshy.ai/llms-full.txt

Examples of task error responses, showing both cases with and without specific error codes and documentation URLs.

```json
{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}
```

```json
{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}
```

--------------------------------

### Create a Rigging Task

Source: https://docs.meshy.ai/en/api/rigging

Examples for initiating a rigging task using a model URL via cURL, JavaScript, and Python.

```bash
# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'
```

```javascript
import axios from 'axios'

// Rig a model from a URL
const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };
const payload = {
  model_url: "YOUR_MODEL_URL_OR_DATA_URI",
  height_meters: 1.8
};

try {
  const response = await axios.post(
    'https://api.meshy.ai/openapi/v1/rigging',
    payload,
    { headers }
  );
  console.log(response.data);
} catch (error) {
  console.error(error);
}
```

```python
import requests

// Rig a model from a URL
payload = {
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
}
headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

response = requests.post(
    "https://api.meshy.ai/openapi/v1/rigging",
    headers=headers,
    json=payload,
)
response.raise_for_status()
print(response.json())
```

--------------------------------

### Install Meshy MCP Server

Source: https://docs.meshy.ai/en/api/ai

Detects installed AI clients and configures Meshy for each. Ensure you replace 'msy_YOUR_API_KEY' with your actual Meshy API key.

```bash
# Detects installed AI clients and configures Meshy for each
npx add-mcp @meshy-ai/meshy-mcp-server --env MESHY_API_KEY=msy_YOUR_API_KEY
```

--------------------------------

### POST /openapi/creative-lab/keycap/v1/build

Source: https://docs.meshy.ai/llms-full.txt

Builds a chosen candidate into a 3D keycap.

```APIDOC
## POST /openapi/creative-lab/keycap/v1/build

### Description
Builds the chosen candidate into a 3D keycap.

### Method
POST

### Endpoint
https://api.meshy.ai/openapi/creative-lab/keycap/v1/build

### Parameters
#### Request Body
- **input_task_id** (string) - Required - The UUID of the prototype task.
- **candidate_id** (string) - Required - The ID of the candidate to build.
- **options** (object) - Required - Configuration options for the build.

### Request Example
{
  "input_task_id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "candidate_id": "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b",
  "options": {
    "base_model": "cherry-mx-1x1-r1",
    "head_size_mm": 23,
    "vertical_offset_mm": 0
  }
}

### Response
#### Success Response (200)
- **result** (string) - The ID of the created build task.

#### Response Example
{
  "result": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af"
}
```

--------------------------------

### GET /openapi/v1/balance -- Get Balance

Source: https://docs.meshy.ai/en/api/balance

This endpoint retrieves the current credit balance for the authenticated user. It returns an object containing the current balance of credits.

```APIDOC
## GET /openapi/v1/balance -- Get Balance

### Description
This endpoint retrieves the current credit balance for the authenticated user.

### Method
GET

### Endpoint
/openapi/v1/balance

### Request Example
```bash
curl https://api.meshy.ai/openapi/v1/balance \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

### Response
#### Success Response (200)
- **balance** (integer) - The current credit balance.

#### Response Example
```json
{
  "balance": 1000
}
```
```

--------------------------------

### Get Balance using Python (Requests)

Source: https://docs.meshy.ai/en/api/balance

This Python code uses the requests library to get your credit balance. It demonstrates how to set the Authorization header for the API request.

```python
import requests

headers = {
  "Authorization": f"Bearer {YOUR_API_KEY}"
}

response = requests.get(
  "https://api.meshy.ai/openapi/v1/balance",
  headers=headers,
)
response.raise_for_status()
print(response.json())
```

--------------------------------

### Example 400 Bad Request Error

Source: https://docs.meshy.ai/en/api/errors

This is an example of a 400 Bad Request error response. It indicates that the request was malformed or contained invalid parameters, such as an unsupported file extension.

```bash
{
  "message": "Invalid model file extension: .3dm"
}
```

--------------------------------

### List Convert Tasks using Python (requests)

Source: https://docs.meshy.ai/en/api/convert

This Python example shows how to list convert tasks using the requests library, including setting the Authorization header and passing query parameters for pagination.

```python
import requests

headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

response = requests.get(
    "https://api.meshy.ai/openapi/v1/convert",
    headers=headers,
    params={"page_size": 10}
)
response.raise_for_status()
print(response.json())
```
Tokens:
Raw