====== 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|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//model To use APIs of the sandbox, the POST needs to be submitted to: https://imatsandbox.materialise.net/web-api/tool//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): ^Parameter^Description^Required?^HTTP headers^ | ''file'' | File stream|Yes (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"| |''error''|List | 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 === 418674f3-f8a5-43bd-a06d-e8e95831b2d9 cb8272c6-14fe-4ebf-bfab-520f6f39af17 Box_inch.stl inch 645.1600000000 645.1600000000 645.1600000000 268536.0000000000 24973.9000000000 Succeeded 2014-12-07T00:00:00+02:00 === 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 (). Following extensions are supported: | Checked by allowed extensions. \\ {{page>Tips#formats&nofooter&noheader}} | | 108 | Model file is too big. Files should be less than Mb. | {{page>Tips#size&nofooter&noheader}} | | 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. | | | 112 | Specified toolID is no more active. | toolId was deactivated | | 123 | Model file name is too long. It should not exceed 120 characters. | | | 124 | Processing of file refused by API service. | | === Example of Response with error in XML === 418674f3-f8a5-43bd-a06d-e8e95831b2d9 0ab3f316-5df4-4a77-a01d-46210943ac56 2print_bad.stl mm 73.7159000000 118.8810000000 27.3087000000 85.2411000000 354.9360000000 StillNeedsFixing 2014-12-07T00:00:00+02:00 Cannot process the model. For details see Model Status. 109 === Example of Response with error in JSON === { "error":{ "message":"Such toolID doesn’t exist.", "code":103 } }