NAV
javascript shell python

Introduction

Welcome to the Social Image API Documentation!

You can use the API to generate images based on your templates that you or your team design in the app.

We have language bindings in Shell, Python, and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To check authentication, use this code:

fetch(`https://api.socialimage.app/v1/authenticate/`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${YOUR_PROJECT_API_KEY}`,
  },
});

import requests
import json
# POST the data to the API with your API Key
response = requests.post('https://api.socialimage.app/v1/authenticate',headers={'Authorization': 'Bearer YOUR_PROJECT_API_KEY'}, data=json.dumps(payload))
# Prints the JSON response
print(response.text)
# Use json.loads to parse the response
image_response_data = json.loads(response.text)

# With shell, you can just pass the correct header with each request
curl -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_PROJECT_API_KEY" \
   https://api.socialimage.app/v1/authenticate -v

Make sure to replace YOUR_PROJECT_API_KEY with your API key.

The above command returns JSON structured like this:

{
  "message": "Authentication successful.",
  "project": "Your Project Name",
  "project_id": "1949658f-bb74-4160-8f22-cd0d33388b9c"
}

The Social Image API keys to allow access to the API. You can register a new Social Image API key by creating an account :)

Social Image expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer YOUR_PROJECT_API_KEY

Images

Generate an image by sending a template ID and modifications to your template. These modifications can be images, text, fonts or colours, for example.

Image Object

{
  "url": "https://cdn.socialimage.app/images/651bd834d98c91d3ffddfc44a46c4ac6.png",
  "template": "468eb332-db60-40bc-9a33-3b8bee022d7b",
  "modifications": [
    {
      "name": "background_image",
      "url": "https://cnet1.cbsistatic.com/img/2ZjmzrycBZQD9Dpnt_EnfQ7TTro=/940x0/2020/05/31/5112f3db-5af6-431c-bc0d-a8108ccad2ee/spacex-falcon-9-launch.jpg"
    },
    {
      "name": "avatar",
      "url": "https://images.barrons.com/im-182667?width=620&size=1.5"
    }
  ],
  "images_remaining": 9,
  "created_at": "2022-02-06T17:12:31.993Z",
  "image_id": "43399fc7-d458-440e-9b57-67eaade622d0",
  "webhook_url": "https://example.com/handleIncomingImages",
  "webhook_response_code": 200
}

These attributes are provided by Social Image. Other attributes including in the response are provided by the user when the creation request is submitted.

Attribute Type Description
images_remaining Number The number of images your account can generate after this request has been fulfilled.
self String The API URL to this image object.
image_id String The unique ID of this image.
url String The Social Image CDN URL to the generated image.
webhook_response_code Number The HTTP response code received one the payload has been posted to your provided webhook_url. Or null if no webhook_url is provided.
created_at ISO DateString The time at which the image was generated. E.g 2022-02-06T17:20:07.268Z

Create an Image



import requests
import json
# Craft your request payload with the ID of your template
# Add your template modifications
payload = {
    "template": "YOUR_TEMPLATE_ID",
    "transparent": "true",
    "max_quality": "false",
    "modifications": [
        {
            "name": "quote",
            "text": "I could either watch it happen or be a part of it.",
            "color": "#000",
            "backgroundColor": "#000",
            "font": "Lato",
            "textTransform": "uppercase",
            "visible": "true"
        },
        {
            "name": "background_image",
            "url": "https://cnet1.cbsistatic.com/img/2ZjmzrycBZQD9Dpnt_EnfQ7TTro=/940x0/2020/05/31/5112f3db-5af6-431c-bc0d-a8108ccad2ee/spacex-falcon-9-launch.jpg",
            "screenshotURL": "https://www.socialimage.app",
            "visible": "true"
        },
        {
            "name": "avatar",
            "url": "https://images.barrons.com/im-182667?width=620&size=1.5",
            "visible": "true"
        },
        {
          "name": "starRating",
          "percent: "50",
        },
        {
          "name": "qrCode",
          "data": "https://www.socialimage.app/",
        }
    ]
}
# POST the data to the API with your API Key
response = requests.post('https://api.socialimage.app/v1/generate',headers={'Authorization': 'Bearer YOUR_PROJECT_API_KEY'}, data=json.dumps(payload))
# Prints the JSON response
print(response.text)
# Use json.loads to parse the response
image_response_data = json.loads(response.text)
# Outputs the url only
print(image_response_data["url"])


# With shell, you can just pass the correct header with each request
curl -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_PROJECT_API_KEY" \
 --request POST --data '{
   "template":"YOUR_TEMPLATE_ID",
   "webhook_url":"https://example.com/handleIncomingImages",
   "modifications":[{"name":"quote","text":"I could either watch it happen or be a part of it."}]}' \
   https://api.socialimage.app/v1/generate -v

The above command returns JSON structured like this:

{
  "url": "https://cdn.socialimage.app/images/651bd734d98c91d3ffddfc44a46c4ac6.png",
  "template": "YOUR_TEMPLATE_ID",
  "modifications": [
    {
      "name": "quote",
      "text": "I could either watch it happen or be a part of it.",
      "color": "#000",
      "backgroundColor": "#000",
      "font": "Lato",
      "textTransform": "uppercase",
      "visible": "true"
    },
    {
      "name": "background_image",
      "url": "https://cnet1.cbsistatic.com/img/2ZjmzrycBZQD9Dpnt_EnfQ7TTro=/940x0/2020/05/31/5112f3db-5af6-431c-bc0d-a8108ccad2ee/spacex-falcon-9-launch.jpg",
      "screenshotURL": "https://www.socialimage.app",
      "visible": "true"
    },
    {
      "name": "avatar",
      "url": "https://images.barrons.com/im-182667?width=620&size=1.5",
      "visible": "true"
    },
    {
      "name": "starRating",
      "percent": "50"
    },
    {
      "name": "qrCode",
      "data": "https://www.socialimage.app/"
    }
  ],
  "images_remaining": 9,
  "created_at": "2022-02-06T17:12:31.993Z",
  "image_id": "43399fc7-d458-440e-9b57-67eaade622d0",
  "webhook_url": "https://example.com/handleIncomingImages",
  "webhook_response_code": 200
}

This endpoint generates an image based on the template and modifications that you provide.

HTTP Request

POST https://api.socialimage.app/v1/generate

Options for template objects are provided in the modifications array with one or more objects to modify.

General

Parameter Required Description
template Yes The id for your template. How to find a template ID
transparent No If "true", render image as a PNG with a transparent background. Defaults to false.
max_quality No If "true", render image with max quality possible. Defaults to false 80% quality to keep image sizes small.
render_pdf No If "true", a PDF will be rendered alongside your image. Rendering a PDF costs 3 API credits.

TextBox Options

Parameter Required Description
name Yes The name of your textbox. This can be changed in the template editor. This name of your textbox is shown in the layers section.
text No Your updated text for your textbox. I.e your new blog post title or quote etc. You can also add emoji's to your text.
color No Override the text color. Supply a valid hex colour - E.g #000 #eeeeee
backgroundColor No Override the background color. Supply a valid hex colour - E.g #000 #eeeeee
font No Override the font used. Supply a valid font family name. This is as it appears in the font dropdown in the template editor.
textTransform No Override the default textTransform for your text. Valid options - "uppercase" or "lowercase"
visible No Toggle the visibility of your object in the generated image. Valid options: "true" or "false"

Image Options

Parameter Required Description
name Yes The name of your image. This can be changed in the template editor. This name of your image is shown in the layers section.
url No A valid URL to a publically accessible image that returns a 200 response.
smart_crop_enabled No Toggle the "Smart Crop" feature on your image
filter No Change the Filter used on your image. Set to "none" to remove the filter. See below for a list of the available filters.
visible No Toggle the visibility of your object in the generated image. Valid options: "true" or "false"

Avatar Image Options (Circular Image)

Parameter Required Description
name Yes The name of your circular image. This can be changed in the template editor. This name of your circular image is shown in the layers section.
url No A valid URL to a publically accessible image that returns a 200 response. This will replace the default image provided in the template.
smart_crop_enabled No Toggle the "Smart Crop" feature on your image
filter No Change the Filter used on your image. E.g "Grayscale". Set to "none" to remove the filter.
visible No Toggle the visibility of your object in the generated image. Valid options: "true" or "false"

Filters

Below is a list of the Filters that are currently available for images. Provide the name of the filter as a string when making an image generation request.

[
  "none",
  "Grayscale",
  "Sepia",
  "Brownie",
  "Vintage",
  "Pixelate",
  "Blur 10%",
  "Blur 25%",
  "Blur 50%",
  "Blur 75%",
  "Blur 100%",
  "Technicolor",
  "Polaroid",
  "Kodachrome",
  "BlackWhite"
]

Rectangle Object

Parameter Required Description
name Yes The name of your circular image. This can be changed in the template editor. This name of your circular image is shown in the layers section.
visible No Toggle the visibility of your object in the generated image. Valid options: "true" or "false"

Star Rating Object

The Star Rating Object allows you to add a simple star rating to your templates. Possible use cases include but are not limited to, product share images or book review share images etc.

Parameter Required Description
name Yes The name of the star rating object you wish to modify
percent No The perecentage you wish the stars to be filled to. E.g "50" or "75". Must be a number between 0-100

QR Code Object

The QR Code Object allows you to add a dynamic QR Code to your templates. Possible use cases include but are not limited to, event ID cards, event signage, conference room signage etc..

Parameter Required Description
name Yes The name of the QR Code object you wish to modify
data No The data you'd like the QR Code to use. This is usually a URL e.g https://www.socialimage.app

Chart Object

The Chart Object offers dynamic advanced chart rendering. Provide the data sets you'd like to render and the labels to use.

Parameter Required Description
name Yes The name of the QR Code object you wish to modify
chart_datasets No 1 or more datasets to use for the chart. An example value has been added below.
chart_lables No The labels to use for the data on this chart

chart_datasets

This must be an array of datasets. You can add 1 or more datasets.

[
  {
    "label": "www.socialimage.app",
    "data": [1, 2, 22, 4, 5, 6, 7],
    "borderColor": "blue",
    "backgroundColor": "blue"
  },
  {
    "label": "www.socialimage.app",
    "data": [1, 2, 22, 4, 5, 6, 7],
    "borderColor": "blue",
    "backgroundColor": "blue"
  }
]
Pie Chart

If you're using a Pie Chart then your backgroundColor property should be an array of colors that correlate to the data.

E.g.

[
  {
    "label": "www.socialimage.app",
    "data": [1, 2, 22, 4, 5, 6, 7],
    "backgroundColor": [
      "rgb(255, 99, 132)",
      "rgb(255, 159, 64)",
      "rgb(255, 205, 86)",
      "rgb(75, 192, 192)",
      "rgb(54, 162, 235)",
      "rgb(153, 102, 255)",
      "rgb(201, 203, 207)"
    ]
  }
]

chart_labels

You must provide an array of text strings for the chart_labels modification.

["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]

Retrieve an Image

Retrieve an Image you have already generated using the image_id provided.

Parameters

Parameter Required Type Description
image_id Yes String The unique image_id for the generated image you want to retrieve. 
fetch(`https://api.socialimage.app/v1/image/${IMAGE_ID}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${YOUR_PROJECT_API_KEY}`,
  },
});

