Creative Lab — Keycap API

Source photo for Meshy to turn into keycap design images. We currently support .jpg, .jpeg, .png, and .webp formats.

The format is detected by decoding the image data, not from the URL's file extension — a URL with no extension, or one that redirects, works as long as the bytes decode to a supported format. HTTP redirects are followed. EXIF orientation is normalized, so a rotated phone photo is used the way it looks.

Limits: at least 32 pixels on each side, at most 178,956,970 pixels in total, and at most 20,000,000 bytes once downloaded. For a data URI the limit applies to the decoded bytes, so the source file itself may be up to that size — it is the base64 text that is about a third larger, which matters for your request body, not for this limit. A data URI must declare an image/* content type and ;base64.

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 task name for display purposes. Maximum 100 characters.

The request was unacceptable. Common causes:

• Missing parameter: image_url is required.
• Invalid image format: The provided image_url is not a supported format (.jpg, .jpeg, .png, .webp).
• Image dimensions out of range: The image is too small, exceeds the maximum file size, or exceeds the maximum pixel count.
• Unreachable URL: The image_url could not be downloaded (404 or timeout).
• Invalid Data URI: The base64 string is malformed.
• Content flagged: The input image was flagged by NSFW moderation.

Authentication failed. Please check your API key.

The account is on the free plan (a paid plan is required to create tasks) or has insufficient credits.

The input image was flagged by intellectual property moderation.

You have exceeded your rate limit.

An unexpected server-side error occurred — for example the content-moderation service was unavailable, staging the input image failed, or the task could not be created. No task is created in this case, so retrying is safe.

The task ID of a prototype task created via this same OpenAPI endpoint. The prototype must have been created by the same Meshy account, must have reached SUCCEEDED, and must have produced at least one candidate.

Prototype tasks created through the webapp are not accepted — the build endpoint accepts only prototype tasks produced by POST /openapi/creative-lab/keycap/v1/prototype and refuses any other source with 404.

The candidate to build, taken from the candidate_ids array of the succeeded prototype task. Must belong to that task; any other value is rejected with 400.

Optional task name for display purposes. Maximum 100 characters.

The keycap base to build on. Currently the only available value is cherry-mx-1x1-r1 — a standard Cherry MX profile 1u keycap. 3–5 additional mainstream standard sizes are planned; custom sizes are not supported.

Target size of the sculpted head, in millimeters: its longest dimension is scaled to this value. Range: [10, 40]. Values above roughly 32.9 may be reduced so the head still fits the base's protective footprint limit, so the delivered longest dimension can be smaller than requested. The applied value is not echoed back on the task object today — if you need to confirm the size you actually received, measure the bounding box of the keycap-head mesh in the downloaded model.

Vertical offset applied to the head before it is seated on the base, in millimeters. Range: [-5, 5].

The request was unacceptable. Common causes:

• Missing parameter: input_task_id and candidate_id are required.
• Invalid UUID: The input_task_id is not a valid UUID.
• Parent not succeeded: The referenced prototype task has not reached SUCCEEDED yet.
• No candidates: The prototype task succeeded but produced no candidates.
• Unknown candidate: candidate_id is not one of the input task's candidates.
• Options out of range: One of the options fields fell outside its allowed range or enum set.

Authentication failed. Please check your API key.

The account is on the free plan (a paid plan is required to create tasks) or has insufficient credits.

The referenced prototype task does not exist, belongs to a different user, or was created through the webapp (only API-mode prototype tasks chain into build).

You have exceeded your rate limit.

An unexpected server-side error occurred — for example the content-moderation service was unavailable, staging the input image failed, or the task could not be created. No task is created in this case, so retrying is safe.

Unique identifier for the keycap task to retrieve.

Unique identifier for the keycap task to cancel.

The task is already in a terminal state and cannot be cancelled.

The task does not exist, belongs to a different user, or its stage does not match the URL path.

An unexpected server-side error occurred while cancelling. The task may or may not have been cancelled — re-read it to confirm before retrying.

Unique identifier for the keycap task to stream.

Either prototype or build. The collection returns only tasks whose stage matches the URL — fetching /prototype never returns build tasks and vice versa.

Page number for pagination.

Page size limit. Maximum allowed is 100 items.

Field to sort by. Available values:

• +created_at: Sort by creation time in ascending order.
• -created_at: Sort by creation time in descending order.

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.

Type of the task. The value is creative-lab-keycap-prototype.

The task name supplied when the task was created. Empty string if no name was provided.

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

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.

Timestamp of when the task was created, in milliseconds.

Timestamp of when the task was started, in milliseconds. If the task is not started yet, this property will be 0.

Timestamp of when the task was finished, in milliseconds. If the task is not finished yet, this property will be 0.

Timestamp of when the task result expires, in milliseconds.

The count of preceding tasks.

Error details for failed tasks. See Errors for the full task_error object reference.

The number of credits consumed by this task. A task that reaches SUCCEEDED is charged the full amount for its stage. A task that never gets created (a 4xx at request time, including a moderation rejection) is not charged at all. A task that reaches FAILED returns 0 — the charge is refunded, including an asynchronous moderation block. Cancelling via DELETE refunds only while the task is still PENDING; a task already IN_PROGRESS stays charged, because the work has been spent.

Downloadable URL of the finished-keycap design render — what the candidate looks like as a finished keycap. Holds a single entry; image_urls[i] corresponds to candidate_ids[i]. Empty until the task reaches SUCCEEDED. The URL is for display only; the build endpoint consumes candidate_ids, not these URLs. Same URL lifecycle as model_urls: signed, no Authorization header, valid until expires_at, and stable when the task is re-read.

Opaque candidate identifiers, parallel to image_urls. Pass the entry matching your chosen design as the build request's candidate_id. Do not make any assumptions about the format of these ids.

Unique identifier for the task.

Type of the task. The value is creative-lab-keycap-build.

The task name supplied when the task was created. Empty string if no name was provided.

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

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.

Timestamp of when the task was created, in milliseconds.

Timestamp of when the task was started, in milliseconds.

Timestamp of when the task was finished, in milliseconds.

Timestamp of when the task result expires, in milliseconds.

The count of preceding tasks. Meaningful only when status is PENDING.

Error details for failed tasks. See Errors for the full task_error object reference.

The number of credits consumed by this task. A task that reaches SUCCEEDED is charged the full amount for its stage. A task that never gets created (a 4xx at request time, including a moderation rejection) is not charged at all. A task that reaches FAILED returns 0 — the charge is refunded, including an asynchronous moderation block. Cancelling via DELETE refunds only while the task is still PENDING; a task already IN_PROGRESS stays charged, because the work has been spent.

Downloadable URLs for the generated model artifacts. Both the GLB and the OBJ bundle are exported at real-world millimeter scale, Y-up, with the front of the keycap facing +Z. Meshes are named keycap-head and keycap-base; when the base falls back to a pattern fill, a third mesh keycap-base-interior is also present for the stem cavity. Do not assume exactly two meshes.

These are signed URLs: fetch them without an Authorization header. They stay valid until expires_at, which is 3 days after finished_at, and re-reading the task inside that window returns the identical URL rather than a freshly signed one. Download and store the files yourself before then — there is no way to refresh an expired link.

Downloadable URLs for intermediate process images, keyed by kind. Same URL lifecycle as model_urls: signed, no Authorization header, valid until expires_at, and stable when the task is re-read. Currently emitted kinds:

• head_design — the chosen candidate's design image the build consumed (always present).
• composite — the finished-keycap display render of the chosen candidate (present when available).
• base_canvas — the painted keycap-base canvas (present when available).

Treat the key set as open-ended; new kinds may be added without a breaking change.