Collections

Collection allows you to create multiple images from multiple templates within a single request

Use cases

Generally, there are two use cases of collection,

1. To create images from multiple similar templates in a collection.

   Image if you have a similar template but with different dimension. For example, you could have three templates - one for Instagram post, one for Pinterest, and one for open graph.

2. To create image from randomly selected template in a collection.

   If you have multiple templates with similar content but with different design, you might want to generate an image randomly from the collection of templates. This is useful if you want to create Instagram post but you don't want the design to be the same.

How to create template collection

Before you can send a request to collection endpoint, you need to create the collection first.

1. Go to "Collections" tab and click on "+ New Collection"

2. Add the template that you want to add into the collection and save your changes.

Templates Compatibility

For best compatibility, each template's fields must have similar types. i.e. a field named text_1 must be of type textbox in all the templates.

Endpoints

Collection endpoint only available in asynchronous mode.

Create images from a template collection

POST https://api.usestencil.com/v1/collections

Create images from a template collection. This endpoint returns immediately. To get the images, you can specify a webhook_url or poll the collection endpoint.

Request Body

Name	Type	Description
select	number	Select n number of templates randomly from the collection. Leave blank to generate all.
metadata	object	Additional metadata that you want to add. This will be returned when the images are ready.
webhook_url	string	Webhook URL to call when the image is ready
modifications	array	Array of modifications. Similar to modifications in Images section.
collection	string	Collection ID

200 When the images are ready, the status field is set to completed. Otherwise, it is pending.

{
  "created_at": "2021-09-06T07:10:36.134Z",
  "id": "80b49653-2f71-4c2e-af92-cc861d686993",
  "images": [
    {
      "image_url": null,
      "image_url_jpg": null,
      "template_id": "4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7"
    }
  ],
  "metadata": null,
  "modifications": [
    {
      "name": "text_1",
      "text": "Hello world"
    },
    {
      "name": "author",
      "text": "Shulhi"
    }
  ],
  "self": "http://api.usestencil.test:4000/v1/collections/80b49653-2f71-4c2e-af92-cc861d686993",
  "status": "pending",
  "templates": [
    {
      "template": "Template 1",
      "template_id": "4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7"
    },
    {
      "template": "Template 2",
      "template_id": "1a7625b3-41ef-4838-9919-c684b98b93b4"
    }
  ],
  "updated_at": "2021-09-06T07:10:39.382Z",
  "webhook_url": null
}

Retrieve images from template collection

GET https://api.usestencil.com/v1/collections/:id

When the images are ready, the status field is set to completed.

Path Parameters

Name	Type	Description
id	string	The ID returned from previous POST request

200

{
  "created_at": "2021-09-06T07:10:36.134Z",
  "id": "80b49653-2f71-4c2e-af92-cc861d686993",
  "images": [
    {
      "image_url": "https://cdn.usestencil.com/images/4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7/ff6a4383-c35e-430f-b5d5-af124cf28a11.png",
      "image_url_jpg": "https://cdn.usestencil.com/images/4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7/ff6a4383-c35e-430f-b5d5-af124cf28a11.jpeg",
      "template_id": "4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7"
    }
  ],
  "metadata": null,
  "modifications": [
    {
      "name": "text_1",
      "text": "Hello world"
    },
    {
      "name": "author",
      "text": "Shulhi"
    }
  ],
  "self": "http://api.usestencil.test:4000/v1/collections/80b49653-2f71-4c2e-af92-cc861d686993",
  "status": "completed",
  "templates": [
    {
      "template": "Template 1",
      "template_id": "4c0a708e-fff0-4256-ad4b-45f4c2f2ebd7"
    },
    {
      "template": "Template 2",
      "template_id": "1a7625b3-41ef-4838-9919-c684b98b93b4"
    }
  ],
  "updated_at": "2021-09-06T07:10:39.382Z",
  "webhook_url": null
}