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

> Use the Magika Python API to identify data from bytes. Call Magika.identifyBytes() to classify raw byte sequences and get content type, confidence, and MIME type.

- Repository: [Google/magika](https://github.com/google/magika)
- Tags: how-to-guide
- Published: 2026-04-16

---

**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`](https://github.com/google/magika/blob/main/python/src/magika/magika.py), the constructor loads the default ONNX model and initializes the inference pipeline.

```python
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`](https://github.com/google/magika/blob/main/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:

```python
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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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:

```python
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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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.