Direct upload

This method allows uploading a design directly to Sculpteo with a single POST request, without end-user interaction. The 3D content and meta information should be posted to the same URL:


The LANGUAGE_CODE should be set to either en (for English) or fr (for French), so that the response is localized.

The 3D content should be sent to the UPLOAD_URL as a multipart POST data attachement parameter ‘file’. It must be a single file in one of our supported 3D formats. Its filename should be provided and its extension should be consistent with the 3D content format whenever possible. If the design has external textures, they should all be zipped to an archive and the .zip file should be sent instead. The maximum size is 500MB.

Alternatively, in case multipart POST data attachement is not possible, the design file may be encoded in base64 and sent as a string in the ‘file’ parameter. In this case the filename should also be given in the ‘filename’ parameter We expect the “urlsafe” version of base64 encoding, where the “+” and “/” signs are replaced with “-” and “_”.

The following parameters are required and should be posted along the content:


the name of the design

The following parameters are optional and may be posted along the content:


a description of the design (default empty)


keywords for searching the design (default empty)


allow other people to see the model, 0=no, 1=yes (default ‘1’)


allow other people to order a 3D print of this design, 0=no, 1=yes (default ‘1’)


allow other people to customize this design, 0=no, 1=yes (default ‘0’)


the default unit of the design, one of ‘mm’, ‘cm’, ‘in’, ‘ft’, ‘yd’ (default ‘cm’)


the default scale of the design, in floating point format (see below)


comma separated list of floats, representing scales at which the design can be ordered (see below)


comma separated list of materials, limiting the choice of materials in which the design can be printed. See WorkFlow for list of available materials.


orientation of the design thumbnails, a triplet representing a rotation before projection to the XZ plane, angle is given in degree by the norm of the triplet (default 0,0,0 for no rotation)


you can create trackids from Your Account/Your Shop/ Design tracking. When you associate designs with a trackid during the upload, you can then get info on sales data on these designs

The default printing material is automatically detected depending on file format. Currently it is multicolor if the 3D content has colors or textures, and white plastic otherwise.

If unit and scale is unset, the unit is assumed to be centimeters, and autoscaling is enabled. If unit is set but scale is unset, scale is assumed to be 1.0 and autoscaling is disabled. Otherwise, if scale is unset or set to 0.0, autoscaling is enabled.

Autoscaling consists setting scale to 1.0, then increasing it by multiple of 10 until the design is unlikely to break (for small designs), then reducing it by multiples of 10 until the design fits into the default printer for the default material (for large designs). Note that if autoscaling is disabled, the design may not be printable at its initial scale.

If sizes is present, default scale is discarded, and orderable sizes for the design will restricted to this list of scales.

In case the “X-Requested-With: XMLHttpRequest” header is set when POSTing the content, the response is provided in JSON format. In case of success, the content is a dictionary indicating design information in the following format:


unique identifier of the design


name of the design


default scale of the design


default unit of the design


dimension of the axis-aligned bounding box along the X dimension in model units


dimension of the axis-aligned bounding box along the Y dimension in model units


dimension of the axis-aligned bounding box along the Z dimension in model units

In case of error, the content is a dictionary containing a single ‘error’ key explaining the reason for failure. When the “X-Requested-With: XMLHttpRequest” header is set, the acceptance of the “Terms of Use” is implied. This mode is appropriate for uploading a design from your server, or from JavaScript.

When the “X-Requested-With: XMLHttpRequest” header is not set, the server response consists in a redirect to a Sculpteo-hosted web page showing the 3D model in case of success, or in HTML content in case of error, explaining the reason. In this case, “Terms of Use” must be explicitly accepted, by POSTing an additional parameter “terms” with value “1”. Also, the ‘share’, ‘print_authorization’, ‘customizable’, ‘unit’, ‘scale’, ‘rotation’ parameters become mandatory and must be POSTed as well. This mode is appropriate for uploading a design by suppling a form to the end-user.

It is possible to POST the content and information over HTTPS, to secure the upload. In this case, some extra optional parameters may be supplied to better control ownerships and rights of the uploaded content:


the username of the designer for this design


the password of the designer for this design


the code of the shop design list where to store the design

