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 or manage keys in API keys (Pro plan and up).

Responses

200Successful Response

application/json

dataGetAiVideoModelsResponse | nullrequirednullable

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

modelsAiVideoModelDto[]required

Machine-readable model capabilities: allowed values and defaults per parameter, plus media constraints. Pricing is not included (use GET /api/v1/ai_video/cost).

capabilitiesstring[]required

Supported generation modes, such as text_to_video and image_to_video.

descriptionstringrequired

Public model summary.

model_idstringrequired

Public model ID to send in AI video requests.

paramsAiVideoModelParamsrequired

aspect_ratioStringChoicesrequired

defaultstring | nullrequirednullable

Value used when the request omits this parameter.

valuesstring[]required

Currently accepted values for this model.

duration_secDurationChoicesrequired

defaultinteger | nullrequirednullable

Clip duration used when omitted.

valuesinteger[]required

Accepted integer clip durations in seconds.

first_frameMediaConstraints | nullrequirednullable

First-frame image constraints; null when image-to-video is unsupported.

Minimum and maximum width/height ratio.

dimension_px[integer | null, integer | null] | nullnullable

Minimum and maximum pixel length per side.

Minimum and maximum single-reference duration in seconds.

formatsstring[] | nullnullable

Accepted file extensions for this media slot.

Minimum and maximum frame rate; a null upper bound means no upper limit.

max_mbinteger | nullnullable

Maximum media file size in MiB, including gateway limits.

generate_audioAudioCapabilityrequired

defaultbooleanrequired

Whether native audio is generated when omitted; does not change price.

promptPromptCapabilityrequired

max_lengthinteger | nullrequirednullable

Maximum prompt characters; null when unspecified.

supports_ref_syntaxboolean | nullnullable

Present when in-prompt reference syntax is supported.

refsVideoReferencesrequired

acceptstring[]required

Accepted media kinds: image, video, or audio.

audioMediaConstraintsrequired

Minimum and maximum width/height ratio.

dimension_px[integer | null, integer | null] | nullnullable

Minimum and maximum pixel length per side.

Minimum and maximum single-reference duration in seconds.

formatsstring[] | nullnullable

Accepted file extensions for this media slot.

Minimum and maximum frame rate; a null upper bound means no upper limit.

max_mbinteger | nullnullable

Maximum media file size in MiB, including gateway limits.

imageMediaConstraintsrequired

Minimum and maximum width/height ratio.

dimension_px[integer | null, integer | null] | nullnullable

Minimum and maximum pixel length per side.

Minimum and maximum single-reference duration in seconds.

formatsstring[] | nullnullable

Accepted file extensions for this media slot.

Minimum and maximum frame rate; a null upper bound means no upper limit.

max_mbinteger | nullnullable

Maximum media file size in MiB, including gateway limits.

maxintegerrequired

Maximum references across all media kinds; zero means unsupported.

max_per_kindReferenceKindLimits | nullnullable

Optional per-kind count limits, in addition to max.

audiointeger | nullnullable

Maximum number of audio references when specified.

imageinteger | nullnullable

Maximum number of image references when specified.

videointeger | nullnullable

Maximum number of video references when specified.

total_duration_sec_maxReferenceDurationLimits | nullnullable

Optional aggregate duration limits, by media kind.

audionumber | integer | nullnullable

Maximum total audio-reference duration in seconds.

videonumber | integer | nullnullable

Maximum total video-reference duration in seconds.

videoMediaConstraintsrequired

Minimum and maximum width/height ratio.

dimension_px[integer | null, integer | null] | nullnullable

Minimum and maximum pixel length per side.

Minimum and maximum single-reference duration in seconds.

formatsstring[] | nullnullable

Accepted file extensions for this media slot.

Minimum and maximum frame rate; a null upper bound means no upper limit.

max_mbinteger | nullnullable

Maximum media file size in MiB, including gateway limits.

resolutionStringChoicesrequired

defaultstring | nullrequirednullable

Value used when the request omits this parameter.

valuesstring[]required

Currently accepted values for this model.

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.

GET /api/v1/ai_video/models

from visionstory import VisionStoryClient

