Image To 3D API

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


POST/openapi/v1/image-to-3d

Create an Image To 3D Task

This endpoint allows you to create a new Image To 3D task. Refer to The Image To 3D Task Object to see which properties are included with Image To 3D task object.

Parameters

Required attributes

  • Name
    image_url
    Type
    string
    Description

    Provide an image for Meshy to use in model creation. 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>.

Optional attributes

  • Name
    enable_pbr
    Type
    boolean
    Description

    Generate PBR Maps (metallic, roughness, normal) in addition to the base color. Default to true if not specified.

  • Name
    ai_model
    Type
    string
    Description

    ID of the model to use. Default to meshy-4 if not specified. Available values:

    • meshy-4: equivalent to hard surface_mode
    • meshy-3: equivalent to organic surface_mode
  • Name
    surface_mode
    Type
    string
    Description

    Describe your desired surface mode. Default to organic if not specified. Available values:

    • organic
    • hard
  • Name
    topology
    Type
    string
    Description

    Specify the topology of the generated model. Default to triangle if not specified. Available values:

    • quad: Generate a quad-dominant mesh.
    • triangle: Generate a decimated triangle mesh.
  • 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:

    • Premium users: 3,000 to 100,000 (inclusive)
    • Free users: 10,000 to 30,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 a triangular mesh, ignoring topology and target_polycount. Default to true if not specified.

Returns

The result property of the response contains the task id of the newly created Image To 3D task.

Request

POST
/openapi/v1/image-to-3d
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -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>",
    "enable_pbr": true,
    "should_remesh": true
  }'


 ## Using Data URI example
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}",
    "enable_pbr": true,
    "should_remesh": true
  }'

Response

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

GET/openapi/v1/image-to-3d/:id

Retrieve an Image To 3D Task

This endpoint allows you to retrieve an Image To 3D task given a valid task id. Refer to The Image To 3D Task Object to see which properties are included with Image To 3D task object.

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the Image To 3D task to retrieve.

Returns

The response contains the Image To 3D task object. Check The Image To 3D Task Object section for details.

Request

GET
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v1/image-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=***",
    "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=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": ""
  }
}

The Image To 3D Task Object

The Image To 3D Task object is a work unit that Meshy keeps track of to generate a 3D model from an image input. 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_url
    Type
    string
    Description

    Downloadable URL to the textured 3D model file generated by Meshy.

  • 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
      obj
      Type
      string
      Description

      Downloadable URL to the OBJ file.

    • Name
      usdz
      Type
      string
      Description

      Downloadable URL to the USDZ file.

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

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the task was created, in miliseconds.

  • Name
    expires_at
    Type
    timestamp
    Description

    Timestamp of when the task result expires, 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.

  • 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 Image 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=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?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=***",
  "progress": 1,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": ""
  },
}