# 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](/image-editing-api/async-api-reference.md#webhook-notification) for more info. ```json { "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": { "model": "v1" | "v2", "prompt": "add a duck", "inference_steps": 50, "guidance_scale": 4.0, "aspect_ratio": "1:1" } } ``` See [Image AI Edit I/O](/image-ai-edit-api/image-ai-edit-i-o.md) and [Image AI Edit Options](/image-ai-edit-api/image-ai-edit-options.md) learn about request data. ## Async Ai Edit Generation Api > AI Edit ```json {"openapi":"3.1.0","info":{"title":"Claid REST API","version":"v1"},"tags":[{"name":"Image","description":"Encompasses operations with images."}],"security":[{"OAuth2PasswordBearer":["image_editing"]},{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"token"}},"description":"To work with the Claid API, send requests over HTTPS and authenticate using the `Authorization` header in the following format:`Authorization: Bearer `. You do not need to provide a password.\n\nTo get your API key, [sign in to your Claid account](https://claid.ai/login) and click ***Create API key*** button from the ***Overview*** or ***API keys*** pages.\n\nClaid API’s base URL is `https://api.claid.ai/v1/`. All available endpoints are listed in the [Storage](#tag/Storage) and [Image](#tag/Image) sections. \n\n## Bearer\n\nThis API uses OAuth 2.0 [bearer token](https://datatracker.ietf.org/doc/html/rfc6750) (API key) to authorize requests."}},"schemas":{"AiEditAPIRequest":{"title":"AiEditAPIRequest","required":["input","options"],"type":"object","properties":{"output":{"title":"Output","anyOf":[{"$ref":"#/components/schemas/AIEditRequestOutputObject"},{"type":"string","minLength":1,"maxLength":4096,"format":"uri"}],"description":"Customize output format, destination and number of images.","default":{"number_of_images":1,"format":"png"}},"input":{"title":"Input URL","maxLength":4096,"minLength":1,"type":"string","description":"URL of the input image. Image must be accessible by our system.","format":"uri"},"options":{"title":"Options","allOf":[{"$ref":"#/components/schemas/AiEditRequestOptionsObject"}],"description":"Customize the generation."}},"additionalProperties":false},"AIEditRequestOutputObject":{"title":"AIEditRequestOutputObject","type":"object","properties":{"number_of_images":{"title":"Number of images","maximum":4,"minimum":1,"type":"integer","description":"Number of output images.","default":1},"destination":{"title":"Destination","maxLength":4096,"minLength":1,"type":"string","description":"Customize the result output.","format":"uri"},"format":{"allOf":[{"$ref":"#/components/schemas/AiEditFormatEnum"}],"description":"Output image format.","default":"png"}},"additionalProperties":false},"AiEditFormatEnum":{"title":"AiEditFormatEnum","enum":["jpeg","png"],"type":"string","description":"An enumeration."},"AiEditRequestOptionsObject":{"title":"AiEditRequestOptionsObject","required":["prompt"],"type":"object","properties":{"model":{"allOf":[{"$ref":"#/components/schemas/AIEditModelAPI"}],"description":"Model to be used for generation.","default":"v2"},"prompt":{"title":"Prompt","maxLength":5000,"minLength":3,"type":"string","description":"Prompt for the generation."},"aspect_ratio":{"allOf":[{"$ref":"#/components/schemas/AiEditAspectRatio"}],"description":"Aspect ratio of the generated images."},"inference_steps":{"title":"Inference Steps","maximum":50,"minimum":1,"type":"integer","description":"Number of inference steps."},"guidance_scale":{"title":"Guidance Scale","maximum":10,"minimum":1,"type":"number","description":"Guidance scale for the generation."}},"additionalProperties":false},"AIEditModelAPI":{"title":"AIEditModelAPI","enum":["v1","v2"],"type":"string","description":"An enumeration."},"AiEditAspectRatio":{"title":"AiEditAspectRatio","enum":["1:1","2:3","3:2","3:4","4:3","9:16","16:9","9:21","21:9"],"type":"string","description":"An enumeration."},"Response_AiEditAcceptedResponse_":{"title":"Response[AiEditAcceptedResponse]","type":"object","properties":{"data":{"$ref":"#/components/schemas/AiEditAcceptedResponse"}},"description":"Wrapper for responses"},"AiEditAcceptedResponse":{"title":"AiEditAcceptedResponse","required":["id","status","created_at","request","result_url"],"type":"object","properties":{"id":{"title":"Id","type":"integer"},"status":{"$ref":"#/components/schemas/APIV1Status"},"created_at":{"title":"Created At","type":"string","format":"date-time"},"request":{"title":"Request","type":"object"},"result_url":{"title":"Result Url","maxLength":65536,"minLength":1,"type":"string","format":"uri"}}},"APIV1Status":{"title":"APIV1Status","enum":["ACCEPTED","WAITING","PROCESSING","DONE","ERROR","CANCELLED","PAUSED"],"type":"string","description":"An enumeration."},"HttpErrorDetails":{"title":"HttpErrorDetails","required":["error_code","error_type","error_message"],"type":"object","properties":{"error_code":{"title":"Error Code","type":"string"},"error_type":{"$ref":"#/components/schemas/ErrorType"},"error_message":{"title":"Error Message","type":"string"},"error_details":{"title":"Error Details","type":"object","default":{}}}},"ErrorType":{"title":"ErrorType","enum":["auth","dlvr","general","le","survey","storage","image","user_settings","user","validation","analytics","scene","billing","web","runtime_settings","animation","custom_models"],"type":"string","description":"An enumeration."}}},"paths":{"/v1/image/ai-edit":{"post":{"tags":["Image"],"summary":"Async Ai Edit Generation Api","description":"AI Edit","operationId":"async_ai_edit_generation_api_v1_image_ai_edit_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiEditAPIRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response_AiEditAcceptedResponse_"}}}},"401":{"description":"Authorization is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"402":{"description":"No API calls left.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"403":{"description":"Not enough permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"422":{"description":"Unprocessable Entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"429":{"description":"Too many requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}}}}}}} ``` #### **Request** {% tabs %} {% tab title="HTTP" %} ```http 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" } } ``` {% endtab %} {% tab title="cURL" %} ```shell curl -X POST --location "https://api.claid.ai/v1/image/ai-edit" --http1.1 \ -H "Host: api.claid.ai" \ -H "Authorization: Bearer {YOUR_API_KEY}" \ -H "Content-Type: application/json" \ -d "{ \"input\": \"https://picsum.photos/500\", \"options\": { \"prompt\": \"add a duck\" } }" ``` {% endtab %} {% endtabs %} #### **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:
ParameterTypeDescription
idintegerTask ID.
statusstringRequest processing status. For a valid request can only have one value: ACCEPTED.
result_urlstringURL of GET endpoint that can be used to get the result manually and get request status while it is still in process.
created_atstringExact time when the processing was requested.
requestobjectThe body of the request that was used for processing.
#### **Response body** ```json { "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](/image-editing-api/api-reference.md#request-headers) and [Response Headers](/image-editing-api/api-reference.md#response-headers) to learn about headers. ### Webhook notification See [Webhook notification](/image-editing-api/async-api-reference.md#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. ## Async Ai Edit Generation Api Status > Get AI Edit generation result ```json {"openapi":"3.1.0","info":{"title":"Claid REST API","version":"v1"},"tags":[{"name":"Image","description":"Encompasses operations with images."}],"security":[{"OAuth2PasswordBearer":["image_editing"]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"token"}},"description":"To work with the Claid API, send requests over HTTPS and authenticate using the `Authorization` header in the following format:`Authorization: Bearer `. You do not need to provide a password.\n\nTo get your API key, [sign in to your Claid account](https://claid.ai/login) and click ***Create API key*** button from the ***Overview*** or ***API keys*** pages.\n\nClaid API’s base URL is `https://api.claid.ai/v1/`. All available endpoints are listed in the [Storage](#tag/Storage) and [Image](#tag/Image) sections. \n\n## Bearer\n\nThis API uses OAuth 2.0 [bearer token](https://datatracker.ietf.org/doc/html/rfc6750) (API key) to authorize requests."}},"schemas":{"Response_AiEditResultResponse_":{"title":"Response[AiEditResultResponse]","type":"object","properties":{"data":{"$ref":"#/components/schemas/AiEditResultResponse"}},"description":"Wrapper for responses"},"AiEditResultResponse":{"title":"AiEditResultResponse","required":["id","status","created_at","request"],"type":"object","properties":{"id":{"title":"Id","type":"integer"},"status":{"$ref":"#/components/schemas/APIV1Status"},"created_at":{"title":"Created At","type":"string","format":"date-time"},"request":{"title":"Request","type":"object"},"errors":{"title":"Errors","type":"array","items":{"$ref":"#/components/schemas/AiEditError"}},"result":{"$ref":"#/components/schemas/AiEditResult"}}},"APIV1Status":{"title":"APIV1Status","enum":["ACCEPTED","WAITING","PROCESSING","DONE","ERROR","CANCELLED","PAUSED"],"type":"string","description":"An enumeration."},"AiEditError":{"title":"AiEditError","required":["error","created_at"],"type":"object","properties":{"error":{"title":"Error","type":"string"},"created_at":{"title":"Created At","type":"string","format":"date-time"}}},"AiEditResult":{"title":"AiEditResult","required":["input_object","output_objects"],"type":"object","properties":{"input_object":{"$ref":"#/components/schemas/AiEditImageObject"},"output_objects":{"title":"Output Objects","type":"array","items":{"$ref":"#/components/schemas/AiEditOutputImageObject"}}}},"AiEditImageObject":{"title":"AiEditImageObject","type":"object","properties":{"ext":{"title":"Ext","type":"string","description":"File extension."},"mps":{"title":"Mps","type":"number","description":"Megapixel count"},"mime":{"title":"Mime","type":"string","description":"MIME type (also known as 'media type')"},"format":{"title":"Format","type":"string","description":"File format."},"width":{"title":"Width","type":"integer","description":"Image width in pixels"},"height":{"title":"Height","type":"integer","description":"Image height in pixels"}}},"AiEditOutputImageObject":{"title":"AiEditOutputImageObject","type":"object","properties":{"ext":{"title":"Ext","type":"string","description":"File extension."},"mps":{"title":"Mps","type":"number","description":"Megapixel count"},"mime":{"title":"Mime","type":"string","description":"MIME type (also known as 'media type')"},"format":{"title":"Format","type":"string","description":"File format."},"width":{"title":"Width","type":"integer","description":"Image width in pixels"},"height":{"title":"Height","type":"integer","description":"Image height in pixels"},"tmp_url":{"title":"Tmp Url","type":"string","description":"Temporal URL of a processed image"},"object_key":{"title":"Object Key","type":"string","description":"Path to a processed image in a bucket"},"object_bucket":{"title":"Object Bucket","type":"string","description":"Bucket name"},"object_uri":{"title":"Object Uri","type":"string","description":"URI of a processed image in a bucket"},"claid_storage_uri":{"title":"Claid Storage Uri","type":"string","description":"URI of a processed image in a storage"}}},"HttpErrorDetails":{"title":"HttpErrorDetails","required":["error_code","error_type","error_message"],"type":"object","properties":{"error_code":{"title":"Error Code","type":"string"},"error_type":{"$ref":"#/components/schemas/ErrorType"},"error_message":{"title":"Error Message","type":"string"},"error_details":{"title":"Error Details","type":"object","default":{}}}},"ErrorType":{"title":"ErrorType","enum":["auth","dlvr","general","le","survey","storage","image","user_settings","user","validation","analytics","scene","billing","web","runtime_settings","animation","custom_models"],"type":"string","description":"An enumeration."},"HTTPValidationError":{"title":"HTTPValidationError","type":"object","properties":{"detail":{"title":"Detail","type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}}},"ValidationError":{"title":"ValidationError","required":["loc","msg","type"],"type":"object","properties":{"loc":{"title":"Location","type":"array","items":{"type":"string"}},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}}}}},"paths":{"/v1/image/ai-edit/{ai_edit_id}":{"get":{"tags":["Image"],"summary":"Async Ai Edit Generation Api Status","description":"Get AI Edit generation result","operationId":"async_ai_edit_generation_api_status_v1_image_ai_edit__ai_edit_id__get","parameters":[{"required":true,"schema":{"title":"Ai Edit Id","type":"integer"},"name":"ai_edit_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response_AiEditResultResponse_"}}}},"401":{"description":"Authorization is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"403":{"description":"Not enough permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"404":{"description":"Web image not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` #### **Request** {% tabs %} {% tab title="HTTP" %} ```http GET /v1/image/ai-edit/1 HTTP/1.1 Host: api.claid.ai Authorization: Bearer {YOUR_API_KEY} ``` {% endtab %} {% tab title="cURL" %} ```shell curl -X GET --location "https://api.claid.ai/v1/image/ai-edit/1" --http1.1 \ -H "Host: api.claid.ai" \ -H "Authorization: Bearer {YOUR_API_KEY}" ``` {% endtab %} {% endtabs %} #### **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 the request, input and output images. Image information shown in the response:
ParameterTypeDescription
idintegerTask ID.
statusstringRequest processing status. Can have values: ACCEPTED, PROCESSING, ERROR, DONE.
created_atstringExact time when the processing was requested.
requestobjectThe body of the request that was used for processing.
errorslist List of errors, if any are occurred during image processing (status will have ERROR value), in other cases - will be empty.
resultobjectResult 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:
ParameterTypeDescription
extstringFile extension. Can have values: jpg, png.
mpsfloatMegapixel count.
mimestringMIME type (also known as ‘media type’).
widthintegerImage width in pixels.
heightintegerImage height in pixels.
formatstringFile format. Can have values: jpeg, png.
tmp_urlstringTemporary URL of a processed image. Is available only for output_objects.
Read an item from `errors` property:
ParameterTypeDescription
errorstringError message in text.
created_atintegerExact time when the error was catched.
#### **Response body** ```json { "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](/image-editing-api/api-reference.md#response-headers) to learn about headers. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.claid.ai/image-ai-edit-api/async-api-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.