curl -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_PROJECT_API_KEY" \
 --request POST https://api.socialimage.app/v1/image/IMAGE_ID -v

import requests
import json
# POST the data to the API with your API Key
response = requests.post('https://api.socialimage.app/v1/image/IMAGE_ID',headers={'Authorization': 'Bearer YOUR_PROJECT_API_KEY'})
# Parse the JSON response
image_response_data = json.loads(response.text)
# Outputs the image url only
print(image_response_data["url"])

Templates

Template Object

{
  "url": "https://cdn.socialimage.app/images/651bd834d98c91d3ffddfc44a46c4ac6.png",
  "template": "468eb332-db60-40bc-9a33-3b8bee022d7b",
  "modifications": [
    {
      "name": "background_image",
      "url": "https://cnet1.cbsistatic.com/img/2ZjmzrycBZQD9Dpnt_EnfQ7TTro=/940x0/2020/05/31/5112f3db-5af6-431c-bc0d-a8108ccad2ee/spacex-falcon-9-launch.jpg"
    },
    {
      "name": "avatar",
      "url": "https://images.barrons.com/im-182667?width=620&size=1.5"
    }
  ],
  "images_remaining": 9,
  "created_at": "2022-02-06T17:12:31.993Z",
  "image_id": "43399fc7-d458-440e-9b57-67eaade622d0",
  "webhook_url": "https://example.com/handleIncomingImages",
  "webhook_response_code": 200
}

