Skip to main content

Using the Node SDK

The Dragoneye Node.js SDK simplifies integrating with our APIs in your JavaScript/TypeScript projects. This guide covers installation, example usage, type definitions, and available endpoints.

Installation​

Install the SDK using npm:

npm install dragoneye-node

Quick Start​

Prerequisites

Don't have an API key yet? See Creating an Access Token.

Once installed, you can call the classifier using your desired model:

import { Dragoneye } from "dragoneye-node";

const dragoneyeClient = new Dragoneye({
  apiKey: "<YOUR_ACCESS_TOKEN>",
});

// Example: predict from an image
const image = await Dragoneye.Image.fromFilePath("example.jpg");
const imageResult = await dragoneyeClient.classification.predictImage(
  image,
  "recognize_anything/your_model_name" // change to your desired model
);

// 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.
const video = await Dragoneye.Video.fromFilePath("example.mp4", "any-file-name");
const videoResult = await dragoneyeClient.classification.predictVideo(
  video,
  "recognize_anything/your_model_name"
);

// Accessing image results
for (const obj of imageResult.object_predictions) {
  console.log("Bbox:", obj.normalizedBbox);
  for (const pred of obj.predictions) {
    console.log(
      `  Category: ${pred.category.name} (score: ${pred.category.score})`
    );
    for (const attr of pred.attributes) {
      for (const opt of attr.options) {
        console.log(`      ${opt.name}: ${opt.score}`);
      }
    }
  }
}
Model names

Model names follow the format recognize_anything/model_name. Use the name you specified when creating the model — see Creating a Custom Vision Model for more details.

Example Video Response​

Below is an example of what a ClassificationPredictVideoResponse looks like for a Building Detection model. The response maps each sampled frame's timestamp (in microseconds) to the objects detected in that frame:

{
  prediction_task_uuid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  original_file_name: "any-file-name",
  frames_per_second: 1,
  timestamp_us_to_predictions: {
    0: [
      {
        frame_id: "frame_0",
        timestamp_microseconds: 0,
        normalizedBbox: [0.12, 0.25, 0.55, 0.78],
        predictions: [
          {
            category: {
              id: 2084323334,
              name: "House (detached)",
              score: 0.92,
            },
            attributes: [
              {
                attribute_id: 1371766615,
                name: "Building Exterior Color",
                options: [
                  { option_id: 3498033303, name: "White / Off-white", score: 0.85 },
                  { option_id: 496739380, name: "Light gray", score: 0.10 },
                  // ... remaining options omitted for brevity
                ],
              },
              {
                attribute_id: 448392115,
                name: "Building Exterior Material",
                options: [
                  { option_id: 3887467550, name: "Wood (incl. timber siding)", score: 0.78 },
                  { option_id: 562768697, name: "Brick", score: 0.12 },
                  // ...
                ],
              },
              {
                attribute_id: 4240554102,
                name: "Building Size (Stories)",
                options: [
                  { option_id: 3067238669, name: "2 stories", score: 0.91 },
                  { option_id: 2398426374, name: "1 story", score: 0.06 },
                  // ...
                ],
              },
            ],
          },
        ],
      },
      {
        frame_id: "frame_0",
        timestamp_microseconds: 0,
        normalizedBbox: [0.60, 0.30, 0.88, 0.75],
        predictions: [
          {
            category: {
              id: 3212613421,
              name: "Garage (detached)",
              score: 0.87,
            },
            attributes: [
              // ... attributes omitted for brevity
            ],
          },
        ],
      },
    ],
    1000000: [
      // Objects detected at t=1s (1,000,000 microseconds)
      // ...
    ],
  },
}

Each timestamp key (e.g., 0, 1000000) corresponds to a sampled frame. Within each frame, every detected object has its own bounding box, category prediction with a confidence score, and attribute predictions with scored options.

Types and Endpoints​

Types​

The response types form a nested hierarchy. Here's how they fit together for image predictions:

ClassificationPredictImageResponse
└── object_predictions: ClassificationObjectPrediction[]
    ├── normalizedBbox: [x_min, y_min, x_max, y_max]
    └── predictions: ClassificationCategoryPrediction[]
        ├── category: ClassificationCategory { id, name, score }
        └── attributes: ClassificationAttributeResponse[]
            └── options: ClassificationAttributeOption[] { option_id, name, score }

For video predictions, ClassificationPredictVideoResponse maps timestamps to arrays of ClassificationVideoObjectPrediction (which extends ClassificationObjectPrediction with frame_id and timestamp_microseconds).

NormalizedBbox​

Represents the location of an object in an image. It is an array of four numbers: [x_min, y_min, x_max, y_max].

export type NormalizedBbox = [number, number, number, number];

PredictionTaskUUID​

A branded string type representing a prediction task UUID.

export type PredictionTaskUUID = Brand<string, "PredictionTaskUUID">;

PredictionType​

Defines whether a prediction is for an "image" or a "video".

export type PredictionType = "image" | "video";

ClassificationAttributeOption​

Represents a single option within an attribute prediction.

export interface ClassificationAttributeOption {
  option_id: number;
  name: string;
  score: number;
}

ClassificationAttributeResponse​

Contains the attribute prediction with its possible options.

export interface ClassificationAttributeResponse {
  attribute_id: number;
  name: string;
  options: ClassificationAttributeOption[];
}

ClassificationCategory​

Represents a predicted category for a detected object.

export interface ClassificationCategory {
  id: number;
  name: string;
  score: number;
}

ClassificationCategoryPrediction​

Combines a category prediction with its associated attribute predictions.

