Text to 3D API is a feature that allows you to integrate Meshy's Text to 3D capabilities into your own application. In this section, you'll find all the information
you need to get started with this API.
The workflow of Text to 3D involves two stages: the preview stage and the refine stage. In the preview stage, a base mesh is generated with no texture applied, allowing you to evaluate the geometry. In the refine stage, the preview mesh is textured based on the text prompt.
This endpoint allows you to create a new Text to 3D Preview task. Refer to
The Text to 3D Task Object to see which
properties are included with Text to 3D task object.
Parameters
Required attributes
Name
mode
Type
string
Description
This field should be set to "preview" when creating a preview task.
Name
prompt
Type
string
Description
Describe what kind of object the 3D model is. Maximum 600 characters.
Optional attributes
Name
art_style
Type
string
Description
Describe your desired art style of the object.
Available values:
realistic: Realistic style
sculpture: Sculpture style
Default to realistic if not specified.
Note that enable_pbr should be set to false when using Sculpture style, as Sculpture style generates its own set of PBR maps.
Name
seed
Type
integer
Description
Seed of the task.
When you use the same prompt and seed, you will generate the same result in most cases. However, the same seed may occasionally produce different results from a previous task due to our software and hardware updates.
Name
ai_model
Type
string
Description
ID of the model to use.
Available values:
meshy-4
latest
Default to meshy-4 if not specified.
The refine task will use the same model as the corresponding preview task.
Name
topology
Type
string
Description
Specify the topology of the generated model.
Available values:
quad: Generate a quad-dominant mesh.
triangle: Generate a decimated triangle mesh.
Default to triangle if not specified.
Name
target_polycount
Type
integer
Description
Specify the target number of polygons in the generated model. The actual number of polygons may deviate from the target depending on the complexity of the geometry.
The valid value range varies depending on the user tier:
100 to 300,000 (inclusive)
Default to 30,000 if not specified.
Name
should_remesh
Type
boolean
Description
The should_remesh flag controls whether to enable the remesh phase.
When set to false, it directly returns an unprocessed triangular mesh, ignoring topology and target_polycount.
Default to true if not specified.
Name
symmetry_mode
Type
string
Description
The symmetry_mode field controls symmetry behavior during the model generation process.
The valid values are:
off: Disables symmetry.
auto: Automatically determines and applies symmetry based on input geometry.
on: Enforces symmetry during generation.
Default to auto if not specified.
Returns
The result property of the response contains the task id of the newly created Text to 3D task.
This endpoint allows you to create a new Text to 3D Refine task.
Parameters
Required attributes
Name
mode
Type
string
Description
This field should be set to "refine" when creating a refine task.
Name
preview_task_id
Type
string
Description
The corresponding preview task id.
The status of the given preview task must be SUCCEEDED.
Optional attributes
Name
enable_pbr
Type
boolean
Description
Generate PBR Maps (metallic, roughness, normal) in addition to the base color.
Default to false if not specified.
Note that enable_pbr should be set to false when using Sculpture style, as Sculpture style generates its own set of PBR maps.
At this time, enable_pbr=true requires ai_model to be meshy-4.
Name
texture_prompt
Type
string
Description
Provide an additional text prompt to guide the texturing process. Maximum 600 characters.
Name
texture_image_url
Type
string
Description
Provide a 2d image to guide the texturing process. We currently support .jpg, .jpeg, and .png formats.
There are two ways to provide the image:
Publicly accessible URL: A URL that is accessible from the public internet
Data URI: A base64-encoded data URI of the image. Example of a data URI: data:image/jpeg;base64,<your base64-encoded image data>
Image texturing may not work optimally if there are substantial geometry differences between the original asset and uploaded image. Only one of texture_image_url or texture_prompt may be used to guide the texturing process. If both parameters are provided, then texture_prompt will be used to texture the model by default. Texturing via either text or image will cost 10 credits per task.
At this time, texture_image_url requires ai_model to be meshy-4.
Returns
The result property of the response contains the task id of the newly created Text to 3D task.
This endpoint allows you to retrieve a Text to 3D task given a valid task id.
Refer to The Text to 3D Task Object to see which
properties are included with Text to 3D task object.
This endpoint works for both preview and refine tasks.
Parameters
Name
id
Type
path
Description
Unique identifier for the Text to 3D task to retrieve.
The Text to 3D Task object is a work unit that Meshy keeps track of to generate a 3D model from a text input. There are two stages of the Text to 3D API, preview and refine. Preview stage is for generating a mesh-only 3D model, and refine stage is for generating a textured 3D model based on the preview stage's result.
The object 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. The property for a format will be omitted if the format is not generated instead of returning an empty string.
Name
glb
Type
string
Description
Downloadable URL to the GLB file.
Name
fbx
Type
string
Description
Downloadable URL to the FBX file.
Name
usdz
Type
string
Description
Downloadable URL to the USDZ file.
Name
obj
Type
string
Description
Downloadable URL to the OBJ file.
Name
mtl
Type
string
Description
Downloadable URL to the MTL file.
Name
prompt
Type
string
Description
This is unmodified prompt that was used to create the task.
Name
negative_prompt
Type
string
Description
Deprecated field maintained for backward compatibility. This field has no functional impact on generated models.
Name
art_style
Type
string
Description
This is unmodified art_style that was used to create the preview task.
Name
texture_richness
Type
string
Description
Deprecated field maintained for backward compatibility. This field has no functional impact on generated models.
Name
texture_prompt
Type
string
Description
Additional text prompt provided to guide the texturing process during the refine stage.
Name
texture_image_url
Type
string
Description
Downloadable URL to the texture image that was used to guide the texturing process.
Name
thumbnail_url
Type
string
Description
Downloadable URL to the thumbnail image of the model file.
Name
video_url
Type
string
Description
Downloadable URL to the preview video.
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
seed
Type
integer
Description
Seed of the task.
When you use the same prompt and seed, you will generate the same result in most cases. However, the same seed may occasionally produce different results from a previous task due to our software and hardware updates.
Name
started_at
Type
timestamp
Description
Timestamp of when the task was started, in milliseconds. 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 milliseconds.
Name
finished_at
Type
timestamp
Description
Timestamp of when the task was finished, in milliseconds. 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, CANCELED.
Name
texture_urls
Type
array
Description
An array of texture URL objects that are generated from the task. Normally this only contains one texture URL object. Each texture URL has the following properties:
Name
base_color
Type
string
Description
Downloadable URL to the base color map image.
Name
metallic
Type
string
Description
Downloadable URL to the metallic map image.
If the task is created with enable_pbr: false, this property will be omitted.
Name
normal
Type
string
Description
Downloadable URL to the normal map image.
If the task is created with enable_pbr: false, this property will be omitted.
Name
roughness
Type
string
Description
Downloadable URL to the roughness map image.
If the task is created with enable_pbr: false, this property will be omitted.
Name
preceding_tasks
Type
integer
Description
The count of preceding tasks.
The value of this field is meaningful only if the task status is PENDING.
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 3D Task Object
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","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=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***","obj":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***" },"prompt":"a monster mask","art_style":"realistic","texture_richness":"high","texture_prompt":"green slimy skin with scales and warts","texture_image_url":"","thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","video_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.mp4?Expires=***","progress":1,"seed":1234,"started_at":1692771667037,"created_at":1692771650657,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" }}