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

const createUserMedia = async (mediaUrl) => {
  const response = await fetch("https://api.submagic.co/v1/user-media", {
    method: "POST",
    headers: {
      "x-api-key": "sk-your-api-key-here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: mediaUrl,
    }),
  });

  const data = await response.json();
  console.log("User media created:", data.userMediaId);
  return data;
};

// Usage
const media = await createUserMedia(
  "https://example.com/media/sample-video.mp4"
);

import requests

def create_user_media(media_url):
    url = 'https://api.submagic.co/v1/user-media'
    headers = {
        'x-api-key': 'sk-your-api-key-here',
        'Content-Type': 'application/json'
    }
    data = {
        'url': media_url
    }

    response = requests.post(url, headers=headers, json=data)
    result = response.json()

    print(f"User media created: {result['userMediaId']}")
    return result

# Usage
media = create_user_media('https://example.com/media/sample-video.mp4')

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

POST

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

const createUserMedia = async (mediaUrl) => {
  const response = await fetch("https://api.submagic.co/v1/user-media", {
    method: "POST",
    headers: {
      "x-api-key": "sk-your-api-key-here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: mediaUrl,
    }),
  });

  const data = await response.json();
  console.log("User media created:", data.userMediaId);
  return data;
};

// Usage
const media = await createUserMedia(
  "https://example.com/media/sample-video.mp4"
);

import requests

def create_user_media(media_url):
    url = 'https://api.submagic.co/v1/user-media'
    headers = {
        'x-api-key': 'sk-your-api-key-here',
        'Content-Type': 'application/json'
    }
    data = {
        'url': media_url
    }

    response = requests.post(url, headers=headers, json=data)
    result = response.json()

    print(f"User media created: {result['userMediaId']}")
    return result

# Usage
media = create_user_media('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

string

required

Your Submagic API key starting with sk-

Request Body

string

required

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

Response

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

const createUserMedia = async (mediaUrl) => {
  const response = await fetch("https://api.submagic.co/v1/user-media", {
    method: "POST",
    headers: {
      "x-api-key": "sk-your-api-key-here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: mediaUrl,
    }),
  });

  const data = await response.json();
  console.log("User media created:", data.userMediaId);
  return data;
};

// Usage
const media = await createUserMedia(
  "https://example.com/media/sample-video.mp4"
);

import requests

def create_user_media(media_url):
    url = 'https://api.submagic.co/v1/user-media'
    headers = {
        'x-api-key': 'sk-your-api-key-here',
        'Content-Type': 'application/json'
    }
    data = {
        'url': media_url
    }

    response = requests.post(url, headers=headers, json=data)
    result = response.json()

    print(f"User media created: {result['userMediaId']}")
    return result

# Usage
media = create_user_media('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

object

{
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "field": "url",
      "message": "Must be a valid URL",
      "value": "invalid-url"
    }
  ]
}

object

{
  "error": "VALIDATION_ERROR",
  "message": "The following media is not ready yet: df7d8cfd-eb82-4865-8b32-df3396b972b1. Please wait for the upload to complete."
}

{
  "error": "VALIDATION_ERROR",
  "message": "URLs from social media platforms are not supported. Please use a direct download 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\"."
}

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."
}

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"
}

Get Started

Guides

API Reference

Create User Media

Create User Media

Authentication

Request Body

Response

Using User Media in Projects

Error Responses

​Create User Media

​Authentication

​Request Body

​Response

​Using User Media in Projects

​Error Responses

Create User Media

Authentication

Request Body

Response

Using User Media in Projects

Error Responses