PIX4Dengine Cloud API Documentation

Download OpenAPI specification:Download

Authentication

OAuth2

PIX4Dengine Cloud authentication procedure

This document describes how to get started with the PIX4Dengine Cloud REST API, which provides third party applications access to the Pix4D cloud service. It allows a PIX4Dengine Cloud client to access his/her data on the cloud and perform a range of operations on them.

  • For end to end security, HTTPS is used in all the APIs
  • The base URL for API endpoints is: https://cloud.pix4d.com
  • Each REST API call needs to be authenticated. See Authentication below
  • The communication format is expected to be JSON, unless otherwise stated

Getting access to PIX4Dengine Cloud REST API

To register the application and start using the PIX4Dengine Cloud REST API you will need to acquire a PIX4Dengine Cloud license. Please contact us at https://www.pix4d.com/enterprise-contact and we'll help you get set up and will give you a pair of client_id/client_secret that represents your application, the one that will connect to the API and that you will use to authenticate to the API.

Note that as its name suggests, client_secret is a password identifying the client application and therefore should be handle securely.

API Authentication

Equipped with the API client_id/client_secret, the first step is to retrieve an authentication token. An authentication token identifies both the application connecting to the API and the Pix4D user this application is connecting on behalf of.

This token must then be passed along every single request that the application makes to the API. It is passed in the HTTP Authorization header, like so:

Authorization: Bearer <ACCESS_TOKEN>

The PIX4Dengine Cloud REST API uses OAuth 2.0, the industry standard for connecting apps and accounts. OAuth 2.0 supports several "authentication flows" to retrieve an authentication token. Pix4D supports several of them that are each used for a specific purpose, but for PIX4Dengine Cloud customers, only one is relevant: "Client Credentials"

Client Credentials flow

Using this flow, an API client application can get access to its own Pix4D user account (and only to that account). With this method, the authentication is straightforward and only requires the applications' client_id/client_secret pair

The client must send the following HTTP POST request to https://cloud.pix4d.com/oauth2/token/ with a payload containing:

  • grant_type: client_credentials
  • client_id: the client ID of the application that was given to you by your Pix4D contact
  • client_secret: the client_secret of the application that was given to you by your Pix4D contact
  • token_format: jwt

example:

curl -X POST \
  -d "grant_type=client_credentials&token_format=jwt&client_id=YuB7fu…&client_secret=GMSVvt8dF…" \
  https://cloud.pix4d.com/oauth2/token/

Token information

Token content

The response you receive when performing the authentication request above has the following content (In JSON):

  • access_token: the token value that you will have to join in all your requests
  • token_type: for Pix4D, this is always a Bearer token
  • expires_in: the number of seconds the token is valid for. After this number of seconds, API requests using this token will get rejected and you will need to request a new token through the authentication procedure again
  • scope: describe what the token is valid for. In this case, it's always "read write" since you get a full access to your own account
{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 36000,
  "scope": "read write"
}

Refreshing the token

When the token expires, you simply need to perform the above authentication procedure again to get a fresh token.

Using the API

For an in-depth description of all possible API commands, please refer to the API documentation. This documentation is only available for users who already have an API access.

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://cloud.pix4d.com/oauth2/token
Scopes:
  • cloud:read -

    Grant read access

  • cloud:write -

    Grant write access

First Example

In this guide, you will discover how to get a token, upload a new project, get it processed, and access the results.

Prerequisites

API Access

You need a PIX4Dengine Cloud license to authenticate and get an access to the API. Please contact your Pix4D reseller to start a trial if you don't have a license already. More information is available on PIX4Dengine Cloud on our product page.

With this license comes your authentication information, your Client ID and Client Secret Key which are the two values you need in this guide.

Terminal tooling

This guide can be completed from the Terminal, using basic tooling:

  • curl command line is used to call the API, it should be included in your OS or docker image.
  • aws-cli is used to upload and download the data, you can get it directly from AWS: https://aws.amazon.com/cli/

Photos to process

We will use a set of photos to be processed in this guide. If you don't have a good dataset at your disposal, feel free to download one of our sample datasets, for example the building dataset. Select "Download", then "Input Images" from the UI. We consider you are unzipping the archive in ./photos in this guide.

Authenticate

