Creative Lab — Fridge Magnet API

Turn your photos into custom fridge magnets — a rounded-rectangle colorized depth relief with a flat magnetic back, sized for the fridge — in two stages: prototype generates a colorized concept image from your input photo, then build turns that concept image into a relief 3D model. The two stages are linked via input_task_id.

POST /openapi/creative-lab/fridge-magnet/v1/prototype
POST /openapi/creative-lab/fridge-magnet/v1/build

POST/openapi/creative-lab/fridge-magnet/v1/prototype

Create a Fridge Magnet Prototype Task

Generate a single colorized concept image from the source photo. The returned task ID is what you pass as input_task_id to the build endpoint. Refer to The Fridge Magnet Prototype Task Object for the response shape.

Parameters

Name
image_url
Type
string
Required
Description
Source photo for Meshy to colorize into a fridge-magnet-ready concept image. We currently support .jpg, .jpeg, .png, and .webp formats.
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>.
Name
name
Type
string
Description
Optional task name for display purposes. Maximum 100 characters.

Returns

The result property of the response contains the task id of the newly created fridge magnet prototype task. Poll the Get a Task endpoint or subscribe to the stream until the task reaches SUCCEEDED, then pass that ID to the build endpoint as input_task_id.

Failure Modes

Name
400 - Bad Request
Description
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 or intellectual property moderation.
Name
401 - Unauthorized
Description
Authentication failed. Please check your API key.
Name
402 - Payment Required
Description
Insufficient credits to perform this task.
Name
429 - Too Many Requests
Description
You have exceeded your rate limit.

Request

POST

/openapi/creative-lab/fridge-magnet/v1/prototype

# 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"
}

POST/openapi/creative-lab/fridge-magnet/v1/build

Create a Fridge Magnet Build Task

Generate the final 3D-printable fridge magnet from a succeeded prototype task. The build runs a depth-map relief pipeline on the prototype's colorized concept image and ships a single mesh artifact in the format you ask for. Refer to The Fridge Magnet Build Task Object for the response shape.

Parameters

Name
input_task_id
Type
string
Required
Description
The task ID of a prototype task created via this same OpenAPI endpoint. The prototype must have been created with the same API key, must have reached SUCCEEDED, and must have produced exactly one candidate image.
Prototype tasks created through the webapp are not accepted — the build endpoint accepts only prototype tasks produced by POST /openapi/creative-lab/fridge-magnet/v1/prototype and refuses any other source with 404.
Name
name
Type
string
Description
Optional task name for display purposes. Maximum 100 characters.

`options`

Optional tuning parameters for the relief geometry. Every field has a sensible default — send only the ones you want to override.

Name
badge_shape
Type
string
default rounded-rect
Description
Outline silhouette of the fridge magnet. Available values:
- circle
- rounded-rect (default)
- hexagon
- shield
- star
Name
size_mm
Type
number
default 60
Description
Bounding square edge length of the fridge magnet, in millimeters. Range: (0, 400].
Name
relief_height_mm
Type
number
default 3.3
Description
Maximum relief height above the base, in millimeters. Range: [0, 20].
Name
relief_offset_mm
Type
number
default 0
Description
Vertical offset applied to the relief before extrusion, in millimeters. Range: [0, 20].
Name
base_thickness_mm
Type
number
default 2.0
Description
Thickness of the flat base plate behind the relief, in millimeters. The fridge-magnet default is a chunkier 2 mm base — gives the magnet enough body to grip the fridge without the relief feeling fragile. Range: [0, 20].
Name
has_closed_back
Type
boolean
default true
Description
Whether the back of the fridge magnet is sealed as a closed surface (the side you glue the magnet to). Set to false for an open shell.
Name
relief_curve
Type
string
default linear
Description
Transfer curve mapping depth-map values to relief height. Available values:
- linear (default)
- gamma
- s-curve
Name
curve_param
Type
number
default 1.0
Description
Shape parameter for the transfer curve (only meaningful when relief_curve is gamma). Range: (0, 10].
Name
invert_depth
Type
boolean
default false
Description
Invert the depth-map interpretation so darker regions become higher relief.
Name
smoothing
Type
number
default 0.24
Description
Smoothing strength applied to the depth map before relief extraction. Range: [0, 10].
Name
relief_scale
Type
number
default 1.0
Description
Vertical scale multiplier applied on top of relief_height_mm. Range: (0, 10].
Name
depth_threshold
Type
number
default 0.1
Description
Low-pass threshold for depth-map values; anything below this is clamped to zero. Range: [0, 1].
Name
remove_background
Type
boolean
default true
Description
Automatically remove the background of the prototype's concept image before reliefing.
Name
export_resolution
Type
integer
default 512
Description
Mesh resolution used for export. Range: [64, 2048].

