Retexture API

Required unless you send model_url. The ID of a task that produced a 3D model to texture, for example a Text to 3D, Image to 3D, Remesh, or Retexture task. The task must be one you created with the API and have the status SUCCEEDED. Meshy textures the task's GLB.

Required unless you send input_task_id. The model to texture, as a public URL or a data URI. If you send both, Meshy uses input_task_id.

The model must be a GLB, glTF, OBJ, FBX, or STL file of at most 400 MB from an http or https URL, or 100 MB as a data URI. For a data URI, use the MIME type application/octet-stream, for example data:application/octet-stream;base64,<your base64-encoded model data>.

A file over 100 MB must also follow these rules:

• A GLB, glTF, FBX, or OBJ file can have at most 10,000,000 faces. Meshy counts faces as triangles, so a quad counts as 2, and a mesh drawn more than once counts once per copy.
• An FBX file must be binary FBX 7.1 or newer.
• A GLB or glTF file must not use Draco compression.

Required unless you send image_style_url or multiview_image_urls. Text that describes the texture you want, up to 800 characters. Longer text returns 400.

Required unless you send text_style_prompt or multiview_image_urls. A 2D image whose style the texture follows, as a public URL or a data URI (data:image/jpeg;base64,<your base64-encoded image data>). If you send both text_style_prompt and image_style_url, Meshy uses image_style_url.

The image must be a .jpg, .jpeg, .png, or .webp file of at most 20 MB.

The texture might not fit well when the object in the image has a very different shape from the model.

Required unless you send text_style_prompt or image_style_url. One to four images of the same object from different views. The first image is the main (front) view. The order of the other views (left, back, right) doesn't matter. An empty array, or more than four images, returns 400.

Each image follows the same format and size rules as image_style_url, at most 20 MB per image. You can't combine multiview_image_urls with text_style_prompt or image_style_url.

multiview_image_urls needs an explicit "ai_model": "meshy-7". Any other ai_model, including the default latest, returns 400.

The AI model that generates the texture.

Available values:

• meshy-6-lite
• meshy-6
• meshy-7
• latest: Meshy 7

Whether to keep the model's UV layout instead of generating a new one.

• For a model Meshy generated, from input_task_id or a model_url that points to a Meshy output, use true to reuse its optimized UV layout.
• For a model you uploaded from elsewhere, use true to keep UVs that are already good. Leave it false to let Meshy generate new UVs, which suits a model without proper UV mapping.

Whether to also generate PBR maps (metallic, roughness, and normal) with the base color. With meshy-6, Meshy also generates an emission map, except at a texture_resolution of 8k. meshy-6-lite, meshy-7, and latest don't generate an emission map.

The size of the base color texture. Higher resolutions capture more surface detail.

Available values:

• 2k: 2048 × 2048 pixels
• 4k: 4096 × 4096 pixels
• 8k: 8192 × 8192 pixels

4k and 8k need an ai_model of meshy-6, meshy-7, or latest. With meshy-6-lite, they return 400. At 8k, Meshy doesn't generate an emission map.

Use texture_resolution instead. true is the same as texture_resolution: "4k". If you send both, Meshy uses texture_resolution.

Whether to remove highlights and shadows from the base color texture. The result works better under your own lighting.

Meshy applies it only with meshy-6, at a texture_resolution of 2k or 4k. With meshy-7 or latest, or at 8k, Meshy accepts it and ignores it. With meshy-6-lite, sending it with any value returns 400.

The file formats to generate. Meshy generates only the formats you list, which can shorten the task. If you leave it out, Meshy generates every format except 3mf.

Available values:

• glb
• obj
• fbx
• stl
• usdz
• 3mf

Whether to also render a preview with a transparent background (RGBA), returned in alpha_thumbnail_url when you get the task. thumbnail_url doesn't change.

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

• Missing parameter: Neither model_url nor input_task_id was sent.
• Missing style: None of text_style_prompt, image_style_url, and multiview_image_urls was sent.
• Conflicting style inputs: multiview_image_urls was sent with text_style_prompt or image_style_url.
• Unsupported model for multi-view: multiview_image_urls was sent without an explicit "ai_model": "meshy-7".
• Invalid input task: input_task_id isn't a successful task of a supported type.
• Invalid model format: The model_url file has an unsupported extension.
• Unreachable URL: Meshy can't download the model_url file, the image_style_url image, or a multiview_image_urls image.
• Model file too large: The model_url file is over 400 MB from an http or https URL, or over 100 MB as a data URI.
• Too many faces: The model_url file is over 100 MB and has more than 10,000,000 faces. Reduce the face count, then send the file again.
• ASCII FBX over 100 MB: The model_url file is an ASCII FBX over 100 MB. Send it as binary FBX or GLB.
• Unreadable model file: The model_url file is over 100 MB, and Meshy can't read its header. For example, it's a Draco-compressed GLB or glTF, or a binary FBX older than 7.1.
• Model header too complex: The model_url file is over 100 MB, and its header has too many meshes, nodes, or records to check. Reduce the number of objects in the file, then send it again.
• Image too large: The image_style_url image or a multiview_image_urls image is over 20 MB.

Fix the request, then send it again. 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.

input_task_id is a bas-relief model, which this endpoint can't retexture. The message is This model type does not support this operation. Send a different model.

input_task_id doesn't match any of your tasks. Check the task ID, then send the request again.

You exceeded your rate limit. Wait, then retry. See Rate limits.

The task ID from the create response.

The ID of the task to delete.

The page number to return.

The number of tasks per page, up to 100.

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

Download URLs for the textured 3D model, one per file format.

The text prompt you created the task with.

The style image you created the task with.

Download URLs for the multi-view reference images you created the task with. Present only when you created the task with multiview_image_urls.

Download URL for a thumbnail image of the model.

Download URL for a version of thumbnail_url with a transparent background (RGBA). Present only when you created the task with alpha_thumbnail: true and Meshy rendered the transparent preview.

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

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

Time the task was created, in Unix milliseconds.

Time the task's results expire, in Unix milliseconds.

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

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

Download URLs for the generated textures, as an array of objects. The array usually holds one object. Each object has these fields:

The number of tasks ahead of this one in the queue. Present only while the task is PENDING.

The error details when the task fails. See Errors.

The number of credits the task used. Present when the status is PENDING, IN_PROGRESS, or SUCCEEDED. It's 0 for a FAILED task, because Meshy refunds the credits when a task fails.