Create Template

Create a new image template that can be used for generating images.

ℹ️

You will need to authenticate to use this API. See authentication.

💡

The template system supports various Handlebars helpers for dynamic content manipulation. Check out the Template Helpers section to learn about available helpers for formatting dates, performing calculations, manipulating strings, and more.

Request

POST https://api.ojo.so/v1/template

Headers

Header	Value	Description
Content-Type	application/json	Specify that the request body is JSON

Request Body

Field	Type	Description
html	string	The HTML content of the template (must be Base64 encoded)
variables	object	(Optional) Variables used in the template

The HTML content must be Base64 encoded. You can encode your HTML content using our HTML Encoder, or use standard Base64 encoding functions available in your programming language:

// JavaScript example
const encodedHtml = btoa('<div>Hello World!</div>');

# Python example
import base64
encoded_html = base64.b64encode('<div>Hello World!</div>'.encode()).decode()

Dynamic Template

You can create your template with Handlebars expressions and generate images by providing the necessary data. When making a request to generate an image, include a modify object in your request body with the data to populate your Handlebars placeholders. Learn how to create image with variables.

Example:

{
  "templateId": "template-uuid-123",
  "modify": {
    "title": "Welcome to Our Site",
    "user": {
      "name": "Alice Smith"
    },
    "showDetails": true,
    "items": ["Item 1", "Item 2", "Item 3"]
  }
}

curl --request POST \
  --url https://api.ojo.so/v1/template \
  --header 'Authorization: Bearer <API Key>' \
  --header 'Content-Type: application/json' \
  --header 'x-template-defaults: {"title":"Default Title"}' \
  --data '{
    "html": "...encoded HTML content...",
    "variables": {
      "title": "My Template Title"
    }
  }'

import requests
import json
 
url = "https://api.ojo.so/v1/template"
 
payload = json.dumps({
"html": "...encoded HTML content...",
"variables": {
"title": "My Template Title"
}
})
headers = {
'Authorization': 'Bearer <API Key>',
'Content-Type': 'application/json',
'x-template-defaults': '{"title":"Default Title"}'
}
 
response = requests.request("POST", url, headers=headers, data=payload)
 
print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <API Key>',
    'Content-Type': 'application/json',
    'x-template-defaults': '{"title":"Default Title"}'
  },
  body: JSON.stringify({
    html: '...encoded HTML content...",',
    variables: {
      title: 'My Template Title'
    }
  })
};
 
fetch('https://api.ojo.so/v1/template', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php
 
$curl = curl_init();
 
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ojo.so/v1/template",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'html' => '...encoded HTML content...",',
'variables' => [
'title' => 'My Template Title'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <API Key>",
"Content-Type: application/json",
"x-template-defaults: {\"title\":\"Default Title\"}"
],
]);
 
$response = curl_exec($curl);
$err = curl_error($curl);
 
curl_close($curl);
 
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

package main
 
import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)
 
func main() {
  url := "https://api.ojo.so/v1/template"
 
  payload := strings.NewReader(`{
    "html": "...encoded HTML content...",
    "variables": {
      "title": "My Template Title"
    }
  }`)
 
  req, _ := http.NewRequest("POST", url, payload)
 
  req.Header.Add("Authorization", "Bearer <API Key>")
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("x-template-defaults", "{\"title\":\"Default Title\"}")
 
  res, _ := http.DefaultClient.Do(req)
 
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)
 
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"html\": \"...encoded HTML content...",\",\n  \"variables\": {\n    \"title\": \"My Template Title\"\n  }\n}");
Request request = new Request.Builder()
  .url("https://api.ojo.so/v1/template")
  .method("POST", body)
  .addHeader("Authorization", "Bearer <API Key>")
  .addHeader("Content-Type", "application/json")
  .addHeader("x-template-defaults", "{\"title\":\"Default Title\"}")
  .build();
Response response = client.newCall(request).execute();

Response

Template successfully created.

{
  "id": "template-uuid-123",
  "message": "Template created successfully"
}

Your API key might be invalid or expired.

{
  "error": true,
  "message": "Unauthorized"
}

Request payload unprocessable. Update necessary fields and try again.

{
  "error": true,
  "message": "Failed to decode `html`. Ensure it is properly encoded. Visit https://ojo.so/tools/html-encoder"
}

You have hit your rate limit. You can view rate limit details here.

Too Many Requests

An unexpected error occurred. Try again later. If the issue persists, please reach out.

{
  "error": true,
  "message": "Internal server error"
}

Transform Image Update Template