export interface ClassificationCategoryPrediction {
  category: ClassificationCategory;
  attributes: ClassificationAttributeResponse[];
}

ClassificationObjectPrediction​

Represents a predicted object in an image.

export interface ClassificationObjectPrediction {
  normalizedBbox: NormalizedBbox;
  predictions: ClassificationCategoryPrediction[];
}

ClassificationPredictImageResponse​

Response structure for image predictions.

export interface ClassificationPredictImageResponse {
  object_predictions: ClassificationObjectPrediction[];
  original_file_name?: string;
  prediction_task_uuid: PredictionTaskUUID;
}

ClassificationVideoObjectPrediction​

Extends ClassificationObjectPrediction with video-specific fields.

export interface ClassificationVideoObjectPrediction
  extends ClassificationObjectPrediction {
  frame_id: string;
  timestamp_microseconds: number;
}

ClassificationPredictVideoResponse​

Response structure for video predictions. Predictions are keyed by timestamp in microseconds.

export interface ClassificationPredictVideoResponse {
  timestamp_us_to_predictions: Record<
    number,
    ClassificationVideoObjectPrediction[]
  >;
  frames_per_second: number;
  original_file_name?: string;
  prediction_task_uuid: PredictionTaskUUID;
}

PredictionTaskStatusResponse​

Represents the status of an async prediction task.

export interface PredictionTaskStatusResponse {
  prediction_task_uuid: PredictionTaskUUID;
  prediction_type: PredictionType;
  status: PredictionTaskState; // e.g. "predicted", "failed"
}

Endpoints​

dragoneyeClient.classification.predictImage​

await dragoneyeClient.classification.predictImage(
  media: Image,
  modelName: string,
  timeoutSeconds?: number,
): Promise<ClassificationPredictImageResponse>

Performs a classification prediction on a single image.

ParameterTypeDefaultDescription
mediaImagerequiredAn Image object (from fromFilePath, fromBlob, fromUrl, etc.).
modelNamestringrequiredThe name of the model to use for prediction.
timeoutSecondsnumberundefinedMaximum wait time in seconds. Throws PredictionTaskError on timeout. undefined polls indefinitely.

Returns: Promise<ClassificationPredictImageResponse> — detected objects and their predictions.

dragoneyeClient.classification.predictVideo​

await dragoneyeClient.classification.predictVideo(
  media: Video,
  modelName: string,
  framesPerSecond: number = 1,
  timeoutSeconds?: number,
): Promise<ClassificationPredictVideoResponse>

Performs a classification prediction on a video.

ParameterTypeDefaultDescription
mediaVideorequiredA Video object (from fromFilePath, fromBlob, fromUrl, etc.).
modelNamestringrequiredThe name of the model to use for prediction.
framesPerSecondnumber1How many frames per second to sample from the video.
timeoutSecondsnumberundefinedMaximum wait time in seconds. Throws PredictionTaskError on timeout. undefined polls indefinitely.

Returns: Promise<ClassificationPredictVideoResponse> — frame-level prediction results.

dragoneyeClient.classification.getStatus​

await dragoneyeClient.classification.getStatus(
  predictionTaskUuid: PredictionTaskUUID,
): Promise<PredictionTaskStatusResponse>

Checks the status of an in-progress prediction task.

ParameterTypeDefaultDescription
predictionTaskUuidPredictionTaskUUIDrequiredThe UUID of the prediction task.

Returns: Promise<PredictionTaskStatusResponse> — the task's current status.

dragoneyeClient.classification.getImageResults​

await dragoneyeClient.classification.getImageResults(
  predictionTaskUuid: PredictionTaskUUID,
): Promise<ClassificationPredictImageResponse>

Fetches the results of a completed image prediction task.

ParameterTypeDefaultDescription
predictionTaskUuidPredictionTaskUUIDrequiredThe UUID of the prediction task.

Returns: Promise<ClassificationPredictImageResponse>

dragoneyeClient.classification.getVideoResults​

await dragoneyeClient.classification.getVideoResults(
  predictionTaskUuid: PredictionTaskUUID,
): Promise<ClassificationPredictVideoResponse>

Fetches the results of a completed video prediction task.

ParameterTypeDefaultDescription
predictionTaskUuidPredictionTaskUUIDrequiredThe UUID of the prediction task.

Returns: Promise<ClassificationPredictVideoResponse>

Error Handling​

The SDK defines the following error types:

ErrorWhen it's thrown
PredictionTaskErrorThe prediction task failed on the server or timed out.
PredictionUploadErrorThe media file could not be uploaded.
PredictionTaskBeginErrorThe prediction task could not be started.
PredictionTaskResultsUnavailableErrorResults were requested for a task that has not completed.
IncorrectMediaTypeErrorWrong media type was passed (e.g., a Video to predictImage).
import { Dragoneye } from "dragoneye-node";

try {
  const result = await dragoneyeClient.classification.predictImage(
    image,
    "recognize_anything/your_model_name"
  );
} catch (error) {
  if (error instanceof Dragoneye.Common.PredictionUploadError) {
    console.error("Failed to upload media — check file path and format");
  } else if (error instanceof Dragoneye.Common.PredictionTaskError) {
    console.error("Prediction task failed on the server");
  }
}

Notes​

  • All methods are asynchronous and return Promises.
  • For images, always use predictImage. For videos, use predictVideo. Passing the wrong media type will throw an IncorrectMediaTypeError.
  • Predictions run as tasks: the SDK automatically begins the task, uploads media, initiates prediction, polls for completion, and retrieves results.