How to Use the Magika Python API to Identify Data from Bytes

Call Magika.identify_bytes() after initializing the Magika class to classify raw byte sequences and receive a MagikaResult object containing the detected content type, confidence score, and MIME type metadata.

The Google Magika library is an open-source file type identification system that uses deep learning to detect content types. When working with in-memory data rather than files on disk, the Magika Python API provides a streamlined interface to classify raw bytes efficiently.

Initializing the Magika Client

Before processing byte data, create an instance of the Magika class. According to the source code in python/src/magika/magika.py, the constructor loads the default ONNX model and initializes the inference pipeline.

from magika import Magika

magika = Magika()  # Uses default HIGH_CONFIDENCE prediction mode

This initialization process loads the neural network into memory, making subsequent identification calls fast. You can optionally customize the prediction_mode parameter to adjust confidence thresholds for ambiguous content.

Identifying Bytes with identify_bytes()

The identify_bytes() method serves as the primary entry point for classifying in-memory data. As implemented in python/src/magika/magika.py (lines 68-76), this method strictly validates that the input is a bytes object before processing.

Internally, the method:

1. Wraps the bytes in a Seekable stream using io.BytesIO
2. Forwards the stream to _get_result_from_seekable (lines 96-102)
3. Extracts features and runs the ONNX model via _get_result_or_features_from_seekable (lines 122-146)

Here is a complete working example:

from magika import Magika

# Initialize the client

magika = Magika()

# Sample byte data (truncated PNG header)

png_bytes = b'\x89PNG\r\n\x1a\n' + b'\x00' * 100

# Identify the content

result = magika.identify_bytes(png_bytes)

# Inspect results

print(f"Virtual path: {result.path}")          # Path("-") for bytes

print(f"Label: {result.output.label}")       # ContentTypeLabel.PNG

print(f"Score: {result.score}")              # 0.0 to 1.0

print(f"MIME type: {result.output.mime_type}") # "image/png"

print(f"Is text: {result.output.is_text}")   # False

Understanding the MagikaResult Object

The identify_bytes() method returns a MagikaResult instance defined in python/src/magika/types/magika_result.py. This object encapsulates three key properties:

• result.dl (lines 106-115): Contains the raw deep-learning prediction as a ContentTypeInfo object before confidence thresholding.
• result.output (lines 117-126): Provides the final content type after applying confidence thresholds and heuristics.
• result.score (lines 128-135): Returns the confidence score as a float between 0.0 and 1.0.

The ContentTypeInfo class (python/src/magika/types/content_type_info.py, lines 25-45) exposes human-readable metadata including:

• mime_type: The official MIME type string
• extensions: List of common file extensions
• description: Human-readable format description
• is_text: Boolean flag distinguishing text from binary formats

All content type identifiers are defined in the ContentTypeLabel enum (python/src/magika/types/content_type_label.py, lines 22-34), which includes values like TXT, PDF, PNG, and UNKNOWN.

Configuring Prediction Modes

Magika supports multiple prediction modes that control the confidence threshold for classification. By default, the API uses HIGH_CONFIDENCE mode, which returns UNKNOWN for ambiguous content rather than risk a false positive.

To accept lower-confidence predictions, specify MEDIUM_CONFIDENCE during initialization:

from magika import Magika

# Use medium confidence mode

magika = Magika(prediction_mode=Magika.PredictionMode.MEDIUM_CONFIDENCE)

# Identify text bytes

result = magika.identify_bytes(b'Hello, world!\n')
print(result.output.label)  # ContentTypeLabel.TXT

print(result.score)         # 1.0 (text heuristic bypasses DL model)

Summary

• Import the Magika class and instantiate it to load the ONNX model once for reuse across multiple calls.
• Call identify_bytes() to classify raw byte sequences; the method validates input and wraps bytes in an io.BytesIO stream internally before feature extraction.
• Access classification results through the MagikaResult object, specifically the output property for the final content type and score for the confidence value.
• Reference ContentTypeInfo for MIME types, file extensions, and text/binary classification flags according to python/src/magika/types/content_type_info.py.
• Adjust PredictionMode to balance between precision and coverage when identifying ambiguous byte sequences.

Frequently Asked Questions

What file types can the Magika Python API identify from bytes?

The API can identify hundreds of content types defined in the ContentTypeLabel enum (python/src/magika/types/content_type_label.py), including common formats like PDF, PNG, JavaScript, TXT, and proprietary document formats. The deep learning model analyzes content patterns rather than relying solely on file extensions.

How does Magika handle small or empty byte sequences?

According to the implementation in python/src/magika/magika.py, the _get_result_or_features_from_seekable method (lines 122-146) applies simple heuristics for edge cases. Empty files return immediate results without invoking the neural network, while very small files may bypass deep learning in favor of rule-based detection heuristics.

Can I process multiple byte sequences efficiently?

Yes. Since the Magika class loads the model once during initialization, you should reuse the same instance across multiple identify_bytes() calls. This avoids the overhead of reloading the ONNX model for each classification task and keeps memory usage constant.

What is the difference between the dl and output properties in MagikaResult?

The dl property (python/src/magika/types/magika_result.py, lines 106-115) returns the raw deep-learning prediction before confidence thresholding, while the output property (lines 117-126) returns the final content type after applying confidence thresholds and potential overrides. If the model's confidence is below the threshold, output may return UNKNOWN while dl shows the model's best guess.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}