VisionStory Docs
llms.txt Get API key
Assets/Upload asset
POST/api/v1/asset

Upload a reusable media asset (image / video / audio) from a public URL or inline base64, and get an asset_id to reference across generation requests. Re-uploading identical content returns the existing asset. Limits: image ≤30MB, audio ≤15MB, video ≤100MB.

Headers

X-API-KeystringRequired
Your VisionStory API key (sk-vs-...), kept server-side. Create one at OpenApi (Pro plan and up).

Request body

urlstring | nullOptional
Publicly reachable media URL (image/video/audio). Provide either this or inline_data.
inline_dataInlineDataModel | nullOptional
Media as inline base64 data. Provide either this or url.
Show 2 propertiesHide 2 properties
mime_typestringRequired
MIME type of the inline data, used to detect image vs audio. Audio: ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav']; images: ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].
datastringRequired
The file's raw bytes encoded as a base64 string (no data: URI prefix).

Response

200Successful Response

Successful calls return a standard envelope: the endpoint payload under data (its fields are documented below), plus a message string ("success") and an ISO 8601 server_time.

Response fields (data)
asset_idstringRequired
Unique identifier of the asset; reference it as asset_id in generation requests.
kindstringRequired
Detected media kind: one of image / video / audio.
mimestringOptionalDefault ""
Detected MIME type of the asset, e.g. image/png.
widthintegerOptionalDefault 0
Pixel width for image/video assets; 0 when not applicable.
heightintegerOptionalDefault 0
Pixel height for image/video assets; 0 when not applicable.
duration_secnumberOptionalDefault 0
Duration in seconds for video/audio assets; 0 for images.
created_atintegerOptionalDefault 0
Unix timestamp (seconds) when the asset was uploaded.

Errors

All error responses share one JSON envelope: an error object with a numeric code, a human-readable message, an optional details string, and an optional hint giving an actionable next step (handy for AI agents).

errorErrorDetailRequired
Error payload returned with every non-2xx response. Present only on failure; successful calls use the standard success envelope instead.
Show 4 propertiesHide 4 properties
codeintegerRequired
Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.
messagestringRequired
Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.
detailsstring | nullOptional
Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.
hintstring | nullOptional
Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.