Uploading Photos

The Alpaca API offers a method for you to upload your photo assets and attach to itineraries or collections. We can take care of storage of the file assets, as well as the resizing and distribution via CDN.

There are a number of features that are included to assist your application, including:

• Resizing and optimising assets for use at the desired width/height aspect

• Accessing EXIF data for information about the camera used to take the photo

• Information about the original image upload stats

• AI or manual crop-hint placement for cropping assets

• AI label detection on the photo

• Content association, including attribution, copyright, captions and extended data attributes

The Alpaca API supports the upload of unassigned photos, which don't associate the media to your profile, or can be assigned to your profile. This affects the authorization model, invoking restrictions on whether changes can be made requiring an authorized profile actor.

Alpaca also supports a number of 3rd party hosted image services, including unsplashd (for stock imagery), Flickr (for public photos) and services such as MediaWiki (for open licensed imagery). It is also possible to self-host your assets on your own infrastructure and CDN.

Upload process summarised

To upload your process, you'll need to follow three steps:

1. Request information to perform a upload using startMediaUpload

2. Perform the upload via HTTPS with supplied details

3. Perform finalizeMediaUpload to identify when the media is ready to use

Requesting Upload Target

The API will determine the location that you should upload to and issue you with a token. You will need to take the url and fields list supplied, in order to compose a HTTP multi-part request along with your upload file.

• The token is required to finalize your upload once you have completed your photo upload.

• The url is the HTTPs end-point to send your request

• The fields contain data to include along with your file in your request in order to identify/authorize your request

1# Request information to commence a photo upload via HTTPs
2
3mutation StartPhotoUpload {
4  # Use the startMediaUpload() operation
5  startMediaUpload(
6    # Supply the filename label
7    filename: "cool-mavis-photo.jpeg"
8    # Supply the content type
9    contentType: "image/jpeg"
10  ) {
11    # Request an upload token. This will be used after the upload to call
12    # finalizeMediaUpload in order to inform the API which file upload we are
13    # refering to.
14    token
15    # URL Target to send the file
16    url
17    # Fields to include in HTTPs request (Signing fields)
18    fields
19  }
20}

Sandbox: Configure | Try Operation

Finalise Upload

After you have used the information supplied from startMediaUpload to perform your photo upload, you will need to finalise the request.

This operation indicates a status of the upload and processing stage and can be called to monitor for once the media is ready to be used. This process can take a short while in order for us to verify the upload and perform any required processing on media assets, ahead of it being used.

1# Finalise an upload process commenced with startMediaUpload, supplying content
2# and associations to profile. This operation will register the uploaded file
3# and supply you with ID's necessary to associate with other API types
4
5mutation ProcessPhotoUploadProgress {
6  # use the finalizeMediaUpload operation
7  finalizeMediaUpload(
8    # Supply the token created by startMediaUpload
9    token: "token123"
10    # Supply the profile ID you are authorized to modify. Use authorizedProfiles
11    # operation if you need to identify the profile ID for your API key
12    profileId: "profile/ABC123"
13    # Supply content for the media
14    resource: {
15      # Supply content for the resulting media resource
16      caption: "A photo of us standing out the front of Mavis the Grocer"
17    }
18  ) {
19    # Status will be "AwaitingUpload", "Processing", "Complete" or
20    # "ProcessingFailed" to represent the various states of finalizing the media
21    status
22    resource {
23      # Obtain the media identifier. This will be similar to "media/ABC123"
24      id
25    }
26  }
27}

Sandbox: Configure | Try Operation

Modifying the upload

Once you have completed an upload, your asset will become a MediaResource. You can perform other mutations from this point on the image.

1# Modifies a media asset to change various attributes or content
2
3mutation UpdatePhotoContent {
4  # Use the updateMediaResource operation
5  updateMediaResource(
6    # Supply the ID for the media, as accessed from finalizeMediaUpload
7    id: "media/ABC123"
8    resource: {
9      # Update various content, such as the attribution, caption, copyright
10      attribution: "My Photographer"
11      caption: "Updated caption for media"
12    }
13  ) {
14    # Query back what information you need once successfully modified the
15    # content (such as updated in-memory cache values)
16    resource {
17      # Identifiers
18      id
19      __typename
20
21      # Updated fields
22      attribution
23      caption
24    }
25  }
26}

Sandbox: Configure | Try Operation