External API

The Vidori External API allows you to programmatically import video assets into your platform. You can import videos from URLs (which will be downloaded and transcoded) or link external CDN manifests (HLS/DASH) directly.

Base URL: https://app.vidori.co/api/v1

Authentication

All import requests require an API key. API keys are managed from the Vidori admin panel.

Creating an API Key

Log in to your Vidori admin panel
Open the user menu (top-right corner) and click API Keys
Click Create API Key and give it a name
Copy the key immediately — it will not be shown again

Using the API Key

Include your API key in the X-API-Key header with every request:

X-API-Key: vid_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Import Assets

`POST /api/v1/import`

Import one or more video assets.

Request

Headers:

Header	Required	Description
`X-API-Key`	Yes	Your API key
`Content-Type`	Yes	`application/json`

Body:

{
  "assets": [
    {
      "url": "https://example.com/video.mp4",
      "title": "My Video",
      "description": "A great video",
      "type": "MOVIE",
      "genres": ["Action", "Drama"],
      "tags": ["featured"],
      "production_year": 2024,
      "poster_url": "https://example.com/poster.jpg",
      "content_groups": ["Featured", "New Releases"]
    }
  ]
}

Asset Fields

Field	Type	Required	Description
`url`	string	One of `url` or `external_url`	Video source URL. The video will be downloaded and transcoded to HLS/DASH. Supports direct video URLs and 1000+ platforms (YouTube, Vimeo, etc.).
`external_url`	string	One of `url` or `external_url`	External CDN manifest URL (`.m3u8` for HLS or `.mpd` for DASH). The manifest is linked directly — no download or transcoding occurs.
`type`	string	No	Asset type. Default: `MOVIE`. See Asset Types.
`title`	string	No	Asset title. If not provided, title may be extracted from the video metadata.
`description`	string	No	Asset description.
`genres`	string[]	No	List of genre names (e.g. `["Action", "Drama"]`).
`tags`	string[]	No	List of tag names (e.g. `["featured", "new"]`).
`production_year`	integer	No	Production year (e.g. `2024`).
`poster_url`	string	No	URL of a poster image. All poster variants (landscape, portrait, square, etc.) will be auto-generated from this single image.
`content_groups`	string[]	No	List of content group names (not IDs). Groups are matched by exact name (case-insensitive). Unmatched names are returned as warnings.

Asset Types

Value	Description
`MOVIE`	Standalone video (default)
`EPISODE`	Episode of a series
`SERIES`	Series container
`SEASON`	Season container
`CHANNEL`	Linear channel
`EVENT`	One-time event
`NEWS`	News clip

Response

{
  "results": [
    {
      "asset_id": "550e8400-e29b-41d4-a716-446655440000",
      "job_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "status": "accepted",
      "warnings": []
    }
  ],
  "accepted": 1,
  "failed": 0
}

Field	Description
`asset_id`	UUID of the created asset. Use this to find the asset in the admin panel.
`job_id`	UUID of the ingest job. The job processes asynchronously (download, transcode, etc.).
`status`	`"accepted"` if the asset was submitted for processing, `"failed"` if an error occurred.
`warnings`	List of non-fatal warnings (e.g. unresolved content group names).
`error`	Error message if `status` is `"failed"`.

Limits

Maximum 50 assets per request
Assets are processed asynchronously — the response confirms submission, not completion

Examples

curl -X POST https://app.vidori.co/api/v1/import \
  -H "X-API-Key: vid_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {
        "url": "https://example.com/video.mp4",
        "title": "Getting Started",
        "description": "An introduction to our platform",
        "genres": ["Tutorial"],
        "poster_url": "https://example.com/thumbnail.jpg"
      }
    ]
  }'

curl -X POST https://app.vidori.co/api/v1/import \
  -H "X-API-Key: vid_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {
        "external_url": "https://cdn.example.com/videos/master.m3u8",
        "title": "Live Recording",
        "type": "MOVIE"
      }
    ]
  }'

curl -X POST https://app.vidori.co/api/v1/import \
  -H "X-API-Key: vid_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {
        "url": "https://example.com/video1.mp4",
        "title": "Episode 1",
        "type": "EPISODE",
        "content_groups": ["Season 1"]
      },
      {
        "url": "https://example.com/video2.mp4",
        "title": "Episode 2",
        "type": "EPISODE",
        "content_groups": ["Season 1"]
      }
    ]
  }'

Error Handling

HTTP Status Codes

Code	Description
`200`	Success. Check individual `results[].status` for per-asset outcomes.
`401`	Invalid, revoked, or missing API key.
`422`	Validation error (e.g. missing `url`/`external_url`, batch too large).
`500`	Internal server error.

Validation Error Response

{
  "detail": [
    {
      "loc": ["body", "assets", 0],
      "msg": "Either 'url' or 'external_url' must be provided",
      "type": "value_error"
    }
  ]
}

Partial Failures

A batch request may partially succeed. Always check each results[].status:

{
  "results": [
    {"asset_id": "...", "job_id": "...", "status": "accepted"},
    {"status": "failed", "error": "Invalid URL format"}
  ],
  "accepted": 1,
  "failed": 1
}

Processing Status

After import, assets are processed asynchronously. You can check the status of an asset in the Vidori admin panel under Catalog > On Demand. Asset statuses during processing:

Status	Description
`PROCESSING`	Video is being downloaded and/or transcoded
`READY`	Video is ready for playback
`FAILED`	Processing failed (check admin panel for details)