Skip to main content
POST
https://api.submagic.co
/
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"
  }'

{
  "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 returned userMediaId.
This endpoint requires authentication and has a rate limit of 500 requests per hour.

​
Authentication

​
x-api-key
string
required
Your Submagic API key starting with sk-

​
Request Body

​
url
string
required
Public URL to your video or image file. Must be a valid URL and accessible without authentication.

​
Response

​
userMediaId
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"
  }'

{
  "userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb3a"
}

​
Using User Media in Projects

Once you have a 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"
    }
  ]
}
See the Create Project or Upload Project documentation for more details on using user media in your videos.

​
Error Responses

​
400 Validation Error
object
{
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "field": "url",
      "message": "Must be a valid URL",
      "value": "invalid-url"
    }
  ]
}
​
400 Media Not Ready
object
{
  "error": "VALIDATION_ERROR",
  "message": "The following media is not ready yet: df7d8cfd-eb82-4865-8b32-df3396b972b1. Please wait for the upload to complete."
}
​
401 Unauthorized
object
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
​
429 Rate Limited
object
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "retryAfter": 30
}
​
500 Server Error
object
{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred"
}