Creative Lab — Figure API

Turn a source photo into a chibi-style collectible 3D figure in two stages: prototype generates a styled concept image from your input photo, then build turns that concept image into a textured 3D model. The two stages are linked via 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

Generate a single chibi-style 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 Figure Prototype Task Object for the response shape.

Parameters

  • Name
    image_url
    Type
    string
    Required
    Description

    Source photo for Meshy to stylize as a chibi figure. 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 figure 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/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"
}
POST/openapi/creative-lab/figure/v1/build

Create a Figure Build Task

Generate the final textured 3D figure from a succeeded prototype task. The build runs the same image-to-3D pipeline as Image to 3D, so the response object format and the list of output URLs match exactly. Refer to The Figure 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/figure/v1/prototype and refuses any other source with 404.

  • 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 figure build task. Poll the Get a Task endpoint or subscribe to the stream until the task reaches SUCCEEDED, then download the textured GLB from model_urls.glb (or the OBJ + MTL pair from model_urls.obj and model_urls.mtl if your downstream pipeline prefers OBJ).

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

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

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the figure task to retrieve.

Returns

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

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": 20,
  "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=***"
    }
  ]
}
DELETE/openapi/creative-lab/figure/v1/(prototype|build)/:id

Delete a Figure Task

Cancel a figure 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 figure 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/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).
GET/openapi/creative-lab/figure/v1/(prototype|build)/:id/stream

Stream a Figure Task

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

Returns

Returns a stream of Figure Prototype or Figure 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/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.
// 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-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "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=***"
    }
  ]
}
GET/openapi/creative-lab/figure/v1/(prototype|build)

List Figure Tasks

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

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

The Figure Prototype Task Object

The Figure Prototype Task object is a work unit that Meshy keeps track of to generate a chibi-style 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-figure-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 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=***"
  ]
}

The Figure Build Task Object

The Figure Build Task object is a work unit that Meshy keeps track of to generate a textured 3D figure from a succeeded prototype task. It runs the same image-to-3D pipeline used by Image to 3D, so the output fields mirror that endpoint's task object.

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-figure-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
    prompt
    Type
    string
    Description

    Always empty for figure build. Present for cross-endpoint compatibility with the shared V2ImageTo3DTaskResponse shape used by Image to 3D.

  • Name
    negative_prompt
    Type
    string
    Description

    Always empty for figure build. Present for cross-endpoint compatibility.

  • Name
    texture_prompt
    Type
    string
    Description

    Always empty for figure build. Present for cross-endpoint compatibility.

  • Name
    texture_image_url
    Type
    string
    Description

    Always empty for figure build. Present for cross-endpoint compatibility.

  • Name
    model_urls
    Type
    object
    Description

    Downloadable URLs for the generated 3D model. The figure build emits a textured GLB plus the OBJ + MTL pair for pipelines that prefer Wavefront OBJ. The field shape matches the Image to 3D model_urls object so future format additions slot in without a breaking change.

    • Name
      glb
      Type
      string
      Description

      Downloadable URL to the textured GLB file.

    • Name
      obj
      Type
      string
      Description

      Downloadable URL to the Wavefront OBJ file (geometry + UV).

    • Name
      mtl
      Type
      string
      Description

      Downloadable URL to the OBJ companion MTL material file. Pair with obj and the entry from texture_urls[0].base_color.

  • Name
    thumbnail_url
    Type
    string
    Description

    Downloadable URL to the thumbnail image of the model file.

  • Name
    texture_urls
    Type
    array
    Description

    An array of texture URL objects generated by this task. Currently contains a single object with the base color map.

    • Name
      base_color
      Type
      string
      Description

      Downloadable URL to the base color map image.

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