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
ai_model
Type
string
Description
ID of the model to use.

Available values:

meshy-4: equivalent to hard surface_mode
Default to meshy-4 if not specified.

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:

Premium users: 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 a triangular mesh, ignoring topology and target_polycount.

Default to true if not specified.

Name
enable_pbr
Type
boolean
Description
Generate PBR Maps (metallic, roughness, normal) in addition to the base color.

Default to false if not specified.

Name
should_texture
Type
boolean
Description
The should_texture flag determines if textures are generated. Setting it to false skips the texture phase, providing a mesh without textures for 5 credits. Setting it to true adds texture generation, costing an additional 10 credits. 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.

Name
texture_prompt
Type
string
Description
Provide a text prompt to guide the texturing process.

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

Request
cURL
JavaScript
Python
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,
    "should_texture": 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,
    "should_texture": true
  }'

Copy
Copied!
Response
{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Copy
Copied!
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
cURL
JavaScript
Python
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}"

Copy
Copied!
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": ""
  }
}

Copy
Copied!
GET
/openapi/v1/image-to-3d
List Image to 3D Tasks
This endpoint allows you to retrieve a list of Image to 3D tasks.

Parameters
Optional attributes
Name
page_num
Type
integer
Description
Page number for pagination. Starts and defaults to 1.

Name
page_size
Type
integer
Description
Page size limit. Defaults to 10 items. Maximum allowed is 50 items.

Name
sort_by
Type
string
Description
Field to sort by. Available values:

+created_at: Sort by creation time ascendly.
-created_at: Sort by creation time descendly.
Returns
Returns a paginated list of The Image to 3D Task Objects.

Request
cURL
JavaScript
Python
GET
/openapi/v1/image-to-3d
curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Copy
Copied!
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": ""
    }
  }
]

Copy
Copied!
GET
/openapi/v1/image-to-3d/:id/stream
Stream an Image to 3D Task
This endpoint streams real-time updates for an Image to 3D task using Server-Sent Events (SSE).

Parameters
Name
id
Type
path
Description
Unique identifier for the Image to 3D task to stream.

Returns
Returns a stream of The Image to 3D Task Objects as Server-Sent Events.

For PENDING or IN_PROGRESS tasks, the response stream will only include necessary progress and status fields.

Request
cURL
JavaScript
Python
GET
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Copy
Copied!
Response Stream
// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "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": ""
  }
}

Copy
Copied!
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. 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
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, 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 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": ""
  },
}