Create Images from Templates (Bulk)

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

ℹ️

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
templates	array	Array of template objects to generate images from
defaultOptions	object	(Optional) Default options to apply to all templates unless overridden

Template Object

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 (overrides defaultOptions)
viewportWidth	number	(Optional) Width of the viewport in pixels (overrides defaultOptions)
transparentBackground	boolean	(Optional) When true, generates images with transparent backgrounds (overrides defaultOptions)

DefaultOptions Object

Parameter	Type	Description
viewportHeight	number	(Optional) Default height of the viewport in pixels (default: 800)
viewportWidth	number	(Optional) Default width of the viewport in pixels (default: 1280)
transparentBackground	boolean	(Optional) Default transparent background setting (default: false)

curl --request POST \
  --url https://api.ojo.so/v1/image/bulk \
  --header 'Authorization: Bearer <API Key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "defaultOptions": {
      "viewportWidth": 1200,
      "viewportHeight": 630,
      "transparentBackground": false
    },
    "templates": [
      {
        "templateId": "product-card-template",
        "modifications": [
          {
            "title": "Premium Headphones",
            "price": "$199.99",
            "color": "#FF5733"
          },
          {
            "title": "Wireless Earbuds",
            "price": "$89.99",
            "color": "#33FF57"
          }
        ]
      },
      {
        "templateId": "social-post-template",
        "viewportHeight": 1080,
        "viewportWidth": 1080,
        "modifications": [
          {
            "heading": "Summer Sale",
            "tagline": "Up to 50% off",
            "bgColor": "#3357FF"
          }
        ]
      }
    ]
  }'

import requests
 
url = "https://api.ojo.so/v1/image/bulk"
 
payload = {
"defaultOptions": {
"viewportWidth": 1200,
"viewportHeight": 630,
"transparentBackground": False
},
"templates": [
{
"templateId": "product-card-template",
"modifications": [
{
"title": "Premium Headphones",
"price": "$199.99",
"color": "#FF5733"
},
{
"title": "Wireless Earbuds",
"price": "$89.99",
"color": "#33FF57"
}
]
},
{
"templateId": "social-post-template",
"viewportHeight": 1080,
"viewportWidth": 1080,
"modifications": [
{
"heading": "Summer Sale",
"tagline": "Up to 50% off",
"bgColor": "#3357FF"
}
]
}
]
}
 
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({
    "defaultOptions": {
      "viewportWidth": 1200,
      "viewportHeight": 630,
      "transparentBackground": false
    },
    "templates": [
      {
        "templateId": "product-card-template",
        "modifications": [
          {
            "title": "Premium Headphones",
            "price": "$199.99",
            "color": "#FF5733"
          },
          {
            "title": "Wireless Earbuds",
            "price": "$89.99",
            "color": "#33FF57"
          }
        ]
      },
      {
        "templateId": "social-post-template",
        "viewportHeight": 1080,
        "viewportWidth": 1080,
        "modifications": [
          {
            "heading": "Summer Sale",
            "tagline": "Up to 50% off",
            "bgColor": "#3357FF"
          }
        ]
      }
    ]
  })
};
 
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([
'defaultOptions' => [
'viewportWidth' => 1200,
'viewportHeight' => 630,
'transparentBackground' => false
],
'templates' => [
[
'templateId' => 'product-card-template',
'modifications' => [
[
'title' => 'Premium Headphones',
'price' => '$199.99',
'color' => '#FF5733'
],
[
'title' => 'Wireless Earbuds',
'price' => '$89.99',
'color' => '#33FF57'
]
]
],
[
'templateId' => 'social-post-template',
'viewportHeight' => 1080,
'viewportWidth' => 1080,
'modifications' => [
[
'heading' => 'Summer Sale',
'tagline' => 'Up to 50% off',
'bgColor' => '#3357FF'
]
]
]
]
]),
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(`{
    "defaultOptions": {
      "viewportWidth": 1200,
      "viewportHeight": 630,
      "transparentBackground": false
    },
    "templates": [
      {
        "templateId": "product-card-template",
        "modifications": [
          {
            "title": "Premium Headphones",
            "price": "$199.99",
            "color": "#FF5733"
          },
          {
            "title": "Wireless Earbuds",
            "price": "$89.99",
            "color": "#33FF57"
          }
        ]
      },
      {
        "templateId": "social-post-template",
        "viewportHeight": 1080,
        "viewportWidth": 1080,
        "modifications": [
          {
            "heading": "Summer Sale",
            "tagline": "Up to 50% off",
            "bgColor": "#3357FF"
          }
        ]
      }
    ]
  }`)
 
  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  \"defaultOptions\": {\n    \"viewportWidth\": 1200,\n    \"viewportHeight\": 630,\n    \"transparentBackground\": false\n  },\n  \"templates\": [\n    {\n      \"templateId\": \"product-card-template\",\n      \"modifications\": [\n        {\n          \"title\": \"Premium Headphones\",\n          \"price\": \"$199.99\",\n          \"color\": \"#FF5733\"\n        },\n        {\n          \"title\": \"Wireless Earbuds\",\n          \"price\": \"$89.99\",\n          \"color\": \"#33FF57\"\n        }\n      ]\n    },\n    {\n      \"templateId\": \"social-post-template\",\n      \"viewportHeight\": 1080,\n      \"viewportWidth\": 1080,\n      \"modifications\": [\n        {\n          \"heading\": \"Summer Sale\",\n          \"tagline\": \"Up to 50% off\",\n          \"bgColor\": \"#3357FF\"\n        }\n      ]\n    }\n  ]\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",
      "templateId": "product-card-template",
      "imageUrl": "https://example.com/path/to/image1.png",
      "createdAt": "2023-08-29T12:34:56Z"
    },
    {
      "id": "image-id-2",
      "templateId": "product-card-template",
      "imageUrl": "https://example.com/path/to/image2.png",
      "createdAt": "2023-08-29T12:34:57Z"
    },
    {
      "id": "image-id-3",
      "templateId": "social-post-template",
      "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",
      "templateId": "product-card-template",
      "imageUrl": "https://example.com/path/to/image1.png",
      "createdAt": "2023-08-29T12:34:56Z"
    },
    {
      "id": "image-id-3",
      "templateId": "social-post-template",
      "imageUrl": "https://example.com/path/to/image3.png",
      "createdAt": "2023-08-29T12:34:58Z"
    }
  ],
  "errors": [
    {
      "templateId": "product-card-template",
      "modify": {
        "title": "Wireless Earbuds",
        "price": "$89.99",
        "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 template ID is invalid.

{
  "error": true,
  "message": "Template not found: template-xyz"
}

Request payload unprocessable. Update necessary fields and try again.

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

Or when a template doesn’t have a templateId:

{
  "error": true,
  "message": "Provided inputs are not valid",
  "validationErrors": ["Each template must include 'templateId'"]
}

Or when a template doesn’t have modifications:

{
  "error": true,
  "message": "Provided inputs are not valid",
  "validationErrors": [
    "Template ID product-card-template must include non-empty 'modifications' array"
  ]
}

Or when exceeding the maximum batch size:

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

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 across all templates combined.
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