Get Visual Status

Check visual generation status and errors, then retrieve finished image or video URLs.

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. If the response includes error, generation has stopped and the status will not change again, even if status is not a final status.

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.

If error is set, stop polling and report the error. For example, a visual can stay at script-ready with an error when AI media generation failed before export.

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

Response: Stopped With Error

{
  "item": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "script-ready",
    "createdAt": "2025-03-10T15:30:00Z",
    "mediaUrl": null,
    "imageUrls": null,
    "error": "2/5 media failed to generate. The video has been saved as a draft. View the video here: https://my.blotato.com/videos/a1b2c3d4-e5f6-7890-abcd-ef1234567890 to retry generating the media.",
    "errorMetadata": {
      "numDraftOverlays": 2,
      "numAiOverlays": 5
    }
  }
}

Polling Pattern

1. Create visual: POST /videos/from-templates -> get item.id
2. Poll: GET /videos/creations/{id}
3. If item.error is set: stop and report the error
4. If item.status = "done": use item.mediaUrl or item.imageUrls
5. If item.status = "creation-from-template-failed" or "insufficient-credits": stop and report it
6. If item.status = "draft": report the draft, not a completed render
7. Otherwise: wait at least 15 seconds, go to step 2

How Long It Takes

Most visuals finish within a few minutes. AI video renders take up to 10-15 minutes. A long render is normal and does not mean the request failed. Keep polling until the status reads done or the response includes error. Treat a visual as stopped when error is set, even if status is still script-ready. If the wait exceeds your execution window, save the visual ID and report its current status. Check the existing visual before submitting another create request. Creating another visual starts another job and uses credits.

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