{
  "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"
      },
      "AiVideoModelDto": {
        "additionalProperties": false,
        "properties": {
          "capabilities": {
            "description": "Supported generation modes, such as text_to_video and image_to_video.",
            "items": {
              "type": "string"
            },
            "title": "Capabilities",
            "type": "array"
          },
          "description": {
            "description": "Public model summary.",
            "title": "Description",
            "type": "string"
          },
          "model_id": {
            "description": "Public model ID to send in AI video requests.",
            "title": "Model Id",
            "type": "string"
          },
          "params": {
            "$ref": "#/components/schemas/AiVideoModelParams",
            "description": "Model-specific allowed values, defaults, and media limits; pricing is queried separately."
          }
        },
        "required": [
          "model_id",
          "description",
          "capabilities",
          "params"
        ],
        "title": "AiVideoModelDto",
        "type": "object"
      },
      "AiVideoModelParams": {
        "additionalProperties": false,
        "properties": {
          "aspect_ratio": {
            "$ref": "#/components/schemas/StringChoices",
            "description": "Allowed aspect ratios and default; input-mode restrictions still apply."
          },
          "duration_sec": {
            "$ref": "#/components/schemas/DurationChoices",
            "description": "Allowed clip durations and default."
          },
          "first_frame": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MediaConstraints"
              },
              {
                "type": "null"
              }
            ],
            "description": "First-frame image constraints; null when image-to-video is unsupported."
          },
          "generate_audio": {
            "$ref": "#/components/schemas/AudioCapability",
            "description": "Native-audio default; reference combinations may restrict it."
          },
          "prompt": {
            "$ref": "#/components/schemas/PromptCapability",
            "description": "Prompt length and reference-syntax support."
          },
          "refs": {
            "$ref": "#/components/schemas/VideoReferences",
            "description": "Reference media types, counts, and constraints."
          },
          "resolution": {
            "$ref": "#/components/schemas/StringChoices",
            "description": "Allowed resolutions and default for this model."
          }
        },
        "required": [
          "prompt",
          "duration_sec",
          "aspect_ratio",
          "resolution",
          "generate_audio",
          "refs",
          "first_frame"
        ],
        "title": "AiVideoModelParams",
        "type": "object"
      },
      "AlignRequest": {
        "additionalProperties": false,
        "properties": {
          "audio": {
            "$ref": "#/components/schemas/MediaRef",
            "description": "Audio to align: a WAV or MP3 up to 15MB (asset_id / url / inline_data)."
          },
          "text": {
            "description": "The exact text spoken in the audio (e.g. the script you synthesized with POST /api/v1/tts). Timestamps are aligned against this text.",
            "minLength": 1,
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "audio",
          "text"
        ],
        "title": "AlignRequest",
        "type": "object"
      },
      "AlignResponse": {
        "properties": {
          "cost_credit": {
            "default": 0,
            "description": "Credits charged for this request.",
            "title": "Cost Credit",
            "type": "integer"
          },
          "duration_sec": {
            "default": 0,
            "description": "Duration of the input audio in seconds.",
            "title": "Duration Sec",
            "type": "number"
          },
          "words": {
            "description": "Word-level timestamps for the given text.",
            "items": {
              "$ref": "#/components/schemas/WordDto"
            },
            "title": "Words",
            "type": "array"
          }
        },
        "title": "AlignResponse",
        "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"
      },
      "AudioCapability": {
        "additionalProperties": false,
        "properties": {
          "default": {
            "description": "Whether native audio is generated when omitted; does not change price.",
            "title": "Default",
            "type": "boolean"
          }
        },
        "required": [
          "default"
        ],
        "title": "AudioCapability",
        "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.",
            "title": "Created At",
            "type": "integer"
          },
          "default_voice_id": {
            "default": "",
            "description": "The voice this avatar was set up with. `voice_id` is required in a text script, so copy this value when you want the avatar's own voice (rather than guessing one). May be empty for avatars without a preset voice.",
            "title": "Default Voice Id",
            "type": "string"
          },
          "framing": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/AvatarFraming"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Current framing per aspect ratio, always 3 entries in the order 9:16, 16:9, 1:1. New avatars start with automatic framing; change it with POST /api/v1/avatar/framing. It is shared with the web editor. Always null for public avatars, which cannot be reframed through the API.",
            "title": "Framing"
          },
          "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"
      },
      "AvatarFraming": {
        "properties": {
          "aspect_ratio": {
            "description": "Aspect ratio this framing applies to.",
            "enum": [
              "9:16",
              "16:9",
              "1:1"
            ],
            "title": "Aspect Ratio",
            "type": "string"
          },
          "image_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "URL of the reference image videos in this aspect ratio currently use.",
            "title": "Image Url"
          },
          "offset_x": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Horizontal position of the framed area within the room it can move, from -1 to 1: `-1` touches the left edge, `0` is centered, `1` touches the right edge. It has no effect when the framed area already spans the full width. null when `zoom` is null.",
            "title": "Offset X"
          },
          "offset_y": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Vertical position of the framed area within the room it can move, from -1 to 1: `-1` touches the top edge, `0` is centered, `1` touches the bottom edge. It has no effect when the framed area already spans the full height. null when `zoom` is null.",
            "title": "Offset Y"
          },
          "zoom": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Zoom level, at least 1. `1` is the largest area of this aspect ratio that fits in the avatar's source image (the widest framing, e.g. full body); `2` halves the framed width and height, making the person appear twice as large. null for avatars created before framing was supported.",
            "title": "Zoom"
          }
        },
        "required": [
          "aspect_ratio"
        ],
        "title": "AvatarFraming",
        "type": "object"
      },
      "BaseSuccessResponse_AiVideoCostResponse_": {
        "properties": {
          "data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AiVideoCostResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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_AlignResponse_": {
        "properties": {
          "data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AlignResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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[AlignResponse]",
        "type": "object"
      },
      "BaseSuccessResponse_CloneVoiceResponse_": {
        "properties": {
          "data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CloneVoiceResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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_MediaUnderstandResponse_": {
        "properties": {
          "data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MediaUnderstandResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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[MediaUnderstandResponse]",
        "type": "object"
      },
      "BaseSuccessResponse_TranscribeResponse_": {
        "properties": {
          "data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TranscribeResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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[TranscribeResponse]",
        "type": "object"
      },
      "BaseSuccessResponse_Union_GetAiVideoResponse__GetAiVideosBatchResponse__": {
        "properties": {
          "data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/GetAiVideoResponse"
              },
              {
                "$ref": "#/components/schemas/GetAiVideosBatchResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload.",
            "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"
      },
      "BaseSuccessResponse_UpdateAvatarFramingResponse_": {
        "properties": {
          "data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UpdateAvatarFramingResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload."
          },
          "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[UpdateAvatarFramingResponse]",
        "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": {
          "gender": {
            "default": "",
            "description": "Voice gender detected from the audio sample; empty if detection is still pending.",
            "title": "Gender",
            "type": "string"
          },
          "language": {
            "default": "",
            "description": "Primary language detected from the audio sample, e.g. `english`; empty if detection is still pending.",
            "title": "Language",
            "type": "string"
          },
          "locale": {
            "default": "",
            "description": "BCP 47 locale detected for the clone (e.g. `en-US`), same vocabulary as the `locale` field of GET /api/v1/voices and the `locale` parameter of POST /api/v1/tts; empty if detection was unavailable.",
            "title": "Locale",
            "type": "string"
          },
          "preview_audio_url": {
            "default": "",
            "description": "URL of a short sample clip synthesized with the cloned voice; empty if not ready yet.",
            "title": "Preview Audio Url",
            "type": "string"
          },
          "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"
              },
              {
                "type": "null"
              }
            ],
            "description": "Aspect ratio such as `16:9` / `9:16` / `1:1`, or `adaptive` to let the model follow the input material. Allowed values vary by model; defaults to the model default. `wan-3.0` always follows the references when `refs` is set, so passing both is a 400.",
            "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": "Clip length in seconds. Allowed values vary by model (see GET /api/v1/ai_video/models); defaults to the model default. Longer clips cost more credits.",
            "title": "Duration Sec"
          },
          "end_frame": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MediaRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "Image to use as the last frame. Requires `first_frame`."
          },
          "first_frame": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MediaRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "Image to use as the first frame; providing it switches the request to image-to-video (models listing `image_to_video` in `capabilities` only). Mutually exclusive with `refs`."
          },
          "generate_audio": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Whether to generate a native audio track; defaults to true on every model and never changes the price. `kling-3.0-omni` cannot combine it with a video reference (400).",
            "title": "Generate Audio"
          },
          "model_id": {
            "description": "Model to generate with. Use an id from GET /api/v1/ai_video/models, e.g. `seedance-2.0`.",
            "examples": [
              "seedance-2.0"
            ],
            "title": "Model Id",
            "type": "string"
          },
          "prompt": {
            "description": "Text description of the video to generate. For image-to-video it describes the motion applied to `first_frame`.",
            "minLength": 1,
            "title": "Prompt",
            "type": "string"
          },
          "refs": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/MediaRef"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Multimodal reference materials (image/video/audio) that guide text-to-video. Only models whose `refs.max` is greater than 0 in GET /api/v1/ai_video/models accept it; `refs.max_per_kind` and `refs.total_duration_sec_max` there give the per-type limits. References never change the price. Mutually exclusive with `first_frame`.",
            "title": "Refs"
          },
          "resolution": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Output resolution such as `480p` / `720p` / `1080p` / `4k`. Allowed values vary by model (4K is `kling-3.0` only; 480p is available on every Seedance and Wan model but not on Kling); defaults to the model default — `kling-3.0-omni` is the only model that defaults to 1080p, every other model defaults to 720p. Higher resolutions cost more credits.",
            "title": "Resolution"
          }
        },
        "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.",
            "title": "Created At",
            "type": "integer"
          },
          "default_voice_id": {
            "default": "",
            "description": "The voice this avatar was set up with. `voice_id` is required in a text script, so copy this value when you want the avatar's own voice (rather than guessing one). May be empty for avatars without a preset voice.",
            "title": "Default Voice Id",
            "type": "string"
          },
          "framing": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/AvatarFraming"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Current framing per aspect ratio, always 3 entries in the order 9:16, 16:9, 1:1. New avatars start with automatic framing; change it with POST /api/v1/avatar/framing. It is shared with the web editor. Always null for public avatars, which cannot be reframed through the API.",
            "title": "Framing"
          },
          "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"
              },
              {
                "type": "null"
              }
            ],
            "description": "Aspect ratio such as 1:1 / 16:9 / 9:16; defaults to 1:1",
            "title": "Aspect Ratio"
          },
          "model_id": {
            "description": "Model id, check GET /api/v1/image/models",
            "title": "Model Id",
            "type": "string"
          },
          "prompt": {
            "description": "Text prompt; also carries edit instructions when refs are given",
            "minLength": 1,
            "title": "Prompt",
            "type": "string"
          },
          "refs": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/MediaRef"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Reference images (asset_id / url / inline_data). The limit differs per model — read `params.refs.max` from GET /api/v1/image/models (4 for `nano-banana-*`, 6 for `gpt-image-*`, 10 for `seedream-5.0-pro`, 14 for `seedream-5.0-lite`).",
            "title": "Refs"
          },
          "resolution": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Output resolution tier. Supported tiers and the default differ per model — read `params.resolution` from GET /api/v1/image/models. Some models are priced per tier (`credit_by_resolution`).",
            "title": "Resolution"
          }
        },
        "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": {
          "locale": {
            "anyOf": [
              {
                "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional BCP 47 locale (e.g. `en-GB`, `zh-TW`) steering pronunciation and accent for multilingual voices, applied best-effort per voice engine. Defaults to the voice's native locale.",
            "title": "Locale"
          },
          "speech_rate": {
            "anyOf": [
              {
                "enum": [
                  "slow",
                  "normal",
                  "fast"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Relative speaking pace: `slow` / `normal` / `fast`; defaults to `normal`. Same vocabulary as `text_script.speech_rate` in POST /api/v1/video. Applied by the voice engine where it supports pacing natively, otherwise by a ~10% time-stretch of the audio (pitch preserved); the exact duration change varies by voice, so read `X-Audio-Duration-Sec`.",
            "title": "Speech Rate"
          },
          "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`.",
            "title": "Model Id",
            "type": "string"
          },
          "resolution": {
            "default": "720p",
            "description": "Output resolution: `720p`, `1080p`, or `2k`. Higher values cost more credits and take longer to render; defaults to `720p`.",
            "enum": [
              "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"
      },
      "DurationChoices": {
        "additionalProperties": false,
        "properties": {
          "default": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Clip duration used when omitted.",
            "title": "Default"
          },
          "values": {
            "description": "Accepted integer clip durations in seconds.",
            "items": {
              "type": "integer"
            },
            "title": "Values",
            "type": "array"
          }
        },
        "required": [
          "values",
          "default"
        ],
        "title": "DurationChoices",
        "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": {
        "additionalProperties": false,
        "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": {
              "$ref": "#/components/schemas/AiVideoModelDto"
            },
            "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": {
          "avatars": {
            "description": "Avatars on this page, newest first: your own avatars, or the public library when the request sets `is_public=true`.",
            "items": {
              "$ref": "#/components/schemas/AvatarDto"
            },
            "title": "Avatars",
            "type": "array"
          },
          "next_cursor": {
            "default": 0,
            "description": "Cursor for the next page; pass it back as `cursor`. 0 means no more pages.",
            "title": "Next Cursor",
            "type": "integer"
          }
        },
        "required": [
          "avatars"
        ],
        "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": {
        "additionalProperties": false,
        "properties": {
          "models": {
            "description": "Machine-readable model capabilities, including credit_per_image",
            "items": {
              "$ref": "#/components/schemas/ImageModelDto"
            },
            "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. Included on the first page only when paginating.",
            "items": {
              "$ref": "#/components/schemas/VoiceDto"
            },
            "title": "My Voices",
            "type": "array"
          },
          "next_cursor": {
            "default": 0,
            "description": "Cursor for the next page of `public_voices`; pass it back as `cursor`. 0 means no more pages (always 0 when the request did not paginate).",
            "title": "Next Cursor",
            "type": "integer"
          },
          "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"
      },
      "ImageModelDto": {
        "additionalProperties": false,
        "properties": {
          "credit_by_resolution": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Credits per image for each supported resolution. Some models (such as the GPT Image ones) cost more at 2K than at 1K; for the others every resolution has the same price.",
            "title": "Credit By Resolution",
            "type": "object"
          },
          "credit_per_image": {
            "description": "Current credits per image at the model's default resolution. Example prices illustrate the response only; query this endpoint for live pricing.",
            "title": "Credit Per Image",
            "type": "integer"
          },
          "description": {
            "description": "Public model summary.",
            "title": "Description",
            "type": "string"
          },
          "model_id": {
            "description": "Public model ID to send in image-generation requests.",
            "title": "Model Id",
            "type": "string"
          },
          "params": {
            "$ref": "#/components/schemas/ImageModelParams",
            "description": "Allowed image parameters and defaults."
          }
        },
        "required": [
          "model_id",
          "description",
          "credit_per_image",
          "credit_by_resolution",
          "params"
        ],
        "title": "ImageModelDto",
        "type": "object"
      },
      "ImageModelParams": {
        "additionalProperties": false,
        "properties": {
          "aspect_ratio": {
            "$ref": "#/components/schemas/StringChoices",
            "description": "Supported image aspect ratios and default."
          },
          "prompt": {
            "$ref": "#/components/schemas/ImagePromptCapability",
            "description": "Prompt-length limit."
          },
          "refs": {
            "$ref": "#/components/schemas/ImageReferences",
            "description": "Reference-image count and accepted kinds."
          },
          "resolution": {
            "$ref": "#/components/schemas/StringChoices",
            "description": "Supported output sizes and default."
          }
        },
        "required": [
          "prompt",
          "aspect_ratio",
          "resolution",
          "refs"
        ],
        "title": "ImageModelParams",
        "type": "object"
      },
      "ImagePromptCapability": {
        "additionalProperties": false,
        "properties": {
          "max_length": {
            "description": "Maximum prompt characters for image generation or editing.",
            "title": "Max Length",
            "type": "integer"
          }
        },
        "required": [
          "max_length"
        ],
        "title": "ImagePromptCapability",
        "type": "object"
      },
      "ImageReferences": {
        "additionalProperties": false,
        "properties": {
          "accept": {
            "description": "Accepted reference kinds; currently image.",
            "items": {
              "type": "string"
            },
            "title": "Accept",
            "type": "array"
          },
          "max": {
            "description": "Maximum reference images per request.",
            "title": "Max",
            "type": "integer"
          }
        },
        "required": [
          "max",
          "accept"
        ],
        "title": "ImageReferences",
        "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; the gateway uses it to tell image / audio / video apart. The accepted set depends on the endpoint — see the field carrying this object. Talking video accepts audio ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav'] and images ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].",
            "title": "Mime Type",
            "type": "string"
          }
        },
        "required": [
          "mime_type",
          "data"
        ],
        "title": "InlineDataModel",
        "type": "object"
      },
      "MediaConstraints": {
        "additionalProperties": false,
        "properties": {
          "aspect_ratio_range": {
            "anyOf": [
              {
                "maxItems": 2,
                "minItems": 2,
                "prefixItems": [
                  {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                ],
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Minimum and maximum width/height ratio.",
            "title": "Aspect Ratio Range"
          },
          "dimension_px": {
            "anyOf": [
              {
                "maxItems": 2,
                "minItems": 2,
                "prefixItems": [
                  {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                ],
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Minimum and maximum pixel length per side.",
            "title": "Dimension Px"
          },
          "duration_sec_range": {
            "anyOf": [
              {
                "maxItems": 2,
                "minItems": 2,
                "prefixItems": [
                  {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                ],
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Minimum and maximum single-reference duration in seconds.",
            "title": "Duration Sec Range"
          },
          "formats": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Accepted file extensions for this media slot.",
            "title": "Formats"
          },
          "fps_range": {
            "anyOf": [
              {
                "maxItems": 2,
                "minItems": 2,
                "prefixItems": [
                  {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                ],
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Minimum and maximum frame rate; a null upper bound means no upper limit.",
            "title": "Fps Range"
          },
          "max_mb": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Maximum media file size in MiB, including gateway limits.",
            "title": "Max Mb"
          }
        },
        "title": "MediaConstraints",
        "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. Images: image/jpeg, image/jpg, image/png, image/webp, image/bmp, image/tiff, image/gif; audio: audio/wav, audio/x-wav, audio/wave, audio/mpeg, audio/mp3; video: video/mp4, video/quicktime, video/mov."
          },
          "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"
      },
      "MediaUnderstandRequest": {
        "additionalProperties": false,
        "properties": {
          "inputs": {
            "description": "1-8 media items (image / audio / video), each as `asset_id`, public `url`, or `inline_data`. Mixed kinds are fine. Not stored beyond the request.",
            "items": {
              "$ref": "#/components/schemas/MediaRef"
            },
            "maxItems": 8,
            "minItems": 1,
            "title": "Inputs",
            "type": "array"
          },
          "prompt": {
            "description": "What to extract or label. Describe the task and, if helpful, the meaning of each schema field; the model sees the media in `inputs` in the given order.",
            "maxLength": 5000,
            "minLength": 1,
            "title": "Prompt",
            "type": "string"
          },
          "schema": {
            "additionalProperties": true,
            "description": "JSON Schema (draft 2020-12 subset) the output must conform to. Top level must be an object. Keep it flat and explicit — enums for closed label sets, `description` on each field.",
            "title": "Schema",
            "type": "object"
          }
        },
        "required": [
          "prompt",
          "inputs",
          "schema"
        ],
        "title": "MediaUnderstandRequest",
        "type": "object"
      },
      "MediaUnderstandResponse": {
        "properties": {
          "cost_credit": {
            "description": "Credits charged for this call (usage priced at upstream rates, rounded up to a whole credit, minimum 1).",
            "title": "Cost Credit",
            "type": "integer"
          },
          "output": {
            "additionalProperties": true,
            "description": "The structured result, conforming to the request `schema`.",
            "title": "Output",
            "type": "object"
          },
          "usage": {
            "$ref": "#/components/schemas/MediaUnderstandUsage",
            "description": "Upstream token usage this call was billed on."
          }
        },
        "required": [
          "output",
          "usage",
          "cost_credit"
        ],
        "title": "MediaUnderstandResponse",
        "type": "object"
      },
      "MediaUnderstandUsage": {
        "properties": {
          "input_tokens": {
            "default": 0,
            "description": "Tokens consumed by the prompt and media inputs.",
            "title": "Input Tokens",
            "type": "integer"
          },
          "output_tokens": {
            "default": 0,
            "description": "Tokens generated (including the model's reasoning).",
            "title": "Output Tokens",
            "type": "integer"
          }
        },
        "title": "MediaUnderstandUsage",
        "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_character_v4`. Retired `vs_talk_*` ids are still accepted and transparently mapped to `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": [
                "720p",
                "1080p",
                "2k"
              ],
              "type": "string"
            },
            "title": "Resolutions",
            "type": "array"
          }
        },
        "required": [
          "model_id",
          "description",
          "max_duration_seconds"
        ],
        "title": "ModelDto",
        "type": "object"
      },
      "PromptCapability": {
        "additionalProperties": false,
        "properties": {
          "max_length": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Maximum prompt characters; null when unspecified.",
            "title": "Max Length"
          },
          "supports_ref_syntax": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Present when in-prompt reference syntax is supported.",
            "title": "Supports Ref Syntax"
          }
        },
        "required": [
          "max_length"
        ],
        "title": "PromptCapability",
        "type": "object"
      },
      "ReferenceDurationLimits": {
        "additionalProperties": false,
        "properties": {
          "audio": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Maximum total audio-reference duration in seconds.",
            "title": "Audio"
          },
          "video": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Maximum total video-reference duration in seconds.",
            "title": "Video"
          }
        },
        "title": "ReferenceDurationLimits",
        "type": "object"
      },
      "ReferenceKindLimits": {
        "additionalProperties": false,
        "properties": {
          "audio": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Maximum number of audio references when specified.",
            "title": "Audio"
          },
          "image": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Maximum number of image references when specified.",
            "title": "Image"
          },
          "video": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Maximum number of video references when specified.",
            "title": "Video"
          }
        },
        "title": "ReferenceKindLimits",
        "type": "object"
      },
      "StringChoices": {
        "additionalProperties": false,
        "properties": {
          "default": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Value used when the request omits this parameter.",
            "title": "Default"
          },
          "values": {
            "description": "Currently accepted values for this model.",
            "items": {
              "type": "string"
            },
            "title": "Values",
            "type": "array"
          }
        },
        "required": [
          "values",
          "default"
        ],
        "title": "StringChoices",
        "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"
      },
      "TranscribeRequest": {
        "additionalProperties": false,
        "properties": {
          "audio": {
            "$ref": "#/components/schemas/MediaRef",
            "description": "Audio to transcribe: a WAV or MP3 up to 15MB (asset_id / url / inline_data). This synchronous endpoint suits short clips; very long audio may time out."
          },
          "diarize": {
            "default": false,
            "description": "Set true to detect speaker turns; each word then carries a `speaker` label.",
            "title": "Diarize",
            "type": "boolean"
          },
          "srt": {
            "default": false,
            "description": "Set true to also return an SRT subtitle rendering of the transcript.",
            "title": "Srt",
            "type": "boolean"
          }
        },
        "required": [
          "audio"
        ],
        "title": "TranscribeRequest",
        "type": "object"
      },
      "TranscribeResponse": {
        "properties": {
          "cost_credit": {
            "default": 0,
            "description": "Credits charged for this request.",
            "title": "Cost Credit",
            "type": "integer"
          },
          "duration_sec": {
            "default": 0,
            "description": "Duration of the input audio in seconds.",
            "title": "Duration Sec",
            "type": "number"
          },
          "language": {
            "default": "",
            "description": "Detected language code of the audio, e.g. `en`; may be empty.",
            "title": "Language",
            "type": "string"
          },
          "srt": {
            "default": "",
            "description": "SRT subtitle text; empty unless `srt: true` was requested.",
            "title": "Srt",
            "type": "string"
          },
          "text": {
            "description": "Full transcript text.",
            "title": "Text",
            "type": "string"
          },
          "words": {
            "description": "Word-level timestamps.",
            "items": {
              "$ref": "#/components/schemas/WordDto"
            },
            "title": "Words",
            "type": "array"
          }
        },
        "required": [
          "text"
        ],
        "title": "TranscribeResponse",
        "type": "object"
      },
      "UpdateAvatarFramingRequest": {
        "properties": {
          "aspect_ratio": {
            "description": "Aspect ratio whose framing to change.",
            "enum": [
              "9:16",
              "16:9",
              "1:1"
            ],
            "title": "Aspect Ratio",
            "type": "string"
          },
          "avatar_id": {
            "description": "Id of one of your own avatars (listed by GET /api/v1/avatars). Public avatars cannot be reframed through the API.",
            "title": "Avatar Id",
            "type": "string"
          },
          "offset_x": {
            "description": "Horizontal position of the framed area within the room it can move, from -1 to 1: `-1` touches the left edge, `0` is centered, `1` touches the right edge. It has no effect when the framed area already spans the full width.",
            "maximum": 1,
            "minimum": -1,
            "title": "Offset X",
            "type": "number"
          },
          "offset_y": {
            "description": "Vertical position of the framed area within the room it can move, from -1 to 1: `-1` touches the top edge, `0` is centered, `1` touches the bottom edge. It has no effect when the framed area already spans the full height.",
            "maximum": 1,
            "minimum": -1,
            "title": "Offset Y",
            "type": "number"
          },
          "zoom": {
            "description": "Zoom level, at least 1. `1` is the largest area of this aspect ratio that fits in the avatar's source image (the widest framing, e.g. full body); `2` halves the framed width and height, making the person appear twice as large.",
            "minimum": 1,
            "title": "Zoom",
            "type": "number"
          }
        },
        "required": [
          "avatar_id",
          "aspect_ratio",
          "zoom",
          "offset_x",
          "offset_y"
        ],
        "title": "UpdateAvatarFramingRequest",
        "type": "object"
      },
      "UpdateAvatarFramingResponse": {
        "properties": {
          "aspect_ratio": {
            "description": "Aspect ratio this framing applies to.",
            "enum": [
              "9:16",
              "16:9",
              "1:1"
            ],
            "title": "Aspect Ratio",
            "type": "string"
          },
          "avatar_id": {
            "description": "Id of the avatar whose framing was changed.",
            "title": "Avatar Id",
            "type": "string"
          },
          "image_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "URL of the reference image videos in this aspect ratio currently use.",
            "title": "Image Url"
          },
          "offset_x": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Horizontal position of the framed area within the room it can move, from -1 to 1: `-1` touches the left edge, `0` is centered, `1` touches the right edge. It has no effect when the framed area already spans the full width. null when `zoom` is null.",
            "title": "Offset X"
          },
          "offset_y": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Vertical position of the framed area within the room it can move, from -1 to 1: `-1` touches the top edge, `0` is centered, `1` touches the bottom edge. It has no effect when the framed area already spans the full height. null when `zoom` is null.",
            "title": "Offset Y"
          },
          "zoom": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Zoom level, at least 1. `1` is the largest area of this aspect ratio that fits in the avatar's source image (the widest framing, e.g. full body); `2` halves the framed width and height, making the person appear twice as large. null for avatars created before framing was supported.",
            "title": "Zoom"
          }
        },
        "required": [
          "aspect_ratio",
          "avatar_id"
        ],
        "title": "UpdateAvatarFramingResponse",
        "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"
      },
      "VideoReferences": {
        "additionalProperties": false,
        "properties": {
          "accept": {
            "description": "Accepted media kinds: image, video, or audio.",
            "items": {
              "type": "string"
            },
            "title": "Accept",
            "type": "array"
          },
          "audio": {
            "$ref": "#/components/schemas/MediaConstraints",
            "description": "Audio-reference constraints; use only if audio is accepted."
          },
          "image": {
            "$ref": "#/components/schemas/MediaConstraints",
            "description": "Image-reference constraints; use only if image is accepted."
          },
          "max": {
            "description": "Maximum references across all media kinds; zero means unsupported.",
            "title": "Max",
            "type": "integer"
          },
          "max_per_kind": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReferenceKindLimits"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional per-kind count limits, in addition to max."
          },
          "total_duration_sec_max": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReferenceDurationLimits"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional aggregate duration limits, by media kind."
          },
          "video": {
            "$ref": "#/components/schemas/MediaConstraints",
            "description": "Video-reference constraints; use only if video is accepted."
          }
        },
        "required": [
          "max",
          "accept",
          "image",
          "video",
          "audio"
        ],
        "title": "VideoReferences",
        "type": "object"
      },
      "VoiceDto": {
        "properties": {
          "accent": {
            "default": "",
            "description": "Accent, e.g. `american` / `british` / `mandarin`; may be empty.",
            "title": "Accent",
            "type": "string"
          },
          "age": {
            "default": "",
            "description": "Perceived age band, e.g. `young` / `middle-aged` / `old`; may be empty.",
            "title": "Age",
            "type": "string"
          },
          "gender": {
            "default": "",
            "description": "Voice gender, e.g. `male` / `female`; may be empty.",
            "title": "Gender",
            "type": "string"
          },
          "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": "Human-readable primary language, e.g. `english`. Use `locale` for the machine-readable tag.",
            "title": "Language",
            "type": "string"
          },
          "locale": {
            "default": "",
            "description": "BCP 47 locale of this voice, e.g. `en-US` / `en-GB` / `zh-TW` / `zh-HK`; a bare language code when no region is known; empty for prompt-driven voices (gemini). Filter with `locale`, and pass the same value as `locale` to POST /api/v1/tts to pin pronunciation.",
            "title": "Locale",
            "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. Filter with `provider`. 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 to help pick a voice; superseded by the structured fields below but kept for compatibility. May be empty.",
            "title": "Tags"
          },
          "use_cases": {
            "description": "Suggested use cases, e.g. `narration` / `conversational`; may be empty.",
            "items": {
              "type": "string"
            },
            "title": "Use Cases",
            "type": "array"
          },
          "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"
      },
      "WordDto": {
        "properties": {
          "end_sec": {
            "description": "Word end time in seconds.",
            "title": "End Sec",
            "type": "number"
          },
          "speaker": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Speaker label, present only when `diarize` was requested.",
            "title": "Speaker"
          },
          "start_sec": {
            "description": "Word start time in seconds.",
            "title": "Start Sec",
            "type": "number"
          },
          "text": {
            "description": "The word as written.",
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "text",
          "start_sec",
          "end_sec"
        ],
        "title": "WordDto",
        "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.13",
    "description": "Generate talking-avatar videos, clone voices, synthesize speech, transcribe audio, extract structured information from media, generate AI images and video, and manage reusable assets through one authenticated REST API.",
    "x-last-reviewed": "2026-09-24",
    "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 any account with an active paid subscription; 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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "deleted": true
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_DeleteResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nresult = client.delete_ai_video(\"video_123456\")\nprint(result)"
          },
          {
            "lang": "REST",
            "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 any account with an active paid subscription; 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": {
                "examples": {
                  "batch": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Batch query using video_ids",
                    "value": {
                      "data": {
                        "videos": [
                          {
                            "aspect_ratio": "16:9",
                            "cost_credit": 16,
                            "cover_url": "https://example.com/cover.jpg",
                            "created_at": 1788480000,
                            "duration_sec": 8,
                            "error": null,
                            "model_id": "wan-3.0",
                            "resolution": "720p",
                            "status": "created",
                            "video_id": "example_ai_video_id",
                            "video_url": "https://example.com/video.mp4"
                          },
                          {
                            "aspect_ratio": "16:9",
                            "cost_credit": 0,
                            "cover_url": null,
                            "created_at": 1788480000,
                            "duration_sec": 0,
                            "error": {
                              "code": 37100,
                              "message": "The content could not be processed."
                            },
                            "model_id": "wan-3.0",
                            "resolution": "720p",
                            "status": "failed",
                            "video_id": "example_failed_video_id",
                            "video_url": null
                          }
                        ]
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  },
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "aspect_ratio": "16:9",
                        "cost_credit": 16,
                        "cover_url": "https://example.com/cover.jpg",
                        "created_at": 1788480000,
                        "duration_sec": 8,
                        "error": null,
                        "model_id": "wan-3.0",
                        "resolution": "720p",
                        "status": "created",
                        "video_id": "example_ai_video_id",
                        "video_url": "https://example.com/video.mp4"
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_Union_GetAiVideoResponse__GetAiVideosBatchResponse__"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nvideo = client.get_ai_video(\"video_123456\")\nprint(video)"
          },
          {
            "lang": "REST",
            "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 any account with an active paid subscription. 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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "cost_credit": 16,
                        "status": "queued",
                        "video_id": "example_ai_video_id"
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_CreateAiVideoResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nvideo = client.create_ai_video({\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})\nprint(video)"
          },
          {
            "lang": "REST",
            "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 any account with an active paid subscription; 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. `480p` / `720p` / `1080p` / `4k`. 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. `480p` / `720p` / `1080p` / `4k`. Allowed values vary by model; omit to use the model default.",
              "title": "Resolution"
            },
            "example": "720p"
          },
          {
            "description": "Whether a native audio track is requested. Accepted for parity with the create request; audio never changes the price.",
            "in": "query",
            "name": "generate_audio",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Whether a native audio track is requested. Accepted for parity with the create request; audio never changes the price.",
              "title": "Generate Audio"
            },
            "example": true
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "credit": 16
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_AiVideoCostResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\ncost = client.ai_video_cost(\n    model_id=\"seedance-2.0\",\n    duration_sec=8,\n    resolution=\"720p\",\n    generate_audio=True,\n)\nprint(cost)"
          },
          {
            "lang": "REST",
            "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 any account with an active paid subscription; 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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "models": [
                          {
                            "capabilities": [
                              "text_to_video",
                              "image_to_video"
                            ],
                            "description": "Seedance 2.5 latest: single clips up to 30s, multimodal references; 480p / 720p / 1080p, defaults to 720p.",
                            "model_id": "seedance-2.5",
                            "params": {
                              "aspect_ratio": {
                                "default": "9:16",
                                "values": [
                                  "16:9",
                                  "9:16",
                                  "4:3",
                                  "3:4",
                                  "1:1"
                                ]
                              },
                              "duration_sec": {
                                "default": 15,
                                "values": [
                                  4,
                                  5,
                                  6,
                                  7,
                                  8,
                                  9,
                                  10,
                                  11,
                                  12,
                                  13,
                                  14,
                                  15,
                                  16,
                                  17,
                                  18,
                                  19,
                                  20,
                                  21,
                                  22,
                                  23,
                                  24,
                                  25,
                                  26,
                                  27,
                                  28,
                                  29,
                                  30
                                ]
                              },
                              "first_frame": {
                                "aspect_ratio_range": [
                                  0.4,
                                  2.5
                                ],
                                "dimension_px": [
                                  300,
                                  6000
                                ],
                                "formats": [
                                  "jpg",
                                  "jpeg",
                                  "png",
                                  "webp",
                                  "bmp",
                                  "tiff",
                                  "gif"
                                ],
                                "max_mb": 30
                              },
                              "generate_audio": {
                                "default": true
                              },
                              "prompt": {
                                "max_length": 5000
                              },
                              "refs": {
                                "accept": [
                                  "image",
                                  "video",
                                  "audio"
                                ],
                                "audio": {
                                  "duration_sec_range": [
                                    2,
                                    15
                                  ],
                                  "formats": [
                                    "wav",
                                    "mp3"
                                  ],
                                  "max_mb": 15
                                },
                                "image": {
                                  "aspect_ratio_range": [
                                    0.4,
                                    2.5
                                  ],
                                  "dimension_px": [
                                    300,
                                    6000
                                  ],
                                  "formats": [
                                    "jpg",
                                    "jpeg",
                                    "png",
                                    "webp",
                                    "bmp",
                                    "tiff",
                                    "gif"
                                  ],
                                  "max_mb": 30
                                },
                                "max": 9,
                                "video": {
                                  "aspect_ratio_range": [
                                    0.4,
                                    2.5
                                  ],
                                  "dimension_px": [
                                    300,
                                    6000
                                  ],
                                  "duration_sec_range": [
                                    2,
                                    15
                                  ],
                                  "formats": [
                                    "mp4",
                                    "mov"
                                  ],
                                  "fps_range": [
                                    24,
                                    60
                                  ],
                                  "max_mb": 100
                                }
                              },
                              "resolution": {
                                "default": "720p",
                                "values": [
                                  "480p",
                                  "720p",
                                  "1080p"
                                ]
                              }
                            }
                          },
                          {
                            "capabilities": [
                              "text_to_video",
                              "image_to_video"
                            ],
                            "description": "Seedance 2.0 flagship: multimodal references (image/video/audio); 480p / 720p / 1080p, defaults to 720p.",
                            "model_id": "seedance-2.0",
                            "params": {
                              "aspect_ratio": {
                                "default": "9:16",
                                "values": [
                                  "16:9",
                                  "9:16",
                                  "4:3",
                                  "3:4",
                                  "1:1"
                                ]
                              },
                              "duration_sec": {
                                "default": 5,
                                "values": [
                                  4,
                                  5,
                                  6,
                                  7,
                                  8,
                                  9,
                                  10,
                                  11,
                                  12,
                                  13,
                                  14,
                                  15
                                ]
                              },
                              "first_frame": {
                                "aspect_ratio_range": [
                                  0.4,
                                  2.5
                                ],
                                "dimension_px": [
                                  300,
                                  6000
                                ],
                                "formats": [
                                  "jpg",
                                  "jpeg",
                                  "png",
                                  "webp",
                                  "bmp",
                                  "tiff",
                                  "gif"
                                ],
                                "max_mb": 30
                              },
                              "generate_audio": {
                                "default": true
                              },
                              "prompt": {
                                "max_length": 5000
                              },
                              "refs": {
                                "accept": [
                                  "image",
                                  "video",
                                  "audio"
                                ],
                                "audio": {
                                  "duration_sec_range": [
                                    2,
                                    15
                                  ],
                                  "formats": [
                                    "wav",
                                    "mp3"
                                  ],
                                  "max_mb": 15
                                },
                                "image": {
                                  "aspect_ratio_range": [
                                    0.4,
                                    2.5
                                  ],
                                  "dimension_px": [
                                    300,
                                    6000
                                  ],
                                  "formats": [
                                    "jpg",
                                    "jpeg",
                                    "png",
                                    "webp",
                                    "bmp",
                                    "tiff",
                                    "gif"
                                  ],
                                  "max_mb": 30
                                },
                                "max": 9,
                                "video": {
                                  "aspect_ratio_range": [
                                    0.4,
                                    2.5
                                  ],
                                  "dimension_px": [
                                    300,
                                    6000
                                  ],
                                  "duration_sec_range": [
                                    2,
                                    15
                                  ],
                                  "formats": [
                                    "mp4",
                                    "mov"
                                  ],
                                  "fps_range": [
                                    24,
                                    60
                                  ],
                                  "max_mb": 100
                                }
                              },
                              "resolution": {
                                "default": "720p",
                                "values": [
                                  "480p",
                                  "720p",
                                  "1080p"
                                ]
                              }
                            }
                          },
                          {
                            "capabilities": [
                              "text_to_video",
                              "image_to_video"
                            ],
                            "description": "Seedance 2.0 Fast: lower latency and cost; 480p / 720p, defaults to 720p.",
                            "model_id": "seedance-2.0-fast",
                            "params": {
                              "aspect_ratio": {
                                "default": "9:16",
                                "values": [
                                  "16:9",
                                  "9:16",
                                  "4:3",
                                  "3:4",
                                  "1:1"
                                ]
                              },
                              "duration_sec": {
                                "default": 5,
                                "values": [
                                  4,
                                  5,
                                  6,
                                  7,
                                  8,
                                  9,
                                  10,
                                  11,
                                  12,
                                  13,
                                  14,
                                  15
                                ]
                              },
                              "first_frame": {
                                "aspect_ratio_range": [
                                  0.4,
                                  2.5
                                ],
                                "dimension_px": [
                                  300,
                                  6000
                                ],
                                "formats": [
                                  "jpg",
                                  "jpeg",
                                  "png",
                                  "webp",
                                  "bmp",
                                  "tiff",
                                  "gif"
                                ],
                                "max_mb": 30
                              },
                              "generate_audio": {
                                "default": true
                              },
                              "prompt": {
                                "max_length": 5000
                              },
                              "refs": {
                                "accept": [
                                  "image",
                                  "video",
                                  "audio"
                                ],
                                "audio": {
                                  "duration_sec_range": [
                                    2,
                                    15
                                  ],
                                  "formats": [
                                    "wav",
                                    "mp3"
                                  ],
                                  "max_mb": 15
                                },
                                "image": {
                                  "aspect_ratio_range": [
                                    0.4,
                                    2.5
                                  ],
                                  "dimension_px": [
                                    300,
                                    6000
                                  ],
                                  "formats": [
                                    "jpg",
                                    "jpeg",
                                    "png",
                                    "webp",
                                    "bmp",
                                    "tiff",
                                    "gif"
                                  ],
                                  "max_mb": 30
                                },
                                "max": 9,
                                "video": {
                                  "aspect_ratio_range": [
                                    0.4,
                                    2.5
                                  ],
                                  "dimension_px": [
                                    300,
                                    6000
                                  ],
                                  "duration_sec_range": [
                                    2,
                                    15
                                  ],
                                  "formats": [
                                    "mp4",
                                    "mov"
                                  ],
                                  "fps_range": [
                                    24,
                                    60
                                  ],
                                  "max_mb": 100
                                }
                              },
                              "resolution": {
                                "default": "720p",
                                "values": [
                                  "480p",
                                  "720p"
                                ]
                              }
                            }
                          },
                          {
                            "capabilities": [
                              "text_to_video",
                              "image_to_video"
                            ],
                            "description": "Seedance 2.0 Mini: lightweight and economical; 480p / 720p, defaults to 720p.",
                            "model_id": "seedance-2.0-mini",
                            "params": {
                              "aspect_ratio": {
                                "default": "16:9",
                                "values": [
                                  "16:9",
                                  "9:16",
                                  "4:3",
                                  "3:4",
                                  "1:1"
                                ]
                              },
                              "duration_sec": {
                                "default": 5,
                                "values": [
                                  4,
                                  5,
                                  6,
                                  7,
                                  8,
                                  9,
                                  10,
                                  11,
                                  12,
                                  13,
                                  14,
                                  15
                                ]
                              },
                              "first_frame": {
                                "aspect_ratio_range": [
                                  0.4,
                                  2.5
                                ],
                                "dimension_px": [
                                  300,
                                  6000
                                ],
                                "formats": [
                                  "jpg",
                                  "jpeg",
                                  "png",
                                  "webp",
                                  "bmp",
                                  "tiff",
                                  "gif"
                                ],
                                "max_mb": 30
                              },
                              "generate_audio": {
                                "default": true
                              },
                              "prompt": {
                                "max_length": 5000
                              },
                              "refs": {
                                "accept": [
                                  "image",
                                  "video",
                                  "audio"
                                ],
                                "audio": {
                                  "duration_sec_range": [
                                    2,
                                    15
                                  ],
                                  "formats": [
                                    "wav",
                                    "mp3"
                                  ],
                                  "max_mb": 15
                                },
                                "image": {
                                  "aspect_ratio_range": [
                                    0.4,
                                    2.5
                                  ],
                                  "dimension_px": [
                                    300,
                                    6000
                                  ],
                                  "formats": [
                                    "jpg",
                                    "jpeg",
                                    "png",
                                    "webp",
                                    "bmp",
                                    "tiff",
                                    "gif"
                                  ],
                                  "max_mb": 30
                                },
                                "max": 9,
                                "video": {
                                  "aspect_ratio_range": [
                                    0.4,
                                    2.5
                                  ],
                                  "dimension_px": [
                                    300,
                                    6000
                                  ],
                                  "duration_sec_range": [
                                    2,
                                    15
                                  ],
                                  "formats": [
                                    "mp4",
                                    "mov"
                                  ],
                                  "fps_range": [
                                    24,
                                    60
                                  ],
                                  "max_mb": 100
                                }
                              },
                              "resolution": {
                                "default": "720p",
                                "values": [
                                  "480p",
                                  "720p"
                                ]
                              }
                            }
                          },
                          {
                            "capabilities": [
                              "text_to_video",
                              "image_to_video"
                            ],
                            "description": "Kling 3.0: text-to-video and image-to-video (first/last frame) up to 4K; 5s or 10s clips; native audio on by default.",
                            "model_id": "kling-3.0",
                            "params": {
                              "aspect_ratio": {
                                "default": "16:9",
                                "values": [
                                  "16:9",
                                  "9:16",
                                  "1:1"
                                ]
                              },
                              "duration_sec": {
                                "default": 5,
                                "values": [
                                  5,
                                  10
                                ]
                              },
                              "first_frame": {
                                "aspect_ratio_range": [
                                  0.4,
                                  2.5
                                ],
                                "dimension_px": [
                                  300,
                                  null
                                ],
                                "max_mb": 10
                              },
                              "generate_audio": {
                                "default": true
                              },
                              "prompt": {
                                "max_length": 2500
                              },
                              "refs": {
                                "accept": [],
                                "audio": {
                                  "max_mb": 15
                                },
                                "image": {
                                  "max_mb": 30
                                },
                                "max": 0,
                                "video": {
                                  "max_mb": 100
                                }
                              },
                              "resolution": {
                                "default": "720p",
                                "values": [
                                  "720p",
                                  "1080p",
                                  "4k"
                                ]
                              }
                            }
                          },
                          {
                            "capabilities": [
                              "text_to_video"
                            ],
                            "description": "Kling 3.0 Omni: text-to-video guided by up to 7 image/video references with in-prompt reference syntax; 720p / 1080p; 3 / 5 / 7 / 10 / 15 s clips; native audio on by default.",
                            "model_id": "kling-3.0-omni",
                            "params": {
                              "aspect_ratio": {
                                "default": "16:9",
                                "values": [
                                  "16:9",
                                  "9:16",
                                  "1:1"
                                ]
                              },
                              "duration_sec": {
                                "default": 5,
                                "values": [
                                  3,
                                  5,
                                  7,
                                  10,
                                  15
                                ]
                              },
                              "first_frame": null,
                              "generate_audio": {
                                "default": true
                              },
                              "prompt": {
                                "max_length": 2500,
                                "supports_ref_syntax": true
                              },
                              "refs": {
                                "accept": [
                                  "image",
                                  "video"
                                ],
                                "audio": {
                                  "max_mb": 15
                                },
                                "image": {
                                  "aspect_ratio_range": [
                                    0.4,
                                    2.5
                                  ],
                                  "dimension_px": [
                                    300,
                                    null
                                  ],
                                  "max_mb": 10
                                },
                                "max": 7,
                                "video": {
                                  "aspect_ratio_range": [
                                    0.4,
                                    2.5
                                  ],
                                  "dimension_px": [
                                    720,
                                    2160
                                  ],
                                  "duration_sec_range": [
                                    3,
                                    15
                                  ],
                                  "max_mb": 100
                                }
                              },
                              "resolution": {
                                "default": "1080p",
                                "values": [
                                  "720p",
                                  "1080p"
                                ]
                              }
                            }
                          },
                          {
                            "capabilities": [
                              "text_to_video",
                              "image_to_video"
                            ],
                            "description": "Wan 3.0: all-in-one text-to-video and image-to-video (first/last frame); image, video and audio references with in-prompt reference syntax; 480p / 720p / 1080p; any length from 2 to 30s; native audio on by default. Defaults to 720p.",
                            "model_id": "wan-3.0",
                            "params": {
                              "aspect_ratio": {
                                "default": "adaptive",
                                "values": [
                                  "adaptive",
                                  "16:9",
                                  "4:3",
                                  "1:1",
                                  "3:4",
                                  "9:16"
                                ]
                              },
                              "duration_sec": {
                                "default": 5,
                                "values": [
                                  2,
                                  3,
                                  4,
                                  5,
                                  6,
                                  7,
                                  8,
                                  9,
                                  10,
                                  11,
                                  12,
                                  13,
                                  14,
                                  15,
                                  16,
                                  17,
                                  18,
                                  19,
                                  20,
                                  21,
                                  22,
                                  23,
                                  24,
                                  25,
                                  26,
                                  27,
                                  28,
                                  29,
                                  30
                                ]
                              },
                              "first_frame": {
                                "aspect_ratio_range": [
                                  0.125,
                                  8
                                ],
                                "dimension_px": [
                                  240,
                                  8000
                                ],
                                "formats": [
                                  "jpg",
                                  "jpeg",
                                  "png",
                                  "bmp",
                                  "webp"
                                ],
                                "max_mb": 20
                              },
                              "generate_audio": {
                                "default": true
                              },
                              "prompt": {
                                "max_length": 20000,
                                "supports_ref_syntax": true
                              },
                              "refs": {
                                "accept": [
                                  "image",
                                  "video",
                                  "audio"
                                ],
                                "audio": {
                                  "duration_sec_range": [
                                    1,
                                    15
                                  ],
                                  "formats": [
                                    "wav",
                                    "mp3"
                                  ],
                                  "max_mb": 15
                                },
                                "image": {
                                  "aspect_ratio_range": [
                                    0.125,
                                    8
                                  ],
                                  "dimension_px": [
                                    240,
                                    8000
                                  ],
                                  "formats": [
                                    "jpg",
                                    "jpeg",
                                    "png",
                                    "bmp",
                                    "webp"
                                  ],
                                  "max_mb": 20
                                },
                                "max": 20,
                                "max_per_kind": {
                                  "audio": 5,
                                  "image": 10,
                                  "video": 5
                                },
                                "total_duration_sec_max": {
                                  "audio": 15,
                                  "video": 15
                                },
                                "video": {
                                  "aspect_ratio_range": [
                                    0.125,
                                    8
                                  ],
                                  "dimension_px": [
                                    240,
                                    4096
                                  ],
                                  "duration_sec_range": [
                                    1,
                                    15
                                  ],
                                  "formats": [
                                    "mp4",
                                    "mov"
                                  ],
                                  "fps_range": [
                                    16,
                                    null
                                  ],
                                  "max_mb": 100
                                }
                              },
                              "resolution": {
                                "default": "720p",
                                "values": [
                                  "480p",
                                  "720p",
                                  "1080p"
                                ]
                              }
                            }
                          },
                          {
                            "capabilities": [
                              "text_to_video",
                              "image_to_video"
                            ],
                            "description": "Wan 3.0 Prime: same capabilities as wan-3.0 at higher quality and 1.5x the price; 480p / 720p / 1080p, defaults to 720p.",
                            "model_id": "wan-3.0-prime",
                            "params": {
                              "aspect_ratio": {
                                "default": "adaptive",
                                "values": [
                                  "adaptive",
                                  "16:9",
                                  "4:3",
                                  "1:1",
                                  "3:4",
                                  "9:16"
                                ]
                              },
                              "duration_sec": {
                                "default": 5,
                                "values": [
                                  2,
                                  3,
                                  4,
                                  5,
                                  6,
                                  7,
                                  8,
                                  9,
                                  10,
                                  11,
                                  12,
                                  13,
                                  14,
                                  15,
                                  16,
                                  17,
                                  18,
                                  19,
                                  20,
                                  21,
                                  22,
                                  23,
                                  24,
                                  25,
                                  26,
                                  27,
                                  28,
                                  29,
                                  30
                                ]
                              },
                              "first_frame": {
                                "aspect_ratio_range": [
                                  0.125,
                                  8
                                ],
                                "dimension_px": [
                                  240,
                                  8000
                                ],
                                "formats": [
                                  "jpg",
                                  "jpeg",
                                  "png",
                                  "bmp",
                                  "webp"
                                ],
                                "max_mb": 20
                              },
                              "generate_audio": {
                                "default": true
                              },
                              "prompt": {
                                "max_length": 20000,
                                "supports_ref_syntax": true
                              },
                              "refs": {
                                "accept": [
                                  "image",
                                  "video",
                                  "audio"
                                ],
                                "audio": {
                                  "duration_sec_range": [
                                    1,
                                    15
                                  ],
                                  "formats": [
                                    "wav",
                                    "mp3"
                                  ],
                                  "max_mb": 15
                                },
                                "image": {
                                  "aspect_ratio_range": [
                                    0.125,
                                    8
                                  ],
                                  "dimension_px": [
                                    240,
                                    8000
                                  ],
                                  "formats": [
                                    "jpg",
                                    "jpeg",
                                    "png",
                                    "bmp",
                                    "webp"
                                  ],
                                  "max_mb": 20
                                },
                                "max": 20,
                                "max_per_kind": {
                                  "audio": 5,
                                  "image": 10,
                                  "video": 5
                                },
                                "total_duration_sec_max": {
                                  "audio": 15,
                                  "video": 15
                                },
                                "video": {
                                  "aspect_ratio_range": [
                                    0.125,
                                    8
                                  ],
                                  "dimension_px": [
                                    240,
                                    4096
                                  ],
                                  "duration_sec_range": [
                                    1,
                                    15
                                  ],
                                  "formats": [
                                    "mp4",
                                    "mov"
                                  ],
                                  "fps_range": [
                                    16,
                                    null
                                  ],
                                  "max_mb": 100
                                }
                              },
                              "resolution": {
                                "default": "720p",
                                "values": [
                                  "480p",
                                  "720p",
                                  "1080p"
                                ]
                              }
                            }
                          }
                        ]
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_GetAiVideoModelsResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nmodels = client.list_ai_video_models()\nprint(models)"
          },
          {
            "lang": "REST",
            "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\nUse `status=queued,creating` before submitting to check how much per-key concurrency you have\nleft — submissions beyond the limit are rejected with 429, not queued, and the 429 body carries\n`details.limit` / `details.in_flight`.\n\nBeta: available to any account with an active paid subscription; 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
          },
          {
            "description": "Filter by status; comma-separated, any of `queued`, `creating`, `created`, `failed`. Omit to return every status. `status=queued,creating` returns exactly the tasks that occupy your per-key concurrency quota, so `len(videos)` is how many slots you are using.",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by status; comma-separated, any of `queued`, `creating`, `created`, `failed`. Omit to return every status. `status=queued,creating` returns exactly the tasks that occupy your per-key concurrency quota, so `len(videos)` is how many slots you are using.",
              "title": "Status"
            },
            "example": "success"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "next_cursor": 0,
                        "videos": [
                          {
                            "aspect_ratio": "16:9",
                            "cost_credit": 16,
                            "cover_url": "https://example.com/cover.jpg",
                            "created_at": 1788480000,
                            "duration_sec": 8,
                            "error": null,
                            "model_id": "wan-3.0",
                            "resolution": "720p",
                            "status": "created",
                            "video_id": "example_ai_video_id",
                            "video_url": "https://example.com/video.mp4"
                          },
                          {
                            "aspect_ratio": "16:9",
                            "cost_credit": 0,
                            "cover_url": null,
                            "created_at": 1788480000,
                            "duration_sec": 0,
                            "error": {
                              "code": 37100,
                              "message": "The content could not be processed."
                            },
                            "model_id": "wan-3.0",
                            "resolution": "720p",
                            "status": "failed",
                            "video_id": "example_failed_video_id",
                            "video_url": null
                          }
                        ]
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_GetAiVideosResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nvideos = client.list_ai_videos(limit=20, status=\"queued,creating\")\nprint(videos)"
          },
          {
            "lang": "REST",
            "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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "deleted": true
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_DeleteResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nresult = client.delete_asset(\"asset_123456\")\nprint(result)"
          },
          {
            "lang": "REST",
            "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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "asset_id": "example_asset_id",
                        "created_at": 1788480000,
                        "duration_sec": 0,
                        "height": 1024,
                        "kind": "image",
                        "mime": "image/png",
                        "width": 1024
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_CreateAssetResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nasset = client.upload_asset(url=\"https://example.com/media/reference.jpg\")\nprint(asset)"
          },
          {
            "lang": "REST",
            "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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "assets": [
                          {
                            "asset_id": "example_asset_id",
                            "created_at": 1788480000,
                            "duration_sec": 0,
                            "height": 1024,
                            "kind": "image",
                            "mime": "image/png",
                            "width": 1024
                          }
                        ],
                        "next_cursor": 0
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_GetAssetsResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nassets = client.list_assets(kind=\"image\", limit=20)\nprint(assets)"
          },
          {
            "lang": "REST",
            "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/audio/align": {
      "post": {
        "description": "Force-align known `text` against its spoken audio and get word-level timestamps — e.g. align a\nscript with the MP3 from POST /api/v1/tts to build accurate subtitles for any voice. Billing:\n1 credit per started 5 minutes of audio, charged only on success. Synchronous — audio up to 30\nminutes. Per-key concurrency is limited during beta; requests beyond the limit are rejected, not\nqueued.",
        "operationId": "align_audio_api_v1_audio_align_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/AlignRequest"
              },
              "example": {
                "audio": {
                  "asset_id": "asset_audio_123456"
                },
                "text": "Welcome to VisionStory."
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "cost_credit": 1,
                        "duration_sec": 1,
                        "words": [
                          {
                            "end_sec": 0.5,
                            "speaker": null,
                            "start_sec": 0,
                            "text": "Hello"
                          },
                          {
                            "end_sec": 1,
                            "speaker": null,
                            "start_sec": 0.5,
                            "text": "world"
                          }
                        ]
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_AlignResponse_"
                }
              }
            },
            "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": "Align text with audio",
        "tags": [
          "Audio"
        ],
        "x-agent-guidance": {
          "exampleIdsArePlaceholders": true,
          "credentialsFromEnvironment": "VISIONSTORY_API_KEY"
        },
        "x-codeSamples": [
          {
            "lang": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nalignment = client.align_audio(\n    text=\"Welcome to VisionStory.\",\n    asset_id=\"asset_audio_123456\",\n)\nprint(alignment)"
          },
          {
            "lang": "REST",
            "source": "import os\nimport requests\n\nresponse = requests.post(\n    \"https://openapi.visionstory.ai/api/v1/audio/align\",\n    headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n    json={\n      \"audio\": {\n        \"asset_id\": \"asset_audio_123456\"\n      },\n      \"text\": \"Welcome to VisionStory.\"\n    },\n)\nresponse.raise_for_status()\nprint(response.json())"
          },
          {
            "lang": "cURL",
            "source": "curl --request POST 'https://openapi.visionstory.ai/api/v1/audio/align' \\\n  --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"audio\": {\n    \"asset_id\": \"asset_audio_123456\"\n  },\n  \"text\": \"Welcome to VisionStory.\"\n}'"
          }
        ]
      }
    },
    "/api/v1/audio/transcribe": {
      "post": {
        "description": "Transcribe speech audio to text with word-level timestamps; optionally detect speaker turns\n(`diarize`) or render an SRT subtitle track (`srt`). Billing: 1 credit per started 5 minutes of\naudio, charged only on success. Synchronous — audio up to 30 minutes. Per-key concurrency is\nlimited during beta; requests beyond the limit are rejected, not queued.",
        "operationId": "transcribe_audio_api_v1_audio_transcribe_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/TranscribeRequest"
              },
              "example": {
                "audio": {
                  "url": "https://example.com/media/interview.mp3"
                },
                "diarize": true,
                "srt": true
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "cost_credit": 1,
                        "duration_sec": 1,
                        "language": "en",
                        "srt": "1\n00:00:00,000 --> 00:00:01,000\nHello world\n",
                        "text": "Hello world",
                        "words": [
                          {
                            "end_sec": 0.5,
                            "speaker": "speaker_0",
                            "start_sec": 0,
                            "text": "Hello"
                          },
                          {
                            "end_sec": 1,
                            "speaker": "speaker_0",
                            "start_sec": 0.5,
                            "text": "world"
                          }
                        ]
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_TranscribeResponse_"
                }
              }
            },
            "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": "Transcribe audio",
        "tags": [
          "Audio"
        ],
        "x-agent-guidance": {
          "exampleIdsArePlaceholders": true,
          "credentialsFromEnvironment": "VISIONSTORY_API_KEY"
        },
        "x-codeSamples": [
          {
            "lang": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\ntranscript = client.transcribe_audio(\n    audio_url=\"https://example.com/media/interview.mp3\",\n    diarize=True,\n    srt=True,\n)\nprint(transcript)"
          },
          {
            "lang": "REST",
            "source": "import os\nimport requests\n\nresponse = requests.post(\n    \"https://openapi.visionstory.ai/api/v1/audio/transcribe\",\n    headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n    json={\n      \"audio\": {\n        \"url\": \"https://example.com/media/interview.mp3\"\n      },\n      \"diarize\": True,\n      \"srt\": True\n    },\n)\nresponse.raise_for_status()\nprint(response.json())"
          },
          {
            "lang": "cURL",
            "source": "curl --request POST 'https://openapi.visionstory.ai/api/v1/audio/transcribe' \\\n  --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"audio\": {\n    \"url\": \"https://example.com/media/interview.mp3\"\n  },\n  \"diarize\": true,\n  \"srt\": true\n}'"
          }
        ]
      }
    },
    "/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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "deleted": true
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_DeleteResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nresult = client.delete_avatar(\"avatar_123456\")\nprint(result)"
          },
          {
            "lang": "REST",
            "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.\n\nThe avatar starts with automatic framing; the response includes it as `framing`. Change it with\nPOST /api/v1/avatar/framing.",
        "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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "aspect_ratios": [
                          "9:16",
                          "16:9",
                          "1:1"
                        ],
                        "avatar_id": "example_avatar_id",
                        "created_at": 1788480000,
                        "default_voice_id": "example_voice_id",
                        "framing": [
                          {
                            "aspect_ratio": "9:16",
                            "image_url": "https://example.com/avatar-9x16.png",
                            "offset_x": 0,
                            "offset_y": 0,
                            "zoom": 1
                          },
                          {
                            "aspect_ratio": "16:9",
                            "image_url": null,
                            "offset_x": 0,
                            "offset_y": -0.4312,
                            "zoom": 1
                          },
                          {
                            "aspect_ratio": "1:1",
                            "image_url": "https://example.com/avatar-1x1.png",
                            "offset_x": 0,
                            "offset_y": -0.6,
                            "zoom": 1.25
                          }
                        ],
                        "thumbnail_url": "https://example.com/avatar.jpg"
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_CreateAvatarResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\navatar = client.create_avatar(image_url=\"https://example.com/media/portrait.jpg\")\nprint(avatar)"
          },
          {
            "lang": "REST",
            "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/avatar/framing": {
      "post": {
        "description": "Change how one of your own avatars is framed for one aspect ratio, using `zoom` and `offset_x` / `offset_y`.\nRead the current values from GET /api/v1/avatars, adjust them, and send all three back. The new framing is\nchecked for a visible face, saved, and used by later videos in that aspect ratio (and by the web editor).\n\nPublic avatars cannot be reframed through the API. The request takes a few seconds because the reference\nimage is cropped and checked.",
        "operationId": "update_avatar_framing_api_v1_avatar_framing_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/UpdateAvatarFramingRequest"
              },
              "example": {
                "aspect_ratio": "9:16",
                "avatar_id": "avatar_123456",
                "offset_x": -1,
                "offset_y": -1,
                "zoom": 1
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "aspect_ratio": "9:16",
                        "avatar_id": "example_avatar_id",
                        "image_url": "https://example.com/avatar-9x16.png",
                        "offset_x": 0,
                        "offset_y": -1,
                        "zoom": 1.2
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_UpdateAvatarFramingResponse_"
                }
              }
            },
            "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": "Update avatar framing",
        "tags": [
          "Avatars"
        ],
        "x-codeSamples": [
          {
            "lang": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nframing = client.update_avatar_framing(\n    avatar_id=\"avatar_123456\",\n    aspect_ratio=\"9:16\",\n    zoom=1.2,\n    offset_x=0,\n    offset_y=-0.25,\n)\nprint(framing)"
          },
          {
            "lang": "REST",
            "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n# zoom=1 frames the widest area (e.g. full body); offset_y=-1 keeps it at the top of the image\npayload = {\n    \"avatar_id\": \"xxxx\",\n    \"aspect_ratio\": \"9:16\",\n    \"zoom\": 1,\n    \"offset_x\": 0,\n    \"offset_y\": -1\n}\nresponse = requests.post(\n    'https://openapi.visionstory.ai/api/v1/avatar/framing', json=payload, headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data']['image_url'])"
          },
          {
            "lang": "cURL",
            "source": "curl -X 'POST' \\\n      'https://openapi.visionstory.ai/api/v1/avatar/framing' \\\n      -H 'accept: application/json' \\\n      -H 'content-type: application/json' \\\n      -H 'X-API-Key: $VISIONSTORY_API_KEY' \\\n      --data '\n{\n    \"avatar_id\": \"xxxx\",\n    \"aspect_ratio\": \"9:16\",\n    \"zoom\": 1,\n    \"offset_x\": 0,\n    \"offset_y\": -1\n}\n'"
          }
        ],
        "x-agent-guidance": {
          "exampleIdsArePlaceholders": true,
          "credentialsFromEnvironment": "VISIONSTORY_API_KEY"
        }
      }
    },
    "/api/v1/avatars": {
      "get": {
        "description": "List either your own avatars or the public avatar library (`is_public=true`), newest first. Pass the previous\npage's `next_cursor` to paginate; `next_cursor=0` means no more pages.",
        "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"
          },
          {
            "description": "`false` lists your own avatars (with their framing); `true` lists the public avatar library instead.",
            "in": "query",
            "name": "is_public",
            "required": false,
            "schema": {
              "default": false,
              "description": "`false` lists your own avatars (with their framing); `true` lists the public avatar library instead.",
              "title": "Is Public",
              "type": "boolean"
            },
            "example": false
          },
          {
            "description": "Pagination cursor from the previous page's `next_cursor`. Omit or pass 0 for the first page.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "default": 0,
              "description": "Pagination cursor from the previous page's `next_cursor`. Omit or pass 0 for the first page.",
              "minimum": 0,
              "title": "Cursor",
              "type": "integer"
            },
            "example": 0
          },
          {
            "description": "Maximum avatars to return per page. Range 1–100; defaults to 20.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "description": "Maximum avatars 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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "avatars": [
                          {
                            "aspect_ratios": [
                              "9:16",
                              "16:9",
                              "1:1"
                            ],
                            "avatar_id": "example_avatar_id",
                            "created_at": 1788480000,
                            "default_voice_id": "example_voice_id",
                            "framing": [
                              {
                                "aspect_ratio": "9:16",
                                "image_url": "https://example.com/avatar-9x16.png",
                                "offset_x": 0,
                                "offset_y": 0,
                                "zoom": 1
                              },
                              {
                                "aspect_ratio": "16:9",
                                "image_url": null,
                                "offset_x": 0,
                                "offset_y": -0.4312,
                                "zoom": 1
                              },
                              {
                                "aspect_ratio": "1:1",
                                "image_url": "https://example.com/avatar-1x1.png",
                                "offset_x": 0,
                                "offset_y": -0.6,
                                "zoom": 1.25
                              }
                            ],
                            "thumbnail_url": "https://example.com/avatar.jpg"
                          }
                        ],
                        "next_cursor": 0
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_GetAvatarsResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\npage = client.list_avatars(\n    is_public=False,\n    limit=20,\n)\nprint(page)"
          },
          {
            "lang": "REST",
            "source": "import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n# is_public=true lists the public avatar library; omit it to list your own avatars\nparams = {\"is_public\": \"true\", \"limit\": 20}\nwhile True:\n    response = requests.get(\n        'https://openapi.visionstory.ai/api/v1/avatars', params=params, headers=headers, timeout=10\n    )\n    resp_data = response.json()['data']\n    for avatar in resp_data['avatars']:\n        print(avatar['avatar_id'])\n    if not resp_data['next_cursor']:\n        break\n    params['cursor'] = resp_data['next_cursor']"
          },
          {
            "lang": "cURL",
            "source": "curl -X 'GET' \\\n      'https://openapi.visionstory.ai/api/v1/avatars?is_public=true&limit=20' \\\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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "remaining": 1000
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_GetCreditsResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\ncredits = client.get_credits()\nprint(credits)"
          },
          {
            "lang": "REST",
            "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 reference images\n(asset_id / url / inline_data; the per-model limit is `params.refs.max` in GET /api/v1/image/models).\nEditing works through instructions in the prompt plus reference images — no mask needed.\nSynchronous: the response contains the image URL directly, and you can pass that URL straight into\nother endpoints (video `refs`, `first_frame`/`end_frame`). GPT Image models are slower (often 20–60\nseconds) — set a client timeout of at least 3 minutes. It is not added to your asset library — use\nPOST /api/v1/asset if you want to keep it there. Credits are charged per image, only on success; some\nmodels are priced per resolution (`credit_by_resolution`). Per-key concurrency is limited during beta;\nrequests 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": "seedream-5.0-lite",
                "prompt": "A red panda barista in a cozy cafe, warm lighting",
                "aspect_ratio": "1:1",
                "resolution": "2K"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "cost_credit": 2,
                        "height": 1024,
                        "model_id": "nano-banana-2",
                        "url": "https://example.com/generated.png",
                        "width": 1024
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_CreateImageResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nimage = client.create_image({\n    \"model_id\": \"seedream-5.0-lite\",\n    \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n    \"aspect_ratio\": \"1:1\",\n    \"resolution\": \"2K\",\n})\nprint(image)"
          },
          {
            "lang": "REST",
            "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\": \"seedream-5.0-lite\",\n      \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n      \"aspect_ratio\": \"1:1\",\n      \"resolution\": \"2K\"\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\": \"seedream-5.0-lite\",\n  \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n  \"aspect_ratio\": \"1:1\",\n  \"resolution\": \"2K\"\n}'"
          }
        ]
      }
    },
    "/api/v1/image/models": {
      "get": {
        "description": "Machine-readable capabilities of available image models: aspect ratios, resolutions, reference\nimage limits, and price: `credit_per_image` at the default resolution, plus `credit_by_resolution`\nfor every supported resolution (GPT Image models cost more at 2K).",
        "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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "models": [
                          {
                            "credit_by_resolution": {
                              "1K": 2,
                              "2K": 2
                            },
                            "credit_per_image": 2,
                            "description": "Balanced quality and speed, strong instruction-following edits.",
                            "model_id": "nano-banana-2",
                            "params": {
                              "aspect_ratio": {
                                "default": "1:1",
                                "values": [
                                  "1:1",
                                  "2:3",
                                  "3:2",
                                  "3:4",
                                  "4:3",
                                  "4:5",
                                  "5:4",
                                  "9:16",
                                  "16:9",
                                  "21:9"
                                ]
                              },
                              "prompt": {
                                "max_length": 5000
                              },
                              "refs": {
                                "accept": [
                                  "image"
                                ],
                                "max": 4
                              },
                              "resolution": {
                                "default": "1K",
                                "values": [
                                  "1K",
                                  "2K"
                                ]
                              }
                            }
                          },
                          {
                            "credit_by_resolution": {
                              "1K": 3,
                              "2K": 3
                            },
                            "credit_per_image": 3,
                            "description": "Highest quality tier, best for detailed scenes; supports 2K output.",
                            "model_id": "nano-banana-pro",
                            "params": {
                              "aspect_ratio": {
                                "default": "1:1",
                                "values": [
                                  "1:1",
                                  "2:3",
                                  "3:2",
                                  "3:4",
                                  "4:3",
                                  "4:5",
                                  "5:4",
                                  "9:16",
                                  "16:9",
                                  "21:9"
                                ]
                              },
                              "prompt": {
                                "max_length": 5000
                              },
                              "refs": {
                                "accept": [
                                  "image"
                                ],
                                "max": 4
                              },
                              "resolution": {
                                "default": "1K",
                                "values": [
                                  "1K",
                                  "2K"
                                ]
                              }
                            }
                          },
                          {
                            "credit_by_resolution": {
                              "2K": 1,
                              "4K": 1
                            },
                            "credit_per_image": 1,
                            "description": "Fast and economical; 2K or 4K output at the same price.",
                            "model_id": "seedream-5.0-lite",
                            "params": {
                              "aspect_ratio": {
                                "default": "1:1",
                                "values": [
                                  "1:1",
                                  "2:3",
                                  "3:2",
                                  "3:4",
                                  "4:3",
                                  "4:5",
                                  "5:4",
                                  "9:16",
                                  "16:9",
                                  "21:9"
                                ]
                              },
                              "prompt": {
                                "max_length": 3000
                              },
                              "refs": {
                                "accept": [
                                  "image"
                                ],
                                "max": 14
                              },
                              "resolution": {
                                "default": "2K",
                                "values": [
                                  "2K",
                                  "4K"
                                ]
                              }
                            }
                          },
                          {
                            "credit_by_resolution": {
                              "1K": 2,
                              "2K": 2
                            },
                            "credit_per_image": 2,
                            "description": "Higher-fidelity Seedream tier; 1K by default, 2K on request.",
                            "model_id": "seedream-5.0-pro",
                            "params": {
                              "aspect_ratio": {
                                "default": "1:1",
                                "values": [
                                  "1:1",
                                  "2:3",
                                  "3:2",
                                  "3:4",
                                  "4:3",
                                  "4:5",
                                  "5:4",
                                  "9:16",
                                  "16:9",
                                  "21:9"
                                ]
                              },
                              "prompt": {
                                "max_length": 3000
                              },
                              "refs": {
                                "accept": [
                                  "image"
                                ],
                                "max": 10
                              },
                              "resolution": {
                                "default": "1K",
                                "values": [
                                  "1K",
                                  "2K"
                                ]
                              }
                            }
                          },
                          {
                            "credit_by_resolution": {
                              "1K": 2,
                              "2K": 3
                            },
                            "credit_per_image": 2,
                            "description": "OpenAI GPT Image 2.5 Flare: fast, high-quality generation and edits.",
                            "model_id": "gpt-image-2.5-flare",
                            "params": {
                              "aspect_ratio": {
                                "default": "1:1",
                                "values": [
                                  "1:1",
                                  "2:3",
                                  "3:2",
                                  "3:4",
                                  "4:3",
                                  "4:5",
                                  "5:4",
                                  "9:16",
                                  "16:9",
                                  "21:9"
                                ]
                              },
                              "prompt": {
                                "max_length": 5000
                              },
                              "refs": {
                                "accept": [
                                  "image"
                                ],
                                "max": 6
                              },
                              "resolution": {
                                "default": "1K",
                                "values": [
                                  "1K",
                                  "2K"
                                ]
                              }
                            }
                          },
                          {
                            "credit_by_resolution": {
                              "1K": 2,
                              "2K": 3
                            },
                            "credit_per_image": 2,
                            "description": "OpenAI GPT Image 2.5 Sunburst: most capable GPT Image model, best for precise edits; slower than Flare.",
                            "model_id": "gpt-image-2.5-sunburst",
                            "params": {
                              "aspect_ratio": {
                                "default": "1:1",
                                "values": [
                                  "1:1",
                                  "2:3",
                                  "3:2",
                                  "3:4",
                                  "4:3",
                                  "4:5",
                                  "5:4",
                                  "9:16",
                                  "16:9",
                                  "21:9"
                                ]
                              },
                              "prompt": {
                                "max_length": 5000
                              },
                              "refs": {
                                "accept": [
                                  "image"
                                ],
                                "max": 6
                              },
                              "resolution": {
                                "default": "1K",
                                "values": [
                                  "1K",
                                  "2K"
                                ]
                              }
                            }
                          },
                          {
                            "credit_by_resolution": {
                              "1K": 2,
                              "2K": 3
                            },
                            "credit_per_image": 2,
                            "description": "OpenAI GPT Image 2: previous-generation GPT Image model.",
                            "model_id": "gpt-image-2",
                            "params": {
                              "aspect_ratio": {
                                "default": "1:1",
                                "values": [
                                  "1:1",
                                  "2:3",
                                  "3:2",
                                  "3:4",
                                  "4:3",
                                  "4:5",
                                  "5:4",
                                  "9:16",
                                  "16:9",
                                  "21:9"
                                ]
                              },
                              "prompt": {
                                "max_length": 5000
                              },
                              "refs": {
                                "accept": [
                                  "image"
                                ],
                                "max": 6
                              },
                              "resolution": {
                                "default": "1K",
                                "values": [
                                  "1K",
                                  "2K"
                                ]
                              }
                            }
                          }
                        ]
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_GetImageModelsResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nmodels = client.list_image_models()\nprint(models)"
          },
          {
            "lang": "REST",
            "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/media/understand": {
      "post": {
        "description": "Label or extract structured information from images, audio, and video with a frontier multimodal model.\nYou supply the instructions (`prompt`), the media (`inputs`), and a JSON `schema`; the response `output`\nconforms to that schema — closed label sets, scores, timestamps, transcribed fields, whatever you define.\nSynchronous. Billing follows the upstream model's token usage (input media and prompt, plus output\nincluding reasoning) at 1 credit per $0.10, rounded up per call, charged only on success. Per-key\nconcurrency is limited during beta; requests beyond the limit are rejected, not queued.",
        "operationId": "understand_media_api_v1_media_understand_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": {
              "example": {
                "inputs": [
                  {
                    "url": "https://example.com/cat.jpg"
                  }
                ],
                "prompt": "Identify the main subject in the image.",
                "schema": {
                  "additionalProperties": false,
                  "properties": {
                    "subject": {
                      "description": "Main subject in the image.",
                      "type": "string"
                    }
                  },
                  "required": [
                    "subject"
                  ],
                  "type": "object"
                }
              },
              "schema": {
                "$ref": "#/components/schemas/MediaUnderstandRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "cost_credit": 1,
                        "output": {
                          "subject": "cat"
                        },
                        "usage": {
                          "input_tokens": 120,
                          "output_tokens": 12
                        }
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_MediaUnderstandResponse_"
                }
              }
            },
            "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": "Understand media (structured)",
        "tags": [
          "Media Understanding"
        ],
        "x-agent-guidance": {
          "exampleIdsArePlaceholders": true,
          "credentialsFromEnvironment": "VISIONSTORY_API_KEY"
        },
        "x-codeSamples": [
          {
            "lang": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nresult = client.understand_media(\n    prompt=\"Identify the main subject in the image.\",\n    inputs=[{\"url\": \"https://example.com/media/photo.jpg\"}],\n    schema={\"type\": \"object\", \"properties\": {\"subject\": {\"type\": \"string\"}},\n            \"required\": [\"subject\"], \"additionalProperties\": False},\n)\nprint(result)"
          },
          {
            "lang": "REST",
            "source": "import os\nimport requests\n\nresponse = requests.post(\n    \"https://openapi.visionstory.ai/api/v1/media/understand\",\n    headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n    json={\n      \"inputs\": [\n        {\n          \"url\": \"https://example.com/cat.jpg\"\n        }\n      ],\n      \"prompt\": \"Identify the main subject in the image.\",\n      \"schema\": {\n        \"additionalProperties\": False,\n        \"properties\": {\n          \"subject\": {\n            \"description\": \"Main subject in the image.\",\n            \"type\": \"string\"\n          }\n        },\n        \"required\": [\n          \"subject\"\n        ],\n        \"type\": \"object\"\n      }\n    },\n)\nresponse.raise_for_status()\nprint(response.json())"
          },
          {
            "lang": "cURL",
            "source": "curl --request POST 'https://openapi.visionstory.ai/api/v1/media/understand' \\\n  --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"inputs\": [\n    {\n      \"url\": \"https://example.com/cat.jpg\"\n    }\n  ],\n  \"prompt\": \"Identify the main subject in the image.\",\n  \"schema\": {\n    \"additionalProperties\": false,\n    \"properties\": {\n      \"subject\": {\n        \"description\": \"Main subject in the image.\",\n        \"type\": \"string\"\n      }\n    },\n    \"required\": [\n      \"subject\"\n    ],\n    \"type\": \"object\"\n  }\n}'"
          }
        ]
      }
    },
    "/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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "models": [
                          {
                            "aspect_ratios": [
                              "9:16",
                              "16:9",
                              "1:1"
                            ],
                            "description": "Character Model v4 provides improved motion quality and stability.",
                            "max_duration_seconds": 600,
                            "model_id": "vs_character_v4",
                            "resolutions": [
                              "720p",
                              "1080p",
                              "2k"
                            ]
                          }
                        ]
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_GetModelsResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nmodels = client.list_models()\nprint(models)"
          },
          {
            "lang": "REST",
            "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",
                "locale": "en-GB",
                "speech_rate": "normal"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "audio/mpeg": {
                "example": "<binary MP3 audio bytes; save the response body as speech.mp3>",
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "MP3 audio (44.1kHz). Usage metadata is returned in response headers. The example text is a binary-body placeholder, not playable audio or JSON.",
            "headers": {
              "X-Audio-Duration-Sec": {
                "description": "Actual generated duration in seconds.",
                "example": 1.5,
                "schema": {
                  "type": "number"
                }
              },
              "X-Audio-Id": {
                "description": "Identifier of the generated audio.",
                "example": "example_audio_id",
                "schema": {
                  "type": "string"
                }
              },
              "X-Cost-Credit": {
                "description": "Credits charged. This example is illustrative, not a quote.",
                "example": 2,
                "schema": {
                  "type": "integer"
                }
              },
              "X-Usage-Characters": {
                "description": "Number of characters billed.",
                "example": 22,
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "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": "SDK",
            "source": "from pathlib import Path\nfrom visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nspeech = client.create_speech(\n    text=\"Welcome to VisionStory.\",\n    voice_id=\"voice_123456\",\n    locale=\"en-GB\",\n    speech_rate=\"normal\",\n)\nPath(\"speech.mp3\").write_bytes(speech[\"audio\"])\nprint({key: value for key, value in speech.items() if key != \"audio\"})"
          },
          {
            "lang": "REST",
            "source": "from pathlib import Path\nimport 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      \"locale\": \"en-GB\",\n      \"speech_rate\": \"normal\"\n    },\n)\nresponse.raise_for_status()\nPath(\"response.mp3\").write_bytes(response.content)"
          },
          {
            "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  \"locale\": \"en-GB\",\n  \"speech_rate\": \"normal\"\n}' \\\n  --output 'response.mp3'"
          }
        ]
      }
    },
    "/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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "deleted": true
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_DeleteResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nresult = client.delete_video(\"video_123456\")\nprint(result)"
          },
          {
            "lang": "REST",
            "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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "aspect_ratio": "9:16",
                        "cost_credit": 10,
                        "created_at": 1788480000,
                        "model_id": "vs_character_v4",
                        "resolution": "720p",
                        "status": "created",
                        "video_id": "example_video_id",
                        "video_url": "https://example.com/avatar-video.mp4"
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_GetVideoResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nvideo = client.get_video(\"video_123456\")\nprint(video)"
          },
          {
            "lang": "REST",
            "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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "video_id": "example_video_id"
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_CreateVideoResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient, build_video_payload\n\nclient = VisionStoryClient.from_env()\npayload = build_video_payload(\n    avatar_id=\"avatar_123456\",\n    text=\"Welcome to VisionStory.\",\n    voice_id=\"voice_123456\",\n)\npayload[\"client_request_id\"] = \"request_20260824_001\"\nvideo = client.create_video(payload)\nprint(video)"
          },
          {
            "lang": "REST",
            "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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "videos": [
                          {
                            "aspect_ratio": "9:16",
                            "cost_credit": 10,
                            "created_at": 1788480000,
                            "model_id": "vs_character_v4",
                            "resolution": "720p",
                            "status": "created",
                            "video_id": "example_video_id",
                            "video_url": "https://example.com/avatar-video.mp4"
                          }
                        ]
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_GetVideosResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nvideos = client.list_videos()\nprint(videos)"
          },
          {
            "lang": "REST",
            "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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "deleted": true
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_DeleteResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nresult = client.delete_voice(\"voice_123456\")\nprint(result)"
          },
          {
            "lang": "REST",
            "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": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "gender": "female",
                        "language": "english",
                        "locale": "en-US",
                        "preview_audio_url": "https://example.com/clone.mp3",
                        "voice_id": "example_cloned_voice_id"
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_CloneVoiceResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nvoice = client.clone_voice(\n    audio_url=\"https://example.com/media/voice-sample.mp3\",\n    preview_text=\"Welcome to VisionStory.\",\n)\nprint(voice)"
          },
          {
            "lang": "REST",
            "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.\nOptionally filter by `locale` and/or `provider`. Pass `limit` (and the returned `next_cursor`) to\npage through the filtered public library; without `limit` the full list is returned in one response.",
        "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"
          },
          {
            "description": "Pagination cursor over `public_voices`, from the previous page's `next_cursor`. Omit or pass 0 for the first page.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "default": 0,
              "description": "Pagination cursor over `public_voices`, from the previous page's `next_cursor`. Omit or pass 0 for the first page.",
              "minimum": 0,
              "title": "Cursor",
              "type": "integer"
            },
            "example": 0
          },
          {
            "description": "Maximum `public_voices` per page (1-500). Omit to return the full library unpaginated (`my_voices` is always returned in full on the first page).",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maximum": 500,
                  "minimum": 1,
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Maximum `public_voices` per page (1-500). Omit to return the full library unpaginated (`my_voices` is always returned in full on the first page).",
              "title": "Limit"
            },
            "example": 50
          },
          {
            "description": "Filter by BCP 47 locale (case-insensitive). A bare language such as `en` or `zh` matches every regional variant; `en-GB` / `zh-TW` / `zh-HK` match that region only. See the `locale` field of each voice.",
            "in": "query",
            "name": "locale",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by BCP 47 locale (case-insensitive). A bare language such as `en` or `zh` matches every regional variant; `en-GB` / `zh-TW` / `zh-HK` match that region only. See the `locale` field of each voice.",
              "title": "Locale"
            },
            "example": "en-GB"
          },
          {
            "description": "Filter to voices from this engine (case-insensitive): `elevenlabs` / `seed` / `gemini` / `minimax`.",
            "in": "query",
            "name": "provider",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter to voices from this engine (case-insensitive): `elevenlabs` / `seed` / `gemini` / `minimax`.",
              "title": "Provider"
            },
            "example": "elevenlabs"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "success": {
                    "description": "Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.",
                    "summary": "Successful response",
                    "value": {
                      "data": {
                        "my_voices": [
                          {
                            "accent": "american",
                            "age": "young",
                            "gender": "female",
                            "is_free": false,
                            "language": "english",
                            "locale": "en-US",
                            "preview_audio_url": "https://example.com/voice.mp3",
                            "provider": "elevenlabs",
                            "tags": "clear narration",
                            "use_cases": [
                              "narration"
                            ],
                            "voice_id": "example_cloned_voice_id"
                          }
                        ],
                        "next_cursor": 0,
                        "public_voices": [
                          {
                            "accent": "american",
                            "age": "young",
                            "gender": "female",
                            "is_free": false,
                            "language": "english",
                            "locale": "en-US",
                            "preview_audio_url": "https://example.com/voice.mp3",
                            "provider": "elevenlabs",
                            "tags": "clear narration",
                            "use_cases": [
                              "narration"
                            ],
                            "voice_id": "example_voice_id"
                          }
                        ]
                      },
                      "message": "success",
                      "server_time": "2026-09-04T00:00:00Z"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/BaseSuccessResponse_GetVoicesResponse_"
                }
              }
            },
            "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": "SDK",
            "source": "from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nvoices = client.list_voices(\n    limit=20,\n    locale=\"en-GB\",\n)\nprint(voices)"
          },
          {
            "lang": "REST",
            "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.13",
    "lastReviewed": "2026-09-24",
    "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"
    }
  ]
}