Text to 3D API

Generate 3D models from text prompts in your own application.

Text to 3D works in two steps. First, create a preview task (mode: "preview") to generate a 3D mesh without texture, so you can check the shape. Then, send the successful preview's task ID to a refine task (mode: "refine") to texture the mesh. Both steps use the same endpoint.

POST/openapi/v2/text-to-3d

Create a Text to 3D preview task

Creates a Text to 3D preview task, which generates an untextured 3D mesh (geometry only) from a text prompt. This is the first step of the two-step workflow. After the preview succeeds, send its task ID in a refine task to texture the mesh. See Create a Text to 3D refine task. For the full response schema, see The Text to 3D task object.

The task runs in the background. For how long a task usually takes, see Processing times.

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

Parameters

Name
mode
Type
string
Required
Description
The step of the two-step workflow. Send preview to create a preview task.
Name
prompt
Type
string
Required
Description
Text that describes the object to generate, up to 800 characters. Longer text returns 400.
Name
model_type
Type
string
default standard
Description
The type of 3D mesh to generate.
Available values:
- standard: a high-detail 3D mesh
- smart-topology: a Smart Topology mesh. Choose the model with ai_model (meshy-t2 or meshy-t2.5).
- lowpoly (deprecated): a low-poly mesh with cleaner polygons
With smart-topology, Meshy ignores should_remesh and decimation_mode, and accepts only topology: triangle.
Meshy retires lowpoly on October 30, 2026. After that date, a request with model_type: "lowpoly" returns an error. Switch to Meshy T2.5 (model_type: "smart-topology" with ai_model: "meshy-t2.5"). With lowpoly, Meshy ignores topology, target_polycount, and should_remesh. ai_model must be meshy-6 or latest, and Meshy uses the same AI model for both. Other models return 400.
Name
ai_model
Type
string
default latest
Description
The AI model that generates the 3D model. The available values depend on model_type.
Standard models (model_type: standard):
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (deprecated): send meshy-7.1 instead
Smart Topology models (model_type: smart-topology):
- meshy-t2: cleaner topology, natively separated parts, triangle output, and a face count you set with target_polycount
- meshy-t2.5 (default): sharper detail for game assets, triangle output, and a face count you set with target_polycount
Name
geometry_resolution
Type
string
default standard
Description
The geometry generation pass. Applies only to preview tasks. A refine with this parameter returns 400.
Available values:
- standard
- 2k: runs the Ultra pass at 2048³
- 4k: runs the Ultra pass at 4096³, for finer surface detail
2k needs meshy-7.1, latest, or the deprecated meshy-7. 4k needs meshy-7.1 or latest. Other models return 400.
Name
ultra_mode
Type
boolean
⚠ deprecated
default false
Description
Send geometry_resolution instead. ultra_mode: true is the same as geometry_resolution: "2k".
Name
should_remesh
Type
boolean
default true (meshy-6-lite), false (other models)
Description
Whether to remesh the model after generation. For the highest-quality 3D model, send false.

Applies only when should_remesh = true

Name
topology
Type
string
default triangle
Description
The face type of the remeshed model.
Available values:
- quad: a quad-dominant mesh
- triangle: a decimated triangle mesh
Smart Topology output is triangle-only. Sending quad with ai_model meshy-t2 or meshy-t2.5 returns 400.
Name
decimation_mode
Type
integer
Description
Adaptive face count, by level. When you set it, Meshy ignores target_polycount.
Available values:
- 1: ultra
- 2: high
- 3: medium
- 4: low

Name
target_polycount
Type
integer
Description
The number of faces to aim for. The result can differ from the target, depending on the geometry. It applies in two separate cases:
- Remesh: with should_remesh: true on a standard model. Meshy remeshes (decimates) the mesh to about this count. If you set decimation_mode, Meshy uses it and ignores target_polycount.
- Smart Topology: with model_type: smart-topology and ai_model meshy-t2 or meshy-t2.5. Meshy generates the model at this face count directly. No remesh runs, and you don't need should_remesh.
The following table shows the range and default for each case:
Case Range Default
Remesh 100 to 300000 30000
meshy-t2 100 to 15000 4000
meshy-t2.5 100 to 30000 15000
A value outside the range returns 400.

