Media library

Save a reference

Use jobs:write for mutations and jobs:read for reads. Saving a URL records a reference; it does not copy the remote file into Vydra storage. Keep the URL accessible for future generation requests.

curl -X POST https://vydra.ai/api/v1/library \
  -H "Authorization: Bearer $VYDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Campaign reference","url":"https://your-media-host.example/reference.webp","kind":"image","folder":"Campaign"}'

name is required (1–200 characters), url must be HTTPS, and kind must be image, video, or audio. The optional folder is at most 100 characters and defaults to the root folder (""). Optional metadata is a JSON object. HTTP 201 returns the saved row in data, including its ID and URL.

Upload a file

curl -X POST https://vydra.ai/api/v1/library \
  -H "Authorization: Bearer $VYDRA_API_KEY" \
  -F "file=@reference.webp;type=image/webp" \
  -F "folder=Campaign"

Use a nonempty file up to 4 MiB (4,194,304 bytes); hosting request limits also apply to the multipart body. Supported MIME types are image/jpeg, image/png, image/webp, image/gif, video/mp4, video/webm, audio/mpeg, and audio/wav. The server uploads to storage and uses the filename as the entry name. Do not manually set the multipart Content-Type header; your client supplies its boundary. Use a saved HTTPS URL for larger media.

Find and organize

curl "https://vydra.ai/api/v1/library?kind=image&folder=Campaign&q=reference" \
  -H "Authorization: Bearer $VYDRA_API_KEY"

curl -X PATCH https://vydra.ai/api/v1/library/ASSET_ID \
  -H "Authorization: Bearer $VYDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Hero reference","folder":"Approved","favorite":true}'

The list returns {"data":[…]}, newest first, with a maximum of 200 saved entries and no pagination. Omit folder for all folders; ?folder= selects only the root. Search matches names. PATCH changes name, folder, or favorite and returns the row under data.

DELETE /library/{id} returns {"success":true}. It removes the saved entry, not the completed generation or underlying stored object. Wrong-organization or missing IDs return 404. Invalid inputs return 400; upload rate limits return 429.

Use generated media

The web library also shows completed job assets. The saved-reference API above does not list those automatically; use GET /assets or retrieve a job result. Pass the returned media URL to a supported reference field in a generation request, or to an image/video/audio input node when running a Studio graph.

Video frame capture in the browser requires cross-origin access from the media host. Imported ZIP workflows limit each embedded asset to 4 MiB and the bundle to 40 MiB. See Studio for workflow portability.