27/02/2025 07:56 Image to 3D API - Meshy Docs

Open Web App

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

image_url string

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

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 1/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

ai_model string
Open Web App
ID of the model to use.

Available values:

meshy-4 : equivalent to hard surface_mode

Default to meshy-4 if not specified.

topology string

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.

target_polycount integer

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.

should_remesh boolean

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.

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 2/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

Default to true if not specified.

Open Web App

enable_pbr boolean

Generate PBR Maps (metallic, roughness, normal) in addition to the base

color.

Default to false if not specified.

should_texture boolean

The should_texture flag controls whether to enable the texture phase.

When set to false, it skips the texture phase, resulting in a mesh without
textures. Default to true if not specified.

symmetry_mode string

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.

texture_prompt string

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.

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 3/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

Request cURL Open Python

JavaScript Web App

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
}'

Response

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

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

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 4/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

Retrieve an Image to 3D Task

Open Web App

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

id path

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-1f1776f
-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-1f1776f7f5
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f5
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f5
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 5/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

"expires_at": 1692771679037,
"finished_at": 1692771669037, Open Web App

"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f177
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f
}
],
"preceding_tasks": 0,
"task_error": {
"message": ""
}
}

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

page_num integer

Page number for pagination. Starts and defaults to 1 .

page_size integer

Page size limit. Defaults to 10 items. Maximum allowed is 50 items.

sort_by string

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 6/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

Field to sort by. Available values:

Open Web App

+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}"

Response

[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-
"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
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 7/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1
Open Web App
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-
}
],
"preceding_tasks": 0,
"task_error": {
"message": ""
}
}
]

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

id path

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

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 8/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

Open Web App

curl -N https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f17
-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.

// For PENDING or IN_PROGRESS tasks, the response stream will not include all fi
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
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f57
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f
"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-1
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1
https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 9/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f177
Open Web App
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f
}
],
"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

id string

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.

model_urls object

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.

glb string

Downloadable URL to the GLB file.

fbx string

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 10/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

Downloadable URL to the FBX file.

Open Web App

obj string

Downloadable URL to the OBJ file.

usdz string

Downloadable URL to the USDZ file.

thumbnail_url string

Downloadable URL to the thumbnail image of the model file.

progress integer

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 .

started_at timestamp

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.

created_at timestamp

Timestamp of when the task was created, in miliseconds.

expires_at timestamp

Timestamp of when the task result expires, in miliseconds.

finished_at timestamp

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 11/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

Timestamp of when the task was finished, in miliseconds. If the task is not
Open Web App
finished yet, this property will be 0 .

status string

Status of the task. Possible values are one of PENDING , IN_PROGRESS ,

SUCCEEDED , FAILED , CANCELED .

texture_urls array

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:

base_color string

Downloadable URL to the base color map image.

metallic string

Downloadable URL to the metallic map image.

If the task is created with enable_pbr: false , this property

will be omitted.

normal string

Downloadable URL to the normal map image.

If the task is created with enable_pbr: false , this property

will be omitted.

roughness string

Downloadable URL to the roughness map image.

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 12/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

If the task is created with enable_pbr: false , this property Open Web App
will be omitted.

preceding_tasks integer

The count of preceding tasks.

The value of this field is meaningful only if the task status is

PENDING .

task_error object

Error object that contains the error message if the task failed. The

message property should be empty if the task succeeded.

message string

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-1f1776f7f5
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f5
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f5
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f
"progress": 1,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 13/14
27/02/2025 07:56 Image to 3D API - Meshy Docs

"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1
Open Web App
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f177
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f
}
],
"preceding_tasks": 0,
"task_error": {
"message": ""
},
}

Previous Next

Text to 3D Remesh

© 2025 Meshy LLC. All rights reserved.

https://docs.meshy.ai/api/image-to-3d#list-image-to-3d-tasks 14/14