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

{
  "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

{
  "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
}

Last updated