Skip to main content

​
Overview

The Mocra Python SDK wraps the Mocra REST API and handles authentication, serialization, and error handling for you. Package: mocra — requires Python 3.10+

​
Installation

pip install mocra

​
Quick start

from mocra import VideoObservabilityApi, ExtraCriterion

api = VideoObservabilityApi("YOUR_API_KEY")
result = api.score_video(
    "https://example.org/video.mp4",
    extra_criteria=[
        ExtraCriterion(
            criterion_name="Blur",
            criterion_description="The video should not be blurry",
        ),
    ],
    ignore_criteria=["UNNATURAL PHYSICS"],
)

print(f"Overall score: {result.severity}")
for criterion in result.criteria:
    print(f"  {criterion.name}: {criterion.score}")

​
VideoObservabilityApi

The main client class. Instantiate it once with your API key and reuse it across requests. 
from mocra import VideoObservabilityApi

api = VideoObservabilityApi("YOUR_API_KEY")

​
Constructor parameters

ParameterTypeDefaultDescription
api_keystrrequiredYour Mocra API key. See the Quickstart to get one.
base_urlstr | None"https://api.mocra.io"Override the API base URL. Useful for testing.
timeoutfloat60.0Request timeout in seconds.
http_clienthttpx.Client | NoneNoneBring your own pre-configured httpx.Client (e.g. with custom proxies or retry logic).

​
score_video()

Analyzes a video against Mocra’s built-in criteria and any custom criteria you provide. 
result = api.score_video(
    video_url,
    extra_criteria=[...],   # optional
    ignore_criteria=[...],  # optional
)

​
Parameters

ParameterTypeDefaultDescription
video_urlstrrequiredPublicly accessible URL of the video to analyze.
extra_criterialist[ExtraCriterion][]Additional custom criteria to evaluate.
ignore_criterialist[str | DefaultCriterion][]Built-in criteria to exclude from the analysis. Accepts raw strings (e.g. "UNNATURAL PHYSICS") or DefaultCriterion enum values.

​
Returns: ObserveResponse

FieldTypeDescription
severityfloatOverall quality score from 1 (worst) to 100 (best).
criterialist[CriterionScore]Per-criterion breakdown. Each item has name: str and score: float (1–100).

​
ExtraCriterion

Defines a custom quality criterion to include in the analysis. 
from mocra import ExtraCriterion

criterion = ExtraCriterion(
    criterion_name="Blur",
    criterion_description="The video should not be blurry",
)
FieldTypeDescription
criterion_namestrShort label for the criterion.
criterion_descriptionstrFull description of what the criterion checks.

​
DefaultCriterion

An enum of the built-in criteria that Mocra evaluates by default. Pass one or more values to ignore_criteria to exclude them from the analysis. 
from mocra import DefaultCriterion

result = api.score_video(
    "https://example.org/video.mp4",
    ignore_criteria=[
        DefaultCriterion.UNNATURAL_PHYSICS,
        DefaultCriterion.FLICKERING,
    ],
)
ValueString equivalent
DefaultCriterion.UNNATURAL_PHYSICS"UNNATURAL PHYSICS"
DefaultCriterion.MORPHING"MORPHING"
DefaultCriterion.FLICKERING"FLICKERING"
DefaultCriterion.ARTIFACTING"ARTIFACTING"
DefaultCriterion.TEXT_ISSUES"TEXT ISSUES"

​
Error handling

The SDK raises MocraError when the API returns a non-200 response, and httpx.HTTPError for network-level failures. 
from mocra import VideoObservabilityApi, MocraError
import httpx

api = VideoObservabilityApi("YOUR_API_KEY")

try:
    result = api.score_video("https://example.org/video.mp4")
except MocraError as e:
    print(f"API error {e.status_code}: {e.message}")
except httpx.HTTPError as e:
    print(f"Network error: {e}")

​
MocraError

AttributeTypeDescription
messagestrHuman-readable error description from the API response.
status_codeint | NoneHTTP status code of the failed response.

​
Context manager

Use VideoObservabilityApi as a context manager to ensure the underlying HTTP connection is closed when you’re done: 
from mocra import VideoObservabilityApi, ExtraCriterion

with VideoObservabilityApi("YOUR_API_KEY") as api:
    result = api.score_video(
        "https://example.org/video.mp4",
        extra_criteria=[
            ExtraCriterion(
                criterion_name="Blur",
                criterion_description="The video should not be blurry",
            ),
        ],
    )
    print(result.severity)
You can also call api.close() manually if you are not using the context manager.