`output`

Optional wire-format selector. Defaults to glb.

Name
format
Type
string
default glb
Description
Artifact bundle returned by the build. Available values:
- glb (default) — returns a single model.glb under model_urls.glb.
- obj — zips model.obj + model.mtl + texture.png and returns the bundle under model_urls.obj.
- zip — zips every artifact the generator emits and returns the bundle under model_urls.bundle_zip.

Returns

The result property of the response contains the task id of the newly created fridge magnet build task. Poll the Get a Task endpoint or subscribe to the stream until the task reaches SUCCEEDED, then download the artifact from the single entry in model_urls.

Failure Modes

Name
400 - Bad Request
Description
The request was unacceptable. Common causes:
- Missing parameter: input_task_id is 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 candidate: The prototype task succeeded but produced no candidate image.
- Options out of range: One of the options fields fell outside its allowed range or enum set.
Name
401 - Unauthorized
Description
Authentication failed. Please check your API key.
Name
402 - Payment Required
Description
Insufficient credits to perform this task.
Name
404 - Not Found
Description
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).
Name
429 - Too Many Requests
Description
You have exceeded your rate limit.

Request

POST

/openapi/creative-lab/fridge-magnet/v1/build

# 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"
}

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id

Retrieve a Fridge Magnet Task

Retrieve a prototype or build task given a valid task id. The URL path must match the task's stage — a build task fetched through /prototype/:id returns 404, and vice versa.

Refer to The Fridge Magnet Prototype Task Object and The Fridge Magnet Build Task Object for response shapes.

Parameters

Name
id
Type
path
Description
Unique identifier for the fridge magnet task to retrieve.

Returns

The response contains the fridge magnet task object. The shape depends on which stage was requested.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

# 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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

DELETE/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id

Delete a Fridge Magnet Task

Cancel a fridge magnet task. If the task is still PENDING, the credits consumed at create-time are refunded. Tasks that are already IN_PROGRESS are cancelled without a refund (the worker may already be burning resources). Tasks that have already reached a terminal state (SUCCEEDED, FAILED, CANCELED) cannot be cancelled.

The URL path must match the task's stage — DELETE on /prototype/:buildId returns 404.

Path Parameters

Name
id
Type
path
Description
Unique identifier for the fridge magnet task to cancel.

Returns

Returns 204 No Content on success with an empty body.

Failure Modes

Name
400 - Bad Request
Description
The task is already in a terminal state and cannot be cancelled.
Name
404 - Not Found
Description
The task does not exist, belongs to a different user, or its stage does not match the URL path.

Request

DELETE

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

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

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id/stream

Stream a Fridge Magnet Task

Stream real-time updates for a fridge magnet task via Server-Sent Events (SSE). The URL path must match the task's stage — opening a stream at /prototype/:buildId/stream emits a single event: error payload with status_code: 404 and closes the stream.

Parameters

Name
id
Type
path
Description
Unique identifier for the fridge magnet task to stream.

Returns

Returns a stream of Fridge Magnet Prototype or Fridge Magnet Build task objects as Server-Sent Events. For PENDING or IN_PROGRESS tasks, the response stream will only include the necessary progress and status fields.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)

List Fridge Magnet Tasks

Retrieve a paginated list of your fridge magnet tasks for a single stage. The URL path selects the stage — /prototype returns prototype tasks; /build returns build tasks. Tasks from the other stage are not included in either response.

Path Parameters

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

Query Parameters

Name
page_num
Type
integer
default 1
Description
Page number for pagination.
Name
page_size
Type
integer
default 10
Description
Page size limit. Maximum allowed is 50 items.
Name
sort_by
Type
string
default -created_at
Description
Field to sort by. Available values:
- +created_at: Sort by creation time in ascending order.
- -created_at: Sort by creation time in descending order.

