Async API Reference
Image AI Edit contract
This endpoint is asynchronous, it returns a response without waiting for an actual result. The actual result should be queried with another request. Or received by a webhook notification, see Webhook notification for more info.
{
"input": "storage://storage-name/input-path/input.png",
"output": {
"destination": "storage://storage-name/result-path/image-name.jpg",
"format": "png",
"number_of_images": 1
},
"options": {
"prompt": "add a duck",
"inference_steps": 50,
"guidance_scale": 4.0,
"aspect_ratio": "1:1"
}
}See Image AI Edit I/O and Image AI Edit Options learn about request data.
AI Edit
Customize output format, destination and number of images.
{"number_of_images":1,"format":"jpeg"}URL of the input image. Image must be accessible by our system.
storage://storage_1/path/image.jpgCustomize the generation.
Successful Response
Authorization is required.
No API calls left.
Not enough permissions.
Unprocessable Entity.
Too many requests.
POST /v1/image/ai-edit HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 219
{
"output": {
"number_of_images": 1,
"destination": "https://example.com",
"format": "jpeg"
},
"input": "storage://storage_1/path/image.jpg",
"options": {
"prompt": "text",
"aspect_ratio": "1:1",
"inference_steps": 50,
"guidance_scale": 4
}
}{
"data": {
"id": 1,
"status": "ACCEPTED",
"created_at": "2025-09-11T19:56:07.947Z",
"request": {},
"result_url": "https://example.com"
}
}Request
POST /v1/image/ai-edit HTTP/1.1
Host: api.claid.ai
Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json
{
"input": "https://picsum.photos/500",
"options": {
"prompt": "add a duck"
}
}Read a response
Once you have made the request to https://api.claid.ai/v1/image/ai-edit you will get a response with information about request status and some other details (listed below).
Request information shown in the response:
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/image/ai-edit/1",
"created_at": "2025-03-13T11:37:09.160554+00:00",
"request": {
"input": "https://picsum.photos/500",
"options": {
"prompt": "add a duck"
}
}
}
}See the Request Headers and Response Headers to learn about headers.
Webhook notification
See Webhook notification to learn about webhook handling.
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.
Get AI Edit generation result
Successful Response
Authorization is required.
Not enough permissions.
Web image not found.
Validation Error
GET /v1/image/ai-edit/{ai_edit_id} HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
"data": {
"id": 1,
"status": "ACCEPTED",
"created_at": "2025-09-11T19:56:07.947Z",
"request": {},
"errors": [
{
"error": "text",
"created_at": "2025-09-11T19:56:07.947Z"
}
],
"result": {
"input_object": {
"ext": "text",
"mps": 1,
"mime": "text",
"format": "text",
"width": 1,
"height": 1
},
"output_objects": [
{
"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
GET /v1/image/ai-edit/1 HTTP/1.1
Host: api.claid.ai
Authorization: Bearer {YOUR_API_KEY}Read a response
Once you have made the request to https://api.claid.ai/v1/image/ai-edit/<task_id> you will get a response with information about the request, input and output images.
Image information shown in the response:
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_objects, in case of processing errors - will be empty. Details are listed below.
Read a input_object and output_objects properties of response result property:
ext
string
File extension. Can have values: jpg, png.
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.
tmp_url
string
Temporary URL of a processed image. Is available only for output_objects.
Read an item from errors property:
error
string
Error message in text.
created_at
integer
Exact time when the error was catched.
Response body
{
"data": {
"id": 1,
"status": "DONE",
"created_at": "2025-03-13T11:37:09.160554+00:00",
"request": {
"input": "https://picsum.photos/500",
"options": {
"prompt": "add a duck"
}
},
"errors": [],
"result": {
"input_object": {
"ext": "jpeg",
"mps": 0.5,
"mime": "image/jpeg",
"format": "JPEG",
"width": 500,
"height": 500
},
"output_objects": [
{
"ext": "jpeg",
"mps": 1.0,
"mime": "image/jpeg",
"format": "JPEG",
"width": 1024,
"height": 1024,
"tmp_url": "https://dl.claid.ai/path-to-output/image-name.png"
}
]
}
}
}See Response headers to learn about headers.
Last updated