Direct Upload

Direct Upload process, opposed to the Standard Upload process, refers to a simplified upload operation that unifies all the necessary steps for our standard Upload (Data registration, Sign upload, Upload items and Confirm upload).

This process has the advantage of providing a simpler and quicker upload process for any data to be uploaded to V7's internal storage.

For the direct upload process, we provide two different mechanism to upload your data:

1. Using file_content field: the contents of each file should be encoded in a Base64 string and uploaded alongside all its metadata to our internal storage.
2. Using file_url field: the file is fetched given a specified URL and uploaded to our internal storage.

🚧

File Content Size limitation

We have a 30MB payload size limit, so when using the file_content field might quickly hit this limit. If you hit this limit you should consider:

1. Splitting the direct upload request into several requests (if you are uploading multiple items in a single request)
2. Use the standard upload process if you have a file that is larger than 30MB
3. If possible, try to upload using the file_url option

Example 1: Upload an image to an existing Dataset using file_content field

Let's start by build the HTTP request payload. We need to define a list of items, which in this case is only a single item. It should include the desired file_name, the path in which we want to store each individual item, as well as the file_contents. The file_contents should be the contents of the file you wish to upload to V7, encoded in a Base64 string. This way we can upload the file_content alongside all the required metadata.

Encoding the file in a Base64 string can be done like this:

cat image.jpg | base64

import base64

image = open("/path/to/image.jpg", "rb")

image_b64 = base64.b64encode(image.read()).decode('ascii')

Example payload:

{
    "dataset_slug": "my-slug",
    "items": [{
        "file_name": "img_1.jpg",
        "path": "/img",
        "file_content": "<IMG-B64-STRING>"
    }]
}

We'll also need the dataset_slug in the body of the request to inform to which dataset we want to upload the file.

Moreover, to perform the request, we require 2 additional values: an API Key, and your Team slugged name.

📘

How to find your Team and Dataset slugged names with your API Key

You need an API Key and your Team and Dataset slugged names. Once you generate an API Key, learn how to find your Team and Dataset slugged name using the CLI here or you can do it through the UI by going to the Settings > Api Keys.

Example 2: Upload a multi-slot layout to an existing Dataset using file_content field

In some cases, we might want to render multiple media types alongside each other on the image canvas using the slots feature.
In this case, we need to provide a list of slots to upload, specifying the desired file_name, the path in which we want to store each individual item as well as the file_contents as before. Additionally, we also specify the slot_name of each individual slot.

Example payload:

{
  "dataset_slug": "my-slug",
  "items": [
    {
      "name": "item_name",
      "slots": [
        {
          "slot_name": "0",
          "file_content": "<IMG-B64-STRING>",
          "filename": "img_1.jpg",
          "type": "image"
        },
        {
          "slot_name": "1",
          "file_content": "<VID-B64-STRING>",
          "filename": "vid_1.mp4",
          "type": "video"
        }
      ]
    }
  ]
}

Example 3: Upload an image to an existing Dataset using file_url field

Instead of uploading the file contents, we can add a URL to the payload and fetch the file using the provided URL. Similarly, as in example 1, we define a list of items, which should include the desired file metadata (e.gfile_name, path) for each individual item. Additionally, we add the file_url field, where we specify the URL for the file we wish to upload to internal storage.

Example payload:

{
    "dataset_slug": "my-slug",
    "items": [{
        "file_name": "img_1.jpg",
        "path": "/img",
        "file_url": "https://www.some-url.com/img_1.jpg"
    }]
}

During the upload process, we'll stream the file from that URL and upload it to our internal storage, making it available in the dataset defined on the payload.

Example 4: Upload a multi-slot layout to an existing Dataset using file_content and file_url fields

We can also easily combine both file_content and file_url in our payloads. This allows us to pick which file source we wish to use in our items/slots. Thus, we can have one item/slot using the file_content field and have another item/slot using the file_url field.

Example payload:

{
  "dataset_slug": "my-slug",
  "items": [
    {
      "name": "item_name",
      "slots": [
        {
          "slot_name": "0",
          "file_url": "https://www.some-url.com/img_1.jpg",
          "filename": "img_1.jpg",
          "type": "image"
        },
        {
          "slot_name": "1",
          "file_content": "<VID-B64-STRING>",
          "filename": "vid_1.mp4",
          "type": "video"
        }
      ]
    }
  ]
}

In this case, for the first slot we will stream the image contents from the provided file_url to internal storage, while for the second slot, we will upload the video using its base64 encoded representation.