Temp file service

The temporary file service allows you to work with assets that are not stored in Content Hub. You can create a temporary file and pass this as a parameter to an API such as the Background removal API, or pass the URL to the GraphQL Asset Management API to create the asset in Content Hub.

The temporary file service supports single upload, for files of up to 100MB in size and multi part upload for files of up to 2GB.

Using the API

The API is implemented as the mutations createTempFileUploadUrl and createTempFileMultipartUploadUrl as part of the GraphQL Asset Management API.

Use createTempFileUploadUrl for uploads of up to 100MB and createTempFileMultipartUploadUrl for uploads up to 2GB in size.

The end point for all requests to the GraphQL Asset Management API is:

https://api.amplience.net/graphql

Amplience uses OAuth2 to authorize access to the GraphQL Asset Management API.

You can also use the API when logged in to the GraphQL playground.

Creating a temporary file

You can create a temporary file as follows:

mutation {
  createTempFileUploadUrl {
    uploadUrl
    downloadUrl
  }
}

This will return an upload URL and a download URL.

• Upload the file by making a PUT request to the upload URL we gave you with the file bytes in the request
• Call the Background removal API passing the download URL.

Note that when uploading to the temporary file service you need to ensure that the Content-Type header is set to a valid format for the image: image/jpeg or image/png, for example.

Example: Uploading a file using the temp file service

This example shows how to upload an image asset using the temp file service and generate a URL to pass to the Background removal API.

Generate a temporary file URL

To generate a temporary URL we use the createTempFileUploadUrl mutation:

mutation {
  createTempFileUploadUrl {
    uploadUrl
    downloadUrl
  }
}

uploadUrl and downloadUrl are returned in the response.

{
  "data": {
    "createTempFileUploadUrl": {
      "uploadUrl": "https://temp-file-upload.amplience.net/52a39c0c-f30a-492e-8eaa-106e23e14daa/WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ29udGVudC1TaGEyNTY9VU5TSUdORUQtUEFZTE9BRCZYLUFtei1DcmVkZW50aWFsPUFTSUFSWlNPVlNXVUpTN040SDdYJTJGMjAyMzExMDklMkZldS13ZXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjMxMTA5VDE3NDA1NlomWC1BbXotRXhwaXJlcz0zNjAwJlgtQW16LVNlY3VyaXR5LVRva2VuPUlRb0piM0pwWjJsdVgyVmpFS0glMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkZ3RWFDV1YxTFhkbGMzUXRNU0pHTUVRQ0lGJTJGMlFWbjNIQWY3bHJnQnY3ellLZGNnUVpzJTJGQUV5SUJVJTJCWk96VjN3S0lXQWlBYjElMkJrQkFnNVN4TUxZUHN6Wnh0MktEVUdkN25JdWVwYkdpWGROWWpmJTJGbkNxSEF3alolMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkY4QkVBTWFEREV5TXpZME5UTXdNakU0TkNJTXdobWF0WkN3ZXF4cEpQNFZLdHNDeWFHaUNDVWtHb2ZHWmZkJTJGaHk0RkduQ1MyNEZ0UDJCeXFmaHNidmolMkZHbTloWEVhajlBR2pnMzVNM2pKZU9YNjBGQ2RHeFNNOCUyQkFOSnlQZWRoYjVUWDRBbEFEZ0xKZUc1QjltU1AyOUhNanl5SVVqZ3hYeVNyb053SHBWVERuUDNueElqUldUaHNsVzYyS2JWaFIlMkZNQkclMkZjdyUyRmhwZDMyaFE2R08xdEpjUHRwUmVOY0t0VWglMkZTWEVnTmR2aUF5alRBeG0xd2J1emNveTFVcko1TUhzRTJPNDBCY0xuVFIwbUx3WXl1azNjVzVrUm9sViUyRjVtQnpZNngxQVhDJTJGZmwlMkIwTzVBJTJCakxJOTRKQlNrVnFEZGZjNTByT1ByeXJGdW5xQlFET2ltd1BtS3hlMzJWN0xIcUg3RmMlMkZ5NCUyQk9YNzlhYzBLVlVQbG8lMkJYSzh5emxjOWN1WWVBM2lhMGRobmxVbmVqQWxuUjlhcUZHWDNoUTNUbEhHVGNrbFl3d3duM0JoczhHT3p2TTVkS2FkOTMlMkIzbkRkdG9QMG1yMkthVkNxV2dnOGxLeXZtZ2tLbGlCNGR5YjVvUERzJTJCallNdmpzNXQ1aHVqMFJIdkk3YyUyQkJKSnN3elltMHFnWTZud0hHMFQ1cFBUWGNrWmVrUWE1RGNoeDVBNmFZaTFkS3B2NSUyQlFJTXlsd1RhQ1pXajZFUUVDNTI1Y1pHaUIwQlRYdzdtV3dBZ0gxcU9HRWNUVUl2NFNsJTJGV2pjVmVmaW5lcjZCb1czM2JNeGE0Um1sSmVGbUhsNUxCQ3F1OXpuTXpYTkdmRklNcXJvTG5DajFqVTE5ZVhKYW1KWjFoMHhtUW0zciUyRmNIa0hCQTAxUCUyQjlHT3FrZ3N6S3UlMkJvcDQ2elNwZlJUNmRUQ0xIVjN1TzBoV1JVMWFZMFElM0QmWC1BbXotU2lnbmF0dXJlPTVmZmEzODliNDAwNGVkNDliZjU2YzRkN2NlNTM5NzMyMGRkNTdkMTc2ZDBjYTQwZDEzMzUxOTY3NGQ2OWI5MjUmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JngtaWQ9UHV0T2JqZWN0",
      "downloadUrl": "https://temp-file-upload.amplience.net/52a39c0c-f30a-492e-8eaa-106e23e14daa"
    }
  }
}

