Replicate Dart Client

A community-maintained Dart client package for Replicate.com, this package let you interact with Replicate.com APIs and create predictions from the available machine learning models.

Key Features.

Easy to call methods for creating, Getting, Cancelling one prediction, and getting a pagination lists of predictions used.
Stream availability for listening to a predictions changes in realtime.
Dynamic inputs for the possibility to use any model available on Replicate.com flexibly.
Wrappers around response fields, for a better developer experience.
Easy to configure, and set your settings using this library.

Full Documentation

You can check the Full Documentation of this library from here.

Usage

Authentication

Before making any requests, you should set your API key so it will be used to make requests to your account on Replicate.com.

  Replicate.apiKey = "<YOUR_API_KEY>";

Recommendation:

it's better to load your api key from a .env file, you can do this in Dart using dotenv package.

Create Prediction

You can call this to start creating a new prediction for the version and input you will provide, since the models can take some time to run, This output will not be available immediately, it will return a Prediction with the returned response from Replicate.com, with a status set to the prediction status at this point:

Prediction prediction = await Replicate.instance.predictions.create(
    version: "<MODEL_VERSION>",
    input: {
      "field_name": "<field_value>",
    },
  );

Note that input takes a Map<String, dynamic> as a value since every model has its input accepted fields.

if you want to create a new prediction for a model that accepts a file field(s), you need just to set that field(s) value to either a network url , or the base64 of that file.

Get Prediction

if you need to get a Prediction at a specific point in time, you can call the Replicate.instance.predictions.get() method, it will return a new Prediction object with the requested prediction data:

Prediction prediction = await Replicate.instance.predictions.get(
    id: "<PREDICTION_ID>",
);

print(prediction); // ...

A Prediction object is a container for prediction progress data (status, logs, output, metrics... ) requested from your Replicate.com dashboard.

When a Prediction is Terminated, the metrics property will have a predictTime property with the amount of CPU or GPU time, in seconds, that this prediction used while running. This is the time you're billed for, and it doesn't include time waiting for the prediction to start.

A Prediction is considered terminated when the status property is one of :

PredictionStatus.succeeded
PredictionStatus.canceled
PredictionStatus.failed

You might want to give a quick look over Get Prediction.

Cancel Prediction

You can cancel a running prediction by calling Replicate.instance.predictions.cancel() :

final canceledPrediction = await Replicate.instance.predictions.cancel(
  id: "<PREDICTION_ID>",
);

Get list of predictions

You can get a paginated list of predictions that you've created with your account by calling :

PaginatedPredictions predictionsPageList = await Replicate.instance.predictions.list();

print(predictionsPageList.results); // ...

This includes predictions created from the API and the Replicate website. Returns 100 records per page.

You can check before requesting the next/previous pagination lists:

if (predictionsPageList.hasNextPage) {
  PaginatedPredictions next = await predictionsPageList.next();
  print(next.results); // ...
}
if (predictionsPageList.hasPreviousPage) {
  PaginatedPredictions prev = await predictionsPageList.previous();
  print(prev.results); // ...
}

Listening to prediction changes.

After Creating a new prediction with Create Prediction, while it is running, you can get a Stream of its changes in real-time by calling:

Stream<Prediction> predictionStream = Replicate.instance.predictions.snapshots(
    id: "<PREDICTION_ID>",
);

predictionStream.listen((Prediction prediction) {
   print(prediction.status); // ...
});

By default, every time the status of the prediction changes, a new Prediction will be emitted to the predictionStream, but you can change and configure this behavior to meet your specific needs by specifying a pollingInterval, shouldTriggerOnlyStatusChanges, stopPollingRequestsOnPredictionTermination..

This functionality is based on polling request as it's recommended by replicate from here.

I don't want to listen to changes by `Stream`.

Well, Replicate.com offers also notifying with webhook feature.

while creating a prediction, you can set the webhookCompleted property to your HTTPS URL which will receive the response when the prediction is completed:

Prediction prediction = await Replicate.instance.predictions.create(
    version: "<MODEL_VERSION>",
    input: {
      "field_name": "<field_value>",
    },
    webhookCompleted: "<YOUR_HTTPS_URL>", // add this
  );

learn more about the webhook feature from here

Get Model

Gets a single model, based on it's owner and name, and returns it as a [ReplicateModel].

ReplicateModel model = await Replicate.instance.models.get(
  modelOwner: "replicate",
  modelNme: "hello-world",
);

print(model);  // ...
print(model.url);  // ...
print(model.owner); // replicate

Get a list of model versions

Gets a model's versions as a paginated list, based on it's owner and name.

if you want to get a specific version, check Get A Model Version.

You can load the next and previous pagination list of a current on, by using next() and previous() method.

if no next or previous pages exists for a pagination list, a NoNextPageException or NoPreviousPageException will be thrown.

For avoiding those exceptions at all, you can check for the next and previos pages existence using the hasNextPage and hasPreviousPage :

PaginatedModels modelVersions = await Replicate.instance.model.versions(
 modelOwner: "replicate",
 modelNme: "hello-world",
);

print(modelVersions.results); // ...

// loads the next page if it exists
if (modelVersions.hasNextPage) {
 PaginatedModels nextPage = await modelVersions.next();

 print(nextPage.results); // ...
}

Get A Model Version

Gets a single model version, based on it's owner, name, and version id.

if you want to get a list of versions, check Get a list of model versions.

PaginationModel modelVersion = await Replicate.instance.models.version(
 modelOwner: "replicate",
 modelNme: "hello-world",
 versionId: "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
);

print(modelVersion.id); // ...

Delete A Model.

Delete a model version and all associated predictions, including all output files.

await Replicate.instance.models.delete(
 modelOwner: "/* Owner */",
 modelNme: "/* Model Name */",
 versionId: "/* Version Id */",
);

if the file os deleted succefully, nothing will happen actually, so you should expect that the model is deleted if none happens in your code, However, when something goes wrong ( if you try to delete a model which you don't own, a ReplicateException will be thrown with the error message ).

Get a collection of models.

Loads a collection of models.

ModelsCollection collection = await Replicate.instance.models.collection(
collectionSlug: "super-resolution",
);

  print(collection.name); // super resolution
  print(collection.models); // ...

Error Handling

ReplicateException

This exception will be thrown when there is an error from the replicate.com end, as example when you hit the rate limit you will get a ReplicateException with the message and the status code of the erorr:

try {
// ...

} on ReplicateException carch(e) {
print(e.message);
print(e.statusCode);
}

NoNextPageException, NoPreviousPageException

These are special and limited exception when working with Get A List Of Model Versions, when you try to get the next() or previous() of a pagintaed list that don't exist, one of those exceptions will be thrown, but the way to avoid them totally are included in the documentation.

try {
PaginatedModels firstPage = // ...
page.previous(); // obviously, there is no previous for first page, right?

} on NoPreviousPageException catch(e) {
print(// no next for this paginated list.);
}

CoocooFroggy/replicate