lowpoly retires Oct 30, 2026. Please switch models before these dates to avoid request errors.

Creative Lab Figure API

Turn a photo into a chibi-style collectible 3D figure in two stages. A prototype task generates a concept image from the photo. A build task turns that image into a textured 3D model, and takes the prototype task's ID as input_task_id.

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

Create a Figure prototype task

Generates one chibi-style 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 Figure prototype task object.

Request

POST
/openapi/creative-lab/figure/v1/prototype
# Stage 1: generate a chibi-style concept image
curl https://api.meshy.ai/openapi/creative-lab/figure/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": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Prototype example
Start with a source portrait, then generate the prototype image used by the build stage.
Source portrait used as the Creative Lab Figure input
Prototype input
Chibi-style figurine prototype image generated from the source photo
Prototype output

Parameters

  • Name
    image_url
    Type
    string
    Required
    Description

    The photo to turn into a chibi figure, 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 name field. A longer name returns 400.

  • Name
    remove_background
    Type
    boolean
    default false
    Description

    Whether to remove the background from the prototype image. true returns a transparent RGBA PNG, so you can place the subject 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.

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

  • Name
    401 - Unauthorized
    Description

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

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

POST/openapi/creative-lab/figure/v1/build

Create a Figure build task

Generates the textured 3D figure from a succeeded prototype task. For its fields, see The Figure build task object.

Request

POST
/openapi/creative-lab/figure/v1/build
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Build example
The build task turns the selected prototype image into a downloadable textured 3D model.
Creative Lab Figure build model preview
Build model preview

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/figure/v1/prototype, with the status SUCCEEDED.

    An ID that isn't one of your Figure 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 name field. A longer name returns 400.

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 textured GLB from model_urls.glb. For an OBJ instead, download model_urls.obj with its material file from model_urls.mtl.

Failure modes

  • Name
    400 - Bad Request
    Description

    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 image. Create a new prototype task.

    The error message says which problem it found.

  • Name
    401 - Unauthorized
    Description

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

  • 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_id doesn't match any Figure 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.

  • 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/openapi/creative-lab/figure/v1/(prototype|build)/:id

Get a Figure 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 Figure prototype task object and The Figure build task object.

Request

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

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

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-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-figure-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,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?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

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

  • Name
    403 - Forbidden
    Description

    Your team has IP Filtering turned on, and Meshy flagged the task's image for third-party intellectual property. 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 Figure 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.

  • Name
    500 - Internal Server Error
    Description

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

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

Delete a Figure task

Cancels a Figure 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

DELETE
/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -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:

    • 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.
  • Name
    404 - Not Found
    Description

    No Figure 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.

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

Stream a Figure task

Streams a Figure 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

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

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?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 Figure 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.

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

List Figure tasks

Returns your Figure 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

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-figure-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=***"
    ]
  }
]

Path parameters

  • Name
    stage
    Type
    path
    Required
    Description

    The stage to list, prototype or build.

Query parameters

  • Name
    page_num
    Type
    integer
    default 1
    Description

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

  • Name
    page_size
    Type
    integer
    default 10
    Description

    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.

  • 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 Figure prototype task object

A prototype task generates a chibi-style 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 Figure Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-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=***"
  ]
}
  • 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-figure-prototype.

  • Name
    name
    Type
    string
    Description

    The name you 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 queue
    • IN_PROGRESS: generating the result
    • SUCCEEDED: final, with the result
    • FAILED: final, with the reason in task_error
    • CANCELED: final, with no result
  • Name
    progress
    Type
    integer
    Description

    Percentage of the work done, from 0 to 100. It's 0 until the task starts and 100 when 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. null until then.

  • Name
    finished_at
    Type
    timestamp
    Description

    Time the task reached a final status, in Unix milliseconds. null until 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 after created_at until 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. 1 means it starts next. 0 after the task leaves the queue, and always 0 in list results.

  • Name
    task_error
    Type
    object
    Description

    Why the task failed. null unless status is FAILED. 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'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.

  • 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 Figure build task object

A build task generates a textured 3D figure from a succeeded prototype task. Its model_urls, thumbnail_url, and texture_urls fields have the same format as in the Image to 3D task object.

Properties

Example Figure Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-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,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.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-figure-build.

  • Name
    name
    Type
    string
    Description

    The name you 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 queue
    • IN_PROGRESS: generating the result
    • SUCCEEDED: final, with the result
    • FAILED: final, with the reason in task_error
    • CANCELED: final, with no result
  • Name
    progress
    Type
    integer
    Description

    Percentage of the work done, from 0 to 100. It's 0 until the task starts and 100 when 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. null until then.

  • Name
    finished_at
    Type
    timestamp
    Description

    Time the task reached a final status, in Unix milliseconds. null until 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 after created_at until 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. 1 means it starts next. 0 after the task leaves the queue, and always 0 in list results.

  • Name
    task_error
    Type
    object
    Description

    Why the task failed. null unless status is FAILED. 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'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.

  • Name
    prompt
    Type
    string
    Description

    Always "" for a Figure build task.

  • Name
    negative_prompt
    Type
    string
    Description

    Always "" for a Figure build task, like prompt.

  • Name
    texture_prompt
    Type
    string
    Description

    Always "" for a Figure build task, like prompt.

  • Name
    texture_image_url
    Type
    string
    Description

    Always "" for a Figure build task, like prompt.

  • Name
    model_urls
    Type
    object
    Description

    Download URLs for the 3D model, as a textured GLB and as an OBJ file with its MTL file.

    • Name
      glb
      Type
      string
      Description

      Download URL for the textured GLB file.

    • Name
      obj
      Type
      string
      Description

      Download URL for the OBJ file, with the geometry and UVs.

    • Name
      mtl
      Type
      string
      Description

      Download URL for the MTL material file that goes with obj. Use it with obj and the texture in texture_urls[0].base_color.

  • Name
    thumbnail_url
    Type
    string
    Description

    Download URL for a preview image of the model.

  • Name
    texture_urls
    Type
    array
    Description

    The texture maps, as an array with one object that holds the base color map.

    • Name
      base_color
      Type
      string
      Description

      Download URL for the base color map.