Site Tools

Upload Model API

What is the Upload Model API?

With the Upload Model API, you can upload a 3D model to our server. The API then analyses the model, returns a reference to the model to be used in other APIs, and calculates the dimensions and parameters of the uploaded model, namely,

  • X, Y and Z dimensions;
  • volume;
  • surface area

It also returns ID of your model which can be used In Pricing APIs and Cart APIs.

Who Should Use this API?

The Upload Model API is for users who have an application or website that generates instant prices for models to be 3D printed.

If you want to use the Pricing APIs to calculate a price, the dimensions of the model or model ID are required. You can use the Upload Model API to get the dimensions of a specific model.

The returned reference to the uploaded model, the model ID, can be used in other APIs like the Cart Item Creation API.

Try it Out

Do you have questions about how your server should upload a 3D model? Our demo page should be able to help you . This page is connected to our production site and can be also used to test your tool ID.

The demo page of Upload Model API on production server:

https://i.materialise.com/api/demo/upload-model-api.html

Also, we’ve developed a sandbox server, which is an isolated server (not hooked up to a payment system or production environment, allowing you to test the service without getting billed) to try out your code and integration with us. This is different from our demo pages which are used to check if a particular API is working.

The demo page of Upload Model API on sandbox server:

https://imatsandbox.materialise.net/api/demo/upload-model-api.html

How Does it Work?

The Upload Model API works by posting data to our service.

You can use either XML or JSON formats for posting.

To specify the exact content type which your client can accept and parse, the Accept header in your request has to be set to one of the following content type:

• text/json
• application/json
• text/xml
• application/xml

The tool ID needs to be specified in the tool ID HTTP header. To upload a model and get parameters on production environment, POST request to:

https://i.materialise.com/web-api/tool/<toolID>/model

To use APIs of the sandbox, the POST needs to be submitted to:

https://imatsandbox.materialise.net/web-api/tool/<toolID>/model

Content-Type is multipart/form-data.

Request should consist of two parts:

• File (Content-Disposition: form-data; name=“file”; filename=“12.csv” Content-Type: application/octet-stream)
• File units (Content-Disposition: form-data; name=“fileUnits”)

The server will return a structured response in XML or JSON which your application can parse to retrieve model parameters and model ID.

Documentation

Structure of the Request

The request could look like this (parameters names are case-sensitive):

ParameterDescriptionRequired?HTTP headers
file File streamYes (if fileUrl is not specified) Content-Disposition: form-data; name=“file”; filename=“filename.stl”
Content-Type: application/octet-stream
fileUrl Link to file Yes (if file is not specified) Content-Disposition: form-data; name=“fileUrl”
fileUnits Mm/inch Yes Content-Disposition: form-data; name=“fileUnits”

Structure of the Response

Parameter Type Always shown? Explanation
toolID String (36), required format: GUID Yes Your tool ID
modelID String (36), required format: GUID Yes ID of model
modelFileName String (36) Yes Name of uploaded file from the request
fileUnits String (36) Yes The unit system in which the model file is saved. The value is “mm” or “inch”. If this parameter is not send or the value is empty then “mm” is used.

This parameter should only show the unit system in which the physical model is saved in.
xDimMm Decimal, separated by a period Yes X dimension of the model, mm
yDimMm Decimal, separated by a period Yes Y dimension of the model, mm
zDimMm Decimal, separated by a period Yes Z dimension of the model, mm
volumeCm3 Decimal, separated by a period Yes Volume of the model, cm3
surfaceCm2 Decimal, separated by a period Yes Total surface of the model, cm2
modelStatus String Yes Model status. Possible statuses are:
* succeeded (the model was processed successfully)
* neededFixing (the model was fixed automatically)
* stillNeedsFixing (the model has to be fixed manually by support engineer)
* backEndException (the model can’t be processed)
validUntil Date (ISO format) Yes If the model is not ordered, this is the last date when the file will still be available. This is 30 days in advance by default.
After this date, the file is removed from the server.

Example: “2014-02-28T00:00:00+02:00”
errorList No Section is shown only in case of error in the request or when model status is not “succeeded”

Response Examples

Example of Response in XML

 <Model xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ToolID>418674f3-f8a5-43bd-a06d-e8e95831b2d9</ToolID>
  <ModelID>cb8272c6-14fe-4ebf-bfab-520f6f39af17</ModelID>
  <ModelFileName>Box_inch.stl</ModelFileName>
  <FileUnits>inch</FileUnits>
  <XDimMm>645.1600000000</XDimMm>
  <YDimMm>645.1600000000</YDimMm>
  <ZDimMm>645.1600000000</ZDimMm>
  <VolumeCm3>268536.0000000000</VolumeCm3>
  <SurfaceCm2>24973.9000000000</SurfaceCm2>
  <ModelStatus>Succeeded</ModelStatus>
  <ValidUntil>2014-12-07T00:00:00+02:00</ValidUntil>
</Model>

Example of Response in JSON

{
    "toolID":"418674f3-f8a5-43bd-a06d-e8e95831b2d9",
    "modelID":"f2d1a0fe-2942-4db1-a828-0fdf21977b32",
    "modelFileName":"Box.stl",
    "fileUnits":"mm",
    "xDimMm":10,
    "yDimMm":10,
    "zDimMm":10,
    "volumeCm3":1,
    "surfaceCm2":6,
    "modelStatus":"succeeded",
    "validUntil":"2014-12-07T00:00:00+02:00"
} 

Errors

Code Message Description
-1 Success
101 Request format is wrong
102 toolID was not specified.
103 Such toolID doesn’t exist
104 fileUnits value is not supported. Please specify mm or inch.
105 ModelFile was not provided
107 File format is not supported (<extension>). Following extensions are supported: <ext1, ext2, …>Checked by allowed extensions.

Currently we support processing models of following formats: .3ds, .stl, .igs, .model, .mxp, .obj, .wrl, .3dm, .zip, .rar, .7z, .skp, .dae, .fbx, .matPart, .ply, .magics, .mgx, .x3d, .x3dv, .3MF, .stp, .step, .prt, zpr.

108 Model file is too big. Files should be less than <max file size> Mb.

Size of uloaded model should be less than 100 MB.

109 Cannot process the model. For details see Model Status.
110 The format of the fileLink could not be determined.
111 Our server can’t reach the model file using the provided link.
112Specified toolID is no more active. toolId was deactivated
123Model file name is too long. It should not exceed 120 characters.

Example of Response with error in XML

 <Model xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ToolID>418674f3-f8a5-43bd-a06d-e8e95831b2d9</ToolID>
  <ModelID>0ab3f316-5df4-4a77-a01d-46210943ac56</ModelID>
  <ModelFileName>2print_bad.stl</ModelFileName>
  <FileUnits>mm</FileUnits>
  <XDimMm>73.7159000000</XDimMm>
  <YDimMm>118.8810000000</YDimMm>
  <ZDimMm>27.3087000000</ZDimMm>
  <VolumeCm3>85.2411000000</VolumeCm3>
  <SurfaceCm2>354.9360000000</SurfaceCm2>
  <ModelStatus>StillNeedsFixing</ModelStatus>
  <ValidUntil>2014-12-07T00:00:00+02:00</ValidUntil>
  <Error>
    <Message>Cannot process the model. For details see Model Status.</Message>
    <Code>109</Code>
  </Error>
</Model>

Example of Response with error in JSON

   {
    "error":{
        "message":"Such toolID doesn’t exist.",
        "code":103
    }
}