VisionStory OpenAPI
Get API key
AI Video/List AI video models
GET/api/v1/ai_video/models

List available AI video models with the allowed values and defaults for every parameter, plus media constraints for first_frame and multimodal refs. Pricing is not included — use GET /api/v1/ai_video/cost for authoritative cost estimation.

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 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)
modelsarray of AiVideoModelDtoRequired
Machine-readable model capabilities: allowed values and defaults per parameter, plus media constraints. Pricing is not included (use GET /api/v1/ai_video/cost).
Show 4 propertiesHide 4 properties
model_idstringRequired
Public model ID to send in AI video requests.
descriptionstringRequired
Public model summary.
capabilitiesarray of stringRequired
Supported generation modes, such as text_to_video and image_to_video.
paramsAiVideoModelParamsRequired
Model-specific allowed values, defaults, and media limits; pricing is queried separately.
Show 7 propertiesHide 7 properties
promptPromptCapabilityRequired
Prompt length and reference-syntax support.
Show 2 propertiesHide 2 properties
max_lengthinteger | nullRequired
Maximum prompt characters; null when unspecified.
supports_ref_syntaxboolean | nullOptional
Present when in-prompt reference syntax is supported.
duration_secDurationChoicesRequired
Allowed clip durations and default.
Show 2 propertiesHide 2 properties
valuesarray of integerRequired
Accepted integer clip durations in seconds.
defaultinteger | nullRequired
Clip duration used when omitted.
aspect_ratioStringChoicesRequired
Allowed aspect ratios and default; input-mode restrictions still apply.
Show 2 propertiesHide 2 properties
valuesarray of stringRequired
Currently accepted values for this model.
defaultstring | nullRequired
Value used when the request omits this parameter.
resolutionStringChoicesRequired
Allowed resolutions and default for this model.
Show 2 propertiesHide 2 properties
valuesarray of stringRequired
Currently accepted values for this model.
defaultstring | nullRequired
Value used when the request omits this parameter.
generate_audioAudioCapabilityRequired
Native-audio default; reference combinations may restrict it.
Show 1 propertyHide 1 property
defaultbooleanRequired
Whether native audio is generated when omitted; does not change price.
refsVideoReferencesRequired
Reference media types, counts, and constraints.
Show 7 propertiesHide 7 properties
maxintegerRequired
Maximum references across all media kinds; zero means unsupported.
acceptarray of stringRequired
Accepted media kinds: image, video, or audio.
imageMediaConstraintsRequired
Image-reference constraints; use only if image is accepted.
Show 6 propertiesHide 6 properties
max_mbinteger | nullOptional
Maximum media file size in MiB, including gateway limits.
dimension_pxarray of any | nullOptional
Minimum and maximum pixel length per side.
aspect_ratio_rangearray of any | nullOptional
Minimum and maximum width/height ratio.
duration_sec_rangearray of any | nullOptional
Minimum and maximum single-reference duration in seconds.
fps_rangearray of any | nullOptional
Minimum and maximum frame rate; a null upper bound means no upper limit.
formatsarray of string | nullOptional
Accepted file extensions for this media slot.
videoMediaConstraintsRequired
Video-reference constraints; use only if video is accepted.
Show 6 propertiesHide 6 properties
max_mbinteger | nullOptional
Maximum media file size in MiB, including gateway limits.
dimension_pxarray of any | nullOptional
Minimum and maximum pixel length per side.
aspect_ratio_rangearray of any | nullOptional
Minimum and maximum width/height ratio.
duration_sec_rangearray of any | nullOptional
Minimum and maximum single-reference duration in seconds.
fps_rangearray of any | nullOptional
Minimum and maximum frame rate; a null upper bound means no upper limit.
formatsarray of string | nullOptional
Accepted file extensions for this media slot.
audioMediaConstraintsRequired
Audio-reference constraints; use only if audio is accepted.
Show 6 propertiesHide 6 properties
max_mbinteger | nullOptional
Maximum media file size in MiB, including gateway limits.
dimension_pxarray of any | nullOptional
Minimum and maximum pixel length per side.
aspect_ratio_rangearray of any | nullOptional
Minimum and maximum width/height ratio.
duration_sec_rangearray of any | nullOptional
Minimum and maximum single-reference duration in seconds.
fps_rangearray of any | nullOptional
Minimum and maximum frame rate; a null upper bound means no upper limit.
formatsarray of string | nullOptional
Accepted file extensions for this media slot.
max_per_kindReferenceKindLimits | nullOptional
Optional per-kind count limits, in addition to max.
Show 3 propertiesHide 3 properties
imageinteger | nullOptional
Maximum number of image references when specified.
videointeger | nullOptional
Maximum number of video references when specified.
audiointeger | nullOptional
Maximum number of audio references when specified.
total_duration_sec_maxReferenceDurationLimits | nullOptional
Optional aggregate duration limits, by media kind.
Show 2 propertiesHide 2 properties
videonumber | integer | nullOptional
Maximum total video-reference duration in seconds.
audionumber | integer | nullOptional
Maximum total audio-reference duration in seconds.
first_frameMediaConstraints | nullRequired
First-frame image constraints; null when image-to-video is unsupported.
Show 6 propertiesHide 6 properties
max_mbinteger | nullOptional
Maximum media file size in MiB, including gateway limits.
dimension_pxarray of any | nullOptional
Minimum and maximum pixel length per side.
aspect_ratio_rangearray of any | nullOptional
Minimum and maximum width/height ratio.
duration_sec_rangearray of any | nullOptional
Minimum and maximum single-reference duration in seconds.
fps_rangearray of any | nullOptional
Minimum and maximum frame rate; a null upper bound means no upper limit.
formatsarray of string | nullOptional
Accepted file extensions for this media slot.

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.