curl -X POST "https://api.submagic.co/v1/user-media" \
-H "x-api-key: sk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/media/sample-video.mp4"
}'
const createUserMedia = async (mediaUrl) => {
const response = await fetch("https://api.submagic.co/v1/user-media", {
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: mediaUrl,
}),
});
const data = await response.json();
console.log("User media created:", data.userMediaId);
return data;
};
// Usage
const media = await createUserMedia(
"https://example.com/media/sample-video.mp4"
);
import requests
def create_user_media(media_url):
url = 'https://api.submagic.co/v1/user-media'
headers = {
'x-api-key': 'sk-your-api-key-here',
'Content-Type': 'application/json'
}
data = {
'url': media_url
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"User media created: {result['userMediaId']}")
return result
# Usage
media = create_user_media('https://example.com/media/sample-video.mp4')
{
"userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb3a"
}
API Reference
Create User Media
Upload media to your library from a URL for use in video projects as B-roll
POST
/
v1
/
user-media
curl -X POST "https://api.submagic.co/v1/user-media" \
-H "x-api-key: sk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/media/sample-video.mp4"
}'
const createUserMedia = async (mediaUrl) => {
const response = await fetch("https://api.submagic.co/v1/user-media", {
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: mediaUrl,
}),
});
const data = await response.json();
console.log("User media created:", data.userMediaId);
return data;
};
// Usage
const media = await createUserMedia(
"https://example.com/media/sample-video.mp4"
);
import requests
def create_user_media(media_url):
url = 'https://api.submagic.co/v1/user-media'
headers = {
'x-api-key': 'sk-your-api-key-here',
'Content-Type': 'application/json'
}
data = {
'url': media_url
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"User media created: {result['userMediaId']}")
return result
# Usage
media = create_user_media('https://example.com/media/sample-video.mp4')
{
"userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb3a"
}
Create User Media
Upload video or image files to your user media library by providing a URL. This media can then be referenced in your video projects 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
string
required
Public URL to your video or image file. Must be a valid URL and accessible
without authentication.
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" \
-H "x-api-key: sk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/media/sample-video.mp4"
}'
const createUserMedia = async (mediaUrl) => {
const response = await fetch("https://api.submagic.co/v1/user-media", {
method: "POST",
headers: {
"x-api-key": "sk-your-api-key-here",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: mediaUrl,
}),
});
const data = await response.json();
console.log("User media created:", data.userMediaId);
return data;
};
// Usage
const media = await createUserMedia(
"https://example.com/media/sample-video.mp4"
);
import requests
def create_user_media(media_url):
url = 'https://api.submagic.co/v1/user-media'
headers = {
'x-api-key': 'sk-your-api-key-here',
'Content-Type': 'application/json'
}
data = {
'url': media_url
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"User media created: {result['userMediaId']}")
return result
# Usage
media = create_user_media('https://example.com/media/sample-video.mp4')
{
"userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb3a"
}
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",
"layout": "pip-top-right"
}
]
}
Error Responses
object
{
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{
"field": "url",
"message": "Must be a valid URL",
"value": "invalid-url"
}
]
}
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": "VALIDATION_ERROR",
"message": "URLs from social media platforms are not supported. Please use a direct download link."
}
object
Returned when
url is a Google Drive folder or other Drive link that doesn’t
point to a single file. Share a direct file link with access set to “Anyone
with the link”.{
"error": "VALIDATION_ERROR",
"message": "This looks like a Google Drive folder or an unsupported Drive link. Please share a direct link to a single file (e.g. https://drive.google.com/file/d/FILE_ID/view) with access set to \"Anyone with the link\"."
}
object
Returned when
url can’t be reached or serves a web page instead of a media
file (e.g. a broken link, a login wall, or a share page rather than a direct
download).{
"error": "VALIDATION_ERROR",
"message": "The provided URL does not point to a downloadable media file. Please provide a direct download link to a video, audio, or image file."
}
object
{
"error": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
object
{
"error": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"retryAfter": 30
}
object
{
"error": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred"
}

