{ "components": { "schemas": { "AiVideoCostResponse": { "properties": { "credit": { "description": "Estimated credits the generation will cost with the given parameters. Uses the same formula as the actual charge.", "title": "Credit", "type": "integer" } }, "required": [ "credit" ], "title": "AiVideoCostResponse", "type": "object" }, "AiVideoDto": { "properties": { "aspect_ratio": { "default": "", "description": "Output aspect ratio of the generated video (e.g. `16:9`, `9:16`); empty until known.", "title": "Aspect Ratio", "type": "string" }, "cost_credit": { "default": 0, "description": "Credits charged for this task; 0 when it failed (the charge is auto-refunded).", "title": "Cost Credit", "type": "integer" }, "cover_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the video's cover/thumbnail image when available.", "title": "Cover Url" }, "created_at": { "default": 0, "description": "Unix timestamp (seconds) when the task was created.", "title": "Created At", "type": "integer" }, "duration_sec": { "default": 0, "description": "Length of the generated video in seconds; 0 until known.", "title": "Duration Sec", "type": "number" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/AiVideoErrorDto" }, { "type": "null" } ], "description": "Failure detail; present only when status is `failed`." }, "model_id": { "description": "Model used to generate this video; see GET /api/v1/ai_video/models.", "examples": [ "seedance-2.0" ], "title": "Model Id", "type": "string" }, "resolution": { "default": "", "description": "Output resolution of the generated video (e.g. `720p`, `1080p`); empty until known.", "title": "Resolution", "type": "string" }, "status": { "description": "Current task status: `queued` (waiting), `creating` (rendering), `created` (ready), or `failed`.", "title": "Status", "type": "string" }, "video_id": { "description": "Unique identifier of the video task.", "title": "Video Id", "type": "string" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Download URL of the generated video; present once status is `created`.", "title": "Video Url" } }, "required": [ "video_id", "model_id", "status" ], "title": "AiVideoDto", "type": "object" }, "AiVideoErrorDto": { "properties": { "code": { "description": "Numeric code identifying why generation failed.", "title": "Code", "type": "integer" }, "message": { "description": "Human-readable explanation of the failure.", "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "AiVideoErrorDto", "type": "object" }, "AssetDto": { "properties": { "asset_id": { "description": "Unique identifier of the asset; reference it as `asset_id` in generation requests.", "title": "Asset Id", "type": "string" }, "created_at": { "default": 0, "description": "Unix timestamp (seconds) when the asset was uploaded.", "title": "Created At", "type": "integer" }, "duration_sec": { "default": 0, "description": "Duration in seconds for video/audio assets; 0 for images.", "title": "Duration Sec", "type": "number" }, "height": { "default": 0, "description": "Pixel height for image/video assets; 0 when not applicable.", "title": "Height", "type": "integer" }, "kind": { "description": "Detected media kind: one of `image` / `video` / `audio`.", "title": "Kind", "type": "string" }, "mime": { "default": "", "description": "Detected MIME type of the asset, e.g. `image/png`.", "title": "Mime", "type": "string" }, "width": { "default": 0, "description": "Pixel width for image/video assets; 0 when not applicable.", "title": "Width", "type": "integer" } }, "required": [ "asset_id", "kind" ], "title": "AssetDto", "type": "object" }, "AudioScript": { "properties": { "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publicly reachable URL of narration audio to drive the avatar. Provide either this or `inline_data`.", "title": "Audio Url" }, "denoise": { "default": false, "description": "If true, apply noise reduction to the uploaded audio before generation.", "title": "Denoise", "type": "boolean" }, "inline_data": { "anyOf": [ { "$ref": "#/components/schemas/InlineDataModel" }, { "type": "null" } ], "description": "Narration audio as inline base64 data. Provide either this or `audio_url`." }, "voice_change": { "default": false, "description": "If true, re-synthesize the uploaded audio with the voice in `voice_id` (voice conversion) while keeping the original timing.", "title": "Voice Change", "type": "boolean" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target voice for conversion when `voice_change` is true. Use an id from GET /api/v1/voices.", "title": "Voice Id" } }, "title": "AudioScript", "type": "object" }, "AvatarDto": { "properties": { "aspect_ratios": { "description": "Aspect ratios this avatar was prepared for (`1:1` / `9:16` / `16:9`). Choose a matching `aspect_ratio` when generating a video.", "items": { "enum": [ "9:16", "16:9", "1:1" ], "type": "string" }, "title": "Aspect Ratios", "type": "array" }, "avatar_id": { "description": "Unique avatar identifier. Pass it as `avatar_id` when generating a talking video.", "title": "Avatar Id", "type": "string" }, "created_at": { "default": 0, "description": "Unix timestamp (seconds) when the avatar was created; 0 for public/platform avatars.", "title": "Created At", "type": "integer" }, "thumbnail_url": { "description": "URL of the avatar's preview thumbnail image.", "title": "Thumbnail Url", "type": "string" } }, "required": [ "avatar_id", "thumbnail_url" ], "title": "AvatarDto", "type": "object" }, "BaseSuccessResponse_AiVideoCostResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/AiVideoCostResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[AiVideoCostResponse]", "type": "object" }, "BaseSuccessResponse_CloneVoiceResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/CloneVoiceResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[CloneVoiceResponse]", "type": "object" }, "BaseSuccessResponse_CreateAiVideoResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/CreateAiVideoResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[CreateAiVideoResponse]", "type": "object" }, "BaseSuccessResponse_CreateAssetResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/CreateAssetResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[CreateAssetResponse]", "type": "object" }, "BaseSuccessResponse_CreateAvatarResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/CreateAvatarResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[CreateAvatarResponse]", "type": "object" }, "BaseSuccessResponse_CreateImageResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/CreateImageResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[CreateImageResponse]", "type": "object" }, "BaseSuccessResponse_CreateVideoResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/CreateVideoResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[CreateVideoResponse]", "type": "object" }, "BaseSuccessResponse_DeleteResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/DeleteResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[DeleteResponse]", "type": "object" }, "BaseSuccessResponse_GetAiVideoModelsResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetAiVideoModelsResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[GetAiVideoModelsResponse]", "type": "object" }, "BaseSuccessResponse_GetAiVideosResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetAiVideosResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[GetAiVideosResponse]", "type": "object" }, "BaseSuccessResponse_GetAssetsResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetAssetsResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[GetAssetsResponse]", "type": "object" }, "BaseSuccessResponse_GetAvatarsResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetAvatarsResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[GetAvatarsResponse]", "type": "object" }, "BaseSuccessResponse_GetCreditsResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetCreditsResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[GetCreditsResponse]", "type": "object" }, "BaseSuccessResponse_GetImageModelsResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetImageModelsResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[GetImageModelsResponse]", "type": "object" }, "BaseSuccessResponse_GetModelsResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetModelsResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[GetModelsResponse]", "type": "object" }, "BaseSuccessResponse_GetVideoResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetVideoResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[GetVideoResponse]", "type": "object" }, "BaseSuccessResponse_GetVideosResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetVideosResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[GetVideosResponse]", "type": "object" }, "BaseSuccessResponse_GetVoicesResponse_": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetVoicesResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete." }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[GetVoicesResponse]", "type": "object" }, "BaseSuccessResponse_Union_GetAiVideoResponse__GetAiVideosBatchResponse__": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/GetAiVideoResponse" }, { "$ref": "#/components/schemas/GetAiVideosBatchResponse" }, { "type": "null" } ], "description": "The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete.", "title": "Data" }, "message": { "default": "success", "description": "Human-readable status message; `\"success\"` on a successful call.", "title": "Message", "type": "string" }, "server_time": { "description": "Server-side timestamp when the response was produced, in ISO 8601 format (UTC).", "format": "date-time", "title": "Server Time", "type": "string" } }, "required": [ "data", "server_time" ], "title": "BaseSuccessResponse[Union[GetAiVideoResponse, GetAiVideosBatchResponse]]", "type": "object" }, "CloneVoiceRequest": { "properties": { "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publicly reachable URL of a clean voice sample. Provide either this or `inline_data`. Formats: AVI/MP3/MP4/M4A/WAV, up to 30MB.", "title": "Audio Url" }, "inline_data": { "anyOf": [ { "$ref": "#/components/schemas/InlineDataModel" }, { "type": "null" } ], "description": "Voice sample as inline base64 data. Provide either this or `audio_url`." }, "preview_text": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "Text spoken in the generated preview clip for the cloned voice. Defaults to a built-in phrase. Max 100 characters.", "title": "Preview Text" } }, "title": "CloneVoiceRequest", "type": "object" }, "CloneVoiceResponse": { "properties": { "voice_id": { "description": "Unique identifier of the cloned voice. Pass it as `voice_id` in a text script to speak with this voice.", "title": "Voice Id", "type": "string" } }, "required": [ "voice_id" ], "title": "CloneVoiceResponse", "type": "object" }, "CreateAiVideoRequest": { "additionalProperties": false, "properties": { "aspect_ratio": { "anyOf": [ { "type": "string", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ] }, { "type": "null" } ], "description": "Controls the output frame shape. Text-to-video defaults to `9:16` for 2.5 / 2.0 / fast and `16:9` for mini. Image-to-video defaults to `16:9` for every model.", "title": "Aspect Ratio" }, "client_request_id": { "anyOf": [ { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, { "type": "null" } ], "description": "Optional idempotency key. Resubmitting with the same value within 24h returns the original task instead of creating (and charging) a new one. Safe for retries.", "title": "Client Request Id" }, "duration_sec": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "`seedance-2.5`: any whole second from 4–30 (default 15). All `seedance-2.0` variants: any whole second from 4–15 (default 5). Longer clips cost more credits.", "title": "Duration Sec" }, "end_frame": { "anyOf": [ { "$ref": "#/components/schemas/MediaRef" }, { "type": "null" } ], "description": "Optional last-frame image with the same limits as `first_frame`. Requires `first_frame`.", "x-field-description-priority": true }, "first_frame": { "anyOf": [ { "$ref": "#/components/schemas/MediaRef" }, { "type": "null" } ], "description": "First-frame image for image-to-video. Accepts JPEG, PNG, WebP, BMP, TIFF, or GIF up to 30 MB, 300–6000 px per side, and aspect ratio 1:2.5–2.5:1. Mutually exclusive with `refs`.", "x-field-description-priority": true }, "generate_audio": { "anyOf": [ { "type": "boolean", "enum": [ true, false ] }, { "type": "null" } ], "description": "Controls whether the generated video includes a native audio track.", "title": "Generate Audio", "default": true }, "model_id": { "description": "Choose the generation model. The values below are the currently supported IDs; query `GET /api/v1/ai_video/models` for the latest availability.", "examples": [ "seedance-2.0" ], "title": "Model Id", "type": "string", "enum": [ "seedance-2.5", "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-mini" ] }, "prompt": { "description": "Describe the video or, when `first_frame` is present, the motion to apply. Length: 1–2500 characters.", "minLength": 1, "title": "Prompt", "type": "string", "maxLength": 2500 }, "refs": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MediaRef" }, "type": "array", "maxItems": 9 }, { "type": "null" } ], "description": "Up to 9 reference images, videos, or audio files for text-to-video. Image: ≤30 MB. Video: MP4/MOV, ≤100 MB, 2–15 s, 24–60 fps. Audio: WAV/MP3, ≤15 MB, 2–15 s and cannot be the only reference. Mutually exclusive with `first_frame`.", "title": "Refs" }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "720p", "1080p" ] }, { "type": "null" } ], "description": "`1080p` is available only on `seedance-2.0`. Higher resolution costs more credits.", "title": "Resolution", "default": "720p" } }, "required": [ "model_id", "prompt" ], "title": "CreateAiVideoRequest", "type": "object" }, "CreateAiVideoResponse": { "properties": { "cost_credit": { "default": 0, "description": "Credits charged for this task on submission; auto-refunded if generation fails.", "title": "Cost Credit", "type": "integer" }, "status": { "default": "queued", "description": "Initial task status; always `queued` right after creation.", "title": "Status", "type": "string" }, "video_id": { "description": "Identifier of the created task. Poll GET /api/v1/ai_video with it to track progress.", "title": "Video Id", "type": "string" } }, "required": [ "video_id" ], "title": "CreateAiVideoResponse", "type": "object" }, "CreateAssetRequest": { "additionalProperties": false, "properties": { "inline_data": { "anyOf": [ { "$ref": "#/components/schemas/InlineDataModel" }, { "type": "null" } ], "description": "Media as inline base64 data. Provide either this or `url`." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publicly reachable media URL (image/video/audio). Provide either this or `inline_data`.", "title": "Url" } }, "title": "CreateAssetRequest", "type": "object" }, "CreateAssetResponse": { "properties": { "asset_id": { "description": "Unique identifier of the asset; reference it as `asset_id` in generation requests.", "title": "Asset Id", "type": "string" }, "created_at": { "default": 0, "description": "Unix timestamp (seconds) when the asset was uploaded.", "title": "Created At", "type": "integer" }, "duration_sec": { "default": 0, "description": "Duration in seconds for video/audio assets; 0 for images.", "title": "Duration Sec", "type": "number" }, "height": { "default": 0, "description": "Pixel height for image/video assets; 0 when not applicable.", "title": "Height", "type": "integer" }, "kind": { "description": "Detected media kind: one of `image` / `video` / `audio`.", "title": "Kind", "type": "string" }, "mime": { "default": "", "description": "Detected MIME type of the asset, e.g. `image/png`.", "title": "Mime", "type": "string" }, "width": { "default": 0, "description": "Pixel width for image/video assets; 0 when not applicable.", "title": "Width", "type": "integer" } }, "required": [ "asset_id", "kind" ], "title": "CreateAssetResponse", "type": "object" }, "CreateAvatarRequest": { "properties": { "img_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publicly reachable URL of the source image. Provide either this or `inline_data`. Formats: JPEG/PNG/WEBP/HEIC, up to 10MB.", "title": "Img Url" }, "inline_data": { "anyOf": [ { "$ref": "#/components/schemas/InlineDataModel" }, { "type": "null" } ], "description": "Source image as inline base64 data. Provide either this or `img_url`." } }, "title": "CreateAvatarRequest", "type": "object" }, "CreateAvatarResponse": { "description": "Response with created avatar data", "properties": { "aspect_ratios": { "description": "Aspect ratios this avatar was prepared for (`1:1` / `9:16` / `16:9`). Choose a matching `aspect_ratio` when generating a video.", "items": { "enum": [ "9:16", "16:9", "1:1" ], "type": "string" }, "title": "Aspect Ratios", "type": "array" }, "avatar_id": { "description": "Unique avatar identifier. Pass it as `avatar_id` when generating a talking video.", "title": "Avatar Id", "type": "string" }, "created_at": { "default": 0, "description": "Unix timestamp (seconds) when the avatar was created; 0 for public/platform avatars.", "title": "Created At", "type": "integer" }, "thumbnail_url": { "description": "URL of the avatar's preview thumbnail image.", "title": "Thumbnail Url", "type": "string" } }, "required": [ "avatar_id", "thumbnail_url" ], "title": "CreateAvatarResponse", "type": "object" }, "CreateImageRequest": { "additionalProperties": false, "properties": { "aspect_ratio": { "anyOf": [ { "type": "string", "enum": [ "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9" ] }, { "type": "null" } ], "description": "Output frame shape. Supported values are listed below; defaults to `1:1`.", "title": "Aspect Ratio", "default": "1:1" }, "model_id": { "description": "Choose an image model. The values below are the currently supported IDs; query `GET /api/v1/image/models` for live availability and credit cost.", "title": "Model Id", "type": "string", "enum": [ "nano-banana", "nano-banana-2", "nano-banana-pro" ], "examples": [ "nano-banana" ] }, "prompt": { "description": "Describe the image to generate, or the edits to apply when `refs` are present. Length: 1–5000 characters.", "minLength": 1, "title": "Prompt", "type": "string", "maxLength": 5000 }, "refs": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MediaRef" }, "type": "array", "maxItems": 4 }, { "type": "null" } ], "description": "Up to 4 reference images for image editing. Each item must provide exactly one of `asset_id`, `url`, or `inline_data`.", "title": "Refs", "x-field-description-priority": true }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "1K", "2K" ] }, { "type": "null" } ], "description": "Output resolution tier. `2K` costs more credits; defaults to `1K`.", "title": "Resolution", "default": "1K" } }, "required": [ "model_id", "prompt" ], "title": "CreateImageRequest", "type": "object" }, "CreateImageResponse": { "properties": { "cost_credit": { "default": 0, "description": "Credits charged for this image", "title": "Cost Credit", "type": "integer" }, "height": { "default": 0, "description": "Pixel height", "title": "Height", "type": "integer" }, "model_id": { "default": "", "description": "Model id used", "title": "Model Id", "type": "string" }, "url": { "description": "CDN URL of the generated PNG; pass it directly as a ref or first/last frame elsewhere", "title": "Url", "type": "string" }, "width": { "default": 0, "description": "Pixel width", "title": "Width", "type": "integer" } }, "required": [ "url" ], "title": "CreateImageResponse", "type": "object" }, "CreateSpeechRequest": { "additionalProperties": false, "properties": { "text": { "description": "Text to synthesize, up to 3000 characters", "minLength": 1, "title": "Text", "type": "string" }, "voice_id": { "description": "Public or cloned voice id, check GET /api/v1/voices", "title": "Voice Id", "type": "string" } }, "required": [ "text", "voice_id" ], "title": "CreateSpeechRequest", "type": "object" }, "CreateVideoRequest": { "properties": { "aspect_ratio": { "default": "9:16", "description": "Output aspect ratio for the rendered video; defaults to `9:16`.", "enum": [ "9:16", "16:9", "1:1" ], "title": "Aspect Ratio", "type": "string" }, "audio_script": { "anyOf": [ { "$ref": "#/components/schemas/AudioScript" }, { "type": "null" } ], "description": "Pre-recorded narration audio to drive the avatar. Provide either `audio_script` or `text_script`." }, "avatar_id": { "description": "Avatar that speaks the script. Use an id from GET /api/v1/avatars (public or your own).", "title": "Avatar Id", "type": "string" }, "background_color": { "default": "", "description": "Optional solid background as a 6-digit hex color, e.g. `#00b140`. Leave empty to keep the avatar's original background; setting it renders the avatar on this color (chroma-key friendly).", "title": "Background Color", "type": "string" }, "client_request_id": { "anyOf": [ { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, { "type": "null" } ], "description": "Optional idempotency key. Resubmitting with the same value within 24h returns the original task instead of creating (and charging) a new one. Safe for retries.", "title": "Client Request Id" }, "emotion": { "default": "cheerful", "description": "Expressive tone the avatar performs; defaults to `cheerful`.", "enum": [ "cheerful", "angry", "marketing", "news", "singing" ], "title": "Emotion", "type": "string" }, "model_id": { "default": "vs_character_v4", "description": "Rendering model to use; see GET /api/v1/models. Defaults to `vs_character_v4`. Note: when omitted and `resolution` is `480p`, `vs_talk_v1` is selected automatically.", "title": "Model Id", "type": "string", "enum": [ "vs_character_v4", "vs_talk_v1" ] }, "resolution": { "default": "720p", "description": "Output resolution. Higher values cost more credits and take longer to render; defaults to `720p`. Note: `vs_talk_v1` does not support `2k`.", "enum": [ "480p", "720p", "1080p", "2k" ], "title": "Resolution", "type": "string" }, "text_script": { "anyOf": [ { "$ref": "#/components/schemas/TextScript" }, { "type": "null" } ], "description": "Text-to-speech script (text + voice). Provide either `text_script` or `audio_script`." } }, "required": [ "avatar_id" ], "title": "CreateVideoRequest", "type": "object" }, "CreateVideoResponse": { "properties": { "video_id": { "description": "Identifier of the newly created video task. Poll GET /api/v1/video with it to track progress.", "title": "Video Id", "type": "string" } }, "required": [ "video_id" ], "title": "CreateVideoResponse", "type": "object" }, "DeleteResponse": { "description": "Common response body for DELETE endpoints (avatar / voice / video / ai_video / asset).", "properties": { "deleted": { "default": true, "description": "Always `true` when the request succeeded — the resource has been removed and no longer appears in list endpoints. Deletes are idempotent: deleting an already-removed resource still returns `true`.", "title": "Deleted", "type": "boolean" } }, "title": "DeleteResponse", "type": "object" }, "ErrorDetail": { "properties": { "code": { "description": "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.", "title": "Code", "type": "integer" }, "details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "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.", "title": "Details" }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "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.", "title": "Hint" }, "message": { "description": "Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.", "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "ErrorDetail", "type": "object" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail", "description": "Error payload returned with every non-2xx response. Present only on failure; successful calls use the standard success envelope instead." } }, "required": [ "error" ], "title": "ErrorResponse", "type": "object" }, "GetAiVideoModelsResponse": { "properties": { "models": { "description": "Machine-readable model capabilities: allowed values and defaults per parameter, plus media constraints. Pricing is not included (use GET /api/v1/ai_video/cost).", "items": { "additionalProperties": true, "type": "object" }, "title": "Models", "type": "array" } }, "required": [ "models" ], "title": "GetAiVideoModelsResponse", "type": "object" }, "GetAiVideoResponse": { "properties": { "aspect_ratio": { "default": "", "description": "Output aspect ratio of the generated video (e.g. `16:9`, `9:16`); empty until known.", "title": "Aspect Ratio", "type": "string" }, "cost_credit": { "default": 0, "description": "Credits charged for this task; 0 when it failed (the charge is auto-refunded).", "title": "Cost Credit", "type": "integer" }, "cover_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the video's cover/thumbnail image when available.", "title": "Cover Url" }, "created_at": { "default": 0, "description": "Unix timestamp (seconds) when the task was created.", "title": "Created At", "type": "integer" }, "duration_sec": { "default": 0, "description": "Length of the generated video in seconds; 0 until known.", "title": "Duration Sec", "type": "number" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/AiVideoErrorDto" }, { "type": "null" } ], "description": "Failure detail; present only when status is `failed`." }, "model_id": { "description": "Model used to generate this video; see GET /api/v1/ai_video/models.", "examples": [ "seedance-2.0" ], "title": "Model Id", "type": "string" }, "resolution": { "default": "", "description": "Output resolution of the generated video (e.g. `720p`, `1080p`); empty until known.", "title": "Resolution", "type": "string" }, "status": { "description": "Current task status: `queued` (waiting), `creating` (rendering), `created` (ready), or `failed`.", "title": "Status", "type": "string" }, "video_id": { "description": "Unique identifier of the video task.", "title": "Video Id", "type": "string" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Download URL of the generated video; present once status is `created`.", "title": "Video Url" } }, "required": [ "video_id", "model_id", "status" ], "title": "GetAiVideoResponse", "type": "object" }, "GetAiVideosBatchResponse": { "properties": { "videos": { "description": "Requested video tasks that exist and belong to this account (missing ids are omitted).", "items": { "$ref": "#/components/schemas/AiVideoDto" }, "title": "Videos", "type": "array" } }, "required": [ "videos" ], "title": "GetAiVideosBatchResponse", "type": "object" }, "GetAiVideosResponse": { "properties": { "next_cursor": { "default": 0, "description": "Cursor to fetch the next page; pass it back as `cursor`. 0 means no more pages.", "title": "Next Cursor", "type": "integer" }, "videos": { "description": "Video tasks for this account, newest first.", "items": { "$ref": "#/components/schemas/AiVideoDto" }, "title": "Videos", "type": "array" } }, "required": [ "videos" ], "title": "GetAiVideosResponse", "type": "object" }, "GetAssetsResponse": { "properties": { "assets": { "description": "Uploaded assets for this account, newest first.", "items": { "$ref": "#/components/schemas/AssetDto" }, "title": "Assets", "type": "array" }, "next_cursor": { "default": 0, "description": "Cursor to fetch the next page; pass it back as `cursor`. 0 means no more pages.", "title": "Next Cursor", "type": "integer" } }, "required": [ "assets" ], "title": "GetAssetsResponse", "type": "object" }, "GetAvatarsResponse": { "properties": { "my_avatars": { "description": "Custom avatars created by this account (up to 100 returned).", "items": { "$ref": "#/components/schemas/AvatarDto" }, "title": "My Avatars", "type": "array" }, "public_avatars": { "description": "Platform-provided avatars available to every account.", "items": { "$ref": "#/components/schemas/AvatarDto" }, "title": "Public Avatars", "type": "array" }, "total_cnt": { "description": "Total number of avatars returned across both lists.", "title": "Total Cnt", "type": "integer" } }, "required": [ "public_avatars", "my_avatars", "total_cnt" ], "title": "GetAvatarsResponse", "type": "object" }, "GetCreditsResponse": { "properties": { "remaining": { "description": "Credits currently available on the account. Each generation deducts credits based on model, resolution, and duration.", "title": "Remaining", "type": "integer" } }, "required": [ "remaining" ], "title": "GetCreditsResponse", "type": "object" }, "GetImageModelsResponse": { "properties": { "models": { "description": "Machine-readable model capabilities, including credit_per_image", "items": { "additionalProperties": true, "type": "object" }, "title": "Models", "type": "array" } }, "required": [ "models" ], "title": "GetImageModelsResponse", "type": "object" }, "GetModelsResponse": { "properties": { "models": { "description": "Available avatar rendering models with their supported options.", "items": { "$ref": "#/components/schemas/ModelDto" }, "title": "Models", "type": "array" } }, "required": [ "models" ], "title": "GetModelsResponse", "type": "object" }, "GetVideoResponse": { "description": "Response for getting a single video", "properties": { "aspect_ratio": { "default": "9:16", "description": "Output aspect ratio of the rendered video.", "enum": [ "9:16", "16:9", "1:1" ], "title": "Aspect Ratio", "type": "string" }, "cost_credit": { "default": 0, "description": "Credits charged for this video; 0 when the task failed (the charge is auto-refunded).", "title": "Cost Credit", "type": "integer" }, "created_at": { "description": "Unix timestamp (seconds) when the video task was created.", "title": "Created At", "type": "integer" }, "model_id": { "description": "Identifier of the model that produced this video; see GET /api/v1/models.", "title": "Model Id", "type": "string" }, "resolution": { "default": "480p", "description": "Output resolution of the rendered video.", "enum": [ "480p", "720p", "1080p", "2k" ], "title": "Resolution", "type": "string" }, "status": { "description": "Current task status: `queued` (waiting), `creating` (rendering), `created` (ready), or `failed`.", "title": "Status", "type": "string" }, "video_id": { "description": "Unique identifier of the video task. Use it to poll status or delete the video.", "title": "Video Id", "type": "string" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Download URL of the finished video; empty until status is `created`. Videos are retained for 7 days.", "title": "Video Url" } }, "required": [ "video_id", "model_id", "status", "created_at" ], "title": "GetVideoResponse", "type": "object" }, "GetVideosResponse": { "properties": { "videos": { "description": "Recent videos for the account, most recent first (up to 100; not paginated).", "items": { "$ref": "#/components/schemas/VideoDto" }, "title": "Videos", "type": "array" } }, "required": [ "videos" ], "title": "GetVideosResponse", "type": "object" }, "GetVoicesResponse": { "properties": { "my_voices": { "description": "Voices this account has cloned.", "items": { "$ref": "#/components/schemas/VoiceDto" }, "title": "My Voices", "type": "array" }, "public_voices": { "description": "Platform-provided voices available for text-to-speech.", "items": { "$ref": "#/components/schemas/VoiceDto" }, "title": "Public Voices", "type": "array" } }, "required": [ "public_voices", "my_voices" ], "title": "GetVoicesResponse", "type": "object" }, "InlineDataModel": { "properties": { "data": { "description": "The file's raw bytes encoded as a base64 string (no `data:` URI prefix).", "title": "Data", "type": "string" }, "mime_type": { "description": "MIME type of the inline data, used to detect image vs audio. Audio: ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav']; images: ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].", "title": "Mime Type", "type": "string" } }, "required": [ "mime_type", "data" ], "title": "InlineDataModel", "type": "object" }, "MediaRef": { "additionalProperties": false, "description": "A media reference — provide exactly one of: `asset_id` (from the asset library, reusable across\nrequests), `url` (one-off public URL), or `inline_data` (one-off base64, not stored).", "properties": { "asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Asset ID from POST /api/v1/asset; use for materials reused across requests.", "title": "Asset Id" }, "inline_data": { "anyOf": [ { "$ref": "#/components/schemas/InlineDataModel" }, { "type": "null" } ], "description": "Inline base64 media data for one-off use; not added to your asset library." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publicly accessible media URL for one-off use; not added to your asset library.", "title": "Url" } }, "title": "MediaRef", "type": "object" }, "ModelDto": { "properties": { "aspect_ratios": { "description": "Aspect ratios this model can render; pass one of these as `aspect_ratio` when creating a video.", "items": { "type": "string" }, "title": "Aspect Ratios", "type": "array" }, "description": { "description": "Human-readable summary of the model's strengths and intended use.", "title": "Description", "type": "string" }, "max_duration_seconds": { "description": "Maximum length, in seconds, of a video this model can generate in one request.", "title": "Max Duration Seconds", "type": "integer" }, "model_id": { "description": "Stable model identifier. Pass it as `model_id` when creating a video, e.g. `vs_talk_v1` or `vs_character_v4`.", "title": "Model Id", "type": "string" }, "resolutions": { "description": "Output resolutions this model supports; pass one of these as `resolution`. Higher resolutions cost more credits and take longer to render.", "items": { "enum": [ "480p", "720p", "1080p", "2k" ], "type": "string" }, "title": "Resolutions", "type": "array" } }, "required": [ "model_id", "description", "max_duration_seconds" ], "title": "ModelDto", "type": "object" }, "TextScript": { "properties": { "speech_rate": { "anyOf": [ { "enum": [ "slow", "normal", "fast" ], "type": "string" }, { "type": "null" } ], "default": "normal", "description": "Speaking speed of the synthesized voice; defaults to `normal`.", "title": "Speech Rate" }, "text": { "description": "The script to speak; converted to speech with the selected voice.", "title": "Text", "type": "string" }, "voice_id": { "description": "Voice to synthesize the script with. Use an id from GET /api/v1/voices (a public or your own cloned voice).", "title": "Voice Id", "type": "string" } }, "required": [ "text", "voice_id" ], "title": "TextScript", "type": "object" }, "VideoDto": { "properties": { "aspect_ratio": { "default": "9:16", "description": "Output aspect ratio of the rendered video.", "enum": [ "9:16", "16:9", "1:1" ], "title": "Aspect Ratio", "type": "string" }, "cost_credit": { "default": 0, "description": "Credits charged for this video; 0 when the task failed (the charge is auto-refunded).", "title": "Cost Credit", "type": "integer" }, "created_at": { "description": "Unix timestamp (seconds) when the video task was created.", "title": "Created At", "type": "integer" }, "model_id": { "description": "Identifier of the model that produced this video; see GET /api/v1/models.", "title": "Model Id", "type": "string" }, "resolution": { "default": "480p", "description": "Output resolution of the rendered video.", "enum": [ "480p", "720p", "1080p", "2k" ], "title": "Resolution", "type": "string" }, "status": { "description": "Current task status: `queued` (waiting), `creating` (rendering), `created` (ready), or `failed`.", "title": "Status", "type": "string" }, "video_id": { "description": "Unique identifier of the video task. Use it to poll status or delete the video.", "title": "Video Id", "type": "string" }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Download URL of the finished video; empty until status is `created`. Videos are retained for 7 days.", "title": "Video Url" } }, "required": [ "video_id", "model_id", "status", "created_at" ], "title": "VideoDto", "type": "object" }, "VoiceDto": { "properties": { "is_free": { "description": "Whether this voice is usable on the free plan; premium voices require a paid plan.", "title": "Is Free", "type": "boolean" }, "language": { "description": "Primary language this voice speaks, e.g. `english`.", "title": "Language", "type": "string" }, "preview_audio_url": { "description": "URL of a short sample clip demonstrating how this voice sounds.", "title": "Preview Audio Url", "type": "string" }, "provider": { "default": "", "description": "Speech engine this voice comes from (e.g. elevenlabs / gemini / minimax), so you can pick voices by engine. Descriptive, not a guarantee: synthesis may fall back to another engine.", "title": "Provider", "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text descriptors (e.g. accent, gender, age) to help pick a voice; may be empty.", "title": "Tags" }, "voice_id": { "description": "Voice identifier. Pass it as `voice_id` in a text script, or as the target voice when converting uploaded audio.", "title": "Voice Id", "type": "string" } }, "required": [ "voice_id", "is_free", "preview_audio_url", "language" ], "title": "VoiceDto", "type": "object" } }, "securitySchemes": { "APIKeyHeader": { "description": "API key authenticating every business request. Send it in the `X-API-Key` header, keep it server-side, and create or manage it in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "info": { "title": "VisionStory API", "version": "0.0.6", "description": "Generate talking-avatar videos, clone voices, create avatars, synthesize speech, generate AI images and video, and manage reusable media assets through one authenticated REST API.", "x-last-reviewed": "2026-08-27", "x-documentation-status": "testing" }, "paths": { "/api/v1/ai_video": { "delete": { "description": "Soft-delete an AI video task by `video_id`. Only tasks you created are affected.\n\nBeta: available to allowlisted API keys; standard per-key rate limits apply.\n\nAgent safety: require an explicit user request and confirmation immediately before calling this destructive operation.", "operationId": "delete_ai_video_api_v1_ai_video_delete", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" }, { "description": "Id of the AI video task to delete, as returned by POST /api/v1/ai_video. Only tasks you created are affected (soft-delete).", "in": "query", "name": "video_id", "required": true, "schema": { "description": "Id of the AI video task to delete, as returned by POST /api/v1/ai_video. Only tasks you created are affected (soft-delete).", "title": "Video Id", "type": "string" }, "example": "video_123456" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_DeleteResponse_" }, "example": { "data": { "deleted": true }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Delete AI video", "tags": [ "AI Videos" ], "x-safety": { "destructive": true, "confirmationRequired": true, "instruction": "Do not call this operation unless the user explicitly requested and confirmed deletion." }, "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.delete(\n \"https://openapi.visionstory.ai/api/v1/ai_video\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n params={\n \"video_id\": \"video_123456\"\n },\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request DELETE 'https://openapi.visionstory.ai/api/v1/ai_video?video_id=video_123456' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY'" } ] }, "get": { "description": "Get one task by `video_id`, or up to 20 at once with `video_ids` (comma-separated). Status is\n`queued`, `creating`, `created`, or `failed`; poll every 5-10 seconds. Failed tasks carry an `error`\nobject and `cost_credit=0` (credits auto-refunded).\n\nBeta: available to allowlisted API keys; standard per-key rate limits apply.", "operationId": "get_ai_video_api_v1_ai_video_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" }, { "description": "Id of a single task to fetch, as returned by POST /api/v1/ai_video. Provide either `video_id` or `video_ids`.", "in": "query", "name": "video_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of a single task to fetch, as returned by POST /api/v1/ai_video. Provide either `video_id` or `video_ids`.", "title": "Video Id" }, "example": "video_123456" }, { "description": "Comma-separated task ids for a batch fetch (up to 20), e.g. `101,102,103`. Provide either `video_ids` or `video_id`.", "in": "query", "name": "video_ids", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated task ids for a batch fetch (up to 20), e.g. `101,102,103`. Provide either `video_ids` or `video_id`.", "title": "Video Ids" }, "example": "video_123456" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_Union_GetAiVideoResponse__GetAiVideosBatchResponse__" }, "example": { "data": { "model_id": "vs_character_v4", "status": "success", "video_id": "video_123456", "aspect_ratio": "", "cost_credit": 0, "cover_url": "https://example.com/media/input.mp4", "created_at": 0, "duration_sec": 0 }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Get AI video status", "tags": [ "AI Videos" ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://openapi.visionstory.ai/api/v1/ai_video\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n params={\n \"video_id\": \"video_123456\"\n },\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request GET 'https://openapi.visionstory.ai/api/v1/ai_video?video_id=video_123456' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY'" } ] }, "post": { "description": "Generate a video with a frontier AI model. Provide `first_frame` (optionally `end_frame`) for\nimage-to-video, `refs` for multimodal text-to-video, or neither for pure text-to-video. Credits are\ncharged on submission and refunded automatically if generation fails; poll GET /api/v1/ai_video for\nprogress.\n\nBeta: available to allowlisted API keys. Per-key concurrency is limited during beta; submissions\nbeyond the limit are rejected rather than queued.", "operationId": "create_ai_video_api_v1_ai_video_post", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiVideoRequest" }, "example": { "model_id": "seedance-2.0", "prompt": "A corgi surfing at sunset, cinematic lighting", "duration_sec": 8, "aspect_ratio": "9:16", "resolution": "1080p", "generate_audio": true, "client_request_id": "request_20260824_001" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_CreateAiVideoResponse_" }, "example": { "data": { "video_id": "video_123456", "cost_credit": 0, "status": "queued" }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Generate AI video", "tags": [ "AI Videos" ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://openapi.visionstory.ai/api/v1/ai_video\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n json={\n \"model_id\": \"seedance-2.0\",\n \"prompt\": \"A corgi surfing at sunset, cinematic lighting\",\n \"duration_sec\": 8,\n \"aspect_ratio\": \"9:16\",\n \"resolution\": \"1080p\",\n \"generate_audio\": true,\n \"client_request_id\": \"request_20260824_001\"\n },\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request POST 'https://openapi.visionstory.ai/api/v1/ai_video' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"model_id\": \"seedance-2.0\",\n \"prompt\": \"A corgi surfing at sunset, cinematic lighting\",\n \"duration_sec\": 8,\n \"aspect_ratio\": \"9:16\",\n \"resolution\": \"1080p\",\n \"generate_audio\": true,\n \"client_request_id\": \"request_20260824_001\"\n}'" } ] } }, "/api/v1/ai_video/cost": { "get": { "description": "Estimate the credits a generation will cost before submitting, using the same formula as the actual\ncharge. Omit `resolution` to price the model default.\n\nBeta: available to allowlisted API keys; standard per-key rate limits apply.", "operationId": "get_ai_video_cost_api_v1_ai_video_cost_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" }, { "description": "Model to price for. Use an id from GET /api/v1/ai_video/models, e.g. `seedance-2.0`.", "in": "query", "name": "model_id", "required": true, "schema": { "description": "Model to price for. Use an id from GET /api/v1/ai_video/models, e.g. `seedance-2.0`.", "title": "Model Id", "type": "string" }, "example": "seedance-2.0" }, { "description": "Clip length in seconds to price. Must be an allowed value for the model (see GET /api/v1/ai_video/models).", "in": "query", "name": "duration_sec", "required": true, "schema": { "description": "Clip length in seconds to price. Must be an allowed value for the model (see GET /api/v1/ai_video/models).", "title": "Duration Sec", "type": "integer" }, "example": 8 }, { "description": "Output resolution to price, e.g. `720p` / `1080p`. Allowed values vary by model; omit to use the model default.", "in": "query", "name": "resolution", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Output resolution to price, e.g. `720p` / `1080p`. Allowed values vary by model; omit to use the model default.", "title": "Resolution" }, "example": "720p" }, { "description": "Whether the estimate should include a native audio track. Omit to use the model default.", "in": "query", "name": "generate_audio", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the estimate should include a native audio track. Omit to use the model default.", "title": "Generate Audio" }, "example": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_AiVideoCostResponse_" }, "example": { "data": { "credit": 1 }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Estimate cost", "tags": [ "AI Videos" ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://openapi.visionstory.ai/api/v1/ai_video/cost\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n params={\n \"model_id\": \"seedance-2.0\",\n \"duration_sec\": 8\n },\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request GET 'https://openapi.visionstory.ai/api/v1/ai_video/cost?model_id=seedance-2.0&duration_sec=8' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY'" } ] } }, "/api/v1/ai_video/models": { "get": { "description": "List available AI video models with the allowed values and defaults for every parameter, plus media\nconstraints for `first_frame` and multimodal `refs`. Pricing is not included — use\nGET /api/v1/ai_video/cost for authoritative cost estimation.\n\nBeta: available to allowlisted API keys; standard per-key rate limits apply.", "operationId": "get_ai_video_models_api_v1_ai_video_models_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_GetAiVideoModelsResponse_" }, "example": { "data": { "models": [ { "model_id": "seedance-2.0", "description": "Seedance 2.0 flagship: multimodal references (image/video/audio), up to 1080p.", "capabilities": [ "text_to_video", "image_to_video" ], "params": { "prompt": { "max_length": 2500 }, "duration_sec": { "values": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "default": 5 }, "aspect_ratio": { "values": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "default": "9:16" }, "resolution": { "values": [ "720p", "1080p" ], "default": "720p" }, "generate_audio": { "default": true }, "refs": { "max": 9, "accept": [ "image", "video", "audio" ] } } } ] }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "List AI video models", "tags": [ "AI Videos" ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://openapi.visionstory.ai/api/v1/ai_video/models\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request GET 'https://openapi.visionstory.ai/api/v1/ai_video/models' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY'" } ] } }, "/api/v1/ai_videos": { "get": { "description": "List AI video tasks for this account, newest first. Pass the previous page's `next_cursor` to\npaginate; `next_cursor=0` means no more pages.\n\nBeta: available to allowlisted API keys; standard per-key rate limits apply.", "operationId": "get_ai_videos_api_v1_ai_videos_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" }, { "description": "Pagination cursor from the previous page's `next_cursor`. Omit or pass 0 to start from the newest task.", "in": "query", "name": "cursor", "required": false, "schema": { "default": 0, "description": "Pagination cursor from the previous page's `next_cursor`. Omit or pass 0 to start from the newest task.", "minimum": 0, "title": "Cursor", "type": "integer" }, "example": 0 }, { "description": "Maximum tasks to return per page. Range 1–100; defaults to 20.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Maximum tasks to return per page. Range 1–100; defaults to 20.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" }, "example": 20 } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_GetAiVideosResponse_" }, "example": { "data": { "videos": [ { "model_id": "vs_character_v4", "status": "success", "video_id": "video_123456", "aspect_ratio": "", "cost_credit": 0, "cover_url": "https://example.com/media/input.mp4", "created_at": 0, "duration_sec": 0 } ], "next_cursor": 0 }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "List AI videos", "tags": [ "AI Videos" ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://openapi.visionstory.ai/api/v1/ai_videos\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n params={\n \"cursor\": 0,\n \"limit\": 20\n },\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request GET 'https://openapi.visionstory.ai/api/v1/ai_videos?cursor=0&limit=20' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY'" } ] } }, "/api/v1/asset": { "delete": { "description": "Delete an asset by `asset_id`. Videos already generated from it — or still generating — are\nunaffected.\n\nAgent safety: require an explicit user request and confirmation immediately before calling this destructive operation.", "operationId": "delete_asset_api_v1_asset_delete", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" }, { "description": "Id of the asset to delete, as returned by POST /api/v1/asset (the `asset_id` field). Videos already generated from it (or in progress) are not affected.", "in": "query", "name": "asset_id", "required": true, "schema": { "description": "Id of the asset to delete, as returned by POST /api/v1/asset (the `asset_id` field). Videos already generated from it (or in progress) are not affected.", "title": "Asset Id", "type": "string" }, "example": "asset_123456" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_DeleteResponse_" }, "example": { "data": { "deleted": true }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Delete asset", "tags": [ "Assets" ], "x-safety": { "destructive": true, "confirmationRequired": true, "instruction": "Do not call this operation unless the user explicitly requested and confirmed deletion." }, "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.delete(\n \"https://openapi.visionstory.ai/api/v1/asset\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n params={\n \"asset_id\": \"asset_123456\"\n },\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request DELETE 'https://openapi.visionstory.ai/api/v1/asset?asset_id=asset_123456' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY'" } ] }, "post": { "description": "Upload a reusable media asset (image / video / audio) from a public URL or inline base64, and get an\n`asset_id` to reference across generation requests. Re-uploading identical content returns the\nexisting asset. Limits: image ≤30MB, audio ≤15MB, video ≤100MB.", "operationId": "create_asset_api_v1_asset_post", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetRequest" }, "example": { "url": "https://example.com/media/reference.jpg" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_CreateAssetResponse_" }, "example": { "data": { "asset_id": "asset_123456", "kind": "string", "created_at": 0, "duration_sec": 0, "height": 0, "mime": "", "width": 0 }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Upload asset", "tags": [ "Assets" ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://openapi.visionstory.ai/api/v1/asset\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n json={\n \"url\": \"https://example.com/media/reference.jpg\"\n },\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request POST 'https://openapi.visionstory.ai/api/v1/asset' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"url\": \"https://example.com/media/reference.jpg\"\n}'" } ] } }, "/api/v1/assets": { "get": { "description": "List your uploaded assets, newest first. Pass the previous page's `next_cursor` to paginate\n(`next_cursor=0` means no more pages); optionally filter by `kind` (`image` / `video` / `audio`).", "operationId": "get_assets_api_v1_assets_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" }, { "description": "Filter by media kind. Omit to return assets of all kinds.", "in": "query", "name": "kind", "required": false, "schema": { "anyOf": [ { "enum": [ "image", "video", "audio" ], "type": "string" }, { "type": "null" } ], "description": "Filter by media kind. Omit to return assets of all kinds.", "title": "Kind" }, "example": "image" }, { "description": "Pagination cursor from the previous page's `next_cursor`. Omit or pass 0 to start from the newest asset.", "in": "query", "name": "cursor", "required": false, "schema": { "default": 0, "description": "Pagination cursor from the previous page's `next_cursor`. Omit or pass 0 to start from the newest asset.", "minimum": 0, "title": "Cursor", "type": "integer" }, "example": 0 }, { "description": "Maximum assets to return per page. Range 1–100; defaults to 20.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Maximum assets to return per page. Range 1–100; defaults to 20.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" }, "example": 20 } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_GetAssetsResponse_" }, "example": { "data": { "assets": [ { "asset_id": "asset_123456", "kind": "string", "created_at": 0, "duration_sec": 0, "height": 0, "mime": "", "width": 0 } ], "next_cursor": 0 }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "List assets", "tags": [ "Assets" ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://openapi.visionstory.ai/api/v1/assets\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n params={\n \"cursor\": 0,\n \"limit\": 20\n },\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request GET 'https://openapi.visionstory.ai/api/v1/assets?cursor=0&limit=20' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY'" } ] } }, "/api/v1/avatar": { "delete": { "description": "Delete one of your custom avatars by `avatar_id`. Only avatars you created can be deleted; public\navatars are unaffected.\n\nAgent safety: require an explicit user request and confirmation immediately before calling this destructive operation.", "operationId": "delete_avatar_api_v1_avatar_delete", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" }, { "description": "Id of the custom avatar to delete, as returned by POST /api/v1/avatar (the `avatar_id` field). Only avatars you created can be deleted; public avatars are unaffected.", "in": "query", "name": "avatar_id", "required": true, "schema": { "description": "Id of the custom avatar to delete, as returned by POST /api/v1/avatar (the `avatar_id` field). Only avatars you created can be deleted; public avatars are unaffected.", "title": "Avatar Id", "type": "string" }, "example": "avatar_123456" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_DeleteResponse_" }, "example": { "data": { "deleted": true }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Delete avatar", "tags": [ "Avatars" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nrequests.delete(\n 'https://openapi.visionstory.ai/api/v1/avatar?avatar_id=xxxx', headers=headers\n)" }, { "lang": "cURL", "source": "curl -X 'DELETE' \\\n 'https://openapi.visionstory.ai/api/v1/avatar?avatar_id=xxxx' \\\n -H 'accept: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY'" } ], "x-safety": { "destructive": true, "confirmationRequired": true, "instruction": "Do not call this operation unless the user explicitly requested and confirmed deletion." }, "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } }, "post": { "description": "Create a custom avatar from a single portrait image (JPEG/PNG/WEBP/HEIC, up to 10MB). The returned\n`avatar_id` can then speak any script via POST /api/v1/video.", "operationId": "create_avatar_api_v1_avatar_post", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAvatarRequest" }, "example": { "img_url": "https://example.com/media/portrait.jpg" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_CreateAvatarResponse_" }, "example": { "data": { "avatar_id": "avatar_123456", "thumbnail_url": "https://example.com/media/input.mp4", "aspect_ratios": [ "9:16" ], "created_at": 0 }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Create avatar", "tags": [ "Avatars" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\nimport base64\n\ndef encode_base64(file_path):\n with open(file_path, 'rb') as file:\n encoded_string = base64.b64encode(file.read()).decode('utf-8')\n return encoded_string\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n\n# payload = {\n# \"img_url\": \"https://cdn.visionstory.ai/vman/character/ffcebbfdf9495c501fe70f8453353e3d_4721_head.jpg\"\n# }\n\nimage_file_path = '/path/to/image.jpg'\npayload = {\n \"inline_data\": {\n \"mime_type\": \"image/jpg\",\n \"data\": encode_base64(image_file_path)\n }\n}\n\nresponse = requests.post(\n 'https://openapi.visionstory.ai/api/v1/avatar', json=payload, headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data']['avatar_id'])" }, { "lang": "cURL", "source": "curl -X 'POST' \\\n 'https://openapi.visionstory.ai/api/v1/avatar' \\\n -H 'accept: application/json' \\\n -H 'content-type: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY' \\\n --data '\n{\n \"img_url\": \"https://cdn.visionstory.ai/vman/character/89d9924fc9b73df255e8233613f52de2_3871_norm.jpeg\"\n}\n'" } ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } } }, "/api/v1/avatars": { "get": { "description": "List avatars available to your account: the public platform library plus your own custom avatars\n(up to 100). The response is not paginated.", "operationId": "get_avatars_api_v1_avatars_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_GetAvatarsResponse_" }, "example": { "data": { "my_avatars": [ { "avatar_id": "avatar_123456", "thumbnail_url": "https://example.com/media/input.mp4", "aspect_ratios": [ "9:16" ], "created_at": 0 } ], "public_avatars": [ { "avatar_id": "avatar_123456", "thumbnail_url": "https://example.com/media/input.mp4", "aspect_ratios": [ "9:16" ], "created_at": 0 } ], "total_cnt": 1 }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "List avatars", "tags": [ "Avatars" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nresponse = requests.get(\n 'https://openapi.visionstory.ai/api/v1/avatars', headers=headers, timeout=10\n)\nresp_data = response.json()\nprint(len(resp_data['data']['public_avatars']))\nprint(len(resp_data['data']['my_avatars']))" }, { "lang": "cURL", "source": "curl -X 'GET' \\\n 'https://openapi.visionstory.ai/api/v1/avatars' \\\n -H 'accept: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY'" } ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } } }, "/api/v1/billing/credits": { "get": { "description": "Return the credits currently available on your account. Every generation deducts credits based on\nthe model, resolution, and duration.", "operationId": "get_credits_api_v1_billing_credits_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_GetCreditsResponse_" }, "example": { "data": { "remaining": 1 }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Get credit balance", "tags": [ "Billing" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nresponse = requests.get(\n 'https://openapi.visionstory.ai/api/v1/billing/credits', headers=headers, timeout=10\n)\nresp_data = response.json()\nprint(resp_data['data']['remaining'])" }, { "lang": "cURL", "source": "curl -X 'GET' \\\n 'https://openapi.visionstory.ai/api/v1/billing/credits' \\\n -H 'accept: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY'" } ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } } }, "/api/v1/image": { "post": { "description": "Generate an image from a text prompt, optionally guided by up to 4 reference images\n(asset_id / url / inline_data). Editing works through instructions in the prompt plus reference\nimages — no mask needed. Synchronous: the response contains the image URL directly, and you can\npass that URL straight into other endpoints (video `refs`, `first_frame`/`end_frame`). It is not added\nto your asset library — use POST /api/v1/asset if you want to keep it there. Credits are charged\nper image, only on success. Per-key concurrency is limited during beta; requests beyond the limit are rejected, not queued.", "operationId": "create_image_api_v1_image_post", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImageRequest" }, "example": { "model_id": "nano-banana", "prompt": "A red panda barista in a cozy cafe, warm lighting", "aspect_ratio": "1:1", "resolution": "1K" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_CreateImageResponse_" }, "example": { "data": { "url": "https://example.com/media/input.mp4", "cost_credit": 0, "height": 0, "model_id": "", "width": 0 }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Create Image", "tags": [ "Images" ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://openapi.visionstory.ai/api/v1/image\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n json={\n \"model_id\": \"nano-banana\",\n \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\"\n },\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request POST 'https://openapi.visionstory.ai/api/v1/image' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"model_id\": \"nano-banana\",\n \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\"\n}'" } ] } }, "/api/v1/image/models": { "get": { "description": "Machine-readable capabilities of available image models: aspect ratios, resolutions, reference\nimage limits, and `credit_per_image` (same price as the web product).", "operationId": "get_image_models_api_v1_image_models_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_GetImageModelsResponse_" }, "example": { "data": { "models": [ { "model_id": "nano-banana", "description": "Fast and economical general-purpose image generation.", "credit_per_image": 1, "params": { "prompt": { "max_length": 5000 }, "aspect_ratio": { "values": [ "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9" ], "default": "1:1" }, "resolution": { "values": [ "1K", "2K" ], "default": "1K" }, "refs": { "max": 4, "accept": [ "image" ] } } }, { "model_id": "nano-banana-2", "description": "Balanced quality and speed, strong instruction-following edits.", "credit_per_image": 2, "params": { "prompt": { "max_length": 5000 }, "aspect_ratio": { "values": [ "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9" ], "default": "1:1" }, "resolution": { "values": [ "1K", "2K" ], "default": "1K" }, "refs": { "max": 4, "accept": [ "image" ] } } }, { "model_id": "nano-banana-pro", "description": "Highest quality tier, best for detailed scenes; supports 2K output.", "credit_per_image": 3, "params": { "prompt": { "max_length": 5000 }, "aspect_ratio": { "values": [ "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9" ], "default": "1:1" }, "resolution": { "values": [ "1K", "2K" ], "default": "1K" }, "refs": { "max": 4, "accept": [ "image" ] } } } ] }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Get Image Models", "tags": [ "Images" ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://openapi.visionstory.ai/api/v1/image/models\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request GET 'https://openapi.visionstory.ai/api/v1/image/models' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY'" } ] } }, "/api/v1/models": { "get": { "description": "List the avatar rendering models available for talking-avatar videos. Each entry reports its\nsupported aspect ratios and resolutions and its maximum clip duration. Pass a model's `model_id`\nto POST /api/v1/video.", "operationId": "get_models_api_v1_models_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_GetModelsResponse_" }, "example": { "data": { "models": [ { "description": "string", "max_duration_seconds": 1, "model_id": "vs_character_v4", "aspect_ratios": [ "9:16" ], "resolutions": [ "480p" ] } ] }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "List avatar models", "tags": [ "Models" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nresponse = requests.get(\n 'https://openapi.visionstory.ai/api/v1/models', headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data'])" }, { "lang": "cURL", "source": "curl -X 'GET' \\\n 'https://openapi.visionstory.ai/api/v1/models' \\\n -H 'accept: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY'" } ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } } }, "/api/v1/tts": { "post": { "description": "Convert text to speech with VisionStory smart TTS. Pick a voice from GET /api/v1/voices (public or\nyour cloned voices). The service automatically selects the best synthesis strategy for the voice\nand the text language. Billing: 2 credits per 1000 characters (rounded up), only charged on success.\n\nSynchronous — the response body is the MP3 audio itself (`audio/mpeg`). Duration and billing are\nreturned in the `X-Audio-Duration-Sec`, `X-Usage-Characters` and `X-Cost-Credit` headers. The audio\nis not stored on our side, so save the response body; a repeat call regenerates and bills again. Per-key concurrency is limited during beta; requests beyond the limit are rejected, not queued.", "operationId": "create_speech_api_v1_tts_post", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpeechRequest" }, "example": { "text": "Welcome to VisionStory.", "voice_id": "voice_123456" } } }, "required": true }, "responses": { "200": { "content": { "audio/mpeg": { "schema": { "format": "binary", "type": "string" }, "example": "string" } }, "description": "MP3 audio (44.1kHz). Usage metadata is returned in response headers." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Create Speech", "tags": [ "Speech" ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" }, "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://openapi.visionstory.ai/api/v1/tts\",\n headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n json={\n \"text\": \"Welcome to VisionStory.\",\n \"voice_id\": \"voice_123456\"\n },\n)\nresponse.raise_for_status()\nprint(response.json())" }, { "lang": "cURL", "source": "curl --request POST 'https://openapi.visionstory.ai/api/v1/tts' \\\n --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"text\": \"Welcome to VisionStory.\",\n \"voice_id\": \"voice_123456\"\n}'" } ] } }, "/api/v1/video": { "delete": { "description": "Delete one of your videos by `video_id`. Only videos you created are affected, and deletion cannot\nbe undone.\n\nAgent safety: require an explicit user request and confirmation immediately before calling this destructive operation.", "operationId": "delete_video_api_v1_video_delete", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" }, { "description": "Id of the video to delete, as returned by POST /api/v1/video or GET /api/v1/videos. Only videos you created are affected; deletion is permanent.", "in": "query", "name": "video_id", "required": true, "schema": { "description": "Id of the video to delete, as returned by POST /api/v1/video or GET /api/v1/videos. Only videos you created are affected; deletion is permanent.", "title": "Video Id", "type": "string" }, "example": "video_123456" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_DeleteResponse_" }, "example": { "data": { "deleted": true }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Delete video", "tags": [ "Videos" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nrequests.delete(\n 'https://openapi.visionstory.ai/api/v1/video?video_id=xxxx', headers=headers\n)" }, { "lang": "cURL", "source": "curl -X 'DELETE' \\\n 'https://openapi.visionstory.ai/api/v1/video?video_id=xxxx' \\\n -H 'accept: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY'" } ], "x-safety": { "destructive": true, "confirmationRequired": true, "instruction": "Do not call this operation unless the user explicitly requested and confirmed deletion." }, "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } }, "get": { "description": "Get a single video task by `video_id`, including its status (`queued`, `creating`, `created`, or\n`failed`) and, once ready, the download URL. Poll this to track generation progress.", "operationId": "get_video_detail_api_v1_video_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" }, { "description": "Id of the video task to fetch, as returned by POST /api/v1/video (the `video_id` field) or GET /api/v1/videos.", "in": "query", "name": "video_id", "required": true, "schema": { "description": "Id of the video task to fetch, as returned by POST /api/v1/video (the `video_id` field) or GET /api/v1/videos.", "title": "Video Id", "type": "string" }, "example": "video_123456" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_GetVideoResponse_" }, "example": { "data": { "created_at": 1, "model_id": "vs_character_v4", "status": "success", "video_id": "video_123456", "aspect_ratio": "9:16", "cost_credit": 0, "resolution": "480p", "video_url": "https://example.com/media/input.mp4" }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Get video status", "tags": [ "Videos" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nresponse = requests.get(\n 'https://openapi.visionstory.ai/api/v1/video?video_id=xxxx', headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data'])" }, { "lang": "cURL", "source": "curl -X 'GET' \\\n 'https://openapi.visionstory.ai/api/v1/video?video_id=xxxx' \\\n -H 'accept: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY'" } ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } }, "post": { "description": "Generate a talking-avatar video: an avatar speaks a script provided either as text-to-speech\n(`text_script`) or pre-recorded audio (`audio_script`). Generation is asynchronous — poll\nGET /api/v1/video for status. Finished videos are retained for 7 days, so download promptly.\n\nPass `client_request_id` to make retries idempotent (no double charge).", "operationId": "create_video_api_v1_video_post", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoRequest" }, "example": { "model_id": "vs_character_v4", "avatar_id": "avatar_123456", "text_script": { "text": "Welcome to VisionStory.", "voice_id": "voice_123456", "speech_rate": "normal" }, "aspect_ratio": "9:16", "resolution": "720p", "client_request_id": "request_20260824_001" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_CreateVideoResponse_" }, "example": { "data": { "video_id": "video_123456" }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Generate video", "tags": [ "Videos" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\nimport base64\n\ndef encode_base64(file_path):\n with open(file_path, 'rb') as file:\n encoded_string = base64.b64encode(file.read()).decode('utf-8')\n return encoded_string\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n\n# audio_file_path = '/path/to/audio.mp3'\n# payload = {\n# \"model_id\": 'vs_character_v4',\n# \"avatar_id\": \"4321918387609092991\",\n# \"audio_script\": {\n# \"inline_data\": {\n# \"mime_type\": \"audio/mp3\",\n# \"data\": encode_base64(audio_file_path)\n# },\n# \"voice_change\": True,\n# \"voice_id\": \"Alice\",\n# \"denoise\": True\n# },\n# \"aspect_ratio\": \"1:1\",\n# \"resolution\": \"720p\",\n# \"background_color\": \"#888888\"\n# }\n\npayload = {\n \"model_id\": 'vs_character_v4',\n \"avatar_id\": \"4321918387609092991\",\n \"text_script\": {\n \"text\": \"Hello World, this is my first test video.\",\n \"voice_id\": \"Alice\",\n \"speech_rate\": \"normal\"\n },\n \"aspect_ratio\": \"9:16\",\n \"resolution\": \"720p\"\n}\n\nresponse = requests.post(\n 'https://openapi.visionstory.ai/api/v1/video', json=payload, headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data']['video_id'])" }, { "lang": "cURL", "source": "curl -X 'POST' \\\n 'https://openapi.visionstory.ai/api/v1/video' \\\n -H 'accept: application/json' \\\n -H 'content-type: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY' \\\n --data '\n{\n \"model_id\": \"vs_character_v4\",\n \"avatar_id\": \"4321918387609092991\",\n \"text_script\": {\n \"text\": \"Hello World, this is my first test video.\",\n \"voice_id\": \"Alice\",\n \"speech_rate\": \"normal\"\n },\n \"aspect_ratio\": \"9:16\",\n \"resolution\": \"720p\"\n}\n'" } ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } } }, "/api/v1/videos": { "get": { "description": "List your most recent videos (up to 100, newest first). Not paginated — intended for quick access to\nrecent generation history.", "operationId": "get_videos_api_v1_videos_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_GetVideosResponse_" }, "example": { "data": { "videos": [ { "created_at": 1, "model_id": "vs_character_v4", "status": "success", "video_id": "video_123456", "aspect_ratio": "9:16", "cost_credit": 0, "resolution": "480p", "video_url": "https://example.com/media/input.mp4" } ] }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "List videos", "tags": [ "Videos" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nresponse = requests.get(\n 'https://openapi.visionstory.ai/api/v1/videos', headers=headers, timeout=10\n)\nresp_data = response.json()\nprint(len(resp_data['data']['videos']))" }, { "lang": "cURL", "source": "curl -X 'GET' \\\n 'https://openapi.visionstory.ai/api/v1/videos' \\\n -H 'accept: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY'" } ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } } }, "/api/v1/voice": { "delete": { "description": "Delete one of your cloned voices by `voice_id`. Only voices you created can be removed.\n\nAgent safety: require an explicit user request and confirmation immediately before calling this destructive operation.", "operationId": "delete_voice_api_v1_voice_delete", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" }, { "description": "Id of the cloned voice to delete, as returned by POST /api/v1/voice or listed under `my_voices` in GET /api/v1/voices. Only voices you created can be removed.", "in": "query", "name": "voice_id", "required": true, "schema": { "description": "Id of the cloned voice to delete, as returned by POST /api/v1/voice or listed under `my_voices` in GET /api/v1/voices. Only voices you created can be removed.", "title": "Voice Id", "type": "string" }, "example": "voice_123456" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_DeleteResponse_" }, "example": { "data": { "deleted": true }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Delete voice", "tags": [ "Voices" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nrequests.delete(\n 'https://openapi.visionstory.ai/api/v1/voice?voice_id=xxxx', headers=headers\n)" }, { "lang": "cURL", "source": "curl -X 'DELETE' \\\n 'https://openapi.visionstory.ai/api/v1/voice?voice_id=xxxx' \\\n -H 'accept: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY'" } ], "x-safety": { "destructive": true, "confirmationRequired": true, "instruction": "Do not call this operation unless the user explicitly requested and confirmed deletion." }, "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } }, "post": { "description": "Clone a voice from a clean audio sample (AVI/MP3/MP4/M4A/WAV, up to 30MB) and get a reusable\n`voice_id`. Cloning runs synchronously and can take a while, so set a generous request timeout. The\nnumber of active cloned voices allowed depends on your plan.", "operationId": "clone_voice_api_v1_voice_post", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneVoiceRequest" }, "example": { "audio_url": "https://example.com/media/voice-sample.mp3", "preview_text": "Welcome to VisionStory." } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_CloneVoiceResponse_" }, "example": { "data": { "voice_id": "voice_123456" }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "Clone voice", "tags": [ "Voices" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\nimport base64\n\ndef encode_base64(file_path):\n with open(file_path, 'rb') as file:\n encoded_string = base64.b64encode(file.read()).decode('utf-8')\n return encoded_string\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n\n# payload = {\n# \"audio_url\": \"https://storage.googleapis.com/eleven-public-prod/premade/voices/Xb7hH8MSUJpSbSDYk0k2/d10f7534-11f6-41fe-a012-2de1e482d336.mp3\",\n# \"preview_text\": \"How are you doing guys, this is my voice\"\n# }\n\naudio_file_path = '/path/to/audio.mp3'\npayload = {\n \"inline_data\": {\n \"mime_type\": \"audio/mp3\",\n \"data\": encode_base64(audio_file_path)\n },\n \"preview_text\": \"How are you doing guys, this is my voice\"\n}\n\n# wait for about 15 seconds\nresponse = requests.post(\n 'https://openapi.visionstory.ai/api/v1/voice', json=payload, headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data']['voice_id'])" }, { "lang": "cURL", "source": "curl -X 'POST' \\\n 'https://openapi.visionstory.ai/api/v1/voice' \\\n -H 'accept: application/json' \\\n -H 'content-type: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY' \\\n --data '\n{\n \"audio_url\": \"https://storage.googleapis.com/eleven-public-prod/premade/voices/Xb7hH8MSUJpSbSDYk0k2/d10f7534-11f6-41fe-a012-2de1e482d336.mp3\",\n \"preview_text\": \"How are you doing guys, this is my voice\"\n}\n'" } ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } } }, "/api/v1/voices": { "get": { "description": "List the voices you can synthesize with: the public voice library plus any voices you have cloned.", "operationId": "get_voices_api_v1_voices_get", "parameters": [ { "description": "Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](/api-keys) (Pro plan and up).", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" }, "example": "sk-vs-your-api-key" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSuccessResponse_GetVoicesResponse_" }, "example": { "data": { "my_voices": [ { "is_free": true, "language": "string", "preview_audio_url": "https://example.com/media/input.mp4", "voice_id": "voice_123456", "provider": "", "tags": "string" } ], "public_voices": [ { "is_free": true, "language": "string", "preview_audio_url": "https://example.com/media/input.mp4", "voice_id": "voice_123456", "provider": "", "tags": "string" } ] }, "server_time": "2026-08-24T08:00:00Z", "message": "success" } } }, "description": "Successful Response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 1, "message": "string", "details": "string", "hint": "string" } } } }, "description": "Error 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)." } }, "security": [ { "APIKeyHeader": [] } ], "summary": "List voices", "tags": [ "Voices" ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nresponse = requests.get(\n 'https://openapi.visionstory.ai/api/v1/voices', headers=headers, timeout=10\n)\nresp_data = response.json()\nprint(len(resp_data['data']['public_voices']))\nprint(len(resp_data['data']['my_voices']))" }, { "lang": "cURL", "source": "curl -X 'GET' \\\n 'https://openapi.visionstory.ai/api/v1/voices' \\\n -H 'accept: application/json' \\\n -H 'X-API-Key: $VISIONSTORY_API_KEY'" } ], "x-agent-guidance": { "exampleIdsArePlaceholders": true, "credentialsFromEnvironment": "VISIONSTORY_API_KEY" } } } }, "openapi": "3.1.0", "externalDocs": { "description": "VisionStory developer guides and agent integration instructions", "url": "https://developers.visionstory.ai/llms.txt" }, "x-agent-instructions": { "version": "0.0.6", "lastReviewed": "2026-08-27", "status": "testing", "taskRouting": { "start": "https://developers.visionstory.ai/llms.txt", "agentSetup": "https://developers.visionstory.ai/guides/for-agents.md", "exactSchemas": "https://developers.visionstory.ai/openapi.json", "changesAndDeprecations": "https://developers.visionstory.ai/guides/changelog.md" }, "rules": [ "Read VISIONSTORY_API_KEY from the local environment. Never ask the user to paste it into chat, and never print, log, or commit it.", "Discover current model, avatar, and voice IDs with list operations. Example IDs are placeholders, not guaranteed valid resources.", "Use client_request_id for retry-safe creation requests when supported.", "Poll asynchronous jobs no faster than every 5 seconds and stop after 10 minutes unless the user asks to keep waiting.", "Redact credentials when reporting API errors.", "Do not call DELETE operations without an explicit user request and confirmation." ] }, "servers": [ { "url": "https://openapi.visionstory.ai", "description": "Production" } ] }