Skip to main content

Using the Python SDK

If you're integrating with our APIs using Python, the Dragoneye SDK streamlines the process with minimal setup. Here's how you can get started and explore the types and endpoints in detail.

Installation​

Install the package using pip.

pip install dragoneye-python

Quick Start​

To call the classifier, follow these steps:

import asyncio
from dragoneye import Dragoneye, Video

async def main():
    client = Dragoneye(api_key="<YOUR_ACCESS_TOKEN>")

    # Example: predict from a video
    # NOTE! When loading a file, you can optionally pass a file name or identifier
    # that you use to identify your own files.
    media = Video.from_path(
        path="example.mp4",
        name="any-file-name",
    )
    prediction_result = await client.classification.predict_video(
        media=media,
        model_name="recognize_anything/your_model_name",  # change to your desired model
    )

    print(prediction_result)

asyncio.run(main())

Types and Endpoints​

Types​

TaxonType (Enum) Represents the type of taxon in the prediction.

  • CATEGORY: Represents a category taxon.
  • TRAIT: Represents a trait taxon.

TaxonPrediction Represents a predicted taxon (category or trait) returned by the API.

Attributes:

  • id: Unique identifier for the taxon (TaxonID).
  • type: The type of the taxon (TaxonType).
  • name: The internal name of the taxon.
  • displayName: The user-friendly name of the taxon.
  • score: Optional confidence score for the prediction.
  • children: A sequence of nested child TaxonPrediction objects.

ClassificationObjectPrediction Represents the prediction of an object in an image.

Attributes:

  • normalizedBbox: A bounding box for the detected object (coordinates are normalized).
  • category: The predicted category for the object (TaxonPrediction).
  • traits: A sequence of trait predictions (ClassificationTraitRootPrediction).

ClassificationPredictImageResponse The response object returned after predicting an image.

Attributes:

  • predictions: A sequence of ClassificationObjectPrediction results.

ClassificationPredictVideoResponse The response object returned after predicting a video.

Attributes:

  • predictions: Frame-level predictions across the video.

PredictionTaskStatusResponse Represents the status of a prediction task.

Attributes:

  • prediction_task_uuid: The unique identifier for the task.
  • status: The current task status (predicted, failed, etc.).

TaxonID Type alias for taxon IDs, represented as an int.

NormalizedBbox Type alias for normalized bounding boxes, represented as a tuple of four float values.

Endpoints​

predict_image (Image Classification)​

Performs a classification prediction on a single image.

Arguments:

  • media: A Media object wrapping an image (from file, bytes, or URL).
  • model_name: The name of the model to be used for the prediction.

Response: Returns a ClassificationPredictImageResponse object containing prediction results.

predict_video (Video Classification)​

Performs a classification prediction on a video.

Arguments:

  • media: A Media object wrapping a video.
  • model_name: The name of the model to be used for the prediction.
  • frames_per_second: How many frames per second to sample from the video.

Response: Returns a ClassificationPredictVideoResponse object containing frame-level prediction results.

status (Prediction Task Status)​

Checks the status of a prediction task.

Arguments:

  • prediction_task_uuid: The UUID of the prediction task.

Response: Returns a PredictionTaskStatusResponse object containing the task’s status.

get_results (Retrieve Prediction Results)​

Retrieves the results of a completed prediction task.

Arguments:

  • prediction_task_uuid: The UUID of the prediction task.
  • prediction_type: Either "image" or "video".

Response:

  • If prediction_type="image": returns ClassificationPredictImageResponse.
  • If prediction_type="video": returns ClassificationPredictVideoResponse.

Notes​

  • All public methods are asynchronous. Use asyncio.run or an async loop to call them.
  • For images, always use predict_image. For videos, use predict_video. Passing the wrong media type will raise an IncorrectMediaTypeError.
  • Predictions are executed as tasks: the SDK automatically handles task creation, media upload, polling, and result retrieval.