Importing Videos via Viostream API

→

The Viostream REST API provides a powerful way to programmatically import videos and integrate video management into your applications. This method is ideal for automation, bulk operations, custom integrations, and when you need to programmatically generate embed codes.

Developer Feature

This import method requires programming knowledge and API integration capabilities. For standard uploads, consider using the web interface import options instead.

Prerequisites

Before you can import via API, ensure you have:

• A Viostream account with API access enabled
• Videos hosted on publicly accessible URLs
• Programming knowledge (examples use cURL, Python, JavaScript)
• Understanding of REST API concepts

API Authentication

The Viostream API uses HTTP Basic Authentication. You can create an API key in the Developer Tools section of the  Settings page.

• Username: Your Viostream Access Key (starting with VC-)
• Password: The API key generated above.
• Base URL: https://api.app.viostream.com/v3/api

Getting API Credentials

1. Contact Customer Success to enable API access for your account
2. Retrieve your API credentials from the Developer Tools section of the  Settings page
3. Test authentication with the account info endpoint

curl -u "VC-xxxxxxxx:your-api-key" "https://api.app.viostream.com/v3/api/account/info"

Import Workflow Overview

The API import process involves these steps:

1. Create Media Ingest: Submit video URL for processing
2. Monitor Status: Check ingest progress
3. Find Media by Reference ID: Locate the media using your reference ID
4. Generate Embed Code: Use public ID to create embed URLs

Step 1: Create Media Ingest

Use the /v3/api/media/new endpoint to start importing a video:

warning

Ensure that you use a unique referenceId to ensure you can find the media later. This ID can be any string you choose, such as a video title or identifier.

cURL Example

curl -X POST "https://api.app.viostream.com/v3/api/media/new" \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "sourceUrl": "https://example.com/video.mp4",
    "filename": "Marketing Video Q1 2025",
    "extension": "mp4",
    "referenceId": "mv-q1-2024-001"
  }'

Python Example

import requests
import json

# API configuration
api_base = "https://api.app.viostream.com/v3/api"
username = "your-username"
password = "your-password"

# Media ingest data
ingest_data = {
    "sourceUrl": "https://example.com/video.mp4",
    "filename": "Marketing Video Q1 2024",
    "extension": "mp4",
    "referenceId": "mv-q1-2024-001"
}

# Create media ingest
response = requests.post(
    f"{api_base}/media/new",
    auth=(username, password),
    headers={"Content-Type": "application/json"},
    data=json.dumps(ingest_data)
)

if response.status_code == 200:
    ingest_result = response.json()
    ingest_id = ingest_result["ingestId"]
    print(f"Ingest created with ID: {ingest_id}")
else:
    print(f"Error creating ingest: {response.status_code}")
    print(response.text)

JavaScript/Node.js Example

const axios = require('axios');

const apiBase = 'https://api.app.viostream.com/v3/api';
const credentials = {
  username: 'your-username',
  password: 'your-password'
};

const ingestData = {
  sourceUrl: 'https://example.com/video.mp4',
  filename: 'Marketing Video Q1 2024',
  extension: 'mp4',
  referenceId: 'mv-q1-2024-001'
};

async function createIngest() {
  try {
    const response = await axios.post(
      `${apiBase}/media/new`,
      ingestData,
      {
        auth: credentials,
        headers: { 'Content-Type': 'application/json' }
      }
    );

    const ingestId = response.data.ingestId;
    console.log(`Ingest created with ID: ${ingestId}`);
    return ingestId;
  } catch (error) {
    console.error('Error creating ingest:', error.response?.data || error.message);
  }
}

Request Parameters

• sourceUrl (required): Direct URL to the video file
• filename (required): Display name for the video
• extension (required): File extension (mp4, mov, avi, etc.)
• referenceId (optional): Your custom identifier for tracking

Response

{
  "ingestId": "<randomly-generated-uuid>"
}

Step 2: Monitor Ingest Status

Use the /v3/api/media/new/status/{ingestId} endpoint to check progress:

Python Monitoring Example

import time

