Creative Lab Keycap API

The photo to turn into a keycap design, as a public URL or a data URI (data:image/jpeg;base64,<your base64-encoded image data>).

The image must be a JPG, JPEG, PNG, or WebP file of at most 20 MB (20,000,000 bytes). Each side must be at least 32 pixels, and the image can have at most 178,956,970 pixels in total. An image outside these limits returns 400.

Meshy detects the format from the image data, not from the file extension in the URL. A URL with no extension works, and Meshy follows HTTP redirects. Meshy applies the EXIF orientation, so a rotated phone photo comes out the way it looks.

A data URI must be base64-encoded with an image type, such as data:image/png;base64,..., and the decoded image must be JPEG, PNG, or WebP. The 20 MB limit applies to the decoded image, so the base64 text can be about a third larger.

A name for the task, up to 100 characters. It comes back in the task's name field. A longer name returns 400.

Whether to remove the background from the prototype image. true returns a transparent RGBA PNG, so you can place the keycap on any background. If Meshy can't remove the background, it returns the image with its background, and the task still succeeds.

The head design that the build turns into 3D keeps its background either way. The build paints the keycap base from the image in image_urls, without its background if you sent true. The build returns that image as process_image_urls.composite.

The request can't run. For example:

• image_url is missing.
• The image isn't a JPG, JPEG, PNG, or WebP file.
• The image is too small, over 20 MB, or over the maximum pixel count.
• Meshy can't download the image, for example because the URL returns 404 or times out.
• The data URI isn't valid base64.
• The image was flagged as NSFW.

The error message says which problem it found. Fix the request, then send it again.

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

One of these applies:

• The account doesn't have enough credits.
• The API key, workspace, or member reached its credit limit.
• The account is on the free plan.

Check your credits and plan, then retry.

Your team has IP Filtering turned on, and Meshy flagged the image for third-party intellectual property. Send an image you have the rights to use.

One of these limits was reached:

• You sent more requests than your rate limit allows. Wait a few seconds, 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.

Meshy hit a server error, for example because content moderation or the intellectual property check couldn't run, or Meshy couldn't store the image. Meshy doesn't create the task, and refunds any credits it charged. Retry the request.

The ID of the prototype task to build. It must be a task your account created with POST /openapi/creative-lab/keycap/v1/prototype, with the status SUCCEEDED.

An ID that isn't one of your Keycap prototype tasks from the API returns 404, including a prototype made in the web app.

The candidate to build, from the candidate_ids array of the prototype task. A value that isn't in that array returns 400.

A name for the task, up to 100 characters. It comes back in the task's name field. A longer name returns 400.

The keycap base to build on. The only value is cherry-mx-1x1-r1, a standard Cherry MX profile 1u keycap. Custom sizes aren't supported, and any other value returns 400.

The size of the head along its longest dimension, in millimeters, from 10 to 40. Meshy scales the head so its longest dimension matches this value. A value outside the range returns 400.

For a value above about 32.9, Meshy might reduce the size so the head fits the base's protective footprint limit. The head can then come out smaller than you asked. The task object doesn't return the size Meshy applied. To check it, measure the bounding box of the keycap-head mesh in the model.

The vertical offset to apply to the head before Meshy seats it on the base, in millimeters, from -5 to 5. A value outside the range returns 400.

The request can't run. For example:

• input_task_id is missing or isn't a valid task ID.
• The prototype task's status isn't SUCCEEDED. If it's still running, wait and retry. If it failed or was canceled, create a new prototype task.
• The prototype task succeeded but has no candidates. Create a new prototype task.
• candidate_id is missing, or isn't in the prototype task's candidate_ids. Send a value from that array.
• A field in options is out of range, or base_model isn't an available value.

The error message says which problem it found.

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

One of these applies:

• The account doesn't have enough credits.
• The API key, workspace, or member reached its credit limit.
• The account is on the free plan.

Check your credits and plan, then retry.

input_task_id doesn't match any Keycap prototype task your account created with the API. A prototype made in the web app also returns 404. Send the result ID from a prototype create response.

One of these limits was reached:

• You sent more requests than your rate limit allows. Wait a few seconds, 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.

Meshy couldn't create the task because of a server error. Meshy refunds any credits it charged. Retry the request.

The task ID from the create response.

id isn't a valid task ID. Send the result ID from the create response.

Your team has IP Filtering turned on, and Meshy flagged the prototype task's image for third-party intellectual property. Build tasks and teams on the Enterprise plan don't get this error. Create a prototype task from an image you have the rights to use.

No Keycap task with this ID belongs to your account, or the task's stage doesn't match the path. Check the ID, and use /prototype or /build to match the task.

Meshy couldn't run the intellectual property check. Retry the request.

The ID of the task to cancel.

One of these applies:

