# Async API Reference ### Image to Video contract This endpoint is asynchronous, it returns a response without waiting for an actual result. The actual result should be queried with another request. So you can request Image to Video generation and separately get the result after it's ready. See [Image to Video Options](https://docs.claid.ai/image-to-video-api/image-to-video-options) and [Image to Video I/O](https://docs.claid.ai/image-to-video-api/image-to-video-i-o) to learn about request data. ```json { "input": "storage://storage-name/input-path/input.png", "output": "storage://storage-name/output-path/", "options": { "prompt": "A subtle animation for a product-centered setting, camera zoom out" | { "generate": true } | { "generate": true, "guidelines": "zoom out, glitter particles" }, "negative_prompt": "blur, distort, and low quality", "duration": 5 | 10, "guidance_scale": 0.5 } } ``` ## Video Generate Api > Generate an animation asynchronously ```json {"openapi":"3.1.0","info":{"title":"Claid REST API","version":"v1"},"tags":[{"name":"Video","description":"Encompasses operations with videos."}],"security":[{"OAuth2PasswordBearer":["video_generation"]},{"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":{"ImageVideoRequest":{"title":"ImageVideoRequest","required":["input","options"],"type":"object","properties":{"output":{"title":"Output","maxLength":4096,"minLength":1,"type":"string","description":"Customize the result output.","format":"uri"},"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/VideoOptionsObject"}],"description":"Customize the video."}},"additionalProperties":false},"VideoOptionsObject":{"title":"VideoOptionsObject","required":["prompt"],"type":"object","properties":{"prompt":{"title":"Prompt","anyOf":[{"type":"string","minLength":3,"maxLength":5000},{"$ref":"#/components/schemas/VideoPromptObject"}],"description":"Prompt for the video."},"negative_prompt":{"title":"Negative Prompt","maxLength":5000,"minLength":3,"type":"string","description":"Negative prompt for the video."},"duration":{"allOf":[{"$ref":"#/components/schemas/DurationEnum"}],"description":"Duration of the video.","default":"5"},"guidance_scale":{"title":"Guidance Scale","maximum":1,"minimum":0,"type":"number","description":"Guidance scale for the video.","default":0.5}},"additionalProperties":false},"VideoPromptObject":{"title":"VideoPromptObject","type":"object","properties":{"text":{"title":"Text","maxLength":5000,"minLength":3,"type":"string","description":"Prompt for the video."},"generate":{"title":"Generate","type":"boolean","description":"If `true`, the prompt will be generated automatically based on the input image.By default, the prompt is not auto-generated. If `true`, the `text` is not allowed.","default":false},"guidelines":{"title":"Guidelines","maxLength":1000,"minLength":3,"type":"string","description":"Guidelines for prompt generation. Only available when `generate` is `true`."}}},"DurationEnum":{"title":"DurationEnum","enum":["5","10"],"type":"string","description":"An enumeration."},"Response_VideoAcceptedResponse_":{"title":"Response[VideoAcceptedResponse]","type":"object","properties":{"data":{"$ref":"#/components/schemas/VideoAcceptedResponse"}},"description":"Wrapper for responses"},"VideoAcceptedResponse":{"title":"VideoAcceptedResponse","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":{"$ref":"#/components/schemas/VideoRequestInResponse"},"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."},"VideoRequestInResponse":{"title":"VideoRequestInResponse","required":["input","options"],"type":"object","properties":{"output":{"title":"Output","maxLength":4096,"minLength":1,"type":"string","description":"Customize the result output.","format":"uri"},"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/VideoOptionsObject"}],"description":"Customize the video."}},"additionalProperties":false},"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/video/generate":{"post":{"tags":["Video"],"summary":"Video Generate Api","description":"Generate an animation asynchronously","operationId":"video_generate_api_v1_video_generate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageVideoRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response_VideoAcceptedResponse_"}}}},"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 https://api.claid.ai/v1/video/generate HTTP/1.1 Host: api.claid.ai Authorization: Bearer {YOUR_API_KEY} Content-Type: application/json { "input": "storage://storage-name/input-path/input.png", "output": "storage://storage-name/output-path/", "options": { "prompt": { "generate": true }, "duration": 5 } } ``` {% endtab %} {% tab title="cURL" %} ```shell curl -X POST --location "https://api.claid.ai/v1/video/generate" --http1.1 \ -H "Host: api.claid.ai" \ -H "Authorization: Bearer {YOUR_API_KEY}" \ -H "Content-Type: application/json" \ -d "{ \"input\": \"storage://storage-name/input-path/input.png\", \"output\": \"storage://storage-name/output-path/\", \"options\": { \"prompt\": { \"generate\": true, } \"duration\": 5 } }" ``` {% endtab %} {% endtabs %} #### **Read a response** Once you have made the request to `https://api.claid.ai/v1/video/generate` 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: PROCESSING.
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": "PROCESSING", "created_at": "2025-05-12T15:10:21.517229+00:00", "request": { "output": "storage://storage-name/output-path/", "input": "storage://storage-name/input-path/input.png", "options": { "prompt": { "generate": true }, "duration": "5" } }, "result_url": "http://api.claid.ai/v1/video/generate/1" } } ``` See the [Request Headers](https://docs.claid.ai/image-editing-api/api-reference#request-headers) and [Response Headers](https://docs.claid.ai/image-editing-api/api-reference#response-headers) to learn about headers. ### Result of request processing contract To get the 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. ## Video Generate Api Status > Get the status of the animation generation task ```json {"openapi":"3.1.0","info":{"title":"Claid REST API","version":"v1"},"tags":[{"name":"Video","description":"Encompasses operations with videos."}],"security":[{"OAuth2PasswordBearer":["video_generation"]}],"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_VideoStatusResponse_":{"title":"Response[VideoStatusResponse]","type":"object","properties":{"data":{"$ref":"#/components/schemas/VideoStatusResponse"}},"description":"Wrapper for responses"},"VideoStatusResponse":{"title":"VideoStatusResponse","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":{"$ref":"#/components/schemas/VideoRequestInResponse"},"errors":{"title":"Errors","type":"array","items":{"$ref":"#/components/schemas/VideoError"}},"result":{"$ref":"#/components/schemas/VideoResult"}}},"APIV1Status":{"title":"APIV1Status","enum":["ACCEPTED","WAITING","PROCESSING","DONE","ERROR","CANCELLED","PAUSED"],"type":"string","description":"An enumeration."},"VideoRequestInResponse":{"title":"VideoRequestInResponse","required":["input","options"],"type":"object","properties":{"output":{"title":"Output","maxLength":4096,"minLength":1,"type":"string","description":"Customize the result output.","format":"uri"},"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/VideoOptionsObject"}],"description":"Customize the video."}},"additionalProperties":false},"VideoOptionsObject":{"title":"VideoOptionsObject","required":["prompt"],"type":"object","properties":{"prompt":{"title":"Prompt","anyOf":[{"type":"string","minLength":3,"maxLength":5000},{"$ref":"#/components/schemas/VideoPromptObject"}],"description":"Prompt for the video."},"negative_prompt":{"title":"Negative Prompt","maxLength":5000,"minLength":3,"type":"string","description":"Negative prompt for the video."},"duration":{"allOf":[{"$ref":"#/components/schemas/DurationEnum"}],"description":"Duration of the video.","default":"5"},"guidance_scale":{"title":"Guidance Scale","maximum":1,"minimum":0,"type":"number","description":"Guidance scale for the video.","default":0.5}},"additionalProperties":false},"VideoPromptObject":{"title":"VideoPromptObject","type":"object","properties":{"text":{"title":"Text","maxLength":5000,"minLength":3,"type":"string","description":"Prompt for the video."},"generate":{"title":"Generate","type":"boolean","description":"If `true`, the prompt will be generated automatically based on the input image.By default, the prompt is not auto-generated. If `true`, the `text` is not allowed.","default":false},"guidelines":{"title":"Guidelines","maxLength":1000,"minLength":3,"type":"string","description":"Guidelines for prompt generation. Only available when `generate` is `true`."}}},"DurationEnum":{"title":"DurationEnum","enum":["5","10"],"type":"string","description":"An enumeration."},"VideoError":{"title":"VideoError","required":["error","created_at"],"type":"object","properties":{"error":{"title":"Error","type":"string"},"created_at":{"title":"Created At","type":"string","format":"date-time"}}},"VideoResult":{"title":"VideoResult","required":["input_object","output_object"],"type":"object","properties":{"input_object":{"$ref":"#/components/schemas/VideoInputObject"},"output_object":{"$ref":"#/components/schemas/VideoOutputObject"}}},"VideoInputObject":{"title":"VideoInputObject","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"},"generated_prompt":{"title":"Generated Prompt","type":"string","description":"Generated prompt for the video."}}},"VideoOutputObject":{"title":"VideoOutputObject","type":"object","properties":{"ext":{"title":"Ext","type":"string","description":"File extension.","default":"mp4"},"mime":{"title":"Mime","type":"string","default":"video/mp4"},"format":{"title":"Format","type":"string","description":"File format.","default":"mp4"},"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/video/generate/{animation_id}":{"get":{"tags":["Video"],"summary":"Video Generate Api Status","description":"Get the status of the animation generation task","operationId":"video_generate_api_status_v1_video_generate__animation_id__get","parameters":[{"required":true,"schema":{"title":"Animation Id","type":"integer"},"name":"animation_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response_VideoStatusResponse_"}}}},"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 https://api.claid.ai/v1/video/generate/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/video/generate/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/video/generate/` you will get a response with information about the status of your request. As soon as the processing is done, output video data will appear in the response. Response data:
ParameterTypeDescription
idintegerTask ID.
statusstringRequest processing status. Can have values: 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_object, in case of processing errors - will be empty. Details are listed below.
Video data shown in the response at `data.result.output_object`:
ParameterTypeDescription
extstringFile extension. Will have mp4 value
mimestringMIME type (also known as ‘media type’)
formatstringFile format. Will have mp4 value
tmp_urlstringTemporary URL of a processed video. Will be empty if output is specified
object_keystringVideo file path on the bucket. Will be empty if output is not specified
object_bucketstringBucket where the video file is saved. Will be empty if output is not specified
object_uristringS3/GCS video file identifier. Will be empty if output is not specified
claid_storage_uristringClaid Storage file identifier. Will be empty if output is not specified
`errors` property item data:
ParameterTypeDescription
errorstringError message in text.
created_atstringExact time when the error was catched.
**Response body** ```json { "data": { "id": 1, "status": "DONE", "created_at": "2025-05-12T15:10:21.517229+00:00", "request": { "output": "storage://storage-name/output-path/", "input": "storage://storage-name/input-path/input.png", "options": { "prompt": { "generate": true }, "duration": "5" } }, "errors": [], "result": { "input_object": { "ext": "webp", "mps": 0.3456, "mime": "image/webp", "format": "WEBP", "width": 720, "height": 480, "generated_prompt": "The camera begins with a steady, close-up view from behind, focusing on the ..." }, "output_object": { "ext": "mp4", "mime": "video/mp4", "format": "mp4", "tmp_url": null, "object_key": "output-path/85f2690ba2f64fb8a0c51029c589b271.mp4", "object_bucket": "gcs-claid-bucket", "object_uri": "gs://gcs-claid-bucket/output-path/85f2690ba2f64fb8a0c51029c589b271.mp4", "claid_storage_uri": "storage://storage-name/output-path/85f2690ba2f64fb8a0c51029c589b271.mp4" } } } } ``` #### Headers: See the [Request Headers](https://docs.claid.ai/image-editing-api/api-reference#request-headers) and [Response Headers](https://docs.claid.ai/image-editing-api/api-reference#response-headers) to learn about headers.