Relief API

The photo to turn into a relief, as a public URL or a data URI (data:image/png;base64,...).

The image must be a JPG, JPEG, PNG, or WebP file of at most 20 MB, and at least 32 × 32 pixels. Its longer side can be at most about 16 times its shorter side. Any other image returns 400. Meshy fills transparent areas with black before it builds the relief.

The relief style. It shapes the depth map and sets the default carving_depth_mm.

Available values:

• high: deeper carving, for 3D-printed pieces.
• low: shallow carving, for laser engraving, CNC carving, and thin plaques.

Sending null or "" is the same as leaving it out. Any other value returns 400.

Whether to build the relief model. Set it to false for a depth-map-only task, with no model and no preview image. Meshy still checks the size, carving, base, bend, and resolution parameters, but doesn't use them. It doesn't change the credit cost.

The length of the photo's longer side on the model, measured flat before any bend, from 20 to 250 millimeters. With remove_base, the model can be smaller.

Whether the subject stands out from the plate or is cut into it.

Available values:

• emboss: the nearer parts of the photo stand out.
• engrave: the depth is inverted, so the nearer parts are cut in.

The depth map is the same in both modes.

How deep the relief is carved, from 0 to 60 millimeters. With remove_base set to true, 0 leaves an empty model. The task still succeeds and costs 20 credits, and its GLB and STL files have no geometry.

Whether to cut away the background and build no base plate. When it's true, removal_threshold sets what counts as background. Meshy checks removal_threshold either way.

The thickness of the base plate, from 0.1 to 10 millimeters. When remove_base is true, leave it out or send 0.

Whether to bend the relief, and which way. When it isn't off, bend_axis and bend_angle shape the bend. Meshy checks them either way.

Available values:

• off: a flat relief.
• convex: the front bulges outward.
• concave: the front curves inward.

The number of mesh points along the photo's longer side, from 512 to 2048. A higher value keeps finer detail and makes larger files. At the default 1024, the GLB file is about 40 to 50 MB and the STL file about 80 to 105 MB. A square photo gives the larger sizes. At 2048, they are about 150 MB and 300 MB. A bend makes them larger: the STL file can reach about 800 MB at 2048.

The request can't run. The error message says which problem it found. For example:

• Missing parameter: image_url wasn't sent.
• Invalid parameter: A parameter has the wrong type, is outside its range, or isn't one of its available values. For example, variant isn't high or low, or mesh_resolution isn't an integer from 512 to 2048.
• Base thickness: base_thickness_mm isn't 0 with remove_base set to true, or is below 0.1 without it.
• Unreachable URL: Meshy can't download the image_url image, for example because the URL returns 404 or times out.
• Invalid image: The image isn't a JPG, JPEG, PNG, or WebP file, is over 20 MB, is smaller than 32 × 32 pixels, has too many pixels, or can't be read.
• Extreme aspect ratio: The image's longer side is more than about 16 times its shorter side.

Fix the request, then send it again. Meshy doesn't charge for it. See Errors.

The API key is missing or invalid. Check the Authorization header.

For example:

• Insufficient credits: The account doesn't have enough credits for this task, or the account reached a credit limit. Check your credit balance, then retry.
• Free plan: Creating a task requires a paid plan. Upgrade your plan in your subscription settings, then retry.

Content moderation blocked the image. Meshy doesn't charge for the request. Send a different image.

One of these limits was reached:

• You sent too many requests. Wait, then retry. See Rate limits.
• Too many of your tasks are queued or running. Wait for some to finish, then retry.
• On an unlimited plan with no credits left, you reached the number of tasks that can run without credits. Wait for a task to finish, or add credits.

The task ID from the create response.

The ID of the task to delete.

The page number to return. Starts at and defaults to 1.

The number of tasks per page, up to 100. Defaults to 10. Meshy treats a value from 101 to 255 as 100, and a larger value returns 400.

The sort order.

Available values:

• +created_at: oldest first
• -created_at: newest first

The task ID from the create response.

The task ID. Treat it as an opaque string, and don't rely on its format.

The task type, always relief.

Download URLs for the relief model. The files can be large; mesh_resolution lists typical sizes.

Download URL for the 16-bit grayscale depth map the relief is built from. Brighter pixels are higher. The values are relative heights, not millimeters. Laser engraving and CNC software can use it as a height map. The file is about 1 to 2 MB. Empty if there is none.

Download URL for a preview image of the relief model. Empty if none was rendered, including for a depth-map-only task.

How much of the task is done, as a percentage. It's 0 until the task starts and 100 when it succeeds.

The task status, one of PENDING, IN_PROGRESS, SUCCEEDED, or FAILED.

The number of tasks ahead of this one in the queue. The field is left out when the value is 0, so it appears only while tasks are ahead of this one.

Time the task was created, in Unix milliseconds.

Time the task started, in Unix milliseconds. It's 0 until the task starts.

Time the task finished, in Unix milliseconds. It's 0 until the task finishes.

Time the task's result expires, in Unix milliseconds. It's 0 until the task finishes.

The error details when the task fails. See Errors.

The number of credits the task used: 20, or 0 for a FAILED task, which Meshy refunds.