Async API Reference

Request and response description.

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 and Image to Video I/O to learn about request data.

{
  "input": "storage://storage-name/input-path/input.png",
  "output": "storage://storage-name/output-path/",
  "options": {
    "prompt": {"generate": true} | "A subtle animation for a product-centered setting, camera zoom out",
    "negative_prompt": "blur, distort, and low quality",
    "duration": 5 | 10,
    "guidance_scale": 0.5
  }
}

Video Generate Api

post

Generate an animation asynchronously

Authorizations

OAuth2PasswordBearer

Body

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

Customize the result output.

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

optionsall ofRequired

Customize the video.

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 /generate HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 166

{
  "output": "https://example.com",
  "input": "storage://storage_1/path/image.jpg",
  "options": {
    "prompt": "text",
    "negative_prompt": "text",
    "duration": "5",
    "guidance_scale": 0.5
  }
}

{
  "data": {
    "id": 1,
    "status": "ACCEPTED",
    "created_at": "2025-05-14T13:59:36.419Z",
    "request": {
      "output": "https://example.com",
      "input": "storage://storage_1/path/image.jpg",
      "options": {
        "prompt": "text",
        "negative_prompt": "text",
        "duration": "5",
        "guidance_scale": 0.5
      }
    },
    "result_url": "https://example.com"
  }
}

Request

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

cURL

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

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:

Parameter	Type	Description
id	integer	Task ID.
status	string	Request processing status. For a valid request can only have one value: PROCESSING.
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": "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 and 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

Get the status of the animation generation task

Authorizations

Path parameters

animation_idintegerRequired

Responses

200

Successful Response

application/json

401

Authorization is required.

application/json

403

Not enough permissions.

application/json

404

Web image not found.

application/json

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /generate/{animation_id} HTTP/1.1
Host: 
Accept: */*

{
  "data": {
    "id": 1,
    "status": "ACCEPTED",
    "created_at": "2025-05-14T13:59:36.419Z",
    "request": {
      "output": "https://example.com",
      "input": "storage://storage_1/path/image.jpg",
      "options": {
        "prompt": "text",
        "negative_prompt": "text",
        "duration": "5",
        "guidance_scale": 0.5
      }
    },
    "errors": [
      {
        "error": "text",
        "created_at": "2025-05-14T13:59:36.419Z"
      }
    ],
    "result": {
      "input_object": {
        "ext": "text",
        "mps": 1,
        "mime": "text",
        "format": "text",
        "width": 1,
        "height": 1,
        "generated_prompt": "text"
      },
      "output_object": {
        "ext": "mp4",
        "mime": "video/mp4",
        "format": "mp4",
        "tmp_url": "text",
        "object_key": "text",
        "object_bucket": "text",
        "object_uri": "text",
        "claid_storage_uri": "text"
      }
    }
  }
}

Request

HTTP

GET https://api.claid.ai/v1/video/generate/1 HTTP/1.1
Host: api.claid.ai
Authorization: Bearer {YOUR_API_KEY}

cURL

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

Read a response

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

Parameter	Type	Description
id	integer	Task ID.
status	string	Request processing status. Can have values: 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.

Video data shown in the response at data.result.output_object:

Parameter	Type	Description
ext	string	File extension. Will have mp4 value
mime	string	MIME type (also known as ‘media type’)
format	string	File format. Will have mp4 value
tmp_url	string	Temporary URL of a processed video. Will be empty if output is specified
object_key	string	Video file path on the bucket. Will be empty if output is not specified
object_bucket	string	Bucket where the video file is saved. Will be empty if output is not specified
object_uri	string	S3/GCS video file identifier. Will be empty if output is not specified
claid_storage_uri	string	Claid Storage file identifier. Will be empty if output is not specified

errors property item data:

Parameter	Type	Description
error	string	Error message in text.
created_at	string	Exact time when the error was catched.

Response body

{
  "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 and Response Headers to learn about headers.