Text To 3D API

This is the legacy API for Text to 3D using Meshy-3 & Meshy-3-turbo. We recommend using the new API with Meshy-4 instead.

This is a legacy API and will be deprecated soon. We recommend using the new API with Meshy-4 instead.

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

Create a Text to 3D Preview Task

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.

  • Name
    ai_model
    Type
    string
    Description

    ID of the model to use. Available values:

    • meshy-3-turbo
    • meshy-3

    The refine task will use the same model as the corresponding preview task.

Optional attributes

  • Name
    negative_prompt
    Type
    string
    Description

    Describe what the model should not look like.

  • Name
    art_style
    Type
    string
    Description

    Describe your desired art style of the object. Default to realistic if not specified. Available values:

    • realistic: Realistic style
    • cartoon: Cartoon style
    • sculpture: Sculpture style
    • pbr: PBR style
  • 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 3D task.

Request

POST
/openapi/v2/text-to-3d
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",
  "ai_model": "meshy-3-turbo",
  "negative_prompt": "low quality, low resolution, low poly, ugly",
  "art_style": "realistic",
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
POST/openapi/v2/text-to-3d

Create a Text to 3D Refine 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 preview 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
    texture_richness
    Type
    string
    Description

    Describe your desired texture richness. Available values:

    • high
    • medium
    • low
    • none

    The default value of texture_richness depends on the corresponding preview task's art style:

    • high for realistic
    • medium for cartoon

Returns

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

Request

POST
/openapi/v2/text-to-3d
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"
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v2/text-to-3d/:id

Retrieve a 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.

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the Text to 3D task to retrieve.

Returns

The response contains the Text to 3D task object. Check The Text to 3D Task Object section for details.

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",
  "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",
  "art_style": "realistic",
  "negative_prompt": "low quality, low resolution, low poly, ugly",
  "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": ""
  }
}

The Text to 3D Task Object

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.

    • 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

    This is unmodified negative_prompt that was used to create the task.

  • 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

    This is unmodified texture_richness that was used to create the refine task. If the task is created with ai_model: "meshy-4", there is no texture_richness property.

  • 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.

  • 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
    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.

    • Name
      normal
      Type
      string
      Description

      Downloadable URL to the normal map image.

    • Name
      roughness
      Type
      string
      Description

      Downloadable URL to the roughness map image.

  • 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",
  "negative_prompt": "low quality, low resolution, low poly, ugly",
  "art_style": "realistic",
  "texture_richness": "high",
  "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": ""
  }
}