NAV
shell python

Introduction

Welcome to the Social Image App API Documentation! You can use the API to generate images based on your templates that you 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 authorize, use this code:

import requests
import json
# Craft your request payload with the ID of your template
# Add your template modifications
payload = {
    "template": "YOUR_TEMPLATE_ID",
    "modifications": [
        {
            "name": "quote",
            "text": "I could either watch it happen or be a part of it."
        }
    ]
}
# 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",
   "modifications":[{"name":"quote","text":"I could either watch it happen or be a part of it."}]}' \
   https://api.socialimage.app/v1/generate -v

Make sure to replace YOUR_PROJECT_API_KEY with your API key. Make sure to replace YOUR_TEMPLATE_ID with your Template ID.

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

Social Image App 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

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",
    "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"
        }
    ]
}
# 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",
   "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",
  "images_remaining": 9
}

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.

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.
screenshotURL No A valid publically accessible webpage to screenshot. This currently works for background based images. I.e https://www.socialimage.app
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.
visible No Toggle the visibility of your object in the generated image. Valid options: "true" or "false"

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"

Templates

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'})
# 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 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" }
    ]
  }
]

Get Template

This endpoint gets the template data for a given template id.

import requests
import json
# POST the data to the API with your API Key
response = requests.post('https://api.socialimage.app/v1/template/YOURTEMPLATEID',headers={'Authorization': 'Bearer YOUR_PROJECT_API_KEY'})
# 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 https://api.socialimage.app/v1/template/YOURTEMPLATEID -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": "" }
  ]
}

Response Codes

The Social Image App 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 contact us :)