Returns

Returns a paginated list of the per-stage task object — either the fridge magnet prototype task object when listing /prototype or the fridge magnet build task object when listing /build.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/prototype

# 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=***"
    ]
  }
]

The Fridge Magnet Prototype Task Object

The Fridge Magnet Prototype Task object is a work unit that Meshy keeps track of to generate a colorized concept image from a source photo. The output of this stage is chained into the build stage via input_task_id.

Properties

Name
id
Type
string
Description
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.
Name
type
Type
string
Description
Type of the task. The value is creative-lab-fridge-magnet-prototype.
Name
name
Type
string
Description
The task name supplied when the task was created. Empty string if no name was provided.
Name
status
Type
string
Description
Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
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.
Name
created_at
Type
timestamp
Description
Timestamp of when the task was created, in milliseconds.
A timestamp represents the number of milliseconds elapsed since January 1, 1970 UTC, following the RFC 3339 standard. For example, Friday, September 1, 2023 12:00:00 PM GMT is represented as 1693569600000. This applies to all timestamps in Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp of when the task was started, in milliseconds. If the task is not started yet, this property will be 0.
Name
finished_at
Type
timestamp
Description
Timestamp of when the task was finished, in milliseconds. If the task is not finished yet, this property will be 0.
Name
expires_at
Type
timestamp
Description
Timestamp of when the task result expires, in milliseconds.
Name
preceding_tasks
Type
integer
Description
The count of preceding tasks.
The value of this field is meaningful only if the task status is PENDING.
Name
task_error
Type
object
Description
Error details for failed tasks. See Errors for the full task_error object reference.
Name
consumed_credits
Type
integer
Description
The number of credits consumed by this task. Present when the task status is PENDING, IN_PROGRESS, or SUCCEEDED. Returns 0 for FAILED tasks (credits are refunded on failure).
Name
image_urls
Type
array of strings
Description
Downloadable URLs for the concept image candidates generated by this prototype task. Currently the API always returns exactly one candidate; the field is an array so future revisions can surface multiple candidates without a breaking change.

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=***"
  ]
}

The Fridge Magnet Build Task Object

The Fridge Magnet Build Task object is a work unit that Meshy keeps track of to generate the final 3D fridge magnet mesh from a succeeded prototype task. The build runs a depth-map relief pipeline on the prototype's concept image and publishes a single mesh artifact in the format the caller requested.

Properties

Name
id
Type
string
Description
Unique identifier for the task.
Name
type
Type
string
Description
Type of the task. The value is creative-lab-fridge-magnet-build.
Name
name
Type
string
Description
The task name supplied when the task was created. Empty string if no name was provided.
Name
status
Type
string
Description
Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
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.
Name
created_at
Type
timestamp
Description
Timestamp of when the task was created, in milliseconds.
Name
started_at
Type
timestamp
Description
Timestamp of when the task was started, in milliseconds.
Name
finished_at
Type
timestamp
Description
Timestamp of when the task was finished, in milliseconds.
Name
expires_at
Type
timestamp
Description
Timestamp of when the task result expires, in milliseconds.
Name
preceding_tasks
Type
integer
Description
The count of preceding tasks. Meaningful only when status is PENDING.
Name
task_error
Type
object
Description
Error details for failed tasks. See Errors for the full task_error object reference.
Name
consumed_credits
Type
integer
Description
The number of credits consumed by this task. Returns 0 for FAILED tasks (credits are refunded on failure).
Name
model_urls
Type
object
Description
Downloadable URLs for the generated artifact, keyed by artifact name. Always contains exactly one entry — the format requested via the build request's output.format. The key matches the requested format:
- Name
  glb
  Type
  string
  Description
  Downloadable URL to the GLB file. Present when output.format was glb (the default).
- Name
  obj
  Type
  string
  Description
  Downloadable URL to a zip bundle containing model.obj, model.mtl, and texture.png. Present when output.format was obj.
- Name
  bundle_zip
  Type
  string
  Description
  Downloadable URL to a zip bundle of every artifact the generator emits. Present when output.format was zip.

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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}