We are using OAuth2 Client Credientials flow to generate an access token. Using the Client ID and Client Secret provided with your PIX4Dengine Cloud license, you can get an Access Token using the following curl command:

export PIX4D_CLIENT_ID=__YOUR_CLIENT_ID__
export PIX4D_CLIENT_SECRET=__YOUR_CLIENT_SECRET_KEY__
curl --request POST \
  --url https://cloud.pix4d.com/oauth2/token/ \
  --form client_id=$PIX4D_CLIENT_ID \
  --form client_secret=$PIX4D_CLIENT_SECRET \
  --form grant_type=client_credentials \
  --form token_type=access_token \
  --form token_format=jwt

The response body is a JSON document containing an access_token attribute:

{
  "access_token": "<__PIX4D_ACCESS_TOKEN__>",
  "expires_in": 172800,
  "token_type": "Bearer",
  "scope": "read:cloud write:cloud"
}

For the following example we will reference the token as PIX4D_ACCESS_TOKEN

export PIX4D_ACCESS_TOKEN=__PIX4D_ACCESS_TOKEN__

You can learn more about authentication in the reference documentation (see Authentication).

Create a new project

Let's start by creating a project. The only required parameter is the project name, which can be passed as a JSON payload in the request body.

curl --request POST \
  --url https://cloud.pix4d.com/project/api/v3/projects/ \
  --header "Authorization: Bearer ${PIX4D_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"name": "My first project"}'

The response will be a 201 CREATED and the response body will include the project details. Please keep note of the project id and important AWS S3 properties that we will use later.

This is an extract of the interesting JSON properties

{
  "id": 877866,
  "bucket_name": "prod-pix4d-cloud-default",
  "s3_base_path": "user-123123123121312/project-877866"
}
export PROJECT_ID=<THE PROJECT ID>
export S3_BUCKET=prod-pix4d-cloud-default
export S3_BASE_PATH="user-123123123121312/project-877866"

Upload the photos

It is recommended to use the shell AWS CLI or the python boto3 library but other tools can work as well. First, we need to retrieve the AWS S3 credentials associated with this project:

curl --url https://cloud.pix4d.com/project/api/v3/projects/$PROJECT_ID/s3_credentials/ \
  --header "Authorization: Bearer ${PIX4D_ACCESS_TOKEN}" \
  --header "Content-Type: application/json"

The answer contains all the S3 information we need, at least the access_key, secret_key and the session_token.

{
  "access_key": "ASIATOCJLBKSU2CVJIHR",
  "secret_key": "5OGGBSvn8Sesdu8l...<remainder of the secret key>",
  "session_token": "FwoGZXIvYX...<remainder of security token>",
  "expiration": "2021-05-10T21:55:47Z",
  "bucket": "prod-pix4d-cloud-default",
  "key": "user-199a56ab-7ac6-d6d1-4778-5b4d338fc9de/project-883349",
  "server_time": "2021-05-19T09:55:47.357641+00:00",
  "region": "us-east-1"
}

We can store the S3 credentials in our environment, so that they will get picked up by the AWS CLI tool.

export AWS_ACCESS_KEY_ID=ASIATOCJLBKSU2CVJIHR
export AWS_SECRET_ACCESS_KEY='5OGGBSvn8Sesdu8l...<remainder of the secret key>'
export AWS_SESSION_TOKEN='AQoDYXdzEJr...<remainder of security token>'

Make sure to prefix all your desired destination locations with the path returned in the credentials call. This is the only place for which write access is granted. Make sure that the files are proper images and their names include an extension supported by Pix4Dmapper.

Provided your images are located in a folder located at $HOME/images, and that it contains only images, you can run the command:

aws s3 cp ./images/ "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive

If your folder contains multiple images, you need to copy them one by one, likely using a script.

aws s3 cp $HOME/images/P0350035.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/P0360036.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/P0370037.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/P0380038.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/P0390039.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/P0400040.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/P0410041.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/P0420042.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/P0430043.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/P0440044.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive

You then need to register the images in the PIX4Dengine Cloud API so that they will be processed. It is possible to upload files that are not project inputs, and it is not possible to know which files are meant as input. It is therefore required to register each S3 uploaded file in the API. Register the uploaded files you uploaded (single API call):

