Image To 3D API

This is the legacy API for Image to 3D using Meshy-3. 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/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>.
Name
ai_model
Type
string
Description
ID of the model to use. Available values:
- meshy-3

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

# Using publicly accessible image url
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>",
    "ai_model": "meshy-3"
  }'


# 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}",
    "ai_model": "meshy-3"
  }'

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_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.
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
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.
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 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": ""
  },
}