> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/rest-api-reference/create-video/find-video.md). # 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](/rest-api-reference/create-video.md), 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) ```json { "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 ```json { "item": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "generating-media", "createdAt": "2025-03-10T15:30:00Z", "mediaUrl": null, "imageUrls": null } } ``` #### Response: Failed ```json { "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 ```json { "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 ```http 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` ```json { "statusCode": 404, "message": "Not found" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.blotato.com/rest-api-reference/create-video/find-video.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.