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
media = Video.from_path("example.mp4")
prediction_result = await client.classification.predict_video(
media=media,
model_name="dragoneye/animals", # 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 childTaxonPrediction
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 ofClassificationObjectPrediction
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
: AMedia
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
: AMedia
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"
: returnsClassificationPredictImageResponse
. - If
prediction_type="video"
: returnsClassificationPredictVideoResponse
.
Notes
- All public methods are asynchronous. Use
asyncio.run
or an async loop to call them. - For images, always use
predict_image
. For videos, usepredict_video
. Passing the wrong media type will raise anIncorrectMediaTypeError
. - Predictions are executed as tasks: the SDK automatically handles task creation, media upload, polling, and result retrieval.