Ingest Video Url

POST

ingest

videos

url

curl --request POST \
  --url https://api.mixpeek.com/v1/ingest/videos/url \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/sample-video.mp4",
  "collection": "col_1234567890",
  "asset_update": {
    "asset_id": "<string>",
    "mode": "replace"
  },
  "metadata": {
    "author": "John Doe",
    "category": "Research Paper",
    "tags": [
      "AI",
      "Machine Learning"
    ]
  },
  "skip_duplicate": true,
  "feature_extractors": [
    {
      "interval_sec": 15,
      "read": {
        "enabled": true
      },
      "embed": [
        {
          "embedding_model": "multimodal",
          "type": "url"
        },
        {
          "embedding_model": "text",
          "type": "text",
          "value": "lorem ipsum"
        }
      ],
      "transcribe": {
        "enabled": true
      },
      "describe": {
        "enabled": true
      },
      "detect": {
        "faces": {
          "confidence_threshold": 0.8,
          "enabled": true
        }
      },
      "json_output": {
        "response_shape": {
          "objects": [
            "str"
          ],
          "scenes": [
            "str"
          ]
        }
      },
      "entities": {
        "taxonomy_extraction": {
          "taxonomy": "tax_123",
          "assignment": {
            "enabled": false,
            "mode": "threshold",
            "append": false,
            "confidence_threshold": 0.5
          }
        }
      }
    }
  ]
}'

{
  "task_id": "<string>",
  "status": "PENDING",
  "inputs": [
    "<any>"
  ],
  "outputs": [
    "<any>"
  ]
}

Headers

Authorization

string | null

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings. Example: 'Bearer sk_1234567890abcdef'

X-Namespace

string | null

Optional namespace for data isolation. This can be a namespace name or namespace ID. Example: 'netflix_prod' or 'ns_1234567890'. To create a namespace, use the /namespaces endpoint.

Body

application/json

url

string

required

The URL of the asset to be processed. Must be a valid HTTP or HTTPS URL.

collection

string

required

Unique identifier for the collection where the processed asset will be stored, can be the collection name or collection ID. If neither exist, the collection will be created.

asset_update

object | null

Controls how processing results are stored - either creating a new asset or updating an existing one.

metadata

object

Additional metadata associated with the asset. Can include any key-value pairs relevant to the asset.

skip_duplicate

boolean | null

default:

true

Makes feature extraction idempotent. When True and a duplicate file hash is found, copies features from the existing asset instead of reprocessing. This allows the same file to be used multiple times with different metadata while avoiding redundant processing.

feature_extractors

object[] | null

Settings for video processing. Only applicable if the URL points to a video file.

feature_extractors.interval_sec

integer

default:

Interval in seconds for processing video. Must be greater than or equal to 5, less than 120.

Required range: 5 <= x <= 120

feature_extractors.read

object | null

Settings for reading and analyzing video content.

feature_extractors.embed

object[]

List of embedding settings for generating multiple embeddings. For now, if url is provided, value must be None. Default: [{type: 'url', embedding_model: 'multimodal'}] if none provided.

        Request model for embedding generation.
        
        When multiple EmbeddingRequests use the same embedding_model:
        - All inputs will be embedded in the same vector space
        - The final embedding will be the average of all individual embeddings
        - Original values will be stored with a ' | ' separator
        
        Example:
            Two requests with same model "clip":
            1. type: "text", value: "a dog", embedding_model: "clip"
            2. type: "url", value: "https://example.com/image.jpg", embedding_model: "clip"
            
            Result:
            - vectors["clip"] = average of both embeddings
            - embedding_configs["clip"] = "a dog | https://example.com/image.jpg"

feature_extractors.transcribe

object | null

Settings for transcribing video audio.

feature_extractors.describe

object | null

Settings for generating video descriptions.

feature_extractors.detect

object | null

Settings for object detection in video frames.

feature_extractors.json_output

object | null

Settings for structured JSON output of video analysis.

feature_extractors.entities

object | null

Settings for extracting entities from video content

Response

200

application/json

Successful Response

task_id

string

required

status

enum<string>

Available options:

DONE,

FAILED,

SKIPPED,

CANCELLED,

PROCESSING,

DOWNLOADING,

INITIALIZING,

UPLOADING,

QUEUED,

PENDING

inputs

any[] | null

outputs

any[] | null

Was this page helpful?

Suggest edits Raise issue

Ingest Text Ingest Image Url

curl --request POST \
  --url https://api.mixpeek.com/v1/ingest/videos/url \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/sample-video.mp4",
  "collection": "col_1234567890",
  "asset_update": {
    "asset_id": "<string>",
    "mode": "replace"
  },
  "metadata": {
    "author": "John Doe",
    "category": "Research Paper",
    "tags": [
      "AI",
      "Machine Learning"
    ]
  },
  "skip_duplicate": true,
  "feature_extractors": [
    {
      "interval_sec": 15,
      "read": {
        "enabled": true
      },
      "embed": [
        {
          "embedding_model": "multimodal",
          "type": "url"
        },
        {
          "embedding_model": "text",
          "type": "text",
          "value": "lorem ipsum"
        }
      ],
      "transcribe": {
        "enabled": true
      },
      "describe": {
        "enabled": true
      },
      "detect": {
        "faces": {
          "confidence_threshold": 0.8,
          "enabled": true
        }
      },
      "json_output": {
        "response_shape": {
          "objects": [
            "str"
          ],
          "scenes": [
            "str"
          ]
        }
      },
      "entities": {
        "taxonomy_extraction": {
          "taxonomy": "tax_123",
          "assignment": {
            "enabled": false,
            "mode": "threshold",
            "append": false,
            "confidence_threshold": 0.5
          }
        }
      }
    }
  ]
}'

{
  "task_id": "<string>",
  "status": "PENDING",
  "inputs": [
    "<any>"
  ],
  "outputs": [
    "<any>"
  ]
}

Health

Features

Ingest Assets

Entities

Assets

Collections

Namespaces

Feature Extractors

Tasks

Ingest Video Url

Headers

Body

Response