These attributes are provided by Social Image. Other attributes including in the response are provided by the user when the creation request is submitted.

Attribute Type Description
images_remaining Number The number of images your account can generate after this request has been fulfilled.
self String The API URL to this image object.
image_id String The unique ID of this image.
url String The Social Image CDN URL to the generated image.
webhook_response_code Number The HTTP response code received one the payload has been posted to your provided webhook_url. Or null if no webhook_url is provided.
created_at ISO DateString The time at which the image was generated. E.g 2022-02-06T17:20:07.268Z

Retrieve a Template

This endpoint gets the details of a template from the provided TEMPLATE_ID

fetch(`https://api.socialimage.app/v1/template/${TEMPLATE_ID}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${YOUR_PROJECT_API_KEY}`,
  },
});

import requests
import json
# POST the data to the API with your API Key
response = requests.post('https://api.socialimage.app/v1/template/TEMPLATE_ID',headers={'Authorization': 'Bearer YOUR_PROJECT_API_KEY'})
# Use json.loads to parse the response
image_response_data = json.loads(response.text)
# Outputs the url only
print(image_response_data["url"])


# With shell, you can just pass the correct header with each request
curl -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_PROJECT_API_KEY" \
 --request POST https://api.socialimage.app/v1/template/TEMPLATE_ID -v

