List AI videos — VisionStory API

List AI video tasks for this account, newest first. Pass the previous page's next_cursor to paginate; next_cursor=0 means no more pages.

Use status=queued,creating before submitting to check how much per-key concurrency you have left — submissions beyond the limit are rejected with 429, not queued, and the 429 body carries details.limit / details.in_flight.

Beta: available to any account with an active paid subscription; standard per-key rate limits apply.

Headers

X-API-Keystringrequired

Your VisionStory API key (sk-vs-...), kept server-side. Create or manage keys in API keys (Pro plan and up).

Query parameters

cursorinteger

Pagination cursor from the previous page's next_cursor. Omit or pass 0 to start from the newest task.

Default: 0

limitinteger

Maximum tasks to return per page. Range 1–100; defaults to 20.

Default: 20

statusstring | null

Filter by status; comma-separated, any of queued, creating, created, failed. Omit to return every status. status=queued,creating returns exactly the tasks that occupy your per-key concurrency quota, so len(videos) is how many slots you are using.

Responses

200Successful Response

application/json

dataGetAiVideosResponse | nullrequirednullable

The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload.

next_cursorinteger

Cursor to fetch the next page; pass it back as cursor. 0 means no more pages.

Default: 0

videosAiVideoDto[]required

Video tasks for this account, newest first.

aspect_ratiostring

Output aspect ratio of the generated video (e.g. 16:9, 9:16); empty until known.

Default:

cost_creditinteger

Credits charged for this task; 0 when it failed (the charge is auto-refunded).

Default: 0

cover_urlstring | nullnullable

URL of the video's cover/thumbnail image when available.

created_atinteger

Unix timestamp (seconds) when the task was created.

Default: 0

duration_secnumber

Length of the generated video in seconds; 0 until known.

Default: 0

errorAiVideoErrorDto | nullnullable

Failure detail; present only when status is failed.

codeintegerrequired

Numeric code identifying why generation failed.

messagestringrequired

Human-readable explanation of the failure.

model_idstringrequired

Model used to generate this video; see GET /api/v1/ai_video/models.

resolutionstring

Output resolution of the generated video (e.g. 720p, 1080p); empty until known.

Default:

statusstringrequired

Current task status: queued (waiting), creating (rendering), created (ready), or failed.

video_idstringrequired

Unique identifier of the video task.

video_urlstring | nullnullable

Download URL of the generated video; present once status is created.

messagestring

Human-readable status message; "success" on a successful call.

Default: success

server_timestring · date-timerequired

Server-side timestamp when the response was produced, in ISO 8601 format (UTC).

defaultError response. All failures share one 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 (useful for AI agents).

application/json

errorErrorDetailrequired

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.

detailsstring | nullnullable

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

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.

messagestringrequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.