VisionStory Docs
llms.txt Get API key
Talking Avatar Video/List videos
GET/api/v1/videos

List your most recent videos (up to 100, newest first). Not paginated — intended for quick access to recent generation history.

Headers

X-API-KeystringRequired
Your VisionStory API key (sk-vs-...), kept server-side. Create one at OpenApi (Pro plan and up).

Response

200Successful Response

Successful calls return a standard envelope: the endpoint payload under data (its fields are documented below), plus a message string ("success") and an ISO 8601 server_time.

Response fields (data)
videosarray of VideoDtoRequired
Recent videos for the account, most recent first (up to 100; not paginated).
Show 8 propertiesHide 8 properties
video_idstringRequired
Unique identifier of the video task. Use it to poll status or delete the video.
model_idstringRequired
Identifier of the model that produced this video; see GET /api/v1/models.
statusstringRequired
Current task status: queued (waiting), creating (rendering), created (ready), or failed.
video_urlstring | nullOptional
Download URL of the finished video; empty until status is created. Videos are retained for 7 days.
created_atintegerRequired
Unix timestamp (seconds) when the video task was created.
resolutionstringOptionalDefault "480p"
Output resolution of the rendered video.
Allowed values 480p 720p 1080p 2k
aspect_ratiostringOptionalDefault "9:16"
Output aspect ratio of the rendered video.
Allowed values 9:16 16:9 1:1
cost_creditintegerOptionalDefault 0
Credits charged for this video; 0 when the task failed (the charge is auto-refunded).

Errors

All error responses share one JSON envelope: an error object with a numeric code, a human-readable message, an optional details string, and an optional hint giving an actionable next step (handy for AI agents).

errorErrorDetailRequired
Error payload returned with every non-2xx response. Present only on failure; successful calls use the standard success envelope instead.
Show 4 propertiesHide 4 properties
codeintegerRequired
Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.
messagestringRequired
Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.
detailsstring | nullOptional
Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.
hintstring | nullOptional
Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.