Documentation Index
Fetch the complete documentation index at: https://docs.submagic.co/llms.txt
Use this file to discover all available pages before exploring further.
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"
}
