Using the service

The following examples outline the common usecases when working with the Pictofit Content Service. Keep in mind to add a bearer token to your CURL request with -H "Authorization: Bearer <YOUR-API-KEY>" when following the samples. The section Authentication describes how to retrieve a token.

Create a request

This section describes how you can create a valid request for the PICTOFiT Content Service. In this case we show how this can be done by guiding you through the creation of GARMENT_2D request. Here you need to provide images and additional meta data. Details on the input data can be found here.

Add a Product

To submit a request for creating a 2D Garment, different steps have to be taken. First, a new product entry has to be made. The entry consists of a name, an unique ID and the type of the object. The SKU field is optional and can be used to link it to your product database. In this case GARMENT_2D. Other available Product types can be fetched from the /products/types endpoint. The name is only for you to identify your products and can be arbitrary.

CODE

product.json
{
    "customerId": "<YOUR-CUSTOMER-ID>",
    "name": "My example product",
    "typeId": 1,
    "sku": "<CUSTOMER-UNIQUE-PRODUCT-ID>"
}

CODE

curl -v -X PUT https://api.cs.pictofit.com/v1.5/products/<NEW-UNIQUE-ID> \
    -d "@product.json" \
    -H "Content-Type: application/json" \
    -H 'Authorization: Bearer <YOUR-API-KEY>' \

Next, you need to create one or more configurations. Configurations can be different sizes or colors of a product. Analog to products, a configuration has a name and an optional unique ID. The SKU field is optional and can be used to link it to your product database. Again, you have to provide a fresh UUID (Version 4) for the <NEW-UNIQUE-ID> field as well as the <PRODUCT-ID> of the previously created product.

CODE

configuration.json
{
    "productId": "<PRODUCT-ID>",
    "name": "Default configuration",
    "sku": "<CUSTOMER-UNIQUE-CONFIGURATION-ID>",
}

CODE

curl -v  -X PUT https://api.cs.pictofit.com/v1.5/configurations/<NEW-UNIQUE-ID> \ 
    -d '@configuration.json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR-API-KEY>'

After the configuration entry has been made, you need to add one or more images. Image entries consist of a name, a type (e.g. frontal image, reference image, etc.) and the binary image data. Query the /files/types endpoint to get a list of the available image types. Please see the specifications for the required image types. Valid image mime-types are image/png and image/jpeg. To assign an image to a configuration, the <CONFIGURATION-ID> of the previously created configuration has to be provided.

CODE

curl -v -X POST https://api.cs.pictofit.com/v1.5/files \
    -H 'Authorization: Bearer <YOUR-API-KEY>' \
    -F 'file=@/path/to/your/upload.png;type=image/png' \
    -F 'id=<FRESH-ID-AS-UUID>' \
    -F 'name=frontal_image' \
    -F 'configurationId=<CONFIGURATION-ID>' \
    -F 'typeId=1'

Once you are done adding configurations and images, you have to let us know that the product is ready for processing. Therefore, you have to flag every configuration of the product as ready.

CODE

curl -v -X POST https://api.cs.pictofit.com/v1.5/configurations/<CONFIGURATION-ID>/ready \
    -d '' \
    -H 'Authorization: Bearer <YOUR-API-KEY>'

Now the product is ready for processing and will be transformed into an AR object by the Content Service.

Register Callbacks

The Content Service offers different callbacks to let you know for example that a product has been finished processing. To subscribe to these callbacks, you can simple register an endpoint that receives a POST request once the related event has happened. The id of the related object is appended to the url. The following example illustrates how to register the PRODUCT_COMPLETED callback. You can unregister the callback anytime by simple providing an empty endpoint url. A list of the available callbacks can be retrieved using the /Customer/callbacks/types endpoint.

JSON

callback.json
{
    "url": "https://customer.com/pictofit/product-completed/",
    "authorizationHeaderValue": "<YOUR-SERVER-SECRET>"
}

The url that should be called to trigger the callback. We append the object id to end. The authorizationHeaderValue that will added to the Authorization Header. If empty we do not add the header to the request.

CODE

curl -v -X PUT https://api.cs.pictofit.com/v1.5/customers/<CUSTOMER_ID>/callbacks/<CALLBACK_TYPE_ID> \
 -d '@callback.json' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer <YOUR-API-KEY>'

Test callback implementation

In order to test if your callback implementation is working you can use the following endpoint to trigger the callback: /customers/{customerId}/callbacks/{callbackType}/trigger/{id}

The id is the identifier of the finished object. In this case you can choose an arbitrary UUID. The customerId should be your customer id. The callbackType specifies the callback type that you wanna test here.

Retrieve a Finished Product

Once a product has finished processing, you can retrieve the result for each distinct configuration. Get all configurations of a product using the /products/{productId}/configurations endpoint.

CODE

curl -v -X GET https://api.cs.pictofit.com/v1.5/products/<PRODUCT-ID>/configurations \
    -H 'Authorization: Bearer <YOUR-API-KEY>'

The result will look somewhat like the following snippet.

JSON

[
    {
    "productId": "48d17eb6-88f4-4b99-9f21-2a6653a10bc8",
    "name": "Default",
    "sku": "netaporter1074749",
    "createdAt": 1533892992.2956457,
    "modifiedAt": 1533893672.3920932,
    "stateId": 4,
    "productTypeId": 1,
    "customerId": "428ab0cd-3205-4674-a188-08d5b0355406",
    "url": null,
    "results": [ ... ],
    "metadata": {},
    "id": "85f09939-272c-406f-b3ad-3b4fcc991517"
    }
]

The results field contains the resulting AR object in different formats (you usually will want to use the compressed one). The files hosted by the Content Service are used only for data exchange and must not be used directly from a client.