Creative Lab — Lamp API

Turn a text prompt or a source photo into a 3D-printable lampshade in two stages: prototype generates a stylized matte-white concept image, then build turns that concept image into a hollow STL lampshade (optionally paired with a base disk for a light-source fixture). The two stages are linked via input_task_id.

  • POST /openapi/creative-lab/lamp/v1/prototype
  • POST /openapi/creative-lab/lamp/v1/build
POST/openapi/creative-lab/lamp/v1/prototype

Create a Lamp Prototype Task

Generate a single matte-white concept image for the lampshade — either from a text prompt (text-to-3D) or from a reference photo (image-to-3D). The returned task ID is what you pass as input_task_id to the build endpoint. Refer to The Lamp Prototype Task Object for the response shape.

Parameters

Exactly one of text or image_url is required. Passing both, or neither, returns 400.

  • Name
    text
    Type
    string
    Required
    Description

    Text prompt describing the desired lampshade subject. Required when image_url is omitted. Maximum 800 characters.

  • Name
    image_url
    Type
    string
    Required
    Description

    Source photo Meshy uses as the visual reference for the lampshade. Required when text is omitted. 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
    image_subject
    Type
    string
    default character
    Description

    Subject category hint for the image-to-3D path. Available values:

    • character (default) — single character / object subject (figurine, animal, mascot, etc.).
    • landscape — outdoor scene / panorama subject (mountain, cityscape, forest, etc.).

    Ignored on the text-to-3D path.

  • 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 lamp 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: Exactly one of text or image_url is required.
    • Both provided: Passing both text and image_url is rejected — they are mutually exclusive.
    • 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.
    • Text too long: text exceeds 800 characters.
    • Invalid image_subject: Not one of character / landscape.
  • 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/lamp/v1/prototype
# Stage 1 (image-to-3D): generate a matte-white lampshade concept image
curl https://api.meshy.ai/openapi/creative-lab/lamp/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>",
    "image_subject": "character"
  }'

# Stage 1 (text-to-3D): generate from a text prompt
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "a stylized owl perched on a tree branch under moonlight"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
POST/openapi/creative-lab/lamp/v1/build

Create a Lamp Build Task

Generate the final 3D-printable lampshade from a succeeded prototype task. The build runs an image-to-3D pipeline on the prototype's concept image, then post-processes the mesh through the lamp processor to hollow it, flatten the top, optionally cut a base, and (when a fixture preset is chosen) emit a separate base disk for the light source. Refer to The Lamp 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/lamp/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 lampshade geometry. Every field has a sensible default — send only the ones you want to override.

  • Name
    diameter_mm
    Type
    number
    default 80
    Description

    Target maximum dimension of the lampshade bounding box, in millimeters. The mesh is uniformly scaled to fit. Range: [50, 400].

  • Name
    thickness_mm
    Type
    number
    default 1.5
    Description

    Wall thickness of the hollow lampshade, in millimeters. Range: (0, 10].

  • Name
    cut_amount_percent
    Type
    number
    default 35
    Description

    Percentage of the lampshade height to flatten at the top so the print can sit on the bed. Range: [1, 100].

  • Name
    light_source_preset
    Type
    string
    default bambu_mh001_60mm
    Description

    Light-source fixture preset that determines whether (and what) base disk to emit alongside the lampshade. Available values:

    • bambu_mh001_60mm (default) — emit a 60 mm base disk sized for the Bambu MH001 light source. Result includes model_urls.base_stl.
    • none — no fixture, no base disk. model_urls.base_stl is omitted.
  • Name
    fixture_offset_x_mm
    Type
    number
    default 0
    Description

    Horizontal X-axis offset of the fixture cutout relative to the lampshade center, in millimeters. Only meaningful when light_source_preset ≠ none. Range: [-80, 80].

  • Name
    fixture_offset_z_mm
    Type
    number
    default 0
    Description

    Vertical Z-axis offset of the fixture cutout relative to the lampshade bottom, in millimeters. Range: [-80, 80].

  • Name
    rotate_x_deg
    Type
    number
    default 0
    Description

    Rotation around the X axis applied to the imported mesh before processing, in degrees. Range: [-360, 360].

  • Name
    rotate_y_deg
    Type
    number
    default 0
    Description

    Rotation around the Y axis applied to the imported mesh before processing, in degrees. Range: [-360, 360].

  • Name
    rotate_z_deg
    Type
    number
    default 0
    Description

    Rotation around the Z axis applied to the imported mesh before processing, in degrees. Range: [-360, 360].

  • Name
    include_result_json
    Type
    boolean
    default false
    Description

    When true and output.format is zip, includes the lamp processor's result.json (containing measured mesh metrics + the resolved option set) inside the bundle. Ignored when output.format is stl.