The designer must correspond to a Sculpteo user account. If a designer is provided, the password parameter is mandatory, and must correspond to the password of this user account. The list parameter is optional and if unset the design is not accessible from a shop design list. Shop design lists are managed in the user account ( and the code to provide as parameter value is shown under the list title. Note that setting the designer to a vendor account automatically applies the vendor’s default profit sharing to the design.

Alternatively, if HTTPS is not an option but design ownership needs to be set, it it possible to hash the file content, list value, and a shared secret, and POST the ‘provider’ and ‘hash’ keys in a similar manner to Web2Web upload to give ownership of the content to the given provider. Please contact us if you need this feature, as a provider account needs to be set up.

Tracking uploads and orders

By associating a tracking identifier to API uploads, it is possible to get reports on the number of uploaded and ordered files. First a new tracker must be created to identify those uploads. To do this, log into your user account and create a new tracker in your account ( Then set its UUID as the value for the ‘trackid’ key of the POST request.

Tracking upload progress

It is possible to track file upload progress by polling the following URL:


The UUID value should be set to a unique identifier, for example generated according to RFC4122 (, and should be also appended as a GET parameter named X-Progress-ID to the FORM_URL defined above.

The PROGRESS_URL provides JSON-encoded status data for the upload. It consists in a dictionary containing the following keys:


the current state of the upload


the total size of the uploaded file in bytes


the current number of bytes received

The state may be either:


no file data has been received yet


file upload is in progress


upload failed to complete


upload completed sucessfully

The “size” and “received” keys are only present in the “uploading” state and may be used to present a progress bar to the user.


POST a STL file named “cube”, and dump the JSON response:

curl -v -H "X-Requested-With: XMLHttpRequest" -F "[email protected];filename=cube.stl" --form-string "name=cube"

POST a STL file named “cube” securely, owned by the user account ‘test’ with password ‘test’ in shop list ‘SPs4D22vD8’

curl -v -H "X-Requested-With: XMLHttpRequest" -F "[email protected];filename=cube.stl" --form-string "name=cube" --form-string "designer=test" --form-string "password=test" --form-string "list=SPs4D22vD8'

POST a STL file named “cube”, with a short description, in inch units, orderable at scales 0.5 and 1, materials limited to white and blue plastic :

curl -v -H "X-Requested-With: XMLHttpRequest" -F "[email protected];filename=cube.stl" --form-string "name=cube" --form-string "description=A simple cube." --form-string "unit=in" --form-string "sizes=0.5,1" --form-string "materials=white_plastic,blue_plastic"

Given the UUID of the design, it is possible to visualize the design by going to the following URL:{UUID}

N.B.: When you using the API, it upload design as a designer and not as a user, which is why the design does not appear in your ‘my objects’ page.

Sample Request

By using the following HTML form and PHP code, you can issue a correct POST Request.

The following HTML form asks the user for information. This form only contains the mandatory parameters but can be extended easily.

<form action="upload.php" method="post" enctype="multipart/form-data">
        File     <input type="file" name="file"/><br/>
        Name     <input type="text" name="name"/><br/>
                        <input type="submit" name="submit" value="Upload"/>

PHP code that specifies the right POST parameters to issue a correct request.

	if (isset($_POST['submit'])) { //if the form has been submitted

		$tmpfile = $_FILES['file']['tmp_name'];
		$filename = basename($_FILES['file']['name']);
		$args['file'] = new CurlFile($tmpfile,'file/exgpd',$filename);

		$ch = curl_init();
		curl_setopt($ch, CURLOPT_HTTPHEADER, array("X-Requested-With: XMLHttpRequest")); //header
		curl_setopt($ch,CURLOPT_URL, ''); //url
		curl_setopt($ch, CURLOPT_POSTFIELDS, array( //parameters
				'file' => $args['file'],
				'name' => $_POST['name']
		curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); //To get the answer
		curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); //No HTTPS certificate
		$result = curl_exec($ch);

		echo $result;
Prev: HTTP POST Next: Split 3D content and meta data

» webapi documentation » Uploading Designs » HTTP POST » Direct upload

Last update: 1970-01-01 01:00 (CET)