curl -X POST "https://api.submagic.co/v1/user-media/upload" \
-H "x-api-key: sk-your-api-key-here" \
-F "file=@./my-video.mp4"
const uploadUserMedia = async (file) => {
const formData = new FormData();
formData.append("file", file);
const response = await fetch(
"https://api.submagic.co/v1/user-media/upload",
{
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
},
body: formData,
}
);
const data = await response.json();
console.log("User media uploaded:", data.userMediaId);
return data;
};
// Usage with file input
const fileInput = document.getElementById("media-file");
fileInput.addEventListener("change", async (event) => {
const file = event.target.files[0];
if (file) {
await uploadUserMedia(file);
}
});
import requests
def upload_user_media(file_path):
url = 'https://api.submagic.co/v1/user-media/upload'
headers = {
'x-api-key': 'sk-your-api-key-here'
}
with open(file_path, 'rb') as media_file:
files = {
'file': media_file
}
response = requests.post(url, headers=headers, files=files)
result = response.json()
print(f"User media uploaded: {result['userMediaId']}")
return result
# Usage
media = upload_user_media('./my-video.mp4')
{
"userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb7v"
}
API Reference
Upload User Media
Upload video or image files directly to your media library for use in projects
POST
/
v1
/
user-media
/
upload
curl -X POST "https://api.submagic.co/v1/user-media/upload" \
-H "x-api-key: sk-your-api-key-here" \
-F "file=@./my-video.mp4"
const uploadUserMedia = async (file) => {
const formData = new FormData();
formData.append("file", file);
const response = await fetch(
"https://api.submagic.co/v1/user-media/upload",
{
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
},
body: formData,
}
);
const data = await response.json();
console.log("User media uploaded:", data.userMediaId);
return data;
};
// Usage with file input
const fileInput = document.getElementById("media-file");
fileInput.addEventListener("change", async (event) => {
const file = event.target.files[0];
if (file) {
await uploadUserMedia(file);
}
});
import requests
def upload_user_media(file_path):
url = 'https://api.submagic.co/v1/user-media/upload'
headers = {
'x-api-key': 'sk-your-api-key-here'
}
with open(file_path, 'rb') as media_file:
files = {
'file': media_file
}
response = requests.post(url, headers=headers, files=files)
result = response.json()
print(f"User media uploaded: {result['userMediaId']}")
return result
# Usage
media = upload_user_media('./my-video.mp4')
{
"userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb7v"
}
Upload User Media
Upload video or image files directly to your user media library. This media can then be referenced in your video projects as custom B-roll using the returneduserMediaId.
This endpoint requires authentication and has a rate limit of 500 requests per
hour.
Authentication
string
required
Your Submagic API key starting with
sk-Request Body (multipart/form-data)
file
required
Video or image file to upload. Must be in a supported format.
Response
string
Unique identifier for the uploaded media (UUID format). Use this ID to
reference the media in your video projects.
curl -X POST "https://api.submagic.co/v1/user-media/upload" \
-H "x-api-key: sk-your-api-key-here" \
-F "file=@./my-video.mp4"
const uploadUserMedia = async (file) => {
const formData = new FormData();
formData.append("file", file);
const response = await fetch(
"https://api.submagic.co/v1/user-media/upload",
{
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
},
body: formData,
}
);
const data = await response.json();
console.log("User media uploaded:", data.userMediaId);
return data;
};
// Usage with file input
const fileInput = document.getElementById("media-file");
fileInput.addEventListener("change", async (event) => {
const file = event.target.files[0];
if (file) {
await uploadUserMedia(file);
}
});
import requests
def upload_user_media(file_path):
url = 'https://api.submagic.co/v1/user-media/upload'
headers = {
'x-api-key': 'sk-your-api-key-here'
}
with open(file_path, 'rb') as media_file:
files = {
'file': media_file
}
response = requests.post(url, headers=headers, files=files)
result = response.json()
print(f"User media uploaded: {result['userMediaId']}")
return result
# Usage
media = upload_user_media('./my-video.mp4')
{
"userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb7v"
}
Using User Media in Projects
Once you have auserMediaId, you can reference it in the items array when creating or uploading projects:
{
"items": [
{
"type": "user-media",
"startTime": 5,
"endTime": 10,
"userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb3a"
}
]
}
Error Responses
object
{
"error": "VALIDATION_ERROR",
"message": "File validation failed",
"details": [
{
"field": "file",
"message": "File is required",
"value": null
}
]
}
object
{
"error": "VALIDATION_ERROR",
"message": "The following media is not ready yet: df7d8cfd-eb82-4865-8b32-df3396b972b1. Please wait for the upload to complete."
}
object
{
"error": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
object
{
"error": "PAYLOAD_TOO_LARGE",
"message": "File size exceeds maximum allowed size"
}
object
{
"error": "UNSUPPORTED_MEDIA_TYPE",
"message": "Media format not supported"
}
object
{
"error": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"retryAfter": 30
}
object
{
"error": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred"
}