output

Optional wire-format selector. Defaults to stl.

  • Name
    format
    Type
    string
    default stl
    Description

    Artifact bundle returned by the build. Available values:

    • stl (default) — returns the lampshade as model_urls.lamp_stl, plus model_urls.base_stl when light_source_preset ≠ none.
    • zip — packages every artifact the processor emits (lamp.stl, optional base.stl, optional result.json) into a single zip and returns it under model_urls.bundle_zip.

Returns

The result property of the response contains the task id of the newly created lamp build task. Poll the Get a Task endpoint or subscribe to the stream until the task reaches SUCCEEDED, then download the artifacts from 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/lamp/v1/build
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "diameter_mm": 120,
      "thickness_mm": 2,
      "light_source_preset": "bambu_mh001_60mm",
      "cut_amount_percent": 30
    },
    "output": {
      "format": "stl"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
GET/openapi/creative-lab/lamp/v1/(prototype|build)/:id

Retrieve a Lamp 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 Lamp Prototype Task Object and The Lamp Build Task Object for response shapes.

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the lamp task to retrieve.

Returns

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

Request

GET
/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-lamp-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}
DELETE/openapi/creative-lab/lamp/v1/(prototype|build)/:id

Delete a Lamp Task

Cancel a lamp 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 lamp 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/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).
GET/openapi/creative-lab/lamp/v1/(prototype|build)/:id/stream

Stream a Lamp Task

Stream real-time updates for a lamp 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 lamp task to stream.

Returns

Returns a stream of Lamp Prototype or Lamp 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/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream
curl -N https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/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": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}
GET/openapi/creative-lab/lamp/v1/(prototype|build)

List Lamp Tasks

Retrieve a paginated list of your lamp 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 lamp prototype task object when listing /prototype or the lamp build task object when listing /build.

Request

GET
/openapi/creative-lab/lamp/v1/prototype
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-lamp-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

The Lamp Prototype Task Object

The Lamp Prototype Task object is a work unit that Meshy keeps track of to generate a stylized matte-white concept image from either a text prompt or 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-lamp-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 Lamp Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-lamp-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

The Lamp Build Task Object

The Lamp Build Task object is a work unit that Meshy keeps track of to generate the final 3D-printable lampshade from a succeeded prototype task. The build runs an image-to-3D draft + texture pipeline on the prototype's concept image, then post-processes the mesh through the lamp processor to hollow, flatten, and (optionally) cut a fixture base.

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-lamp-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 artifacts, keyed by artifact name. The set of keys depends on output.format and options.light_source_preset:

    • Name
      lamp_stl
      Type
      string
      Description

      Downloadable URL to the lampshade lamp.stl. Present when output.format was stl (the default).

    • Name
      base_stl
      Type
      string
      Description

      Downloadable URL to the fixture-base base.stl. Present when output.format was stl and options.light_source_preset was not none. Omitted when the fixture preset was none.

    • Name
      bundle_zip
      Type
      string
      Description

      Downloadable URL to a zip bundle of every artifact the processor emits (lamp.stl, optional base.stl, and — when options.include_result_json is true — result.json). Present when output.format was zip. When bundle_zip is present, lamp_stl / base_stl are omitted.

Example Lamp Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}