LogoLogo
  • Overview
  • Quick Start
  • Authentication
  • Rate limits
  • Errors
  • Image Editing API
    • Image I/O
    • Image Operations
      • Restorations
      • Resizing
      • Outpainting
      • Generative Editing
      • Color Adjustments
      • Background
      • Padding
      • Privacy
    • API Reference
    • Async API Reference
    • Batch API Reference
    • Upload API Reference
  • image generation api
    • Image Generation I/O
    • Image Generation Options
    • API Reference
  • AI Background API
    • AI Background I/O
    • AI Background Options
      • Object
      • Scene
      • Product Shadow
    • API Reference
  • Image to Video API
    • Image to Video I/O
    • Image to Video Options
    • Async API Reference
  • Storage Connectors
    • Overview
    • AWS S3
    • Google Cloud Storage
    • Web Folder
    • API Reference
  • Guides
    • E-commerce
    • Real Estate
    • Printing
  • Redoc
  • Blog
Powered by GitBook
On this page
Edit on GitHub
  1. Image Editing API

Batch API Reference

PreviousAsync API ReferenceNextUpload API Reference

Last updated 7 months ago

Batch image edit contract

Batch endpoint allows batch processing of images by specifying a cloud Storage directory as input. See for more info.

In other aspects, the Batch endpoint behaves like the , returning a response without waiting for an actual result that should be queried with another request.

By default, it is expected that the images will be located in the root of the cloud directory that is specified in the input field. To retrieve all images from subdirectories recursively, the input field should have the recursive parameter as following:

{
  "input": {
    "source": "storage://storage_1/input_folder/",
    "recursive": true
  },
  ...
}

In the Batch endpoint you could also set input as list of publicly accessible URLs, so our service can fetch and process them:

{
  "input": ["https://image.site/image.png", "https://image.site/image.png"],
  ...
}

Request image processing

Request

POST /v1-beta1/image/edit/batch HTTP/1.1
Host: api.claid.ai
Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json

{
  "input": "storage://storage_1/input_folder/",
  "operations": {
    "resizing": {
      "width": 1000
    },
    "background": {
      "remove": false
    }
  },
  "output": "storage://storage_1/output_folder/"
}
curl -X POST --location "https://api.claid.ai/v1-beta1/image/edit/batch" --http1.1 \
    -H "Host: api.claid.ai" \
    -H "Authorization: Bearer {YOUR_API_KEY}" \
    -H "Content-Type: application/json" \
    -d "{
          \"input\": \"storage://storage_1/input_folder/\",
          \"operations\": {
            \"resizing\": {
              \"width\": 1000
            },
            \"background\": {
              \"remove\": false
            }
          },
          \"output\": \"storage://storage_1/output_folder/\"
        }"    -H "Authorization: Bearer {YOUR_API_KEY}"

Read a response

Response body

{
  "data": {
    "id": 1,
    "status": "ACCEPTED",
    "result_url": "https://api.claid.ai/v1-beta1/image/edit/batch/1",
    "created_at": "2023-03-13T11:37:09.160554+00:00",
    "request": {
      "input": "storage://storage_1/input_folder/",
      "operations": {
        "resizing": {
            "width": 1000
        },
        "background": {
            "remove": false
        }
      },
      "output": "storage://storage_1/output_folder/"
    }
  }
}

Result of request processing contract

To get Batch image editing result, you need to know the ID of the processing request. Or you can take a ready-to-use link from the result_url property of the response body described above.

Request

GET /v1-beta1/image/edit/batch/1 HTTP/1.1
Host: api.claid.ai
Authorization: Bearer {YOUR_API_KEY}
curl -X GET --location "https://api.claid.ai/v1-beta1/image/edit/batch/1" --http1.1 \
    -H "Host: api.claid.ai" \
    -H "Authorization: Bearer {YOUR_API_KEY}"

Read a response

Once you have made the request to https://api.claid.ai/v1-beta1/image/edit/batch/<task_id> you will get a response with information about the request, input, and output images.

Image information shown in the response:

Parameter
Type
Description

id

integer

Task ID.

status

string

Request processing status. Can have values: ACCEPTED, PROCESSING, ERROR, DONE.

created_at

string

Exact time when the processing was requested.

request

object

The body of the request that was used for processing.

errors

list

