Get Audio

Learn how to retrieve brand audio from your workspace

Published ·Updated

GET
/v1/brand-assets/audio/get
curl -X GET "https://api.orshot.com/v1/brand-assets/audio/get?tag=<TAG>&embedId=<EMBED_ID>&embedUserId=<EMBED_USER_ID>" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>"

Overview#

This endpoint allows you to retrieve a list of brand audio tracks from your workspace. Brand audio can be reused across your video templates without uploading the same file every time.

It returns the 100 most recent audio files. Use Search Brand Assets with page and limit to page through more.

Endpoint
https://api.orshot.com/v1/brand-assets/audio/get

Query Parameters#

ParameterTypeRequiredDescription
tagStringNoComma-separated list of tags to filter by. Returns only audio that has all specified tags.
embedIdStringNoEmbed instance ID. Pair with embedUserId to scope this call to one embed user
embedUserIdStringNoThe same userId your app passes to the embed URL. Requires embedId

Request#

JavaScript
await fetch("https://api.orshot.com/v1/brand-assets/audio/get", {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
JavaScript
await fetch("https://api.orshot.com/v1/brand-assets/audio/get?tag=intro,music", {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
JSON
{
  "data": [
    {
      "id": 42,
      "created_at": "2025-09-10T15:30:45.123Z",
      "name": "background-music.mp3",
      "original_filename": "background-music.mp3",
      "file_size": 2621440,
      "direct_url": "https://storage.orshot.com/cloud/w-50/renders/audio/background-musicmp3-Lp9Xe3Gu6Ra.mp3",
      "duration": 169.5,
      "format": "mp3",
      "mime_type": "audio/mpeg",
      "waveform_url": null,
      "metadata": {},
      "tags": ["intro", "music"],
      "workspace_id": 50,
      "user_id": "abcdef01-2345-6789-abcd-ef0123456789"
    }
  ]
}

Per-User Libraries#

Pass embedId and embedUserId together to return only that embed user's audio instead of the whole workspace library. This is how one embed serves many brands or tenants, each with its own brand space.

Omit them and this endpoint behaves exactly as documented above. See Per-User Brand Assets for the full picture.

Rate Limits#

  • 30 requests per minute per endpoint

Response Fields#

FieldTypeDescription
idNumberUnique identifier for the audio file
created_atStringTimestamp when the audio was uploaded
nameStringThe name you gave the audio, or an auto-generated one
original_filenameStringThe uploaded file's name, or name when there is none
file_sizeNumberSize of the audio file in bytes
direct_urlStringURL to access the audio. Treat this URL as opaque.
durationNumberAudio duration in seconds, or null. Orshot does not read it from the file. It is set only when you pass it in metadata on upload
formatStringAudio format (e.g., mp3, wav)
mime_typeStringMIME type of the audio
waveform_urlStringURL to a waveform image (may be null)
metadataObjectMetadata you sent with the upload. May include keys Orshot adds about how the file was uploaded.
tagsString[]Tags associated with the audio
workspace_idNumberID of the workspace the audio belongs to
user_idStringID of the user who uploaded the audio
Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key
  • Image, PDF and video generation via API
  • Visual editor with AI and smart layouts
  • Zapier, Make, MCP and 40+ integrations
  • White-label embed for your own app
  • 100 free credits a month, no credit card required