Get Audio
Learn how to retrieve brand audio from your workspace
Published ·Updated
/v1/brand-assets/audio/getcurl -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>"const res = await fetch("https://api.orshot.com/v1/brand-assets/audio/get?tag=<TAG>&embedId=<EMBED_ID>&embedUserId=<EMBED_USER_ID>", {
method: "GET",
headers: {
Authorization: "Bearer <ORSHOT_API_KEY>",
},
});
const data = await res.json();import requests
response = requests.get(
"https://api.orshot.com/v1/brand-assets/audio/get?tag=<TAG>&embedId=<EMBED_ID>&embedUserId=<EMBED_USER_ID>",
headers={"Authorization": "Bearer <ORSHOT_API_KEY>"},
)
data = response.json()$ch = curl_init("https://api.orshot.com/v1/brand-assets/audio/get?tag=<TAG>&embedId=<EMBED_ID>&embedUserId=<EMBED_USER_ID>");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer <ORSHOT_API_KEY>",
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);require "net/http"
require "json"
uri = URI("https://api.orshot.com/v1/brand-assets/audio/get?tag=<TAG>&embedId=<EMBED_ID>&embedUserId=<EMBED_USER_ID>")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer <ORSHOT_API_KEY>"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)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.
https://api.orshot.com/v1/brand-assets/audio/getQuery Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
tag | String | No | Comma-separated list of tags to filter by. Returns only audio that has all specified tags. |
embedId | String | No | Embed instance ID. Pair with embedUserId to scope this call to one embed user |
embedUserId | String | No | The same userId your app passes to the embed URL. Requires embedId |
Request#
await fetch("https://api.orshot.com/v1/brand-assets/audio/get", {
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer <ORSHOT_API_KEY>",
},
});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>",
},
});{
"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#
| Field | Type | Description |
|---|---|---|
id | Number | Unique identifier for the audio file |
created_at | String | Timestamp when the audio was uploaded |
name | String | The name you gave the audio, or an auto-generated one |
original_filename | String | The uploaded file's name, or name when there is none |
file_size | Number | Size of the audio file in bytes |
direct_url | String | URL to access the audio. Treat this URL as opaque. |
duration | Number | Audio 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 |
format | String | Audio format (e.g., mp3, wav) |
mime_type | String | MIME type of the audio |
waveform_url | String | URL to a waveform image (may be null) |
metadata | Object | Metadata you sent with the upload. May include keys Orshot adds about how the file was uploaded. |
tags | String[] | Tags associated with the audio |
workspace_id | Number | ID of the workspace the audio belongs to |
user_id | String | ID of the user who uploaded the audio |
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