Text To Voxel API

Text To Voxel API is a feature that allows you to integrate Meshy's Text to Voxel capabilities into your own application. In this section, you'll find all the information you need to get started with this API.

The Text to Voxel Task Model

The Text to Voxel Task model is a work unit that Meshy keeps track of to generate a voxel model from a text input. The model has the following properties:

Properties

Name
id
Type
string
Description
Unique identifier for the task. While we use a k-sortable UUID for task ids as the implementation detail, you should not make any assumptions about the format of the id.
Name
model_urls
Type
object
Description
Downloadable URL to the textured 3D model file generated by Meshy.
- Name
  glb
  Type
  string
  Description
  Downloadable URL to the GLB file.
- Name
  vox
  Type
  string
  Description
  Downloadable URL to the VOX file.
Name
prompt
Type
string
Description
This is unmodified prompt that was used to create the task.
Name
negative_prompt
Type
string
Description
This is unmodified negative_prompt that was used to create the task.
Name
thumbnail_url
Type
string
Description
Downloadable URL to the thumbnail image of the model file.
Name
progress
Type
integer
Description
Progress of the task. If the task is not started yet, this property will be 0. Once the task has succeeded, this will become 100.
Name
started_at
Type
timestamp
Description
Timestamp of when the task was started, in miliseconds. If the task is not started yet, this property will be 0.
A timestamp represents the number of milliseconds elapsed since January 1, 1970 UTC, following the RFC 3339 standard. For example, Friday, September 1, 2023 12:00:00 PM GMT is represented as 1693569600000. This applies to all timestamps in Meshy API.
Name
created_at
Type
timestamp
Description
Timestamp of when the task was created, in miliseconds.
Name
finished_at
Type
timestamp
Description
Timestamp of when the task was finished, in miliseconds. If the task is not finished yet, this property will be 0.
Name
status
Type
string
Description
Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, EXPIRED.
Name
voxel_size_shrink_factor
Type
integer
Description
This field is a parameter used to control the voxel size of three-dimensional data. Higher values correspond to smaller voxel sizes. Possible values are one of 8, 4, 2, 1.
Name
task_error
Type
object
Description
Error object that contains the error message if the task failed. The message property should be empty if the task succeeded.
- Name
  message
  Type
  string
  Description
  Detailed error message.

Example Text to Voxel Task Model

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "vox": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.vox?Expires=***",
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "negative_prompt": "low quality, low resolution, low poly, ugly",
  "progress": 1,
  "seed": 1234,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "voxel_size_shrink_factor": 8,
}

POST/v1/text-to-voxel

Create a Text to Voxel Task

This endpoint allows you to create a new Text to Voxel task. Refer to The Text to Voxel Task Model to see which properties are included with Text to Voxel task object.

Parameters

Required attributes

Name
voxel_size_shrink_factor
Type
integer
Description
This field is a parameter used to control the voxel size of three-dimensional data. Higher values correspond to smaller voxel sizes. Possible values are one of 8, 4, 2, 1.
Name
prompt
Type
string
Description
Describe what kind of object the 3D model is.

Optional attributes

Name
negative_prompt
Type
string
Description
Describe what the model should not look like.
Name
seed
Type
integer
Description
When you use the same prompt and seed, you will generate the same result.

Returns

The result property of the response contains the task id of the newly created Text to Voxel task.

Request

POST

/v1/text-to-voxel

curl https://api.meshy.ai/v1/text-to-voxel \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
  "voxel_size_shrink_factor": 1,
  "prompt": "a monster mask",
  "negative_prompt": "low quality, low resolution, low poly, ugly"
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/v1/text-to-voxel/:id

Retrieve a Text to Voxel Task

This endpoint allows you to retrieve a Text to Voxel task given a valid task id. Refer to The Text to Voxel Task Model to see which properties are included with Text to Voxel task object.

Parameters

Name
id
Type
path
Description
Unique identifier for the Text to Voxel task to retrieve.

Returns

The response contains the Text to Voxel task object. Check The Text to Voxel Task Model section for details.

Request

GET

/v1/text-to-voxel/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/v1/text-to-voxel/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "vox": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.vox?Expires=***",
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "negative_prompt": "low quality, low resolution, low poly, ugly",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "voxel_size_shrink_factor": 8,
}