List of errors, if any are occurred during image processing (status will have ERROR value), in other cases - will be empty.

results

list

List of results in form of input_object and output_object pairs, in case of processing errors - will be empty. Details are listed below.

Response body

{
  "data": {
    "id": 1,
    "status": "DONE",
    "created_at": "2023-03-13T11:37:09.160554+00:00",
    "request": {
      "input": "storage://storage_1/input_folder/",
      "operations": {
        "resizing": {
            "width": 1000
        },
        "background": {
            "remove": false
        }
      },
      "output": "storage://storage_1/output_folder/"
    },
    "errors": [],
    "results": [
      {
        "input_object": {
          "ext": "pnj",
          "mps": 0.04,
          "mime": "image/jpeg",
          "format": "JPEG",
          "width": 200,
          "height": 200
        },
        "output_object": {
          "ext": "jpeg",
          "mps": 1.0,
          "mime": "image/jpeg",
          "format": "JPEG",
          "width": 1000,
          "height": 1000
        }
      },
      {
        "input_object": {
          "ext": "pnj",
          "mps": 0.09,
          "mime": "image/jpeg",
          "format": "JPEG",
          "width": 300,
          "height": 300
        },
        "output_object": {
          "ext": "jpeg",
          "mps": 1.0,
          "mime": "image/jpeg",
          "format": "JPEG",
          "width": 1000,
          "height": 1000
        }
      }
    ]
  }
}

The request body for Batch endpoint is the same as for regular image edit operation, except Storage directories are allowed for input and output parameters. See for more info.

Once you have made the request to https://api.claid.ai/v1-beta1/image/edit/batch you will get a response with information about request status and other details, see the part of the page for more info.

See the and to learn about headers.

See input_object and output_object properties description at the part of the page.

See to learn about headers.

Storage overview
Async endpoint
Image edit contract
Read a response
Async endpoint
Request Headers
Response Headers
Read a response
Async endpoint
Response headers

Image Edit Batch Async Results

get
Authorizations
Path parameters
task_idintegerRequired
Responses
200
Successful Response
application/json
401
Authorization is required.
application/json
403
Not enough permissions.
application/json
404
Batch image edit pipeline not found.
application/json
422
Unprocessable Entity.
application/json
get
GET /v1-beta1/image/edit/batch/{task_id} HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
  "data": {
    "id": 1,
    "status": "ACCEPTED",
    "result_url": "https://example.com",
    "created_at": "2025-06-13T13:58:48.260Z",
    "request": {
      "input": "storage://storage_1/input_folder/ | https://image_url.com/example.jpg | [https://image_url.com/example.jpg, https://image_url.com/example.jpg]",
      "operations": {
        "restorations": {
          "decompress": "moderate",
          "upscale": "smart_enhance",
          "polish": false
        },
        "adjustments": {
          "hdr": 0,
          "exposure": 0,
          "saturation": 0,
          "contrast": 0,
          "sharpness": 0
        },
        "background": {
          "remove": false,
          "color": "text",
          "blur": false
        },
        "resizing": {
          "width": "auto",
          "height": "auto",
          "fit": "crop"
        },
        "padding": "text",
        "privacy": {
          "blur_car_plate": false,
          "identity_crop": false
        },
        "generative": {
          "style_transfer": {
            "style_reference_image": "text",
            "prompt": "text",
            "depth_strength": 1,
            "denoising_strength": 0.75,
            "style_strength": 0.75
          }
        }
      },
      "output": "storage://storage_1/output_folder/"
    },
    "errors": [
      {
        "error": "text",
        "created_at": "text",
        "input_object": {
          "ext": "text",
          "mps": 1,
          "mime": "text",
          "format": "text",
          "width": 1,
          "height": 1
        }
      }
    ],
    "results": [
      {
        "input_object": {
          "ext": "text",
          "mps": 1,
          "mime": "text",
          "format": "text",
          "width": 1,
          "height": 1
        },
        "output_object": {
          "ext": "text",
          "mps": 1,
          "mime": "text",
          "format": "text",
          "width": 1,
          "height": 1,
          "tmp_url": "text",
          "object_key": "text",
          "object_bucket": "text",
          "object_uri": "text",
          "claid_storage_uri": "text"
        }
      }
    ]
  }
}
  • Batch image edit contract
  • Request image processing
  • POSTProcess Batch Image Edit
  • Result of request processing contract
  • GETImage Edit Batch Async Results

