# ImageDescriber

public class **ImageDescriber** extends [Object](https://developer.android.com/reference/java/lang/Object.html)  
Provides an interface for performing image description.

It supports both standard and streaming inferences, as well as methods for preparing and
cleaning up model resources.

Typical usage:


     ImageDescriptionRequest request = ImageDescriptionRequest.builder(bitmap).build();

     ListenableFuture future = imageDescriber.runInference(request);
     Futures.addCallback(future, new FutureCallback<>() {
         @Override
         public void onSuccess(ImageDescriptionResult result) {
             Log.d(TAG, result.getDescription());
         }

         @Override
         public void onFailure(Throwable t) {
             Log.e(TAG, "Failed to describe", t);
         }
     }, executor);
     
### Public Method Summary

|---|---|
| ListenableFuture\<[Integer](https://developer.android.com/reference/java/lang/Integer.html)\> | [checkFeatureStatus](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriber#checkFeatureStatus())() Checks the current availability status of the image description feature. |
| void | [close](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriber#close())() Releases resources associated with the image description engine. |
| ListenableFuture\<[Void](https://developer.android.com/reference/java/lang/Void.html)\> | [downloadFeature](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriber#downloadFeature(com.google.mlkit.genai.common.DownloadCallback))(DownloadCallback callback) Downloads the required model assets for the image description feature if they are not already available. |
| ListenableFuture\<[String](https://developer.android.com/reference/java/lang/String.html)\> | [getBaseModelName](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriber#getBaseModelName())() Returns the name of the base model used by this image describer instance. |
| ListenableFuture\<[Void](https://developer.android.com/reference/java/lang/Void.html)\> | [prepareInferenceEngine](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriber#prepareInferenceEngine())() Prepares the inference engine for use by loading necessary models and initializing runtime components. |
| ListenableFuture\<[ImageDescriptionResult](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionResult)\> | [runInference](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriber#runInference(com.google.mlkit.genai.imagedescription.ImageDescriptionRequest,%20com.google.mlkit.genai.common.StreamingCallback))([ImageDescriptionRequest](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionRequest) request, StreamingCallback streamingCallback) Performs streaming image description inference on the provided image request. |
| ListenableFuture\<[ImageDescriptionResult](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionResult)\> | [runInference](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriber#runInference(com.google.mlkit.genai.imagedescription.ImageDescriptionRequest))([ImageDescriptionRequest](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionRequest) request) Performs asynchronous image description on the provided image request. |

### Inherited Method Summary

From class java.lang.Object

|---|---|
| [Object](https://developer.android.com/reference/java/lang/Object.html) | clone() |
| boolean | equals([Object](https://developer.android.com/reference/java/lang/Object.html) arg0) |
| void | finalize() |
| final [Class](https://developer.android.com/reference/java/lang/Class.html)\<?\> | getClass() |
| int | hashCode() |
| final void | notify() |
| final void | notifyAll() |
| [String](https://developer.android.com/reference/java/lang/String.html) | toString() |
| final void | wait(long arg0, int arg1) |
| final void | wait(long arg0) |
| final void | wait() |

## Public Methods

#### public ListenableFuture\<[Integer](https://developer.android.com/reference/java/lang/Integer.html)\>
**checkFeatureStatus** ()

Checks the current availability status of the image description feature.

##### Returns

- a `https://developers.google.com/android/reference/com/google/common/util/concurrent/ListenableFuture` resolving to a `https://developers.google.com/android/reference/com/google/mlkit/genai/common/FeatureStatus` indicating feature readiness.

#### public void **close** ()

Releases resources associated with the image description engine.

This should be called when the image describer is no longer needed. Can be safely
called multiple times.

#### public ListenableFuture\<[Void](https://developer.android.com/reference/java/lang/Void.html)\> **downloadFeature** (DownloadCallback callback)

Downloads the required model assets for the image description feature if they are
not already available.

Use this method to proactively download models before inference. The provided
`https://developers.google.com/android/reference/com/google/mlkit/genai/common/DownloadCallback`
is invoked to report progress and completion status.

##### Parameters

| callback | a non-null `https://developers.google.com/android/reference/com/google/mlkit/genai/common/DownloadCallback` for receiving download updates. |
|---|---|

##### Returns

- a `https://developers.google.com/android/reference/com/google/common/util/concurrent/ListenableFuture` that completes when the download finishes or fails. It completes immediately if already downloaded.

#### public ListenableFuture\<[String](https://developer.android.com/reference/java/lang/String.html)\>
**getBaseModelName** ()

Returns the name of the base model used by this image describer instance.

The model name may be used for logging, debugging, or feature gating purposes.

##### Returns

- a `https://developers.google.com/android/reference/com/google/common/util/concurrent/ListenableFuture` resolving to the base model name.

#### public ListenableFuture\<[Void](https://developer.android.com/reference/java/lang/Void.html)\> **prepareInferenceEngine** ()

Prepares the inference engine for use by loading necessary models and initializing
runtime components.

If the models haven't been downloaded yet, it will trigger the download and wait for
it to complete first.

While calling this method is optional, we recommend invoking it well before the
first inference call to reduce the latency of the initial inference.

##### Returns

- a cancellable `https://developers.google.com/android/reference/com/google/common/util/concurrent/ListenableFuture` that completes when the engine is ready.

#### public ListenableFuture\<[ImageDescriptionResult](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionResult)\>
**runInference** ([ImageDescriptionRequest](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionRequest) request, StreamingCallback streamingCallback)

Performs streaming image description inference on the provided image request.

Partial results are delivered incrementally through the provided `https://developers.google.com/android/reference/com/google/mlkit/genai/common/StreamingCallback`.
This is useful to build more responsive UI. Streaming can be interrupted by a
`https://developers.google.com/android/reference/com/google/mlkit/genai/common/GenAiException`.
In that case, consider removing any already streamed partial output from the UI.

The returned `https://developers.google.com/android/reference/com/google/common/util/concurrent/ListenableFuture`
is cancellable. If the inference is no longer needed (e.g., the user navigates away),
calling `future.cancel(true)` will attempt to interrupt the process and free
up resources.

Note that inference requests may fail under certain conditions such as:

- Invalid or malformed input in the `https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionRequest`
- Exceeded usage quota or failed safety checks

Appropriate `https://developers.google.com/android/reference/com/google/mlkit/genai/common/GenAiException` handling should be implemented when attaching the callback to the future.

##### Parameters

| request | a non-null `https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionRequest` containing the input image. |
| streamingCallback | a non-null `https://developers.google.com/android/reference/com/google/mlkit/genai/common/StreamingCallback` for receiving streamed results. |
|---|---|

##### Returns

- a cancellable `https://developers.google.com/android/reference/com/google/common/util/concurrent/ListenableFuture` resolving to the final `https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionResult`.

#### public ListenableFuture\<[ImageDescriptionResult](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionResult)\>
**runInference** ([ImageDescriptionRequest](https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionRequest) request)

Performs asynchronous image description on the provided image request.

This is the standard, non-streaming version of inference. The full description is
returned once the model completes processing.

This method is non-blocking. To handle the result, callers should attach a listener
to the returned `https://developers.google.com/android/reference/com/google/common/util/concurrent/ListenableFuture`
using `https://developers.google.com/android/reference/com/google/common/util/concurrent/Futures#addCallback(com.google.common.util.concurrent.ListenableFuture<V>,%20com.google.common.util.concurrent.FutureCallback<?%20super%20V>,%20java.util.concurrent.Executor)` or similar methods. The inference runs on background threads and
may complete at a later time depending on model availability and input size.

The returned `https://developers.google.com/android/reference/com/google/common/util/concurrent/ListenableFuture`
is cancellable. If the inference is no longer needed (e.g., the user navigates away),
calling `future.cancel(true)` will attempt to interrupt the process and free
up resources.

Note that inference requests may fail under certain conditions such as:

- Invalid or malformed input in the `https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionRequest`
- Exceeded usage quota or failed safety checks

Appropriate `https://developers.google.com/android/reference/com/google/mlkit/genai/common/GenAiException` handling should be implemented when attaching the callback to the future.

##### Parameters

| request | a non-null `https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionRequest` containing input image. |
|---|---|

##### Returns

- a cancellable `https://developers.google.com/android/reference/com/google/common/util/concurrent/ListenableFuture` that resolves to a `https://developers.google.com/android/reference/com/google/mlkit/genai/imagedescription/ImageDescriptionResult`.