Stencil Documentation
  • General
  • API
    • Authentication
      • Account
    • Pagination
    • Status Code and Throttling
    • Endpoints
      • Projects
      • Templates
      • Images
      • Collections
      • PDFs
      • Airtable
    • Charts
  • Using Stencil
    • Template Editor (New)
    • Template Editor (Legacy)
      • Limited Markdown Supports
      • Anchoring Element
      • Using Custom Font
      • Circular Text Positioning
    • White Label for Business
      • Setting Up Your First Client
      • DNS Setup with Cloudflare
  • Guides
    • Airtable Integration
      • Basic
    • Integromat Integration
      • Connection
      • Instant Trigger
    • Zapier Integration
      • Authentication
      • Trigger - New Image
      • Action - Create Image
    • Secure Signed Image
      • Basic
    • Query String Integration
      • Basic
      • Cache
    • Forms Integration
    • Case Studies
      • Generate Instagram Post from WooCommerce
      • Generate Open Graph Image for WordPress
      • Generate Personalized SendGrid Email Campaigns
      • Sending Charts to Twitter
      • Generate Instagram Post from Shopify
      • Automating Webflow Open Graph Image
      • Generate certificate of accomplishment
      • Automate Candidate's Certificate Generation
  • LINKS
    • Back to Stencil
    • Got bug?
    • Need feature?
    • Blog
Powered by GitBook
On this page
  • What is query string?
  • Guide
  • Requirements
  • 1. Select template to build query string integration
  • 2. Customize your query strings
  • 3. Testing your integration

Was this helpful?

  1. Guides
  2. Query String Integration

Basic

Guide to generating your first image variation with query string integration

PreviousQuery String IntegrationNextCache

Last updated 3 years ago

Was this helpful?

What is query string?

Query string is a key value pair that you can append to a URL. In this particular use case, we can use it to encode modification that needs to be applied to a template.

A good use case for this integration is to create open graph image, product images for your e-commerce store and many more.

By creating query string URL for your template, you can create variation of the image by just simply modifying the query string.

For example, the link below has two query strings - title and src. It generates the following image.

https://images.usestencil.com/qs/<template_id>/<image_base>.png?title=Pienza%2C%20Italy&src=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1569416078500-3857b00616f8%3Fixid%3DMnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8%26ixlib%3Drb-1.2.1%26auto%3Dformat%26fit%3Dcrop%26w%3D676%26q%3D80

By simply changing the query string title and src to something different, you could generate a new variation like below,

Guide

We will walk you through to create your first image variation.

Requirements

Unlike other integration, this is the simplest form of integration. All you need is your template. If you don't have one, choose from our selection of presets.

1. Select template to build query string integration

From the drop down menu, select "Query String URL". Alternatively, you can select "Console" and navigate to "Integrations" > "Query String".

2. Customize your query strings

You should now see the Query String wizard

Base URL

Our query strings are appended to this base URL. Base URL lets us know which template you want to create variation for.

Allowed Origins

This allows us to block any requests that come from unauthorized domains.

You can specify multiple origins, they must be separated by comma. Wilcard (*) character is allowed. Here's few examples.

Allowed Origins

Description

*

Allow all origins

*.usestencil.com

Allows app.usestencil.com, images.usestencil.com, and anything with that ends with .usestencil.com

usestencil.*

Allows usestencil.com, usestencil.org, usestencil.io, etc

usestencil.com, *.usestencil.com, example.com

Only allows usestencil.com, example.com, app.usestencil.com, api.usestencil.com, etc

We highly recommend that you setup this value to only domains you're going to use the integration with.

Why?

Allowed Query Strings

Here you would customize which query string belongs to which object to be modified.

In this example, we create two query strings - image which should change the src field for bg_image object and title which should change the text field for text_4 object.

Don't forget to save it you're done!

If you're unsure which object belongs to which item on your template, simply go to the "Test API" and consult the table for the right information.

3. Testing your integration

To test your query string, copy the URL from previous step and modify the query strings properly.

https://images.usestencil.com/qs/34aacb1e-a7e4-4b4d-bb64-2bffc3c930a4/CAfyfe8Cicm4bLiuKcTi45.png?image=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1590523277812-c3cc1176dd79%3Fixid%3DMnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8%26ixlib%3Drb-1.2.1%26auto%3Dformat%26fit%3Dcrop%26w%3D675%26q%3D80&text=Grand%20Canyon%2C%20USA

The above links give me,

The first image will take a few seconds to generate. If the modifications remain the same, the subsequent call to the image will retrieve the image from cache.

Unlike , anyone can create variation from this URL. If your templates are really good looking (which I'm sure they are) and without your branding, then anyone can use the URL to create variation for their own use. This will eat up your image generation quota.

The preview will show you how the URL will look like. Of course you need to replace those values with a real value and it must be properly .

Read more about .

Secure Signed Image
URL encoded
cache and quota
First variation
Second variation using the same template
Query String Integration wizard
Test API shows all the available modifications for your specific template
Result