The above command returns JSON structured like this:

{
  "name": "Test Template",
  "id": "b4623026-ab13-4f80-bfa1-6d31a0babdc7",
  "preview_url": null,
  "width": "1200",
  "height": "630",
  "available_modifications": [
    {
      "name": "placeholder_text",
      "visible": "true",
      "text": "",
      "font": "",
      "backgroundColor": "",
      "textTransform": ""
    },
    { "name": "image_rect2", "visible": "true", "url": "" }
  ]
}

List Templates

This endpoint lists all templates for a given project.

import requests
import json
# POST the data to the API with your API Key
response = requests.post('https://api.socialimage.app/v1/templates',headers={'Authorization': 'Bearer YOUR_PROJECT_API_KEY'})
# Use json.loads to parse the response
image_response_data = json.loads(response.text)
# Outputs the url only
print(image_response_data["url"])

fetch(`https://api.socialimage.app/v1/templates`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${YOUR_PROJECT_API_KEY}`,
  },
});

# With shell, you can just pass the correct header with each request
curl -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_PROJECT_API_KEY" \
 --request POST https://api.socialimage.app/v1/templates -v

The above command returns JSON structured like this:

[
  {
    "name": "Test Template",
    "id": "b4623026-ab13-4f80-bfa1-6d31a0babdc7",
    "preview_url": null,
    "width": "1200",
    "height": "630",
    "available_modifications": [
      {
        "name": "placeholder_text",
        "visible": "true",
        "text": "",
        "font": "",
        "backgroundColor": "",
        "textTransform": ""
      },
      { "name": "image_rect2", "visible": "true", "url": "" }
    ]
  },
  {
    "name": "Test Template 2",
    "id": "31a62e67-5253-40c1-b877-e45ab467d3d3",
    "preview_url": null,
    "width": "1080",
    "height": "1080",
    "available_modifications": [
      { "name": "image_rect1", "visible": "true", "url": "" },
      {
        "name": "textbox1",
        "visible": "true",
        "text": "",
        "font": "",
        "backgroundColor": "",
        "textTransform": ""
      },
      { "name": "rect3", "visible": "true" }
    ]
  }
]

Response Codes

The Social Image API uses the following response codes:

Response Codes Meaning
200 Everything is good :)
400 Bad Request -- Check your template ID / modification paramters
401 Unauthorized -- API Key is invalid.
403 Forbidden -- You've run out of monthly images. Please upgrade or wait until your limit renews on...
429 Too many requests. Slow down! This will rarely ever occur since we scale to your requirements.
500 Internal Server Error -- There was an issue our side. Try again and if this persists then send an email to contact@socialimage.app
javascript shell python