Async API Reference

Async image edit contract

Async endpoint returns a response without waiting for an actual result. The actual result should be queried with another request. So you can request image editing and separately get the result after it's ready.

Request image processing

The request body for async endpoint is the same as for regular image edit operation. See Image edit contract for more info.

Async Image Edit

post

Specifies:

• what image will be processed (input)
• how it will be processed (operations)
• where it will be stored (output)

Authorizations

OAuth2PasswordBearer

Body

inputstring · uri · min: 1 · max: 4096Required

URL of the input image. Should be from 1 to 512 characters. Image must be accessible by our system.

Example: storage://storage_1/path/image.jpg

operationsall ofRequired

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

outputany ofOptional

Customize the result output.

Default: {"format":"jpeg"}

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

HTTPcURLJavaScriptPython

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

{
  "input": "storage://storage_1/path/image.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": {
    "format": "jpeg",
    "destination": "storage://storage_1/path/output_image.jpg",
    "metadata": {
      "dpi": 1,
      "color_space": "RGB"
    }
  }
}

{
  "data": {
    "id": 1,
    "status": "ACCEPTED",
    "result_url": "https://example.com",
    "created_at": "2025-09-01T09:54:50.906Z",
    "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
        }
      }
    ],
    "result": {
      "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

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

{
  "input": "https://picsum.photos/200.jpg",
  "operations": {
    "resizing": {
      "width": 1000
    },
    "background": {
      "remove": false
    }
  }
}

cURL

curl -X POST --location "https://api.claid.ai/v1-beta1/image/edit/async" --http1.1 \
    -H "Host: api.claid.ai" \
    -H "Authorization: Bearer {YOUR_API_KEY}" \
    -H "Content-Type: application/json" \
    -d "{
          \"input\": \"https://picsum.photos/200.jpg\",
          \"operations\": {
            \"resizing\": {
              \"width\": 1000
            },
            \"background\": {
              \"remove\": false
            }
          }
        }"

Read a response

Once you have made the request to https://api.claid.ai/v1-beta1/image/edit/async you will get a response with information about request status and some other details (listed below).

Request information shown in the response:

Parameter	Type	Description
id	integer	Task ID.
status	string	Request processing status. For a valid request can only have one value: ACCEPTED.
result_url	string	URL of GET endpoint that can be used to get the result manually and get request status while it is still in process.
created_at	string	Exact time when the processing was requested.
request	object	The body of the request that was used for processing.

Response body

{
  "data": {
    "id": 1,
    "status": "ACCEPTED",
    "result_url": "https://api.claid.ai/v1-beta1/image/edit/async/1",
    "created_at": "2023-03-13T11:37:09.160554+00:00",
    "request": {
      "input": "https://picsum.photos/200.jpg",
      "operations": {
        "resizing": {
            "width": 1000
        },
        "background": {
            "remove": false
        }
      }
    }
  }
}

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

Webhook notification

Webhook notifications are especially useful if you want to automate workflows, monitor request statuses, or trigger actions when an image generation job completes — either successfully or with an error.

See Read a response to learn about webhook data.

How to Set Up Webhook notifications

Go to your Integrations -> Webhook Settings at claid.ai and configure your webhook preferences:

