Upload Audio

Learn how to upload brand audio to your workspace

Published Jul 8, 2026

POST

/v1/brand-assets/audio/add

curl -X POST "https://api.orshot.com/v1/brand-assets/audio/add" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>"

$ch = curl_init("https://api.orshot.com/v1/brand-assets/audio/add");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
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/add")
req = Net::HTTP::Post.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 upload brand audio to your workspace. You can upload audio from a URL, as a base64-encoded string, or as a binary upload.

Endpoint

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

Request#

JavaScript

await fetch("https://api.orshot.com/v1/brand-assets/audio/add", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    file: "https://example.com/audio/background-music.mp3",
    name: "background-music.mp3", // optional
    tags: ["intro", "music"], // optional
    metadata: { // optional
      duration: 169.5,
      description: "Background music track"
    }
  }),
});

JavaScript

const formData = new FormData();
formData.append("file", audioFile); // File object
formData.append("name", "background-music.mp3"); // optional

await fetch("https://api.orshot.com/v1/brand-assets/audio/add", {
method: "POST",
headers: {
Authorization: "Bearer <ORSHOT_API_KEY>",
},
body: formData,
});

JSON

{
  "data": {
    "audio": {
      "id": 42,
      "created_at": "2025-09-11T10:15:30.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-music.mp3",
      "duration": 169.5,
      "format": "mp3",
      "mime_type": "audio/mpeg",
      "waveform_url": null,
      "metadata": {
        "duration": 169.5,
        "description": "Background music track"
      },
      "tags": ["intro", "music"],
      "workspace_id": 50,
      "user_id": "abcdef01-2345-6789-abcd-ef0123456789"
    },
    "url": "https://storage.orshot.com/cloud/w-50/renders/audio/background-music.mp3"
  }
}

Request Parameters#

Parameter	Type	Required	Description
`file`	String	Yes	URL, base64-encoded string, or binary upload of the audio file
`name`	String	No	Custom name for the audio (defaults to original filename or auto-generated)
`tags`	String[]	No	Array of tags to associate with the audio (e.g., `["intro", "music"]`)
`metadata`	Object	No	Custom metadata to attach to the audio (can include `duration`)

Supported Audio Formats#

MP3 (audio/mpeg)
WAV (audio/wav)
M4A (audio/mp4)
AAC (audio/aac)
OGG (audio/ogg)
Opus (audio/opus)
FLAC (audio/flac)
WebM (audio/webm)
AIFF (audio/aiff)
WMA (audio/x-ms-wma)

Notes#

Maximum file size: 50MB
For base64 uploads, include the file extension in the name (e.g., track.wav) so the format is detected correctly — otherwise it defaults to mp3.
Audio is stored as-is; it is re-encoded to AAC automatically when a template is rendered to video.

Error responses#

Input problems return 400 with a plain-language error and, for the two cases agents hit most, a stable code:

AUDIO_NOT_AUDIO: the bytes carry no MP3, WAV, M4A, AAC, OGG, Opus, FLAC, WebM, AIFF or WMA signature. Usually a filename, a description, or placeholder text was sent instead of the file, or a URL served an HTML page.
AUDIO_DATA_INCOMPLETE: the data starts as a real audio file but ends early. The base64 was cut off in transit, the URL served a partial file, or the upload stopped before the end. The error names the fix for how the file was sent.

Hosted chat clients such as ChatGPT and Claude.ai cannot send file bytes, so a base64 file from them is almost always cut off. Pass a publicly reachable audio URL instead.

Query Parameters#

Parameter	Type	Required	Description
`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`

Pass embedId and embedUserId together to add the audio to that embed user's private library instead of the shared 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

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