Upload the image to the temporary file URL

Send a PUT request to upload to the temp file. This example uses cURL, but apart from your own code you could also use API tools such as Postman or Insomnia to send a PUT request. Note that you must set content-type to one of the supported image types- in this case image/jpg.

The filename is woman-black-beret.jpg.

curl https://temp-file-upload.amplience.net/52a39c0c-f30a-492e-8eaa-106e23e14daa/WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ29udGVudC1TaGEyNTY9VU5TSUdORUQtUEFZTE9BRCZYLUFtei1DcmVkZW50aWFsPUFTSUFSWlNPVlNXVUpTN040SDdYJTJGMjAyMzExMDklMkZldS13ZXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjMxMTA5VDE3NDA1NlomWC1BbXotRXhwaXJlcz0zNjAwJlgtQW16LVNlY3VyaXR5LVRva2VuPUlRb0piM0pwWjJsdVgyVmpFS0glMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkZ3RWFDV1YxTFhkbGMzUXRNU0pHTUVRQ0lGJTJGMlFWbjNIQWY3bHJnQnY3ellLZGNnUVpzJTJGQUV5SUJVJTJCWk96VjN3S0lXQWlBYjElMkJrQkFnNVN4TUxZUHN6Wnh0MktEVUdkN25JdWVwYkdpWGROWWpmJTJGbkNxSEF3alolMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkY4QkVBTWFEREV5TXpZME5UTXdNakU0TkNJTXdobWF0WkN3ZXF4cEpQNFZLdHNDeWFHaUNDVWtHb2ZHWmZkJTJGaHk0RkduQ1MyNEZ0UDJCeXFmaHNidmolMkZHbTloWEVhajlBR2pnMzVNM2pKZU9YNjBGQ2RHeFNNOCUyQkFOSnlQZWRoYjVUWDRBbEFEZ0xKZUc1QjltU1AyOUhNanl5SVVqZ3hYeVNyb053SHBWVERuUDNueElqUldUaHNsVzYyS2JWaFIlMkZNQkclMkZjdyUyRmhwZDMyaFE2R08xdEpjUHRwUmVOY0t0VWglMkZTWEVnTmR2aUF5alRBeG0xd2J1emNveTFVcko1TUhzRTJPNDBCY0xuVFIwbUx3WXl1azNjVzVrUm9sViUyRjVtQnpZNngxQVhDJTJGZmwlMkIwTzVBJTJCakxJOTRKQlNrVnFEZGZjNTByT1ByeXJGdW5xQlFET2ltd1BtS3hlMzJWN0xIcUg3RmMlMkZ5NCUyQk9YNzlhYzBLVlVQbG8lMkJYSzh5emxjOWN1WWVBM2lhMGRobmxVbmVqQWxuUjlhcUZHWDNoUTNUbEhHVGNrbFl3d3duM0JoczhHT3p2TTVkS2FkOTMlMkIzbkRkdG9QMG1yMkthVkNxV2dnOGxLeXZtZ2tLbGlCNGR5YjVvUERzJTJCallNdmpzNXQ1aHVqMFJIdkk3YyUyQkJKSnN3elltMHFnWTZud0hHMFQ1cFBUWGNrWmVrUWE1RGNoeDVBNmFZaTFkS3B2NSUyQlFJTXlsd1RhQ1pXajZFUUVDNTI1Y1pHaUIwQlRYdzdtV3dBZ0gxcU9HRWNUVUl2NFNsJTJGV2pjVmVmaW5lcjZCb1czM2JNeGE0Um1sSmVGbUhsNUxCQ3F1OXpuTXpYTkdmRklNcXJvTG5DajFqVTE5ZVhKYW1KWjFoMHhtUW0zciUyRmNIa0hCQTAxUCUyQjlHT3FrZ3N6S3UlMkJvcDQ2elNwZlJUNmRUQ0xIVjN1TzBoV1JVMWFZMFElM0QmWC1BbXotU2lnbmF0dXJlPTVmZmEzODliNDAwNGVkNDliZjU2YzRkN2NlNTM5NzMyMGRkNTdkMTc2ZDBjYTQwZDEzMzUxOTY3NGQ2OWI5MjUmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JngtaWQ9UHV0T2JqZWN0 --upload-file /Users/jonlansdell/woman-black-beret.jpg -H "Content-Type: image/jpg"

