Batch API Reference

Batch image edit contract

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

In other aspects, the Batch endpoint behaves like the Async endpoint, 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

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 Image edit contract for more info.

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

OAuth2PasswordBearerOAuth2PasswordBearer

OAuth2passwordRequired

To work with the Claid API, send requests over HTTPS and authenticate using the Authorization header in the following format:Authorization: Bearer <YOUR_API_KEY>. You do not need to provide a password.

To get your API key, sign in to your Claid account and click Create API key button from the Overview or API keys pages.

Claid API’s base URL is https://api.claid.ai/v1/. All available endpoints are listed in the Storage and Image sections.

Bearer

This API uses OAuth 2.0 bearer token (API key) to authorize requests.

Token URL:

Body

application/json

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

or

string · uri · min: 1 · max: 4096Optional

or

string · uri[] · min: 1Optional

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

/v1/image/edit/batch

HTTPcURLJavaScriptPython

POST /v1/image/edit/batch HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 642

{
  "input": [
    "storage://storage_1/input_folder/",
    "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": "2026-01-25T16:46:09.586Z",
    "request": {
      "input": [
        "storage://storage_1/input_folder/",
        "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"
        }
      }
    ]
  }
}

Request

HTTP

POST /v1/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

Read a response

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

Response body

{
  "data": {
    "id": 1,
    "status": "ACCEPTED",
    "result_url": "https://api.claid.ai/v1/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/"
    }
  }
}

See the Request Headers and Response Headers to learn about headers.

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.

Image Edit Batch Async Results

get

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

To work with the Claid API, send requests over HTTPS and authenticate using the Authorization header in the following format:Authorization: Bearer <YOUR_API_KEY>. You do not need to provide a password.

To get your API key, sign in to your Claid account and click Create API key button from the Overview or API keys pages.

Claid API’s base URL is https://api.claid.ai/v1/. All available endpoints are listed in the Storage and Image sections.

Bearer

This API uses OAuth 2.0 bearer token (API key) to authorize requests.

Token URL:

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

/v1/image/edit/batch/{task_id}

HTTPcURLJavaScriptPython

GET /v1/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": "2026-01-25T16:46:09.586Z",
    "request": {
      "input": [
        "storage://storage_1/input_folder/",
        "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"
        }
      }
    ]
  }
}

Request

HTTP

GET /v1/image/edit/batch/1 HTTP/1.1
Host: api.claid.ai
Authorization: Bearer {YOUR_API_KEY}

cURL

Read a response

Once you have made the request to https://api.claid.ai/v1/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.

See input_object and output_object properties description at the Read a response part of the Async endpoint page.

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

See Response headers to learn about headers.