def wait_for_ingest_completion(ingest_id, max_wait_time=3600):
    """
    Monitor ingest status until completion or timeout
    """
    start_time = time.time()

    while time.time() - start_time < max_wait_time:
        response = requests.get(
            f"{api_base}/media/new/status/{ingest_id}",
            auth=(username, password)
        )

        if response.status_code == 200:
            status_data = response.json()
            status = status_data.get("status")

            print(f"Ingest status: {status}")

            if status == "Online":
                return True
            elif status == "Failed":
                print(f"Ingest failed: {status_data.get('error')}")
                return None
            elif status in ["Processing"]:
                time.sleep(30)  # Wait 30 seconds before checking again
            else:
                print(f"Unknown status: {status}")
                return None
        else:
            print(f"Error checking status: {response.status_code}")
            return None

    print("Ingest timed out")
    return None

# Use the monitoring function
if wait_for_ingest_completion(ingest_id):
    print(f"Video processing completed. Media ID")

Status Values

• Online: Video is ready for viewing
• Processing: Video is being transcoded and processed
• Failed: An error occurred during processing

Step 3: Find Media by Reference ID

Before retrieving media details, you need to find the media ID using your reference ID:

Find Media by Reference ID

def find_media_by_reference_id(reference_id):
    """
    Find media ID using the reference ID
    """
    response = requests.get(
        f"{api_base}/media",
        auth=(username, password),
        params={
            "referenceId": reference_id
        }
    )

    if response.status_code == 200:
        media_list = response.json()
        try:
            items = media_list["listResult"]["items"]
        except KeyError:
            print(f"Malformed response from API")

        if len(items["items"]) > 0:
            return items[0]
        else:
            print(f"No media found with reference ID: {reference_id}")
            return None
    else:
        print(f"Error finding media: {response.status_code}")
        return None

# Find the media ID using reference ID
media_details = find_media_by_reference_id("mv-q1-2025-001")
if media_details:
    public_key = media_details.get("key")
    title = media_details.get("title")
    duration = media_details.get("duration")

    print(f"Video: {title}")
    print(f"Public key: {public_key}")
    print(f"Duration: {duration}")

Media Detail Response

{
  "id": "media_xyz789abc123",
  "key": "abc123def456",
  "title": "Marketing Video Q1 2025",
  "description": null,
  "duration": "00:01:05",
  "status": "Online",
  "createdDate": "2025-08-08T10:30:00Z",
  "referenceId": "mv-q1-2025-001",
  "thumbnail": "https://cdn.viostream.com/thumbnails/abc123def456_small.jpg",
}

Step 4: Generate Embed Codes

Use the public ID to create embed URLs and iframe codes:

Embed URL Construction

def generate_embed_code(public_key):
    """
    Generate iframe embed code from public key
    """
    # Base embed URL
    embed_url = f"https://play.viostream.com/iframe/{public_key}"

    # Generate iframe code
    iframe_code = f'''<div style="padding-bottom:56.25%; position:relative; display:block; width:100%">
      <iframe
        width="100%"
        height="100%"
        src="{embed_url}"
        referrerpolicy="strict-origin-when-cross-origin"
        allow="autoplay; encrypted-media; picture-in-picture"
        allowfullscreen
        frameBorder="0"
        style="position:absolute; top: 0; left: 0">
      </iframe>
    </div>'''

    return {
        "embed_url": embed_url,
        "iframe_code": iframe_code
    }

Best Practices

1. Rate Limiting: Don't exceed reasonable request rates
2. Timeout Handling: Set appropriate timeouts for long operations
3. Error Recovery: Implement retry logic with exponential backoff
4. Logging: Log all API interactions for debugging
5. Validation: Validate URLs and parameters before API calls

Supported File Formats

The API supports the same formats as other import methods:

• MP4 (recommended)
• MOV
• AVI
• WMV
• MKV
• WEBM
• 3GP

API Rate Limits

Be mindful of API limitations:

• Request rate: Reasonable intervals between API calls
• File size: Large files take longer to process

Contact Customer Success for specific rate limit information.

Troubleshooting

Common Issues

Authentication failures:

# Test authentication
curl -u "username:password" "https://api.app.viostream.com/v3/api/account/info"

Invalid URLs:

• Ensure URLs are publicly accessible
• Verify URLs point directly to video files
• Test URLs in browser first

Timeout issues:

• Increase timeout values for large files
• Monitor ingest status more frequently
• Consider breaking large imports into smaller batches

Additional Resources

• Viostream API Documentation
• Supported File Formats

For API access setup, rate limit information, or webhook configuration, contact Customer Success with your integration requirements.