Creative Lab Fridge Magnet API
Turn a photo into a 3D-printable fridge magnet with a colored relief and a flat back, in two stages. A prototype task generates a colorized concept image from the photo. A build task turns that image into a relief 3D model, and takes the prototype task's ID as input_task_id.
POST /openapi/creative-lab/fridge-magnet/v1/prototypePOST /openapi/creative-lab/fridge-magnet/v1/build
Create a Fridge Magnet prototype task
Generates one colorized concept image from a photo. To build the 3D model, pass this task's ID to the build endpoint as input_task_id. For the task's fields, see The Fridge Magnet prototype task object.
Request
# Stage 1: generate a colorized fridge magnet concept image
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype \
-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>"
}'
Response
{
"result": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9"
}
Parameters
- Name
- image_url
- Type
- string
- Required
- Description
The photo to turn into a fridge magnet concept image, 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.
- Name
- name
- Type
- string
- Description
A name for the task, up to 100 characters. It comes back in the task's
namefield. A longer name returns400.
- Name
- remove_background
- Type
- boolean
- default false
- Description
Whether to remove the background from the prototype image.
truereturns a transparent RGBA PNG that keeps the whole magnet, so you can place it on any background. The build also starts from the image without its background. If Meshy can't remove the background, it returns the image with its background, and the task still succeeds.The build's
remove_backgroundoption is separate.
Returns
The result field holds the ID of the new prototype task. Get the task or stream it until status is SUCCEEDED. Then pass the ID to the build endpoint as input_task_id.
Failure modes
- Name
400 - Bad Request- Description
The request can't run. For example:
image_urlis 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
404or 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.
- Name
401 - Unauthorized- Description
The API key is missing or invalid. Check the
Authorizationheader.
- Name
402 - Payment Required- Description
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.
- Name
403 - Forbidden- Description
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.
- Name
429 - Too Many Requests- Description
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.
- Name
500 - Internal Server Error- Description
Meshy hit a server error, for example because it couldn't run the intellectual property check on the image. Meshy doesn't create the task, and refunds any credits it charged. Retry the request.
Create a Fridge Magnet build task
Generates the 3D-printable fridge magnet from a succeeded prototype task. Meshy turns the prototype's concept image into a depth-map relief, and returns one model file in the format you choose. For the task's fields, see The Fridge Magnet build task object.
Request
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
"options": {
"badge_shape": "rounded-rect",
"size_mm": 60,
"relief_height_mm": 3.3
},
"output": {
"format": "glb"
}
}'
Response
{
"result": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0"
}
Parameters
- Name
- input_task_id
- Type
- string
- Required
- Description
The ID of the prototype task to build. It must be a task your account created with
POST /openapi/creative-lab/fridge-magnet/v1/prototype, with the statusSUCCEEDED.An ID that isn't one of your Fridge Magnet prototype tasks from the API returns
404, including a prototype made in the web app.
- Name
- name
- Type
- string
- Description
A name for the task, up to 100 characters. It comes back in the task's
namefield. A longer name returns400.
options
Optional settings for the relief's shape. Every field has a default, so send only the ones you want to change. A value outside a field's range returns 400.
- Name
- badge_shape
- Type
- string
- default rounded-rect
- Description
The magnet's outline when Meshy doesn't trace it from the subject. Meshy uses it when
remove_backgroundisfalse, or when it can't find the subject's outline.Available values:
circlerounded-recthexagonshieldstar
- Name
- size_mm
- Type
- number
- default 60
- Description
The edge length of the magnet's bounding square, in millimeters, up to
400.0uses the default.
- Name
- relief_height_mm
- Type
- number
- default 3.3
- Description
The relief's maximum height above the base, in millimeters, from
0to20.
- Name
- relief_offset_mm
- Type
- number
- default 0
- Description
How far to lower the relief, in millimeters, from
0to20. Meshy subtracts it from the relief's height everywhere, down to the base.
- Name
- base_thickness_mm
- Type
- number
- default 2.0
- Description
The thickness of the flat base plate behind the relief, in millimeters, from
0to20. The default 2 mm base gives the magnet enough body to grip the fridge, so the relief doesn't feel fragile.
- Name
- has_closed_back
- Type
- boolean
- default true
- Description
Whether to close the back of the magnet, the side you glue the magnet to.
falseleaves the back open, as a shell.
- Name
- relief_curve
- Type
- string
- default linear
- Description
The curve that maps depth-map values to relief height.
Available values:
lineargammas-curve
- Name
- curve_param
- Type
- number
- default 1.0
- Description
The strength of the curve, up to
10. Thegammaands-curvecurves use it, andlinearignores it.0uses the default.
- Name
- invert_depth
- Type
- boolean
- default false
- Description
Whether to invert the depth map, so darker areas become higher relief.
- Name
- smoothing
- Type
- number
- default 0.24
- Description
How much to smooth the depth map before Meshy builds the relief, from
0to10.
- Name
- relief_scale
- Type
- number
- default 1.0
- Description
How much to zoom the relief and its texture inside the outline, about the center, up to
10. A value over1enlarges the subject, and a value under1shrinks it. It doesn't change the relief's height.0uses the default.
- Name
- depth_threshold
- Type
- number
- default 0.1
- Description
The depth-map value under which Meshy sets the depth to zero, from
0to1.
- Name
- remove_background
- Type
- boolean
- default true
- Description
Whether to trace the magnet's outline from the subject, so the magnet follows the subject's shape.
falseuses thebadge_shapeoutline instead. Meshy also usesbadge_shapewhen it can't find the subject's outline.This is separate from the prototype's
remove_backgroundparameter, which sets whether the prototype image has a transparent background.
- Name
- export_resolution
- Type
- integer
- default 512
- Description
The mesh resolution of the exported model, from
64to512. Meshy builds the geometry from a 512-pixel depth map, so a finer mesh would add faces without adding detail.0uses the default.
output
Optional. Sets the file format the build returns.
- Name
- format
- Type
- string
- default glb
- Description
The file format the build returns.
Available values:
glb: onemodel.glbfile, inmodel_urls.glbobj: a zip file withmodel.obj,model.mtl, andtexture.png, inmodel_urls.objzip: a zip file with every file Meshy generates, inmodel_urls.bundle_zip
Returns
The result field holds the ID of the new build task. Get the task or stream it until status is SUCCEEDED. Then download the file from the one entry in model_urls.
Failure modes
- Name
400 - Bad Request- Description
The request can't run. For example:
input_task_idis 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 image. Create a new prototype task.
- An
optionsfield is outside its range or isn't an available value.
The error message says which problem it found.
- Name
401 - Unauthorized- Description
The API key is missing or invalid. Check the
Authorizationheader.
- Name
402 - Payment Required- Description
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.
- Name
404 - Not Found- Description
input_task_iddoesn't match any Fridge Magnet prototype task your account created with the API. A prototype made in the web app also returns404. Send theresultID from a prototype create response.
- Name
429 - Too Many Requests- Description
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.
Get a Fridge Magnet task
Returns a prototype or build task. The path must match the task's stage. A build task requested through /prototype/:id returns 404, and so does a prototype task requested through /build/:id.
For the fields, see The Fridge Magnet prototype task object and The Fridge Magnet build task object.
Request
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# Build
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Prototype Response
{
"id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
"type": "creative-lab-fridge-magnet-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543210000,
"started_at": 1729543215000,
"finished_at": 1729543242000,
"expires_at": 1729802442000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
Build Response
{
"id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
"type": "creative-lab-fridge-magnet-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543250000,
"started_at": 1729543258000,
"finished_at": 1729543285000,
"expires_at": 1729802485000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
}
}
Parameters
- Name
- id
- Type
- path
- Description
The task ID from the create response.
Returns
The prototype task object or the build task object, matching the stage in the path.
Failure modes
- Name
400 - Bad Request- Description
idisn't a valid task ID. Send theresultID from the create response.
- Name
403 - Forbidden- Description
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.
- Name
404 - Not Found- Description
No Fridge Magnet task with this ID belongs to your account, or the task's stage doesn't match the path. Check the ID, and use
/prototypeor/buildto match the task.
- Name
500 - Internal Server Error- Description
Meshy couldn't run the intellectual property check. Retry the request.
Delete a Fridge Magnet task
Cancels a Fridge Magnet task. Canceling a PENDING task refunds its credits. An IN_PROGRESS task is canceled without a refund, because a worker has already started it. A task with a final status (SUCCEEDED, FAILED, or CANCELED) can't be canceled.
The path must match the task's stage. For example, DELETE on /prototype/:id with a build task's ID returns 404.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// Returns 204 No Content on success (empty body).
Path parameters
- Name
- id
- Type
- path
- Description
The ID of the task to cancel.
Returns
204 No Content with an empty body.
Failure modes
- Name
400 - Bad Request- Description
One of these applies:
idisn't a valid task ID. Send theresultID from the create response.- The task already has a final status (
SUCCEEDED,FAILED, orCANCELED), so it can't be canceled.
- Name
404 - Not Found- Description
No Fridge Magnet task with this ID belongs to your account, or the task's stage doesn't match the path. Check the ID, and use
/prototypeor/buildto match the task.
Stream a Fridge Magnet task
Streams a Fridge Magnet task's updates as Server-Sent Events (SSE). The path must match the task's stage. If it doesn't, for example a build task's ID at /prototype/:id/stream, the stream sends one error event with status_code: 404 and closes.
Request
curl -N https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Error event example (wrong stage or task not found)
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
"id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
"type": "creative-lab-fridge-magnet-build",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543250000,
"started_at": 1729543258000,
"finished_at": 1729543285000,
"expires_at": 1729802485000,
"task_error": null,
"consumed_credits": 30,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
}
}
Parameters
- Name
- id
- Type
- path
- Description
The task ID from the create response.
Returns
A stream of prototype or build task objects. Each event has the full task object, as Get a Fridge Magnet task returns it. While the task is PENDING or IN_PROGRESS, its output fields are still empty (null, [], or {}), and finished_at is null.
If IP Filtering blocks the task's result, the stream sends one error event in its place, with the status_code that a get request would return.
List Fridge Magnet tasks
Returns your Fridge Magnet tasks of one stage, one page at a time. The path selects the stage. /prototype returns only prototype tasks, and /build returns only build tasks.
Request
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response (List Prototype Tasks)
[
{
"id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
"type": "creative-lab-fridge-magnet-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543210000,
"started_at": 1729543215000,
"finished_at": 1729543242000,
"expires_at": 1729802442000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
]
Path parameters
- Name
- stage
- Type
- path
- Required
- Description
The stage to list,
prototypeorbuild.
Query parameters
- Name
- page_num
- Type
- integer
- default 1
- Description
The page to return, from
1to255.0returns the first page. A value outside0to255returns400.
- Name
- page_size
- Type
- integer
- default 10
- Description
Number of tasks per page, up to
100. A value from101to255returns 100 tasks, and0uses the default. A value outside0to255returns400.
- Name
- sort_by
- Type
- string
- default -created_at
- Description
The sort order.
Available values:
-created_at: newest first+created_at: oldest first
Returns
An array of prototype task objects or build task objects, matching the stage in the path.
The Fridge Magnet prototype task object
A prototype task generates a colorized concept image from a photo. To turn the image into a 3D model, pass the task's ID to the build endpoint as input_task_id.
Properties
Example Fridge Magnet Prototype Task Object
{
"id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
"type": "creative-lab-fridge-magnet-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543210000,
"started_at": 1729543215000,
"finished_at": 1729543242000,
"expires_at": 1729802442000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
- Name
- id
- Type
- string
- Description
The task ID. Don't rely on its format.
- Name
- type
- Type
- string
- Description
The task type, always
creative-lab-fridge-magnet-prototype.
- Name
- name
- Type
- string
- Description
The
nameyou sent when you created the task, or""if you didn't send one.
- Name
- status
- Type
- string
- Description
The task's status.
Available values:
PENDING: waiting in the queueIN_PROGRESS: generating the resultSUCCEEDED: final, with the resultFAILED: final, with the reason intask_errorCANCELED: final, with no result
- Name
- progress
- Type
- integer
- Description
Percentage of the work done, from
0to100. It's0until the task starts and100when it succeeds.
- Name
- created_at
- Type
- timestamp
- Description
Time the task was created, in Unix milliseconds.
- Name
- started_at
- Type
- timestamp
- Description
Time a worker started the task, in Unix milliseconds.
nulluntil then.
- Name
- finished_at
- Type
- timestamp
- Description
Time the task reached a final status, in Unix milliseconds.
nulluntil then.
- Name
- expires_at
- Type
- timestamp
- Description
Time the task's result expires, in Unix milliseconds. It's 3 days after
finished_at, or 3 days aftercreated_atuntil the task finishes. For Enterprise accounts, which keep API results indefinitely, it's about 100 years later. See Asset retention.
- Name
- preceding_tasks
- Type
- integer
- Description
The task's position in the queue while it's
PENDING.1means it starts next.0after the task leaves the queue, and always0in list results.
- Name
- task_error
- Type
- object
- Description
Why the task failed.
nullunlessstatusisFAILED. See Errors.
- Name
- consumed_credits
- Type
- integer
- Description
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'sPENDING. If Meshy can't read the charge, a get or stream response leaves the field out, and a list request returns500. In that case, retry the request.
- Name
- image_urls
- Type
- array of strings
- Description
Download URLs for the concept image. The array has one URL after the task succeeds, and is empty until then.
The Fridge Magnet build task object
A build task generates the 3D fridge magnet from a succeeded prototype task. It returns one model file in the format you requested.
Properties
Example Fridge Magnet Build Task Object
{
"id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
"type": "creative-lab-fridge-magnet-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543250000,
"started_at": 1729543258000,
"finished_at": 1729543285000,
"expires_at": 1729802485000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
}
}
- Name
- id
- Type
- string
- Description
The task ID. Don't rely on its format.
- Name
- type
- Type
- string
- Description
The task type, always
creative-lab-fridge-magnet-build.
- Name
- name
- Type
- string
- Description
The
nameyou sent when you created the task, or""if you didn't send one.
- Name
- status
- Type
- string
- Description
The task's status.
Available values:
PENDING: waiting in the queueIN_PROGRESS: generating the resultSUCCEEDED: final, with the resultFAILED: final, with the reason intask_errorCANCELED: final, with no result
- Name
- progress
- Type
- integer
- Description
Percentage of the work done, from
0to100. It's0until the task starts and100when it succeeds.
- Name
- created_at
- Type
- timestamp
- Description
Time the task was created, in Unix milliseconds.
- Name
- started_at
- Type
- timestamp
- Description
Time a worker started the task, in Unix milliseconds.
nulluntil then.
- Name
- finished_at
- Type
- timestamp
- Description
Time the task reached a final status, in Unix milliseconds.
nulluntil then.
- Name
- expires_at
- Type
- timestamp
- Description
Time the task's result expires, in Unix milliseconds. It's 3 days after
finished_at, or 3 days aftercreated_atuntil the task finishes. For Enterprise accounts, which keep API results indefinitely, it's about 100 years later. See Asset retention.
- Name
- preceding_tasks
- Type
- integer
- Description
The task's position in the queue while it's
PENDING.1means it starts next.0after the task leaves the queue, and always0in list results.
- Name
- task_error
- Type
- object
- Description
Why the task failed.
nullunlessstatusisFAILED. See Errors.
- Name
- consumed_credits
- Type
- integer
- Description
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'sPENDING. If Meshy can't read the charge, a get or stream response leaves the field out, and a list request returns500. In that case, retry the request.
- Name
- model_urls
- Type
- object
- Description
Download URLs for the model file, with one entry for the
output.formatyou requested.{}until the task succeeds.- Name
glb- Type
- string
- Description
Download URL for the GLB file. Present when
output.formatisglb.
- Name
obj- Type
- string
- Description
Download URL for a zip file with
model.obj,model.mtl, andtexture.png. Present whenoutput.formatisobj.
- Name
bundle_zip- Type
- string
- Description
Download URL for a zip file with every file Meshy generates. Present when
output.formatiszip.