Skip to main content
POST
/
enterprise
/
api
/
upload_media
Upload media file or URL
curl --request POST \
  --url https://api.viddyscribe.com/enterprise/api/upload_media \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "input": {
    "type": "url",
    "url": "<string>",
    "filename": "<string>"
  }
}
'
{
  "media_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "duration_seconds": 45.5,
  "frame_rate": 30
}

Documentation Index

Fetch the complete documentation index at: https://docs.viddyscribe.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Usage Examples

​
1. Upload from URL

Ingest a video from a public URL. 
curl -X POST https://api.viddyscribe.com/enterprise/api/upload_media \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "url",
      "url": "https://example.com/video.mp4"
    }
  }'

​
2. Upload Local File

Upload a video file directly. For local files up to 32 MB, multipart upload is supported directly. For larger local files, see Large Local File Upload. 
curl -X POST https://api.viddyscribe.com/enterprise/api/upload_media \
  -H "X-API-Key: YOUR_API_KEY" \
  -F 'input={"type": "file"}' \
  -F "file=@/path/to/video.mp4"

​
3. Request a Signed Upload URL

For larger local files, request a signed upload URL first. 
curl -X POST https://api.viddyscribe.com/enterprise/api/upload_media \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "signed_url",
      "filename": "video.mp4",
      "content_type": "video/mp4"
    }
  }'
Then upload the file to upload_url, call notify_upload_complete, and poll get_upload_status until the upload is ready before generating with media_id. See Large Local File Upload for the full workflow.

​
Common Upload Errors

ErrorHTTP StatusDescription
no_video_stream415The uploaded file is not a valid video stream for processing. This usually means the file contains audio only.
video_too_long403The uploaded video exceeds the maximum duration allowed by the current plan.
file_too_large403The uploaded file exceeds the maximum file size allowed by the current plan.
Example response: 
{
  "error": "no_video_stream",
  "message": "The uploaded file contains audio only. Please upload a video file with at least one video stream."
}

Authorizations

​
X-API-Key
string
header
required

API key for authentication. Obtain from your team admin.

Example: X-API-Key: vsk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Body

​
input
Upload from URL · object
required

Response

Media uploaded successfully

​
media_id
string<uuid>

Unique identifier for the uploaded media

​
status
enum<string>

Upload status

Available options:
created,
existing,
pending_upload
​
duration_seconds
number | null

Video duration in seconds

​
frame_rate
number | null

Video frame rate (fps)

​
upload_url
string<uri> | null

Signed PUT URL returned for signed_url uploads

​
gcs_path
string | null

Storage path associated with the uploaded media

​
content_type
string | null

Content-Type associated with a signed upload