Case	Range	Default
Remesh	`100` to `300000`	`30000`
`meshy-t2`	`100` to `15000`	`4000`
`meshy-t2.5`	`100` to `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ deprecated
default auto
Description
Leave it out. This parameter doesn't affect the output.
Available values:
- off: disables symmetry
- auto: applies symmetry based on the input geometry
- on: enforces symmetry during generation
Name
pose_mode
Type
string
default ""
Description
The pose of the generated model.
Available values:
- a-pose: an A pose
- t-pose: a T pose
- "" (empty string): no specific pose
Name
is_a_t_pose
Type
boolean
⚠ deprecated
default false
Description
Send pose_mode instead. Whether to generate the model in an A pose or a T pose.
Name
art_style
Type
string
⚠ deprecated
default realistic
Description
Leave it out. Meshy ignores it.
Name
moderation
Type
boolean
default false
Description
Whether to screen prompt for harmful content before generating. If Meshy detects harmful content, the request returns 400 and Meshy doesn't create a task.
Name
target_formats
Type
string[]
Description
The file formats to generate. Meshy generates and returns only these formats, which can shorten the task. If you leave it out, Meshy generates every format except 3mf, which it generates only when you request it.
Available values:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
default false
Description
Whether to also render a preview with a transparent background (RGBA), returned in alpha_thumbnail_url when you get the task. thumbnail_url doesn't change.
Name
auto_size
Type
boolean
default false
Description
Whether to estimate the object's real-world height with AI vision and resize the model to it. Meshy puts the origin at the bottom unless you set origin_at.

Applies only when auto_size = true

Name
origin_at
Type
string
default bottom
Description
Where to put the model's origin, bottom or center.

Returns

The result field of the response holds the ID of the new Text to 3D task.

Failure modes

Name
400 - Bad Request
Description
The request can't run. The error message says which problem it found. For example:
- Missing parameter: A required parameter, such as prompt or mode, is missing.
- Prompt too long: prompt is over the character limit.
- Unsupported model for low-poly: model_type: "lowpoly" was sent with an ai_model other than meshy-6 or latest.
- Unsupported model for Ultra: geometry_resolution is 2k or 4k, with an ai_model that can't run it.
Fix the request, then send it again. See Errors.
Name
401 - Unauthorized
Description
The API key is missing or invalid. Check the Authorization header.
Name
402 - Payment Required
Description
For example:
- Insufficient credits: The account doesn't have enough credits for this task, or the account reached a credit limit. Check your credit balance, then retry.
- Free plan: Creating a task requires a paid plan. Upgrade your plan in your subscription settings, then retry.
Name
429 - Too Many Requests
Description
You exceeded your rate limit. Wait, then retry. See Rate limits.

POST/openapi/v2/text-to-3d

Create a Text to 3D refine task

Creates a Text to 3D refine task, which textures the mesh of a completed preview task. Send the ID of a successful preview task as preview_task_id. See Create a Text to 3D preview task. This is the second step of the two-step workflow.

The task runs in the background. For how long a task usually takes, see Processing times.

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

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

Parameters

Name
mode
Type
string
Required
Description
The step of the two-step workflow. Send refine to create a refine task.
Name
preview_task_id
Type
string
Required
Description
The ID of the preview task to texture. The preview task must have the status SUCCEEDED.
Name
enable_pbr
Type
boolean
default false
Description
Whether to also generate PBR maps (metallic, roughness, and normal) with the base color.
With ai_model meshy-6, Meshy also generates an emission map, except at texture_resolution: 8k. meshy-6-lite, meshy-7, meshy-7.1, and latest don't generate an emission map. Neither does a refine of a meshy-t2 or meshy-t2.5 preview that doesn't set ai_model.
Name
texture_resolution
Type
string
default 2k
Description
The resolution of the base color texture. Applies only to refine tasks. A preview with this parameter returns 400.
Available values:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Higher resolutions capture more surface detail. 4k and 8k need ai_model meshy-6, meshy-7.1, or latest. At 8k, Meshy doesn't generate an emission map.
Name
hd_texture
Type
boolean
⚠ deprecated
default false
Description
Send texture_resolution instead. hd_texture: true is the same as texture_resolution: "4k". If you send both, Meshy uses texture_resolution.
Name
texture_prompt
Type
string
Description
Text that guides the texturing, up to 800 characters. Longer text returns 400. Send texture_prompt or texture_image_url, not both. If you send both, Meshy uses texture_prompt.
Name
texture_image_url
Type
string
Description
A 2D image that guides the texturing, as a public URL or a base64-encoded data URI, such as data:image/jpeg;base64,<your base64-encoded image data>.
The image must be a .jpg, .jpeg, .png, or .webp file of at most 20 MB.
Texturing from an image might not work well when the shape in the image differs a lot from the model.
Name
ai_model
Type
string
default inherited from the preview task
Description
The AI model that textures the mesh.
Available values:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (deprecated): send meshy-7.1 instead
Leave it out to use the preview task's model, so the preview and its refine run on the same model end to end. Send a value to override it. An explicit latest resolves the same way as on the preview task, so a latest preview and its latest refine always use the same texture model.
Name
moderation
Type
boolean
default false
Description
Whether to screen texture_prompt and texture_image_url for harmful content before generating. If Meshy detects harmful content, the request returns 400 and Meshy doesn't create a task.
Name
remove_lighting
Type
boolean
default true
Description
Whether to remove highlights and shadows from the base color texture. The cleaner result works better under custom lighting.
Takes effect only when ai_model is meshy-6. meshy-7.1 and latest accept it and ignore it, and so does a refine of a meshy-t2 or meshy-t2.5 preview that doesn't set ai_model. Sending it with meshy-6-lite returns 400.
Name
target_formats
Type
string[]
Description
The file formats to generate. Meshy generates and returns only these formats, which can shorten the task. If you leave it out, Meshy generates every format except 3mf, which it generates only when you request it.
Available values:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
default false
Description
Whether to also render a preview with a transparent background (RGBA), returned in alpha_thumbnail_url when you get the task. thumbnail_url doesn't change.
Name
auto_size
Type
boolean
default false
Description
Whether to estimate the object's real-world height with AI vision and resize the model to it. Meshy puts the origin at the bottom unless you set origin_at.

Applies only when auto_size = true

Name
origin_at
Type
string
default bottom
Description
Where to put the model's origin, bottom or center.

Returns

The result field of the response holds the ID of the new Text to 3D task.

Failure modes

Name
400 - Bad Request
Description
The request can't run. The error message says which problem it found. For example:
- Invalid task ID: preview_task_id is invalid, or doesn't match one of your preview tasks.
- Task not ready: The preview task hasn't succeeded yet.
- Model mismatch: The preview task's AI model doesn't work with the requested refine model.
- Unsupported model for remove_lighting: remove_lighting was sent with ai_model: "meshy-6-lite".
Fix the request, then send it again. See Errors.
Name
401 - Unauthorized
Description
The API key is missing or invalid. Check the Authorization header.
Name
402 - Payment Required
Description
For example:
- Insufficient credits: The account doesn't have enough credits for this task, or the account reached a credit limit. Check your credit balance, then retry.
- Free plan: Creating a task requires a paid plan. Upgrade your plan in your subscription settings, then retry.
Name
429 - Too Many Requests
Description
You exceeded your rate limit. Wait, then retry. See Rate limits.

GET/openapi/v2/text-to-3d/:id

Get a Text to 3D task

Returns a Text to 3D task by its ID. It works for both preview and refine tasks.

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "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=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "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=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}

Parameters

Name
id
Type
path
Description
The task ID from the create response.

Returns

The Text to 3D task object.

Examples

The following table shows a sample model for each mode.

Mode	Sample model
Preview
Refine

DELETE/openapi/v2/text-to-3d/:id

Delete a Text to 3D task

Permanently deletes a Text to 3D task, including its models and data. You can't undo a delete.

Request

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Path parameters

Name
id
Type
path
Description
The ID of the task to delete.

Task status

Deleting a PENDING task refunds the credits it used when you created it.

An IN_PROGRESS task can't be deleted. The request returns 409 Conflict, and the task keeps running. Meshy doesn't refund a task that has started, so deleting it would cost you both the credits and the result. Wait for it to reach SUCCEEDED, FAILED, or CANCELED, then delete it.

Deleting a task in a final status (SUCCEEDED, FAILED, or CANCELED) doesn't refund its credits.

Returns

200 OK when the task is deleted, or 409 Conflict when the task is IN_PROGRESS.

GET/openapi/v2/text-to-3d

List Text to 3D tasks

Returns a list of your Text to 3D tasks.

Request

GET

/openapi/v2/text-to-3d

curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "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=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "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=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

Parameters

Name
page_num
Type
integer
default 1
Description
The page number to return.
Name
page_size
Type
integer
default 10
Description
The number of tasks per page, up to 100.
Name
sort_by
Type
string
Description
The sort order.
Available values:
- +created_at: oldest first
- -created_at: newest first

Returns

A paginated list of Text to 3D task objects.

GET/openapi/v2/text-to-3d/:id/stream

Stream a Text to 3D task

Streams a Text to 3D task's updates as Server-Sent Events (SSE).

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

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

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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_normal.png?Expires=XXX",
    "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
    "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
  }
],
"preceding_tasks": 0,
"task_error": {

  "message": ""

},

"consumed_credits": 20
}

Parameters

Name
id
Type
path
Description
The task ID from the create response.

Returns

A stream of Text to 3D task objects as Server-Sent Events.

Each event holds the full task object, in the same shape the Get endpoint returns. While the task is PENDING or IN_PROGRESS, its result fields don't have values yet.

The Text to 3D task object

A Text to 3D task object describes one task that generates a 3D model from a text prompt. It holds the status, the progress, and the model files when the task succeeds. Text to 3D has two stages, preview and refine. A preview task generates a mesh-only 3D model, and a refine task generates a textured 3D model from the preview's result.

Properties

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "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=***",
  "progress": 100,
  "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_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}

Name
id
Type
string
Description
The task ID. Treat it as an opaque string, and don't rely on its format.
Name
type
Type
string
Description
The task type, text-to-3d-preview for a preview task or text-to-3d-refine for a refine task.
Name
model_urls
Type
object
Description
Download URLs for the generated 3D model, one per file format. A format the task didn't generate has no key, rather than an empty string.
- Name
  glb
  Type
  string
  Description
  The GLB file.
- Name
  fbx
  Type
  string
  Description
  The FBX file.
- Name
  usdz
  Type
  string
  Description
  The USDZ file.
- Name
  obj
  Type
  string
  Description
  The OBJ file.
- Name
  mtl
  Type
  string
  Description
  The MTL file.
- Name
  stl
  Type
  string
  Description
  The STL file.
- Name
  3mf
  Type
  string
  Description
  The 3MF file. Present only when target_formats includes 3mf.
Name
prompt
Type
string
Description
The prompt you sent to create the task, unmodified.
Name
texture_prompt
Type
string
Description
The text prompt you sent to guide the texturing in the refine stage.
Name
ultra_mode
Type
boolean
⚠ deprecated
Description
Read geometry_resolution instead.
Name
geometry_resolution
Type
string
Description
The Ultra tier the preview task ran, 2k or 4k. The field is absent for standard.
Name
texture_image_url
Type
string
Description
Download URL for the image you sent to guide the texturing.
Name
thumbnail_url
Type
string
Description
Download URL for a thumbnail image of the 3D model.
Name
alpha_thumbnail_url
Type
string
Description
Download URL for a version of thumbnail_url with a transparent background (RGBA). Present only when you created the task with alpha_thumbnail: true and Meshy rendered the transparent preview.
Name
video_url
Type
string
⚠ deprecated
Description
Don't rely on this field, because a future release removes it. Download URL for the preview video.
Name
progress
Type
integer
Description
How much of the task is done, as a percentage. It's 0 until the task starts and 100 when it succeeds.
Name
started_at
Type
timestamp
Description
Time the task started, in Unix milliseconds. It's 0 until the task starts.
Name
created_at
Type
timestamp
Description
Time the task was created, in Unix milliseconds.
Name
finished_at
Type
timestamp
Description
Time the task finished, in Unix milliseconds. It's 0 until the task finishes.
Name
status
Type
string
Description
The task status, one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, or CANCELED.
Name
texture_urls
Type
array
Description
Download URLs for the generated texture maps, as an array of objects. It usually holds one object. Each object has these fields:
- Name
  base_color
  Type
  string
  Description
  The base color map.
- Name
  metallic
  Type
  string
  Description
  The metallic map. Absent when you created the task with enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  The normal map. Absent when you created the task with enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  The roughness map. Absent when you created the task with enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  The emission map. Absent in any of these cases:
  
  You created the task with enable_pbr: false.
  
  ai_model is meshy-6-lite, meshy-7, meshy-7.1, or latest.
  
  texture_resolution is 8k.
  
  The task refines a meshy-t2 or meshy-t2.5 preview without setting ai_model.
Name
preceding_tasks
Type
integer
Description
The number of tasks ahead of this one in the queue. The value is meaningful only while the task is PENDING.
Name
task_error
Type
object
Description
The error details when the task fails. See Errors.
Name
consumed_credits
Type
integer
Description
The number of credits the task used. Present when the status is PENDING, IN_PROGRESS, or SUCCEEDED. It's 0 for a FAILED task, because Meshy refunds the credits when a task fails.