Model prep

Model prep gets a model ready for materials and Studio. The REST API and the MCP connector run the same agent as the model page's Actions tab, and a run started here appears there.

Access

REST requests use your workspace API key in X-API-Key. Paths below are relative to https://api.glossi.io/api/v1. MCP tools take the same arguments by name. Errors use the standard shape, { "error": { "code": "...", "message": "..." } }.

Passes

A run does one or more passes, always in this order:

["segment", "parts", "uvs", "materials"] is the model page's Prepare model. refine isn't started here; it is what retry runs.

What it costs

A run that includes segment is a one-off purchase for an uploaded model, paid when it starts; the others use your plan's usage. Models made with AI model creation are prepared at no extra cost. Read the offer before starting a segment run:

curl 'https://api.glossi.io/api/v1/models/MODEL_ID/prep/offer' \
  -H "X-API-Key: $GLOSSI_API_KEY"

{
  "offer": {
    "billing": "PURCHASE",
    "available": true,
    "unavailableReason": null,
    "mode": "CARD",
    "price": { "subtotalMinor": 1500, "totalMinor": 1500, "currency": "USD", "taxTreatment": "STRIPE_AUTOMATIC" },
    "includedRefines": 3,
    "discards": { "max": 0, "left": 0, "next": "PREPAY", "freesAt": null },
    "canApprove": true
  }
}

billing is PURCHASE, USAGE or INCLUDED. Amounts are in minor units (cents). includedRefines is how many changes the purchase covers before you keep it. discards.next is PREPAY when a new run is paid when it starts and isn't refunded on discard. Some organizations' agreements include free discards: then discards.left counts them, next is FREE while any are left, and the result is paid when you keep it. canApprove is whether the key's user may pay for a prep: a workspace owner or admin.

Start a run

curl -X POST 'https://api.glossi.io/api/v1/models/MODEL_ID/prep' \
  -H "X-API-Key: $GLOSSI_API_KEY" -H 'Content-Type: application/json' \
  -d '{ "passes": ["segment", "parts", "uvs", "materials"], "notes": "The strap and buckle are separate parts" }'

Returns 202 with { "job": { ... } }. A model must be READY, and only one run per model can be open at a time (409 PREP_IN_PROGRESS).

Follow a run

GET /models/MODEL_ID/prep/JOB_ID returns the run; GET /models/MODEL_ID/prep?limit=10 lists the model's runs, newest first. Poll every 30 seconds or so: a full prep takes up to about 40 minutes, a single pass a few minutes.

A READY run carries the report: summary, uncertain (what the agent wasn't sure of), changes, partCount, finishGroupCount, bindingProblems, materials, refinesLeft and paysOnKeep.

Change something

curl -X POST 'https://api.glossi.io/api/v1/models/MODEL_ID/prep/JOB_ID/retry' \
  -H "X-API-Key: $GLOSSI_API_KEY" -H 'Content-Type: application/json' \
  -d '{ "feedback": "The laces include the red strip on the tongue" }'

Changes one area of a READY result that split the model, in your words. referenceKeys takes up to 6 screenshots of the area. It starts a new run whose previousJobId is the result it changes. A purchase covers includedRefines changes; after that, 409 REFINES_USED.

Keep or discard

POST .../keep makes the result the model's current version; the previous version stays in its version history. For a paid result it charges the workspace's saved card and returns { "job": { ... }, "payment": { "status": "PAID", ... } }. A card that needs 3-D Secure returns REQUIRES_ACTION: finish it on the model page. 403 APPROVAL_REQUIRED means the key's user isn't a workspace owner or admin.

POST .../discard throws the result away. A prep paid when it started isn't refunded; under an agreement with free discards, it uses one.

Errors