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 returned userMediaId.
This endpoint requires authentication and has a rate limit of 500 requests per
hour.
Authentication
Your Submagic API key starting with sk-
Request Body (multipart/form-data)
Video or image file to upload. Must be in a supported format.
Response
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"
{
"userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb7v"
}
userMediaId, 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
{
"error": "VALIDATION_ERROR",
"message": "File validation failed",
"details": [
{
"field": "file",
"message": "File is required",
"value": null
}
]
}
{
"error": "VALIDATION_ERROR",
"message": "The following media is not ready yet: df7d8cfd-eb82-4865-8b32-df3396b972b1. Please wait for the upload to complete."
}
{
"error": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "File size exceeds maximum allowed size"
}
415 Unsupported Media Type
{
"error": "UNSUPPORTED_MEDIA_TYPE",
"message": "Media format not supported"
}
{
"error": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"retryAfter": 30
}
{
"error": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred"
}