When the upload is complete you can check the contents of the downloadUrl returned by the temporary file service. This should contain the image you uploaded.

Using multi part upload

For any file greater than 100MB in size, such as a video, you will need to break the file into smaller chunks and upload it in parts using the createTempFileMultipartUploadUrl mutation.

createTempFileMultipartUploadUrl takes a fileSize parameter, the size in bytes of the file to be uploaded, as input. In the example shown below we are requesting to upload a 200MB file.

The following will be returned in the response:

• downloadUrl The URL of the uploaded file
• completeUrl The URL to send a POST request to when all parts of the file have been uploaded
• uploadPartUrls An array of URLs to upload each part of the file to using PUT requests.
• minPartSize The minimum size of the parts to be uploaded, in bytes
• maxPartSize The maximum size of the parts to be uploaded, in bytes

mutation {
  createTempFileMultipartUploadUrl(input: { filesize: 200000000 }) {
    downloadUrl
    completeUrl
    uploadPartUrls
    minPartSize
    maxPartSize
  }
}

To upload a file you need to:

• Split the file into parts. The size of each part must be between the minPartSize and maxPartSize. The minimum size of all but the last part is 5MB. The final part may be smaller.
• Upload each part of the file in sequence by sending a PUT request to each URL in the uploadPartUrls array in turn until all of the file is uploaded.

Note that the temporary URLs returned by createTempFileMultipartUploadUrl will expire after one hour.

info

When choosing the size of each section to upload you should consider the speed of your internet connection. Uploading smaller chunks will be more likely to succeed even on slow connections, while using larger chunks will be faster overall, but very large chunks will require a reliable, fast connection.

Sending the complete request

To indicate that the upload is complete, send a POST request to the URL returned in completeUrl.

The body of the POST request is in XML format and should contain a list of all the parts uploaded. For each part you must include:

• The part number
• The ETag of the part returned in the response to the upload request OR one of the checksum fields. The checksum fields can be calculated manually.

An example of the partial body of the request is shown below.

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUpload xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Part>
      <PartNumber>integer</PartNumber>
      <ETag>string</ETag>
      <ChecksumSHA1>string</ChecksumSHA1>
      <ChecksumSHA256>string</ChecksumSHA256>
      <ChecksumCRC32C>string</ChecksumCRC32C>
   </Part>
   ...
</CompleteMultipartUpload>

When the complete request is processed, the file is available at the downloadUrl. This URL can be passed to the createAsset mutation to create the asset in Content Hub.

Example: multi part upload using the temp file service

In this example we're uploading a video named new-blog-post.mp4 with a file size of 11723249 bytes. We'll split the file into parts, upload each part, send the complete request and then create the video asset in Content Hub. This file is small enough to be uploaded in a single part, but we'll upload it in multiple parts to demonstrate the process.

Generate multipart upload URLs

The CreateMultipartUploadUrl mutation is used to generate the upload URLs and the URL to use to send the complete request. When the upload is complete, downloadUrl is used with the createAsset mutation to add the asset to Content Hub.

mutation CreateMultipartUploadUrl {
  createTempFileMultipartUploadUrl(input: { filesize: 11723249 }) {
    downloadUrl
    completeUrl
    uploadPartUrls
    minPartSize
    maxPartSize
  }
}

Example response

We have truncated the URLs for readability, but the array of uploadPartUrls is shown below, together with the completeUrl and downloadUrl.