Process Batch Image Edit

post

Specifies:

  • what images will be processed (input)
  • how they will be processed (operations)
  • where they will be stored (output)
Authorizations
Body
inputany ofRequired

URL of the input file or folder. Should be from 1 to 512 characters. Must be accessible by our system.

Example: storage://storage_1/input_folder/ | https://image_url.com/example.jpg | [https://image_url.com/example.jpg, https://image_url.com/example.jpg]
or
string · uri · min: 1 · max: 4096Optional
or
string · uri[] · min: 1Optional
operationsall ofRequired

Customize the editing workflow so that the output images meet your requirements.

outputany ofOptional

URL of the output folder. If output is not defined, we store the output image on our bucket and return the temporary URL. The name of the output file remains the same as the input file. Images are stored for one day.

Default: {"format":"jpeg"}Example: storage://storage_1/output_folder/
or
string · uri · min: 1 · max: 4096Optional
Responses
200
Successful Response
application/json
401
Authorization is required.
application/json
402
No API calls left.
application/json
403
Not enough permissions.
application/json
422
Unprocessable Entity.
application/json
429
Too many requests.
application/json
post
POST /v1-beta1/image/edit/batch HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 713

{
  "input": "storage://storage_1/input_folder/ | https://image_url.com/example.jpg | [https://image_url.com/example.jpg, https://image_url.com/example.jpg]",
  "operations": {
    "restorations": {
      "decompress": "moderate",
      "upscale": "smart_enhance",
      "polish": false
    },
    "adjustments": {
      "hdr": 0,
      "exposure": 0,
      "saturation": 0,
      "contrast": 0,
      "sharpness": 0
    },
    "background": {
      "remove": false,
      "color": "text",
      "blur": false
    },
    "resizing": {
      "width": "auto",
      "height": "auto",
      "fit": "crop"
    },
    "padding": "text",
    "privacy": {
      "blur_car_plate": false,
      "identity_crop": false
    },
    "generative": {
      "style_transfer": {
        "style_reference_image": "text",
        "prompt": "text",
        "depth_strength": 1,
        "denoising_strength": 0.75,
        "style_strength": 0.75
      }
    }
  },
  "output": "storage://storage_1/output_folder/"
}
{
  "data": {
    "id": 1,
    "status": "ACCEPTED",
    "result_url": "https://example.com",
    "created_at": "2025-06-13T13:58:48.260Z",
    "request": {
      "input": "storage://storage_1/input_folder/ | https://image_url.com/example.jpg | [https://image_url.com/example.jpg, https://image_url.com/example.jpg]",
      "operations": {
        "restorations": {
          "decompress": "moderate",
          "upscale": "smart_enhance",
          "polish": false
        },
        "adjustments": {
          "hdr": 0,
          "exposure": 0,
          "saturation": 0,
          "contrast": 0,
          "sharpness": 0
        },
        "background": {
          "remove": false,
          "color": "text",
          "blur": false
        },
        "resizing": {
          "width": "auto",
          "height": "auto",
          "fit": "crop"
        },
        "padding": "text",
        "privacy": {
          "blur_car_plate": false,
          "identity_crop": false
        },
        "generative": {
          "style_transfer": {
            "style_reference_image": "text",
            "prompt": "text",
            "depth_strength": 1,
            "denoising_strength": 0.75,
            "style_strength": 0.75
          }
        }
      },
      "output": "storage://storage_1/output_folder/"
    },
    "errors": [
      {
        "error": "text",
        "created_at": "text",
        "input_object": {
          "ext": "text",
          "mps": 1,
          "mime": "text",
          "format": "text",
          "width": 1,
          "height": 1
        }
      }
    ],
    "results": [
      {
        "input_object": {
          "ext": "text",
          "mps": 1,
          "mime": "text",
          "format": "text",
          "width": 1,
          "height": 1
        },
        "output_object": {
          "ext": "text",
          "mps": 1,
          "mime": "text",
          "format": "text",
          "width": 1,
          "height": 1,
          "tmp_url": "text",
          "object_key": "text",
          "object_bucket": "text",
          "object_uri": "text",
          "claid_storage_uri": "text",
          "gcs_key": "text",
          "gcs_bucket": "text"
        }
      }
    ]
  }
}