Get Visual Status

Check Visual Creation Status

Endpoint

Base URL: https://backend.blotato.com/v2

URL: /videos/creations/:id

Method: GET

Description

Poll this endpoint to check the status of a visual creation. After submitting a request with Create Visual, use the returned id to track its progress.

Request

Path Parameters

Field	Type	Required	Description
id	string	Yes	The video/visual ID returned by Create Visual

Response

Status Code: 200 OK

Status Values

Status	Description
queueing	Request is queued. Keep polling.
generating-script	AI is generating the script. Keep polling.
script-ready	Script is ready, generating media. Keep polling.
generating-media	Media is being generated. Keep polling.
media-ready	Media is ready, exporting. Keep polling.
exporting	Final export in progress. Keep polling.
done	Complete. mediaUrl and/or imageUrls are available.
creation-from-template-failed	Creation failed.

Response: Done (success)

{
  "item": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "done",
    "createdAt": "2025-03-10T15:30:00Z",
    "mediaUrl": "https://database.blotato.io/user_1/media/video.mp4",
    "imageUrls": ["https://database.blotato.io/user_1/media/slide1.jpg", "https://database.blotato.io/user_1/media/slide2.jpg"]
  }
}

• mediaUrl: URL of the rendered video. Use this in mediaUrls when publishing.

• imageUrls: Array of image URLs (for slideshows/carousels). Use these in mediaUrls when publishing.

Response: In Progress

{
  "item": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "generating-media",
    "createdAt": "2025-03-10T15:30:00Z",
    "mediaUrl": null,
    "imageUrls": null
  }
}

Response: Failed

{
  "item": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "creation-from-template-failed",
    "createdAt": "2025-03-10T15:30:00Z",
    "mediaUrl": null,
    "imageUrls": null
  }
}

Polling Pattern

1. Create visual: POST /videos/from-templates -> get item.id
2. Poll: GET /videos/creations/{id}
3. If status is NOT "done" and NOT "creation-from-template-failed": wait 5 seconds, go to step 2
4. If status = "done": use mediaUrl or imageUrls
5. If status = "creation-from-template-failed": stop, creation failed

Example

GET https://backend.blotato.com/v2/videos/creations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 HTTP/1.1
blotato-api-key: YOUR_API_KEY

Error Response

Status Code: 404 Not Found

{
  "statusCode": 404,
  "message": "Not found"
}