Formatting JSON Files

Learn how to format JSON files to use within the super.AI platform.

JavaScript Object Notation, or JSON, is a human-readable standardised file format. You can use JSON to add data points for processing in large numbers, and you can also download your processed data in JSON.

If you’re not familiar with JSON, you will find a few pointers here, along with examples of how to format your JSON files.

JSON basics

JSON is built around two structures:

  • Objects
    • Key-value pairs
    • Surrounded by curly brackets ({})
  • Arrays
    • Lists of items
    • Surrounded by square brackets ([])

Example JSON object:

{
  "first key":"first value",
  "second key":"second value",
  "third key":"third value"
}

Example JSON array:

["first item", "second item", "third item"]

📘

Commas are important

Each key-value pair or item has a comma after it, except for the last

You can also have arrays inside objects and objects inside arrays.

At super.AI, we always take a JSON array as the input, so your file will always begin and end with square brackets ([]). Each input or set of inputs will then go inside the array as an object.

You can check if your JSON is formatted correctly using an online tool, such as JSON Formatter & Validator.

Below you will find some formatting examples for common inputs.

How to format JSON files for image inputs

For each image you want to submit, you will need to provide an image URL pointing to the input file. Your image file will be inside an object. Use multiple objects, each with a different URL, to create multiple jobs at once.

[
  {
    "image_url":"https://cdn.super.ai/example01.jpeg"
  },
  {
    "image_url":"https://cdn.super.ai/example02.jpeg"
  },
  {
    "image_url":"https://cdn.super.ai/example03.jpeg"
  }
]

How to format JSON files for text inputs

Text is provided as a raw text string in a JSON object. It is the value of the text key. As with images, you can create multiple jobs by using multiple objects.

[
  {
    "text":"As a writer, Orwell produced literary criticism and poetry, fiction and polemical journalism; and is best known for the allegorical novella Animal Farm (1945) and the dystopian novel Nineteen Eighty-Four (1949)"
  },
  {
    "text":"In 1938, his radio anthology series The Mercury Theatre on the Air gave Welles the platform to find international fame as the director and narrator of a radio adaptation of H. G. Wells's novel The War of the Worlds, which caused widespread panic because many listeners thought that an invasion by extraterrestrial beings was actually occurring."
  },
  {
    "text":"Nabokov joined the staff of Wellesley College in 1941 as resident lecturer in comparative literature. The position, created specifically for him, provided an income and free time to write creatively and pursue his lepidoptery."
  }
]

How to format JSON files for multiple input data types

If the project type you’re using takes multiple input data types, e.g., audio and text, you should pair each set of inputs in an object. As always, you can use multiple objects to create multiple jobs. Here’s how it should look:

[
  {
    "audioUrl":"https://cdn.super.ai/example01.mp3",
    "text":"The rain in Spain falls mainly on the plains"
  },
  {
    "audioUrl":"https://cdn.super.ai/example02.mp3",
    "text":"In Hertford, Hereford, and Hampshire, hurricanes hardly happen"
  }
]

How to format JSON files with extra data

Include custom extra data with your inputs by creating additional property keys. We won’t do anything with this data except return it to you when you download your results. You can add extra data to individual data points or to a batch of data points.

🚧

JSON with extra data only through the API

Use our API to submit data points with extra data using JSON—it is not supported by the dashboard. You can use the create jobs endpoint to submit your data points.

Alternatively, you can use the CSV format to submit your data points with extra data through the dashboard.

Individual data points

In this example, an ID property key allows us to decorate each input with a custom ID:

[
  {
    "input":{
      "image_url":"https://cdn.super.ai/example01.jpeg"
    },
    "metadata":{
      "ID":1
    }
  },
  {
    "input":{
      "image_url":"https://cdn.super.ai/example02.jpeg"
    },
    "metadata":{
      "ID":2
    }
  },
  {
    "input":{
      "image_url":"https://cdn.super.ai/example03.jpeg"
    },
    "metadata":{
      "ID":3
    }
  }
]

Batches of data points

This examples shows a batch of 3 data points, all with the same extra data appended:

{
  "inputs": [
    {
      "image_url": "https://cdn.super.ai/example01.jpeg"
    },
    {
      "image_url": "https://cdn.super.ai/example02.jpeg"
    },
    {
    	"image_url": "https://cdn.super.ai/example03.jpeg"
    }
  ],
  "metadata": {"Type":"First batch"}
}