{
  "data": {
    "createTempFileMultipartUploadUrl": {
      "downloadUrl": "https://temp-file-upload.amplience.net/7c9e0ee0-c8a7-4f30-aa49-ebf136be462a",
      "completeUrl": "https://temp-file-upload.amplience.net/7c9e0ee0-c8a7-4f30-aa49-ebf136be462a/WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ29udGVudC1TaGEyNTY9VU5TSUdORUQtUEFZTE9BRCZYLUFtei1DcmVkZW50aWFsPUFTSUFSWlNPVlNXVUtPV05OQ1o0JTJGMjA…",
      "uploadPartUrls": [
        "https://temp-file-upload.amplience.net/7c9e0ee0-c8a7-4f30-aa49-ebf136be462a/WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ29udGVudC1TaGEyNTY9VU5TSUdORUQtUEFZTE9BRCZYLUFtei1DcmVkZW50aWFsPUFTSUFSWlNPVlNXVUtPV05OQ1o0JTJGMjA…",
        "https://temp-file-upload.amplience.net/7c9e0ee0-c8a7-4f30-aa49-ebf136be462a/WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ29udGVudC1TaGEyNTY9VU5TSUdORUQtUEFZTE9BRCZYLUFtei1DcmVkZW50aWFsPUFTSUFSWlNPVlNXVUtPV05OQ1o0JTJGMjA…",
        "https://temp-file-upload.amplience.net/7c9e0ee0-c8a7-4f30-aa49-ebf136be462a/WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ29udGVudC1TaGEyNTY9VU5TSUdORUQtUEFZTE9BRCZYLUFtei1DcmVkZW50aWFsPUFTSUFSWlNPVlNXVUtPV05OQ1o0JTJGMjA…"
      ],
      "minPartSize": 5242880,
      "maxPartSize": 2147483648
    }
  }
}

Split the file into parts

The file needs to be split into parts for upload and for this example we use the split command on the command line. 5MB is used as size of each part. The final part will be smaller.

split -b 5M /Users/jonlansdell/Documents/new-blog-post.mp4

Upload each part

To upload the file go through each URL in the uploadPartUrls array in turn and send a PUT request to the URL including the corresponding part of the file. In this example we'll use cURL to send a PUT request for each of the 3 parts of the file:

curl https://temp-file-upload.amplience.net/7c9e0ee0-c8a7-4f30-aa49-ebf136be462a/truncatedpart1URL --upload-file /Users/jonlansdell/xaa -v

curl https://temp-file-upload.amplience.net/7c9e0ee0-c8a7-4f30-aa49-ebf136be462a/truncatedpart2URL --upload-file /Users/jonlansdell/xab -v

curl https://temp-file-upload.amplience.net/7c9e0ee0-c8a7-4f30-aa49-ebf136be462a/truncatedpart3URL --upload-file /Users/jonlansdell/xac -v

If a PUT request is successful the response will include the ETag for the uploaded part. This should be included in the complete request sent when all parts are uploaded:

< HTTP/2 200
< date: Wed, 04 Sep 2024 11:26:29 GMT
< etag: "97ce90fa408e189f31d7aeb6204c9ea1"

The ETags returned in the response to each request in this example are as follows:

Part 1- 625c1805577b471034e03f28c5620eff

Part 2- f78130fcaf6bd8e1e215482f22b0bbdd

Part 3- 97ce90fa408e189f31d7aeb6204c9ea1

Send the complete request

When each part of the file has been uploaded send a POST request to the URL returned in completeUrl.

POST https://temp-file-upload.amplience.net/truncatedcompleteUrl

The body of the request must be in XML format and include either an ETag for each part of the file, or a checksum that you generate.

Using those ETags, the XML sent in the body of the complete request is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUpload xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Part>
      <PartNumber>1</PartNumber>
      <ETag>625c1805577b471034e03f28c5620eff</ETag>
   </Part>
   <Part>
      <PartNumber>2</PartNumber>
      <ETag>f78130fcaf6bd8e1e215482f22b0bbdd</ETag>
   </Part>
   <Part>
      <PartNumber>3</PartNumber>
      <ETag>97ce90fa408e189f31d7aeb6204c9ea1</ETag>
   </Part>
</CompleteMultipartUpload>

Create the asset in Content Hub

Once the complete request has been sent and 200 response is received, the downloadUrl returned by CreateMultipartUploadUrl can be used to add the asset to Content Hub. downloadUrl should be included in the src parameter. See examples for more details.

mutation {
  createAsset(
    input: {
      name: "new-blog-post"
      type: VIDEO
      filename: "new-blog-post.mp4"
      src: "https://temp-file-upload.amplience.net/7c9e0ee0-c8a7-4f30-aa49-ebf136be462a"
      assetRepositoryId: "QXNzZXRSZXBvc2l0b3J5OmU3Mjc0ZTI0LWQ0MzEtNGY2Yi05YzFiLTQwMDZmYjUwOWIxOQ=="
    }
  ) {
    id
  }
}