POST/orgs/:org/datasets/:dataset/content

Add content to a dataset

Content is added to an existing dataset by sending it to this resource. Content is sent as an array of objects which contains the unique ID for the content, the URL from which it can be retrieved and optional metadata that can be used later in the Vision API for content filtering.

The maximum content body length is 1MB. There is no limit on the number of content items per request.

The ID must be a unique string within the dataset.

A dataset can have multiple content items with different IDs but the same image URL. We allow for the use case when some content doesn’t have yet a permanent image, so a default / generic one is used instead. Having the same image multiple times in a dataset will increase the chance of seeing the image multiple times when making a Vision API request.

Image resolution should be as close to 256 pixels per edge, with a maximum of 1000 pixels. All ratios are accepted, so there is no need to do any padding, but consider cropping to clearly see the product/object. For datasets that have fashion related content you can have better results if the minimum image size is 300 pixels per edge.

Image Resolution Result Reason
447 x 300 pixels Good
  • Correct minimum dimensions for content matter (Fashion - see above)
  • Clear subject
866 x 300 pixels Good
  • Correct minimum height and under maximum with ratio
  • Good cropping to show product
907 x 300 pixels Good
  • Correct minimum height and under maximum with ratio
  • Good cropping to show product
  • Simple & homogeneous backgrounds to other images in dataset
427 x 424 pixels Bad
  • Correct image dimensions
  • Poor cropping
426 x 422 pixels Bad
  • Actual image is less than minimum resolution
  • Padding added
410 x 143 pixels Bad
  • Height less than minimum dimension
  • Good cropping to show product
  • Poor quality image
648 x 300 pixels Bad
  • Correct image resolution
  • Poor cropping showing multiple products, making identifying subject difficult

The optional metadata field is a JSON object that accepts key values of the following types: string, number, boolean and simple arrays with values of type string or number. Although we don’t check that the same keys have the same type for all content in a dataset, enforcing that on your side could avoid filtering issues when using the Vision API.

Upon processing an image, the Visii API adds image_width, image_height and image_url to metadata for use by your UI. Request these values with the fields parameter in the Vision API

Input

URL

Field Type Required Value Description
org string yes

The organisation name.

dataset string yes

The dataset name.

Body

Field Type Required Value Description
content array of objects yes

The content to add to the dataset.

content[].id string yes

The unique ID for the content. Maximum length is 255 characters.

content[].url string yes

An RFC 1738 compliant URL from which the image for the content can be retrieved. Supported image formats are jpeg, jpg and png.

content[].metadata object no

Content metadata information (category, price, quantity, availability, etc.).

Example

{
  "content": [
    {
      "id": "my-id-1",
      "url": "https://example.com/my-content-1.jpg"
    },
    {
      "id": "my-id-2",
      "url": "https://example.com/my-content-2.jpg",
      "metadata": {
        "category": "art",
        "quantity": 10,
        "price": 99.99,
        "available": true
      }
    },
    {
      "id": "my-id-3",
      "url": "https://example.com/my-content-3.jpg",
      "metadata": {
        "category": "drawings",
        "available": false
      }
    }
  ]
}

Request

curl -X POST \
     -H "Authorization: token my-org-api-token" \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.visii.v2+json" \
     -d '{"content":[{"id":"123","url": "http://example.com/image1.jpg"},{"id":"345","url":"http://example.com/image2.jpg"}]}' \
     "https://api.visii.com/orgs/my-org/datasets/my-dataset/content"

Response

Field Type Required Value Description
status string yes

The status of the response.

HTTP/1.1 202 Accepted
{
  "status": "accepted"
}