curl -X GET "https://api.submagic.co/v1/user-media?type=AUDIO&limit=10" \
-H "x-api-key: sk-your-api-key-here"
const listUserMedia = async ({ type, limit, cursor } = {}) => {
const params = new URLSearchParams();
if (type) params.set("type", type);
if (limit) params.set("limit", String(limit));
if (cursor) params.set("cursor", cursor);
const response = await fetch(
`https://api.submagic.co/v1/user-media?${params}`,
{
headers: {
"x-api-key": "sk-your-api-key-here",
},
}
);
const data = await response.json();
console.log(`Fetched ${data.items.length} items`);
return data;
};
// Fetch first page of audio files
const page = await listUserMedia({ type: "AUDIO", limit: 10 });
// Fetch next page
if (page.hasMore) {
const nextPage = await listUserMedia({
type: "AUDIO",
limit: 10,
cursor: page.nextCursor,
});
}
import requests
def list_user_media(media_type=None, limit=None, cursor=None):
url = 'https://api.submagic.co/v1/user-media'
headers = {
'x-api-key': 'sk-your-api-key-here'
}
params = {}
if media_type:
params['type'] = media_type
if limit:
params['limit'] = limit
if cursor:
params['cursor'] = cursor
response = requests.get(url, headers=headers, params=params)
data = response.json()
print(f"Fetched {len(data['items'])} items")
return data
# Fetch first page of audio files
page = list_user_media(media_type='AUDIO', limit=10)
# Fetch next page
if page['hasMore']:
next_page = list_user_media(
media_type='AUDIO',
limit=10,
cursor=page['nextCursor']
)
{
"items": [
{
"id": "88a08eec-712a-45d0-8d0b-3b631700cb3a",
"type": "AUDIO",
"fileName": "background-music.mp3",
"url": "https://cdn.submagic.co/media/88a08eec-712a-45d0-8d0b-3b631700cb3a.mp3",
"metadata": {
"duration": 180.5,
"fileSize": 4500000
},
"createdAt": "2024-01-10T08:00:00.000Z"
},
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "VIDEO",
"fileName": "broll-clip.mp4",
"url": "https://cdn.submagic.co/media/a1b2c3d4-e5f6-7890-abcd-ef1234567890.mp4",
"metadata": {
"width": 1920,
"height": 1080,
"duration": 12.3,
"fileSize": 15000000
},
"createdAt": "2024-01-09T14:30:00.000Z"
}
],
"hasMore": true,
"nextCursor": "f5e4d3c2-b1a0-9876-fedc-ba0987654321"
}
{
"items": [],
"hasMore": false
}
API Reference
List User Media
List the media files in your library
GET
/
v1
/
user-media
curl -X GET "https://api.submagic.co/v1/user-media?type=AUDIO&limit=10" \
-H "x-api-key: sk-your-api-key-here"
const listUserMedia = async ({ type, limit, cursor } = {}) => {
const params = new URLSearchParams();
if (type) params.set("type", type);
if (limit) params.set("limit", String(limit));
if (cursor) params.set("cursor", cursor);
const response = await fetch(
`https://api.submagic.co/v1/user-media?${params}`,
{
headers: {
"x-api-key": "sk-your-api-key-here",
},
}
);
const data = await response.json();
console.log(`Fetched ${data.items.length} items`);
return data;
};
// Fetch first page of audio files
const page = await listUserMedia({ type: "AUDIO", limit: 10 });
// Fetch next page
if (page.hasMore) {
const nextPage = await listUserMedia({
type: "AUDIO",
limit: 10,
cursor: page.nextCursor,
});
}
import requests
def list_user_media(media_type=None, limit=None, cursor=None):
url = 'https://api.submagic.co/v1/user-media'
headers = {
'x-api-key': 'sk-your-api-key-here'
}
params = {}
if media_type:
params['type'] = media_type
if limit:
params['limit'] = limit
if cursor:
params['cursor'] = cursor
response = requests.get(url, headers=headers, params=params)
data = response.json()
print(f"Fetched {len(data['items'])} items")
return data
# Fetch first page of audio files
page = list_user_media(media_type='AUDIO', limit=10)
# Fetch next page
if page['hasMore']:
next_page = list_user_media(
media_type='AUDIO',
limit=10,
cursor=page['nextCursor']
)
{
"items": [
{
"id": "88a08eec-712a-45d0-8d0b-3b631700cb3a",
"type": "AUDIO",
"fileName": "background-music.mp3",
"url": "https://cdn.submagic.co/media/88a08eec-712a-45d0-8d0b-3b631700cb3a.mp3",
"metadata": {
"duration": 180.5,
"fileSize": 4500000
},
"createdAt": "2024-01-10T08:00:00.000Z"
},
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "VIDEO",
"fileName": "broll-clip.mp4",
"url": "https://cdn.submagic.co/media/a1b2c3d4-e5f6-7890-abcd-ef1234567890.mp4",
"metadata": {
"width": 1920,
"height": 1080,
"duration": 12.3,
"fileSize": 15000000
},
"createdAt": "2024-01-09T14:30:00.000Z"
}
],
"hasMore": true,
"nextCursor": "f5e4d3c2-b1a0-9876-fedc-ba0987654321"
}
{
"items": [],
"hasMore": false
}
List User Media
Retrieve a paginated list of media files from your library. You can filter by media type and control pagination using cursor-based navigation.This endpoint requires authentication and has a rate limit of 500 requests per
hour.
Authentication
string
required
Your Submagic API key starting with
sk-Query Parameters
string
Filter by media type. Allowed values:
VIDEO, AUDIO, IMAGE.number
Number of items to return per page (1-100). Defaults to
50.string
UUID cursor for pagination. Pass the
nextCursor value from a previous
response to fetch the next page of results.Response
array
Array of user media objects
Hide User Media Object
Hide User Media Object
string
Unique identifier for the media file (UUID format)
string
Media type:
VIDEO, AUDIO, or IMAGEstring
Original file name of the uploaded media
string
URL to access the media file
object
string
ISO 8601 timestamp when the media was uploaded
boolean
Whether there are more items available beyond this page
string
Cursor to pass as the
cursor query parameter to fetch the next page.
Only present when hasMore is true.curl -X GET "https://api.submagic.co/v1/user-media?type=AUDIO&limit=10" \
-H "x-api-key: sk-your-api-key-here"
const listUserMedia = async ({ type, limit, cursor } = {}) => {
const params = new URLSearchParams();
if (type) params.set("type", type);
if (limit) params.set("limit", String(limit));
if (cursor) params.set("cursor", cursor);
const response = await fetch(
`https://api.submagic.co/v1/user-media?${params}`,
{
headers: {
"x-api-key": "sk-your-api-key-here",
},
}
);
const data = await response.json();
console.log(`Fetched ${data.items.length} items`);
return data;
};
// Fetch first page of audio files
const page = await listUserMedia({ type: "AUDIO", limit: 10 });
// Fetch next page
if (page.hasMore) {
const nextPage = await listUserMedia({
type: "AUDIO",
limit: 10,
cursor: page.nextCursor,
});
}
import requests
def list_user_media(media_type=None, limit=None, cursor=None):
url = 'https://api.submagic.co/v1/user-media'
headers = {
'x-api-key': 'sk-your-api-key-here'
}
params = {}
if media_type:
params['type'] = media_type
if limit:
params['limit'] = limit
if cursor:
params['cursor'] = cursor
response = requests.get(url, headers=headers, params=params)
data = response.json()
print(f"Fetched {len(data['items'])} items")
return data
# Fetch first page of audio files
page = list_user_media(media_type='AUDIO', limit=10)
# Fetch next page
if page['hasMore']:
next_page = list_user_media(
media_type='AUDIO',
limit=10,
cursor=page['nextCursor']
)
{
"items": [
{
"id": "88a08eec-712a-45d0-8d0b-3b631700cb3a",
"type": "AUDIO",
"fileName": "background-music.mp3",
"url": "https://cdn.submagic.co/media/88a08eec-712a-45d0-8d0b-3b631700cb3a.mp3",
"metadata": {
"duration": 180.5,
"fileSize": 4500000
},
"createdAt": "2024-01-10T08:00:00.000Z"
},
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "VIDEO",
"fileName": "broll-clip.mp4",
"url": "https://cdn.submagic.co/media/a1b2c3d4-e5f6-7890-abcd-ef1234567890.mp4",
"metadata": {
"width": 1920,
"height": 1080,
"duration": 12.3,
"fileSize": 15000000
},
"createdAt": "2024-01-09T14:30:00.000Z"
}
],
"hasMore": true,
"nextCursor": "f5e4d3c2-b1a0-9876-fedc-ba0987654321"
}
{
"items": [],
"hasMore": false
}
Error Responses
object
{
"error": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{
"field": "type",
"message": "Must be one of: VIDEO, AUDIO, IMAGE",
"value": "INVALID"
}
]
}
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"
}
⌘I