curl --request POST --url https://cloud.pix4d.com/project/api/v3/projects/$PROJECT_ID/inputs/bulk_register/ \
  --header "Authorization: Bearer ${PIX4D_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data "{
      \"input_file_keys\": [
        \"${S3_BASE_PATH}/P0350035.JPG\",
        \"${S3_BASE_PATH}/P0360036.JPG\",
        \"${S3_BASE_PATH}/P0370037.JPG\",
        \"${S3_BASE_PATH}/P0380038.JPG\",
        \"${S3_BASE_PATH}/P0390039.JPG\",
        \"${S3_BASE_PATH}/P0400040.JPG\",
        \"${S3_BASE_PATH}/P0410041.JPG\",
        \"${S3_BASE_PATH}/P0420042.JPG\",
        \"${S3_BASE_PATH}/P0430043.JPG\",
        \"${S3_BASE_PATH}/P0440044.JPG\"
      ]
    }"

The response should confirm that the various images have been registered amongst other data.

{ "nb_images_registered": 10 }

Start processing

You are now ready to start processing your project:

curl --request POST --url https://cloud.pix4d.com/project/api/v3/projects/$PROJECT_ID/start_processing/ \
  --header "Authorization: Bearer ${PIX4D_ACCESS_TOKEN}" \
  --header "Content-Type: application/json"

Check the processing state

curl --url https://cloud.pix4d.com/project/api/v3/projects/$PROJECT_ID/ \
  --header "Authorization: Bearer ${PIX4D_ACCESS_TOKEN}" \
  --header "Content-Type: application/json"

A response can look like:

{
  "id": 883349,
  "name": "My first project",
  "display_name": "My first project",
  "project_group_id": null,
  "is_demo": false,
  "is_geolocalized": true,
  "create_date": "2021-05-19T11:53:39.504849+02:00",
  "public_status": "PROCESSING",
  "display_detailed_status": "Waiting for processing",
  "error_reason": "",
  "user_display_name": "Jhon Doe",
  "project_thumb": "<__URL__>",
  "detail_url": "https://cloud.pix4d.com/project/api/v3/projects/883349/",
  "acquisition_date": "2021-05-19T11:53:38.973075+02:00",
  "project_type": "pro",
  "image_count": 10,
  "last_datetime_processing_started": "2021-05-19T10:58:10.514800Z",
  "last_datetime_processing_ended": null,
  "bucket_name": "prod-pix4d-cloud-default",
  "s3_bucket_region": "us-east-1",
  "s3_base_path": "user-188a56ab-7ac6-d6d1-4778-5b4d338fc9de/project-883349",
  "never_delete": false,
  "under_trial": false,
  "uuid": "239ae97821d54f98975bc0afa2fcc72f",
  "coordinate_system": "",
  "outputs": {
    "mesh": { "texture_res": {} },
    "images": {
      "project_thumb": {
        "status": "processed",
        "name": "project_thumb.jpg",
        "s3_key": "user-188a56ab-7ac6-d6d1-4778-5b4d338fc9de/project-883349/thumb/project_thumb.jpg",
        "s3_bucket": "prod-pix4d-cloud-default"
      },
      "reflectance": {}
    },
    "map": { "layers": {}, "bounds": { "sw": [0, 0], "ne": [0, 0] } },
    "bundles": {
      "inputs": {
        "status": "requestable",
        "request_url": "https://cloud.pix4d.com/project/api/v3/projects/883349/inputs/zip/"
      }
    },
    "reports": {}
  },
  "min_zoom": -1,
  "max_zoom": -1,
  "proj_pipeline": ""
}

Once the status changes from PROCESSING to DONE, the project's main outputs are ready to be retrieved.

Once the project is processed, by querying its details, it is possible to:

  • Get its PIX4Dcloud visualization page
  • Get its PIX4Dcloud public page link (read-only)
  • Get any asset that was produced (in the form of an S3 link to the asset to be downloaded)

How to process a project

This guide describes all of the different ways to process a project with PIX4Dengine Cloud API. Once the project has been created, in order to process it, the following endpoint must be called:

POST on https://cloud.pix4d.com/project/api/v3/projects/{id}/start_processing/ The full documentation for this endpoint can be found here.

The body request includes:

{
  "custom_template_s3_key": "string",
  "custom_template_s3_bucket":