Create Multimedia

This endpoint allows you to create new multimedia content in the system. The multimedia can be of various types including videos, images, audio, presentations, and immersive content, with additional configuration options for advanced use cases.

🔹 Endpoint Details

POST /api/v1/multimedia

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Request Structure

Required Fields

Field	Type	Required	Description	Example
name	string	Yes	Name of multimedia content	"Product Demo Video"
url	string	Yes	URL where multimedia is accessible	"https://example.com/videos/demo.mp4"
format	string	Yes	Format/MIME type of content	"video/mp4"

Optional Fields

Field	Type	Required	Description	Default
description	string	No	Detailed description	-
size	number	No	Size in bytes	-
duration	number	No	Duration in seconds	-
app	object	No	Application configuration	-
environment	object	No	Environment settings	{}
coverVideo	object	No	Cover video configuration	-
options	object	No	Additional options	-

🧩 Request Examples

Basic Video Upload

curl -X POST "https://openapi.onlive.site/api/v1/multimedia" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "name": "Product Demo Video",
  "url": "https://example.com/multimedia/video-123.mp4",
  "format": "video/mp4",
  "size": 5242880,
  "duration": 300
}'

Immersive Content Upload

curl -X POST "https://openapi.onlive.site/api/v1/multimedia" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "name": "Interactive 3D Experience",
  "description": "Immersive product demonstration with interactive elements",
  "url": "https://example.com/immersive/product-demo",
  "format": "application/immersive",
  "app": {
    "type": "browser",
    "source": {
      "url": "https://example.com/app/source",
      "security": "oauth2"
    },
    "resource": "/path/to/resource",
    "args": "lang=en&theme=dark"
  },
  "coverVideo": {
    "url": "https://example.com/videos/cover-123.mp4",
    "format": "mp4",
    "duration": 30
  },
  "options": {
    "usePixelStreaming": true,
    "showBooking": true,
    "showRegister": true,
    "timeout": 30000
  },
  "environment": {
    "region": "us-east-1",
    "encoding": "h264"
  }
}'

📤 Response Format

Success Response (201 Created)

{
  "id": "7a1c8d4b-3f2e-5697-9a8b-106c4d8e7f9a",
  "createdAt": "2025-05-28T14:30:45.123Z",
  "updatedAt": "2025-05-28T14:30:45.123Z",
  "organizationId": "9b8c7d6e-5f4a-3215-b9a8-c7d6e5f4a321",
  "name": "Interactive 3D Experience",
  "description": "Immersive product demonstration with interactive elements",
  "url": "https://example.com/immersive/product-demo",
  "format": "application/immersive",
  "status": "ready",
  "app": {
    "type": "browser",
    "source": {
      "url": "https://example.com/app/source",
      "security": "oauth2"
    },
    "resource": "/path/to/resource",
    "args": "lang=en&theme=dark"
  },
  "coverVideo": {
    "id": "5a4b3c2d-1e2f-3g4h-5i6j-7k8l9m0n1o2p",
    "url": "https://example.com/videos/cover-123.mp4",
    "format": "mp4",
    "size": 1048576,
    "duration": 30
  },
  "environment": {
    "region": "us-east-1",
    "encoding": "h264"
  },
  "options": {
    "usePixelStreaming": true,
    "timeout": 30000,
    "showBooking": true,
    "showRegister": true
  }
}

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input",
  "errors": [
    {
      "field": "url",
      "message": "url must be a valid URL"
    }
  ]
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions to create multimedia content"
}

413 Payload Too Large

{
  "statusCode": 413,
  "message": "Multimedia content exceeds size limit"
}

422 Unprocessable Entity

{
  "statusCode": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "format",
      "message": "unsupported multimedia format"
    }
  ]
}

📘 Notes

• The organizationId is automatically set from your authentication credentials
• For immersive content, the app configuration is required
• Supported formats include video/, image/, audio/*, and application/immersive
• Default status for newly created multimedia is "need_action"
• The system will validate content accessibility upon creation
• URLs must be publicly accessible or use authorized credentials

✅ Common Use Cases

• 🎥 Video Content: Upload product demonstrations, tutorials, or promotional videos
• 🖼️ Image Galleries: Create image collections for product showcases
• 🔊 Audio Files: Upload narrations, sound effects, or musical accompaniments
• 🌐 Immersive Experiences: Configure interactive 3D environments and simulations
• 📊 Presentations: Upload slide decks and interactive presentations

🔍 Validation Rules

1. Content Validation

   • URL must be accessible and valid
   • Format must be supported
   • Size must be within limits
   • Duration must be reasonable for content type

2. App Configuration Validation

   • Valid application type
   • Accessible source URL
   • Valid resource path
   • Proper security configuration

3. Cover Video Validation

   • Valid format
   • Accessible URL

4. Options Validation

   • Valid boolean flags
   • Timeout within acceptable range (5000-60000ms)

💡 Best Practices

1. Content Management

   • Use descriptive names and detailed descriptions
   • Include appropriate metadata (size, duration)
   • Ensure content is optimized for web delivery
   • Store content on CDNs for faster global delivery

2. Immersive Content

   • Test application before integration
   • Configure pixel streaming for high-quality experiences
   • Consider bandwidth requirements for end users

3. Cover Videos

   • Create engaging previews that highlight key features
   • Keep cover videos short and impactful
   • Ensure consistent formatting with main content

4. Security Considerations

   • Use secure URLs (HTTPS) for all content
   • Implement proper access controls for sensitive content
   • Consider content expiration for temporary access
   • Validate content source integrity