1. URL Provide the endpoint where you want to receive notifications (e.g., https://yourdomain.com/webhooks/claid).

2. Subscribed events Enable types of events you’d like to receive:

   • Success pipelines — when a request completes successfully

   • Failed pipelines — when a request fails

3. Optional: Set new secret to enable signature verification For extra security, you can enable HMAC-SHA256 Webhook Signature Verification by entering a shared secret. This allows you to verify that incoming requests were genuinely sent by us.

Remember to store the secret securely on your server.

Webhook Signature Verification (Optional but Recommended)

If you enable signature verification, each webhook we send will include a signature header:

X-Claid-Hmac-SHA256: <hmac-sha256-signature>

This header contains an HMAC hash computed from the request payload using your shared secret. You can use this hash to verify the authenticity and integrity of the request.

To verify the webhook:

1. Read the raw (not parsed) body of the incoming POST request as a string.

2. Compute the HMAC SHA-256 digest using:

   • The raw request body as the "message"

   • The shared secret as the "key"

3. Compare your computed digest to the value in the X-Claid-Hmac-SHA256 header.

If the values match, the webhook is valid and unmodified.

Python example

import hashlib
import hmac
def verify_signature(payload_body, secret_token, signature_header):
    if not signature_header:
        raise HTTPException(status_code=403, detail="x-hub-signature-256 header is missing!")
    hash_object = hmac.new(secret_token.encode('utf-8'), msg=payload_body, digestmod=hashlib.sha256)
    expected_signature = "sha256=" + hash_object.hexdigest()
    if not hmac.compare_digest(expected_signature, signature_header):
        raise HTTPException(status_code=403, detail="Request signatures didn't match!")

JavaScript example

let encoder = new TextEncoder();

async function verifySignature(secret, header, payload) {
    let parts = header.split("=");
    let sigHex = parts[1];

    let algorithm = { name: "HMAC", hash: { name: 'SHA-256' } };

    let keyBytes = encoder.encode(secret);
    let extractable = false;
    let key = await crypto.subtle.importKey(
        "raw",
        keyBytes,
        algorithm,
        extractable,
        [ "sign", "verify" ],
    );

    let sigBytes = hexToBytes(sigHex);
    let dataBytes = encoder.encode(payload);
    let equal = await crypto.subtle.verify(
        algorithm.name,
        key,
        sigBytes,
        dataBytes,
    );

    return equal;
}

function hexToBytes(hex) {
    let len = hex.length / 2;
    let bytes = new Uint8Array(len);

    let index = 0;
    for (let i = 0; i < hex.length; i += 2) {
        let c = hex.slice(i, i + 2);
        let b = parseInt(c, 16);
        bytes[index] = b;
        index += 1;
    }

    return bytes;
}

TypeScript example

import { Webhooks } from "@octokit/webhooks";

const webhooks = new Webhooks({
  secret: process.env.WEBHOOK_SECRET,
});

const handleWebhook = async (req, res) => {
  const signature = req.headers["x-claid-hmac-sha256"];
  const body = await req.text();

  if (!(await webhooks.verify(body, signature))) {
    res.status(401).send("Unauthorized");
    return;
  }
  // The rest of your logic here
};

Ruby example

def verify_signature(payload_body)
  signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload_body)
  return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, request.env['X_CLAID-HMAC-SHA256'])
end

Delivery Attempts and Timeouts

We attempt to deliver each webhook notification up to 4 times if necessary:

Attempt	Delay from previous attempt
1st (initial)	Immediately
2nd	After 3 seconds
3rd	After 6 seconds
4th (final)	After 12 seconds

Each webhook delivery attempt has a 30-second timeout.

If your server doesn’t respond within 30 seconds or responds with a 5xx error, we’ll retry according to the schedule above.

Result of request processing contract

To get 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.

Async Image Edit Result

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

HTTPcURLJavaScriptPython

GET /v1-beta1/image/edit/async/{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-09-01T09:54:50.906Z",
    "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
        }
      }
    ],
    "result": {
      "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-beta1/image/edit/async/1 HTTP/1.1
Host: api.claid.ai
Authorization: Bearer {YOUR_API_KEY}

cURL

curl -X GET --location "https://api.claid.ai/v1-beta1/image/edit/async/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/async/<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.
result	object	Result object that is contain 2 properties input_object and output_object, in case of processing errors - will be empty. Details are listed below.

Read a input_object and output_object properties of response result property:

Parameter	Type	Description
ext	string	File extension. Can have values: jpg, png, webp, av1.
mps	float	Megapixel count.
mime	string	MIME type (also known as ‘media type’).
width	integer	Image width in pixels.
height	integer	Image height in pixels.
format	string	File format. Can have values: jpeg, png, webp, avif.
tmp_url	string	Temporary URL of a processed image. Is available only for output_object.

Read an item from errors property:

Parameter	Type	Description
error	string	Error message in text.
created_at	integer	Exact time when the error was catched.
input_object	object	Same as input_object from result property. For some errors can be null.

Response body

{
  "data": {
    "id": 1,
    "status": "DONE",
    "created_at": "2023-03-13T11:37:09.160554+00:00",
    "request": {
      "input": "https://picsum.photos/200.jpg",
      "operations": {
        "resizing": {
            "width": 1000
        },
        "background": {
            "remove": false
        }
      }
    },
    "errors": [],
    "result": {
      "input_object": {
        "ext": "pnj",
        "mps": 0.016384,
        "mime": "image/jpeg",
        "format": "JPEG",
        "width": 128,
        "height": 128
      },
      "output_object": {
        "ext": "jpeg",
        "mps": 1.0,
        "mime": "image/jpeg",
        "format": "JPEG",
        "width": 1000,
        "height": 1000,
        "tmp_url": "https://storage.googleapis.com/production-leapi-tmp-public/000/200.jpeg"
      }
    }
  }
}

See Response headers to learn about headers.