client = VisionStoryClient.from_env()
models = client.list_ai_video_models()
print(models)

Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.

200 example

{
  "data": {
    "models": [
      {
        "capabilities": [
          "text_to_video",
          "image_to_video"
        ],
        "description": "Seedance 2.5 latest: single clips up to 30s, multimodal references; 480p / 720p / 1080p, defaults to 720p.",
        "model_id": "seedance-2.5",
        "params": {
          "aspect_ratio": {
            "default": "9:16",
            "values": [
              "16:9",
              "9:16",
              "4:3",
              "3:4",
              "1:1"
            ]
          },
          "duration_sec": {
            "default": 15,
            "values": [
              4,
              5,
              6,
              7,
              8,
              9,
              10,
              11,
              12,
              13,
              14,
              15,
              16,
              17,
              18,
              19,
              20,
              21,
              22,
              23,
              24,
              25,
              26,
              27,
              28,
              29,
              30
            ]
          },
          "first_frame": {
            "aspect_ratio_range": [
              0.4,
              2.5
            ],
            "dimension_px": [
              300,
              6000
            ],
            "formats": [
              "jpg",
              "jpeg",
              "png",
              "webp",
              "bmp",
              "tiff",
              "gif"
            ],
            "max_mb": 30
          },
          "generate_audio": {
            "default": true
          },
          "prompt": {
            "max_length": 5000
          },
          "refs": {
            "accept": [
              "image",
              "video",
              "audio"
            ],
            "audio": {
              "duration_sec_range": [
                2,
                15
              ],
              "formats": [
                "wav",
                "mp3"
              ],
              "max_mb": 15
            },
            "image": {
              "aspect_ratio_range": [
                0.4,
                2.5
              ],
              "dimension_px": [
                300,
                6000
              ],
              "formats": [
                "jpg",
                "jpeg",
                "png",
                "webp",
                "bmp",
                "tiff",
                "gif"
              ],
              "max_mb": 30
            },
            "max": 9,
            "video": {
              "aspect_ratio_range": [
                0.4,
                2.5
              ],
              "dimension_px": [
                300,
                6000
              ],
              "duration_sec_range": [
                2,
                15
              ],
              "formats": [
                "mp4",
                "mov"
              ],
              "fps_range": [
                24,
                60
              ],
              "max_mb": 100
            }
          },
          "resolution": {
            "default": "720p",
            "values": [
              "480p",
              "720p",
              "1080p"
            ]
          }
        }
      },
      {
        "capabilities": [
          "text_to_video",
          "image_to_video"
        ],
        "description": "Seedance 2.0 flagship: multimodal references (image/video/audio); 480p / 720p / 1080p, defaults to 720p.",
        "model_id": "seedance-2.0",
        "params": {
          "aspect_ratio": {
            "default": "9:16",
            "values": [
              "16:9",
              "9:16",
              "4:3",
              "3:4",
              "1:1"
            ]
          },
          "duration_sec": {
            "default": 5,
            "values": [
              4,
              5,
              6,
              7,
              8,
              9,
              10,
              11,
              12,
              13,
              14,
              15
            ]
          },
          "first_frame": {
            "aspect_ratio_range": [
              0.4,
              2.5
            ],
            "dimension_px": [
              300,
              6000
            ],
            "formats": [
              "jpg",
              "jpeg",
              "png",
              "webp",
              "bmp",
              "tiff",
              "gif"
            ],
            "max_mb": 30
          },
          "generate_audio": {
            "default": true
          },
          "prompt": {
            "max_length": 5000
          },
          "refs": {
            "accept": [
              "image",
              "video",
              "audio"
            ],
            "audio": {
              "duration_sec_range": [
                2,
                15
              ],
              "formats": [
                "wav",
                "mp3"
              ],
              "max_mb": 15
            },
            "image": {
              "aspect_ratio_range": [
                0.4,
                2.5
              ],
              "dimension_px": [
                300,
                6000
              ],
              "formats": [
                "jpg",
                "jpeg",
                "png",
                "webp",
                "bmp",
                "tiff",
                "gif"
              ],
              "max_mb": 30
            },
            "max": 9,
            "video": {
              "aspect_ratio_range": [
                0.4,
                2.5
              ],
              "dimension_px": [
                300,
                6000
              ],
              "duration_sec_range": [
                2,
                15
              ],
              "formats": [
                "mp4",
                "mov"
              ],
              "fps_range": [
                24,
                60
              ],
              "max_mb": 100
            }
          },
          "resolution": {
            "default": "720p",
            "values": [
              "480p",
              "720p",
              "1080p"
            ]
          }
        }
      },
      {
        "capabilities": [
          "text_to_video",
          "image_to_video"
        ],
        "description": "Seedance 2.0 Fast: lower latency and cost; 480p / 720p, defaults to 720p.",
        "model_id": "seedance-2.0-fast",
        "params": {
          "aspect_ratio": {
            "default": "9:16",
            "values": [
              "16:9",
              "9:16",
              "4:3",
              "3:4",
              "1:1"
            ]
          },
          "duration_sec": {
            "default": 5,
            "values": [
              4,
              5,
              6,
              7,
              8,
              9,
              10,
              11,
              12,
              13,
              14,
              15
            ]
          },
          "first_frame": {
            "aspect_ratio_range": [
              0.4,
              2.5
            ],
            "dimension_px": [
              300,
              6000
            ],
            "formats": [
              "jpg",
              "jpeg",
              "png",
              "webp",
              "bmp",
              "tiff",
              "gif"
            ],
            "max_mb": 30
          },
          "generate_audio": {
            "default": true
          },
          "prompt": {
            "max_length": 5000
          },
          "refs": {
            "accept": [
              "image",
              "video",
              "audio"
            ],
            "audio": {
              "duration_sec_range": [
                2,
                15
              ],
              "formats": [
                "wav",
                "mp3"
              ],
              "max_mb": 15
            },
            "image": {
              "aspect_ratio_range": [
                0.4,
                2.5
              ],
              "dimension_px": [
                300,
                6000
              ],
              "formats": [
                "jpg",
                "jpeg",
                "png",
                "webp",
                "bmp",
                "tiff",
                "gif"
              ],
              "max_mb": 30
            },
            "max": 9,
            "video": {
              "aspect_ratio_range": [
                0.4,
                2.5
              ],
              "dimension_px": [
                300,
                6000
              ],
              "duration_sec_range": [
                2,
                15
              ],
              "formats": [
                "mp4",
                "mov"
              ],
              "fps_range": [
                24,
                60
              ],
              "max_mb": 100
            }
          },
          "resolution": {
            "default": "720p",
            "values": [
              "480p",
              "720p"
            ]
          }
        }
      },
      {
        "capabilities": [
          "text_to_video",
          "image_to_video"
        ],
        "description": "Seedance 2.0 Mini: lightweight and economical; 480p / 720p, defaults to 720p.",
        "model_id": "seedance-2.0-mini",
        "params": {
          "aspect_ratio": {
            "default": "16:9",
            "values": [
              "16:9",
              "9:16",
              "4:3",
              "3:4",
              "1:1"
            ]
          },
          "duration_sec": {
            "default": 5,
            "values": [
              4,
              5,
              6,
              7,
              8,
              9,
              10,
              11,
              12,
              13,
              14,
              15
            ]
          },
          "first_frame": {
            "aspect_ratio_range": [
              0.4,
              2.5
            ],
            "dimension_px": [
              300,
              6000
            ],
            "formats": [
              "jpg",
              "jpeg",
              "png",
              "webp",
              "bmp",
              "tiff",
              "gif"
            ],
            "max_mb": 30
          },
          "generate_audio": {
            "default": true
          },
          "prompt": {
            "max_length": 5000
          },
          "refs": {
            "accept": [
              "image",
              "video",
              "audio"
            ],
            "audio": {
              "duration_sec_range": [
                2,
                15
              ],
              "formats": [
                "wav",
                "mp3"
              ],
              "max_mb": 15
            },
            "image": {
              "aspect_ratio_range": [
                0.4,
                2.5
              ],
              "dimension_px": [
                300,
                6000
              ],
              "formats": [
                "jpg",
                "jpeg",
                "png",
                "webp",
                "bmp",
                "tiff",
                "gif"
              ],
              "max_mb": 30
            },
            "max": 9,
            "video": {
              "aspect_ratio_range": [
                0.4,
                2.5
              ],
              "dimension_px": [
                300,
                6000
              ],
              "duration_sec_range": [
                2,
                15
              ],
              "formats": [
                "mp4",
                "mov"
              ],
              "fps_range": [
                24,
                60
              ],
              "max_mb": 100
            }
          },
          "resolution": {
            "default": "720p",
            "values": [
              "480p",
              "720p"
            ]
          }
        }
      },
      {
        "capabilities": [
          "text_to_video",
          "image_to_video"
        ],
        "description": "Kling 3.0: text-to-video and image-to-video (first/last frame) up to 4K; 5s or 10s clips; native audio on by default.",
        "model_id": "kling-3.0",
        "params": {
          "aspect_ratio": {
            "default": "16:9",
            "values": [
              "16:9",
              "9:16",
              "1:1"
            ]
          },
          "duration_sec": {
            "default": 5,
            "values": [
              5,
              10
            ]
          },
          "first_frame": {
            "aspect_ratio_range": [
              0.4,
              2.5
            ],
            "dimension_px": [
              300,
              null
            ],
            "max_mb": 10
          },
          "generate_audio": {
            "default": true
          },
          "prompt": {
            "max_length": 2500
          },
          "refs": {
            "accept": [],
            "audio": {
              "max_mb": 15
            },
            "image": {
              "max_mb": 30
            },
            "max": 0,
            "video": {
              "max_mb": 100
            }
          },
          "resolution": {
            "default": "720p",
            "values": [
              "720p",
              "1080p",
              "4k"
            ]
          }
        }
      },
      {
        "capabilities": [
          "text_to_video"
        ],
        "description": "Kling 3.0 Omni: text-to-video guided by up to 7 image/video references with in-prompt reference syntax; 720p / 1080p; 3 / 5 / 7 / 10 / 15 s clips; native audio on by default.",
        "model_id": "kling-3.0-omni",
        "params": {
          "aspect_ratio": {
            "default": "16:9",
            "values": [
              "16:9",
              "9:16",
              "1:1"
            ]
          },
          "duration_sec": {
            "default": 5,
            "values": [
              3,
              5,
              7,
              10,
              15
            ]
          },
          "first_frame": null,
          "generate_audio": {
            "default": true
          },
          "prompt": {
            "max_length": 2500,
            "supports_ref_syntax": true
          },
          "refs": {
            "accept": [
              "image",
              "video"
            ],
            "audio": {
              "max_mb": 15
            },
            "image": {
              "aspect_ratio_range": [
                0.4,
                2.5
              ],
              "dimension_px": [
                300,
                null
              ],
              "max_mb": 10
            },
            "max": 7,
            "video": {
              "aspect_ratio_range": [
                0.4,
                2.5
              ],
              "dimension_px": [
                720,
                2160
              ],
              "duration_sec_range": [
                3,
                15
              ],
              "max_mb": 100
            }
          },
          "resolution": {
            "default": "1080p",
            "values": [
              "720p",
              "1080p"
            ]
          }
        }
      },
      {
        "capabilities": [
          "text_to_video",
          "image_to_video"
        ],
        "description": "Wan 3.0: all-in-one text-to-video and image-to-video (first/last frame); image, video and audio references with in-prompt reference syntax; 480p / 720p / 1080p; any length from 2 to 30s; native audio on by default. Defaults to 720p.",
        "model_id": "wan-3.0",
        "params": {
          "aspect_ratio": {
            "default": "adaptive",
            "values": [
              "adaptive",
              "16:9",
              "4:3",
              "1:1",
              "3:4",
              "9:16"
            ]
          },
          "duration_sec": {
            "default": 5,
            "values": [
              2,
              3,
              4,
              5,
              6,
              7,
              8,
              9,
              10,
              11,
              12,
              13,
              14,
              15,
              16,
              17,
              18,
              19,
              20,
              21,
              22,
              23,
              24,
              25,
              26,
              27,
              28,
              29,
              30
            ]
          },
          "first_frame": {
            "aspect_ratio_range": [
              0.125,
              8
            ],
            "dimension_px": [
              240,
              8000
            ],
            "formats": [
              "jpg",
              "jpeg",
              "png",
              "bmp",
              "webp"
            ],
            "max_mb": 20
          },
          "generate_audio": {
            "default": true
          },
          "prompt": {
            "max_length": 20000,
            "supports_ref_syntax": true
          },
          "refs": {
            "accept": [
              "image",
              "video",
              "audio"
            ],
            "audio": {
              "duration_sec_range": [
                1,
                15
              ],
              "formats": [
                "wav",
                "mp3"
              ],
              "max_mb": 15
            },
            "image": {
              "aspect_ratio_range": [
                0.125,
                8
              ],
              "dimension_px": [
                240,
                8000
              ],
              "formats": [
                "jpg",
                "jpeg",
                "png",
                "bmp",
                "webp"
              ],
              "max_mb": 20
            },
            "max": 20,
            "max_per_kind": {
              "audio": 5,
              "image": 10,
              "video": 5
            },
            "total_duration_sec_max": {
              "audio": 15,
              "video": 15
            },
            "video": {
              "aspect_ratio_range": [
                0.125,
                8
              ],
              "dimension_px": [
                240,
                4096
              ],
              "duration_sec_range": [
                1,
                15
              ],
              "formats": [
                "mp4",
                "mov"
              ],
              "fps_range": [
                16,
                null
              ],
              "max_mb": 100
            }
          },
          "resolution": {
            "default": "720p",
            "values": [
              "480p",
              "720p",
              "1080p"
            ]
          }
        }
      },
      {
        "capabilities": [
          "text_to_video",
          "image_to_video"
        ],
        "description": "Wan 3.0 Prime: same capabilities as wan-3.0 at higher quality and 1.5x the price; 480p / 720p / 1080p, defaults to 720p.",
        "model_id": "wan-3.0-prime",
        "params": {
          "aspect_ratio": {
            "default": "adaptive",
            "values": [
              "adaptive",
              "16:9",
              "4:3",
              "1:1",
              "3:4",
              "9:16"
            ]
          },
          "duration_sec": {
            "default": 5,
            "values": [
              2,
              3,
              4,
              5,
              6,
              7,
              8,
              9,
              10,
              11,
              12,
              13,
              14,
              15,
              16,
              17,
              18,
              19,
              20,
              21,
              22,
              23,
              24,
              25,
              26,
              27,
              28,
              29,
              30
            ]
          },
          "first_frame": {
            "aspect_ratio_range": [
              0.125,
              8
            ],
            "dimension_px": [
              240,
              8000
            ],
            "formats": [
              "jpg",
              "jpeg",
              "png",
              "bmp",
              "webp"
            ],
            "max_mb": 20
          },
          "generate_audio": {
            "default": true
          },
          "prompt": {
            "max_length": 20000,
            "supports_ref_syntax": true
          },
          "refs": {
            "accept": [
              "image",
              "video",
              "audio"
            ],
            "audio": {
              "duration_sec_range": [
                1,
                15
              ],
              "formats": [
                "wav",
                "mp3"
              ],
              "max_mb": 15
            },
            "image": {
              "aspect_ratio_range": [
                0.125,
                8
              ],
              "dimension_px": [
                240,
                8000
              ],
              "formats": [
                "jpg",
                "jpeg",
                "png",
                "bmp",
                "webp"
              ],
              "max_mb": 20
            },
            "max": 20,
            "max_per_kind": {
              "audio": 5,
              "image": 10,
              "video": 5
            },
            "total_duration_sec_max": {
              "audio": 15,
              "video": 15
            },
            "video": {
              "aspect_ratio_range": [
                0.125,
                8
              ],
              "dimension_px": [
                240,
                4096
              ],
              "duration_sec_range": [
                1,
                15
              ],
              "formats": [
                "mp4",
                "mov"
              ],
              "fps_range": [
                16,
                null
              ],
              "max_mb": 100
            }
          },
          "resolution": {
            "default": "720p",
            "values": [
              "480p",
              "720p",
              "1080p"
            ]
          }
        }
      }
    ]
  },
  "message": "success",
  "server_time": "2026-09-04T00:00:00Z"
}