• id isn't a valid task ID. Send the result ID from the create response.
• The task already has a final status (SUCCEEDED, FAILED, or CANCELED), so it can't be canceled.

No Keycap task with this ID belongs to your account, or the task's stage doesn't match the path. Check the ID, and use /prototype or /build to match the task.

Meshy hit a server error while canceling the task, so the task might or might not be canceled. Get the task to check its status before you retry.

The task ID from the create response.

The stage to list, prototype or build.

The page to return, from 1 to 255. 0 returns the first page. A value outside 0 to 255 returns 400.

Number of tasks per page, up to 100. A value from 101 to 255 returns 100 tasks, and 0 uses the default. A value outside 0 to 255 returns 400.

The sort order.

Available values:

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

The task ID. Don't rely on its format.

The task type, always creative-lab-keycap-prototype.

The name you sent when you created the task, or "" if you didn't send one.

The task's status.

Available values:

• PENDING: waiting in the queue
• IN_PROGRESS: generating the result
• SUCCEEDED: final, with the result
• FAILED: final, with the reason in task_error
• CANCELED: final, with no result

Percentage of the work done, from 0 to 100. It's 0 until the task starts and 100 when it succeeds.

Time the task was created, in Unix milliseconds.

Time a worker started the task, in Unix milliseconds. null until then.

Time the task reached a final status, in Unix milliseconds. null until then.

Time the task's result expires, in Unix milliseconds. It's 3 days after finished_at, or 3 days after created_at until the task finishes. For Enterprise accounts, which keep API results indefinitely, it's about 100 years later. See Asset retention.

The task's position in the queue while it's PENDING. 1 means it starts next. 0 after the task leaves the queue, and always 0 in list results.

Why the task failed. null unless status is FAILED. See Errors.

Number of credits charged for the task, after any refund. A request that returns an error isn't charged. A failed task is 0, because Meshy refunds it. Canceling refunds a task only while it's PENDING. If Meshy can't read the charge, a get or stream response leaves the field out, and a list request returns 500. In that case, retry the request.

Download URLs for the image of the finished keycap. The array has one URL after the task succeeds, and is empty until then. image_urls[i] shows the candidate in candidate_ids[i].

These URLs are for display. The build endpoint takes an entry from candidate_ids, not a URL. They're signed URLs, so fetch them without an Authorization header. They stay valid until expires_at, and getting the task again returns the same URLs.

IDs of the candidates, in the same order as image_urls. To build a candidate, send its ID as candidate_id in the build request. Don't rely on the format of these IDs.

The task ID. Don't rely on its format.

The task type, always creative-lab-keycap-build.

The name you sent when you created the task, or "" if you didn't send one.

The task's status.

Available values:

• PENDING: waiting in the queue
• IN_PROGRESS: generating the result
• SUCCEEDED: final, with the result
• FAILED: final, with the reason in task_error
• CANCELED: final, with no result

Percentage of the work done, from 0 to 100. It's 0 until the task starts and 100 when it succeeds.

Time the task was created, in Unix milliseconds.

Time a worker started the task, in Unix milliseconds. null until then.

Time the task reached a final status, in Unix milliseconds. null until then.

Time the task's result expires, in Unix milliseconds. It's 3 days after finished_at, or 3 days after created_at until the task finishes. For Enterprise accounts, which keep API results indefinitely, it's about 100 years later. See Asset retention.

The task's position in the queue while it's PENDING. 1 means it starts next. 0 after the task leaves the queue, and always 0 in list results.

Why the task failed. null unless status is FAILED. See Errors.

Number of credits charged for the task, after any refund. A request that returns an error isn't charged. A failed task is 0, because Meshy refunds it. Canceling refunds a task only while it's PENDING. If Meshy can't read the charge, a get or stream response leaves the field out, and a list request returns 500. In that case, retry the request.

Download URLs for the 3D model. Meshy exports the GLB file and the OBJ bundle at real-world scale in millimeters, Y-up, with the front of the keycap facing +Z.

The model has meshes named keycap-head and keycap-base. When Meshy falls back to a pattern fill for the base, the model also has a keycap-base-interior mesh for the stem cavity. Don't assume the model has exactly two meshes.

These are signed URLs, so fetch them without an Authorization header. They stay valid until expires_at, and getting the task again before then returns the same URLs. An expired URL can't be renewed, so download and store the files before then.

Download URLs for images from the build's steps, keyed by kind. Like model_urls, they're signed URLs, so fetch them without an Authorization header. They stay valid until expires_at, and getting the task again returns the same URLs.

It can have these keys:

• head_design: the design image of the chosen candidate, which the build turned into 3D. Always present.
• composite: the image of the finished keycap for the chosen candidate, which the build painted the base from. Can be missing.
• base_canvas: the painted keycap base. Can be missing.

Meshy may add keys, so ignore a key you don't recognize.