Create Images from Template (Bulk)

Send a POST request to this endpoint to create multiple images at once using a predefined template.

ℹ️

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

ℹ️

This endpoint consumes 1 credit per image generated in the batch. For example, requesting 10 image variations will consume 10 credits.

Request

POST https://api.ojo.so/v1/image/bulk

Request Body

Parameter	Type	Description
templateId	string	The ID of the template to use
modifications	array	Array of objects containing variables to modify in the template for each image
viewportHeight	number	(Optional) Height of the viewport in pixels (default: 800)
viewportWidth	number	(Optional) Width of the viewport in pixels (default: 1280)
transparentBackground	boolean	(Optional) When set to true, generates the image with a transparent background. Defaults to false if not specified.

curl --request POST \
  --url https://api.ojo.so/v1/image/bulk \
  --header 'Authorization: Bearer <API Key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "your-template-id",
    "modifications": [
      {
        "title": "First Image Title",
        "color": "#FF5733"
      },
      {
        "title": "Second Image Title",
        "color": "#33FF57"
      },
      {
        "title": "Third Image Title",
        "color": "#3357FF"
      }
    ],
    "viewportHeight": 1000,
    "viewportWidth": 1500,
    "transparentBackground": false
  }'

import requests
 
url = "https://api.ojo.so/v1/image/bulk"
 
payload = {
"templateId": "your-template-id",
"modifications": [
{
"title": "First Image Title",
"color": "#FF5733"
},
{
"title": "Second Image Title",
"color": "#33FF57"
},
{
"title": "Third Image Title",
"color": "#3357FF"
}
],
"viewportHeight": 1000,
"viewportWidth": 1500,
"transparentBackground": False
}
 
headers = {
"Authorization": "Bearer <API Key>",
"Content-Type": "application/json"
}
 
response = requests.post(url, json=payload, headers=headers)
 
print(response.text)

const options = {
method: 'POST',
headers: {
  'Authorization': 'Bearer <API Key>',
  'Content-Type': 'application/json'
},
body: JSON.stringify({
  templateId: 'your-template-id',
  modifications: [
    {
      title: 'First Image Title',
      color: '#FF5733'
    },
    {
      title: 'Second Image Title',
      color: '#33FF57'
    },
    {
      title: 'Third Image Title',
      color: '#3357FF'
    }
  ],
  viewportHeight: 1000,
  viewportWidth: 1500,
  transparentBackground: false
})
};
 
fetch('https://api.ojo.so/v1/image/bulk', 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/image/bulk",
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([
'templateId' => 'your-template-id',
'modifications' => [
[
'title' => 'First Image Title',
'color' => '#FF5733'
],
[
'title' => 'Second Image Title',
'color' => '#33FF57'
],
[
'title' => 'Third Image Title',
'color' => '#3357FF'
]
],
'viewportHeight' => 1000,
'viewportWidth' => 1500,
'transparentBackground' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <API Key>",
"Content-Type: application/json"
],
]);
 
$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/image/bulk"
payload := strings.NewReader(`{
  "templateId": "your-template-id",
  "modifications": [
    {
      "title": "First Image Title",
      "color": "#FF5733"
    },
    {
      "title": "Second Image Title",
      "color": "#33FF57"
    },
    {
      "title": "Third Image Title",
      "color": "#3357FF"
    }
  ],
  "viewportHeight": 1000,
  "viewportWidth": 1500,
  "transparentBackground": false
}`)
 
req, _ := http.NewRequest("POST", url, payload)
 
req.Header.Add("Authorization", "Bearer <API Key>")
req.Header.Add("Content-Type", "application/json")
 
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  \"templateId\": \"your-template-id\",\n  \"modifications\": [\n    {\n      \"title\": \"First Image Title\",\n      \"color\": \"#FF5733\"\n    },\n    {\n      \"title\": \"Second Image Title\",\n      \"color\": \"#33FF57\"\n    },\n    {\n      \"title\": \"Third Image Title\",\n      \"color\": \"#3357FF\"\n    }\n  ],\n  \"viewportHeight\": 1000,\n  \"viewportWidth\": 1500,\n  \"transparentBackground\": false\n}");
Request request = new Request.Builder()
.url("https://api.ojo.so/v1/image/bulk")
.method("POST", body)
.addHeader("Authorization", "Bearer <API Key>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();

Response

Everything went as planned and your images are generated.

{
  "images": [
    {
      "id": "image-id-1",
      "imageUrl": "https://example.com/path/to/image1.png",
      "createdAt": "2023-08-29T12:34:56Z"
    },
    {
      "id": "image-id-2",
      "imageUrl": "https://example.com/path/to/image2.png",
      "createdAt": "2023-08-29T12:34:57Z"
    },
    {
      "id": "image-id-3",
      "imageUrl": "https://example.com/path/to/image3.png",
      "createdAt": "2023-08-29T12:34:58Z"
    }
  ],
  "totalRequested": 3,
  "successCount": 3,
  "failureCount": 0
}

If some images failed to generate, you will receive both successful results and errors:

{
  "images": [
    {
      "id": "image-id-1",
      "imageUrl": "https://example.com/path/to/image1.png",
      "createdAt": "2023-08-29T12:34:56Z"
    },
    {
      "id": "image-id-3",
      "imageUrl": "https://example.com/path/to/image3.png",
      "createdAt": "2023-08-29T12:34:58Z"
    }
  ],
  "errors": [
    {
      "modify": {
        "title": "Second Image Title",
        "color": "#33FF57"
      },
      "error": "Failed to generate image",
      "logs": ["Error detail information"]
    }
  ],
  "totalRequested": 3,
  "successCount": 2,
  "failureCount": 1
}

Your API key might be invalid or expired.

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

Your credits are depleted. You need to purchase more credits to use the API.

{
  "error": true,
  "message": "Payment Required"
}

Requested templateId is invalid.

{
  "error": true,
  "message": "Template not found"
}

Request payload unprocessable. Update necessary fields and try again.

{
  "error": true,
  "message": "Provided inputs are not valid",
  "validationErrors": ["Provide 'templateId' in the request body"]
}

Or when the modifications array is empty or invalid:

{
  "error": true,
  "message": "Provided inputs are not valid",
  "validationErrors": ["Provide 'modifications' array in the request body"]
}

Or when exceeding the maximum batch size:

{
  "error": true,
  "message": "Provided inputs are not valid",
  "validationErrors": ["Maximum 50 images can be generated at once"]
}

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

Limitations

Maximum Batch Size: You can generate up to 50 images in a single batch request.
Credit Consumption: Each image generated in the batch consumes 1 credit.
Rate Limiting: Bulk requests are subject to the same rate limits as individual requests. See rate limits for details.

Create Image from Template List Images