Skip to main content
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"
  }'

{
  "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",
      "layout": "pip-top-right"
    }
  ]
}
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."
}
​
400 Unsupported Social Media URL
object
{
  "error": "VALIDATION_ERROR",
  "message": "URLs from social media platforms are not supported. Please use a direct download link."
}
​
400 Google Drive Folder 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\"."
}
​
400 URL Not Downloadable
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."
}
​
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"
}