Create a model
POST/api/v1/models
Overview
Create a model from an uploaded file and its default longest dimension. Returns a permanent model ID immediately while inspection runs asynchronously. Retrieve the model for progress and results.
Requires models:write.
Parameters
Idempotency-Key header · optional
Account, method and path scoped retry key, retained for 24 hours from first use. Same body replays the original successful status and body. A changed body returns 409 idempotency_key_reused; an in-flight request returns 409 idempotency_request_in_progress with Retry-After. Retry transient failures with the same key and body.
string
Request body
application/json
source object · required
Reference to an uploaded geometry file and its supporting assets. One file can back multiple models in the same account. Set print size explicitly using longest_dimension_mm.
source fields
file_id string · required
Unique, server-generated file ID. Treat it as an opaque reference.
Min length: 37 · Max length: 37
name string · optional
Optional human-readable model name supplied by the customer. Not unique; id is the system-generated identifier. Unicode category C characters, including control and format characters, are rejected.
Max length: 255
external_id string · optional
Optional identifier from the customer’s system. Stored and returned unchanged. No uniqueness, lookup, or deduplication guarantee. Unicode category C characters, including control and format characters, are rejected.
Max length: 255
metadata object · optional
Optional customer key/value strings. Up to 50 keys, each 1–40 characters; values up to 500 characters. Unicode category C characters (including control and format characters) are rejected in keys and values. No secrets. Not interpreted for pricing, permissions or deduplication.
longest_dimension_mm number · required
Longest bounding-box dimension in millimeters, 30–200 inclusive. Fractional values are accepted. Uniformly scale all axes. At model creation this is the default and inspection reference size; each pricing/quote item explicitly selects its own size. Callers convert other units to millimeters.
Minimum: 30 · Maximum: 200
Responses
Model with current progress and inspection results.
200 response
JSON
{
"id": "MD-739YQ549",
"source": {
"file_id": "file_6c82bd3e319b4bb099310d54a761879e"
},
"name": "Wedding figurine",
"external_id": "design-123",
"created_at": "2026-09-18T18:00:00.000000Z",
"updated_at": "2026-09-18T18:00:00.000000Z",
"status": "processing",
"status_reasons": [
{
"code": "inspection_pending",
"message": "Mesh inspection is running."
}
],
"preview": {
"status": "pending"
},
"longest_dimension_mm": 100,
"mesh_check": {
"status": "pending"
},
"print_check": {
"status": "pending"
},
"repair": {
"required": false,
"applied": false,
"reason": null,
"status": "not_applied",
"fee": 0,
"covered_by_order_id": null
},
"progress": {
"stage": "queued"
},
"volume": null,
"estimated_weight_g": null
}Returns the Model object.
Response headers
X-Request-IDRequest identifier for support. Send X-Request-ID with 8–64 ASCII letters, digits or hyphens to reuse that value; otherwise the server generates a UUID4 hex value. Include the returned X-Request-ID in support requests. Do not put secrets or account IDs in this value.
Idempotent-ReplayedPresent when the original successful response is replayed.
Errors
| HTTP | Code | What to do |
|---|---|---|
| 400 Bad Request | file_not_found | No file with this ID exists in the account, or it expired before a model used it. Register and upload the file again. |
| 400 Bad Request | file_not_ready | The file bytes have not finished uploading, or their size differs from the registration. Finish the upload, then retry. |
| 400 Bad Request | invalid_argument | A field, query parameter or header is invalid. Fix the field named in details, then send the request again. |
| 401 Unauthorized | unauthenticated | The API key is missing, invalid or revoked. Send a valid business API key in Authorization: Bearer. |
| 403 Forbidden | permission_denied | The key lacks the endpoint's scope, or payments lack spending consent. Check the scope listed on the endpoint. |
| 409 Conflict | idempotency_key_reused | This Idempotency-Key was already used with a different body. Retry the original body, or use a new key for a new operation. |
| 409 Conflict | idempotency_request_in_progress | A request with this Idempotency-Key is still running. Wait Retry-After seconds, then retry the same key and body. |
| 413 Content Too Large | request_too_large | The JSON body is over this endpoint's size limit. Send a smaller body. |
| 415 Unsupported Media Type | unsupported_media_type | The body is not JSON. Send Content-Type: application/json. |
| 429 Too Many Requests | resource_exhausted | A rate or account limit was reached. Wait at least Retry-After seconds, then retry. |
| 500 Internal Server Error | internal | The server failed unexpectedly. Retry with backoff; contact support with X-Request-ID if it persists. |
| 503 Service Unavailable | unavailable | A required service is briefly unavailable. Retry with backoff, reusing the same Idempotency-Key. |
API v1 preview