Skip to content
rdlabo.devdocs
日本語

API

Public on-device LLM plugin contract.

method getAvailability()

getAvailability() => Promise<GetAvailabilityResult>

Returns detailed text-model availability. Web feature-detects Chrome's Prompt API; unsupported browsers return unavailable.

Returns: Promise<GetAvailabilityResult>

Since: 2.0.0

method getImageAnalysisAvailability()

getImageAnalysisAvailability() => Promise<GetImageAnalysisAvailabilityResult>

Returns image-analysis availability and the native backend that would handle vision input.
On iOS 27 builds compiled with Xcode 27 / Swift 6.4, returns the text-model status plus
backend: 'foundation-models' and maxImages: 4. Builds made with older Xcode report
unavailable and cannot include iOS 27 vision support. Android reports Gemini Nano prompt
APIs or a configured LiteRT-LM fallback. Web currently reports unavailable for image analysis.

Returns: Promise<GetImageAnalysisAvailabilityResult>

Since: 2.1.0

method downloadModel()

downloadModel() => Promise<void>

Starts an Android or Chrome Web model download. On Web, invoke from a user gesture; Chrome manages the model.

Since: 2.0.0

method configureFallbackModel(...)

configureFallbackModel(options: ConfigureFallbackModelOptions) => Promise<void>

Initializes an explicit Android LiteRT-LM fallback model. Gemini Nano remains preferred when available.
Configuring a model performs local file I/O and may take significant time. iOS and Web reject this API.

Param Type
options ConfigureFallbackModelOptions

Since: 2.0.0

method warmup(...)

warmup(options?: WarmupOptions | undefined) => Promise<void>

Warms model resources. Web creates and destroys a temporary text session; promptPrefix is iOS-only.

Param Type
options WarmupOptions

Since: 1.0.0

method createChat(...)

createChat(options?: CreateChatOptions | undefined) => Promise<CreateChatResult>

Creates a chat owned by the plugin until deletion.

Param Type
options CreateChatOptions

Returns: Promise<CreateChatResult>

Since: 2.0.0

method deleteChat(...)

deleteChat(options: DeleteChatOptions) => Promise<void>

Deletes a chat and cancels its generation.

Param Type
options DeleteChatOptions

Since: 2.0.0

method generateText(...)

generateText(options: GenerateTextOptions) => Promise<GenerateTextResult>

Generates complete text.

Param Type
options GenerateTextOptions

Returns: Promise<GenerateTextResult>

Since: 2.0.0

method streamText(...)

streamText(options: StreamTextOptions) => Promise<StreamTextResult>

Streams native chunks and returns complete text.

Param Type
options GenerateTextOptions

Returns: Promise<GenerateTextResult>

Since: 2.0.0

method cancelGeneration(...)

cancelGeneration(options: CancelGenerationOptions) => Promise<void>

Cancels an in-flight generation.

Param Type
options CancelGenerationOptions

Since: 2.0.0

method addListener('availabilityChange', ...)

addListener(eventName: 'availabilityChange', listenerFunc: AvailabilityChangeListener) => Promise<PluginListenerHandle>

Listens for availability changes. Web emits changes observed during availability checks and session creation/download.

Param Type
eventName 'availabilityChange'
listenerFunc AvailabilityChangeListener

Returns: Promise<PluginListenerHandle>

Since: 2.0.0

method addListener('systemAvailabilityChange', ...)

addListener(eventName: 'systemAvailabilityChange', listenerFunc: SystemAvailabilityChangeListener) => Promise<PluginListenerHandle>
Param Type
eventName 'systemAvailabilityChange'
listenerFunc SystemAvailabilityChangeListener

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

method addListener('downloadProgress', ...)

addListener(eventName: 'downloadProgress', listenerFunc: DownloadProgressListener) => Promise<PluginListenerHandle>

Listens for Android or Chrome Web download progress.

Param Type
eventName 'downloadProgress'
listenerFunc DownloadProgressListener

Returns: Promise<PluginListenerHandle>

Since: 2.0.0

method addListener('textChunk', ...)

addListener(eventName: 'textChunk', listenerFunc: TextChunkListener) => Promise<PluginListenerHandle>

Listens for native text chunks.

Param Type
eventName 'textChunk'
listenerFunc TextChunkListener

Returns: Promise<PluginListenerHandle>

Since: 2.0.0

method addListener('generationStateChange', ...)

addListener(eventName: 'generationStateChange', listenerFunc: GenerationStateChangeListener) => Promise<PluginListenerHandle>

Listens for generation start, completion, cancellation, and failure.

Param Type
eventName 'generationStateChange'
listenerFunc GenerationStateChangeListener

Returns: Promise<PluginListenerHandle>

Since: 2.1.0

method removeAllListeners()

removeAllListeners() => Promise<void>

Removes every plugin listener.

Since: 1.0.0

method generateImage(...)

generateImage(options: GenerateImageOptions) => Promise<GenerateImageResponse>

Generates PNG images on iOS.

Param Type
options GenerateImageOptions

Returns: Promise<GenerateImageResponse>

Since: 1.0.0

method systemAvailability()

systemAvailability() => Promise<SystemAvailabilityResponse>

Returns: Promise<SystemAvailabilityResponse>

Since: 1.0.0

method download()

download() => Promise<void>

Since: 1.0.0

method prompt(...)

prompt(options: PromptOptions) => Promise<PromptResponse>
Param Type
options PromptOptions

Returns: Promise<PromptResponse>

Since: 1.0.0

method endSession(...)

endSession(options: EndSessionOptions) => Promise<void>

Ends a legacy session. Already-ended or unknown session identifiers succeed without effect.

Param Type
options EndSessionOptions

Since: 1.0.0

Interfaces

interface GetAvailabilityResult

Result returned by availability checks.

Prop Type Description Since
status Availability Current text-model availability. 2.0.0

interface GetImageAnalysisAvailabilityResult

Result returned by image-analysis availability checks.

Prop Type Description Since
status Availability Current image-analysis availability. 2.1.0
backend ImageAnalysisBackend Native backend that would handle image analysis when available. 2.1.0
maxImages number Maximum images accepted in one generation for the active backend. 2.1.0

interface ConfigureFallbackModelOptions

Configures an opt-in Android LiteRT-LM fallback used when Gemini Nano is unavailable.
The model must already exist as an app asset or a readable app-managed file. iOS and Web reject this API.

Prop Type Description Since
path string .litertlm model path. Use /android_asset/... for bundled assets or an absolute app-managed file path. 2.0.0
maxTokens number Combined context capacity passed to LiteRT-LM. Defaults to 4096. 2.0.0
maxImages number Maximum images accepted by one generation for a vision-capable model. Defaults to 1. 2.0.0
supportsImages boolean Initializes LiteRT-LM's vision pipeline. Defaults to true; set to false only for a text-only model. 2.0.0

interface WarmupOptions

Warmup options. Android performs global model warmup; iOS can prewarm a chat.
Web creates and releases a temporary session, optionally using a chat's context.

Prop Type Description Since
chatId string Explicit chat identifier to prewarm on iOS or use as context for Web warmup. 2.0.0
sessionId string 1.0.0
promptPrefix string Optional prompt prefix used by Foundation Models. 1.0.0

interface CreateChatResult

Result containing the plugin-owned chat identifier.

Prop Type Description Since
id string Identifier required by generation and deletion calls. 2.0.0

interface CreateChatOptions

Options for creating an owned chat.

Prop Type Description Since
instructions string Persistent system instructions for this chat. 2.0.0
history ChatHistoryOptions History limits applied on iOS, Android, and Web. 2.0.0

interface ChatHistoryOptions

Chat history limits. All implementations retain instructions and discard oldest whole turns.

Prop Type Description Since
maxMessages number Maximum retained messages. Defaults to 20. 2.0.0
maxCharacters number Maximum retained message characters. Defaults to 12000. 2.0.0

interface DeleteChatOptions

Options for deleting a chat.

Prop Type Description Since
id string Chat identifier returned by createChat(). 2.0.0

interface GenerateTextResult

Result of a text generation.

Prop Type Description Since
text string Complete generated text. 2.0.0
generationId string Identifier that can correlate diagnostics with a generation. 2.0.0

interface GenerateTextOptions

Options for a non-streaming generation.

Prop Type Description Since
chatId string Chat identifier returned by createChat(). 2.0.0
prompt string User prompt. 2.0.0
images ImageInput[] Images supplied to a vision-capable backend. On iOS 27+ (builds compiled with Xcode 27 / Swift 6.4), Foundation Models Attachment accepts up to 4 images of at most 32 MiB each via readable absolute paths, file:// URLs, raw Base64, or Base64 data URLs; after a successful generation, attachments are removed from retained chat history while the text prompt and response remain. Android uses Gemini Nano prompt APIs or a configured LiteRT-LM fallback with absolute/file:///content:///Base64 input and ML Kit aggregate pixel limits. Web and text-only backends reject image input with LOCAL_LLM_UNSUPPORTED. 2.1.0
imagePaths string[] Local image paths supplied to a vision-capable Android LiteRT-LM fallback model. Absolute paths, file:// URLs, and readable content:// URIs are accepted. This compatibility path retains the v2.0 LiteRT-LM routing even when ML Kit is available. 2.0.0
options GenerationOptions Optional generation controls. 2.0.0

interface ImageUriInput

Local URI image input.

Prop Type Description Since
uri string Image URI. iOS accepts readable absolute local paths and file:// URLs. Android accepts absolute paths, file:// URLs, and content:// URIs. 2.1.0
base64 Base64 and URI inputs are mutually exclusive. 2.1.0

interface Base64ImageInput

Base64-encoded image input.

Prop Type Description Since
base64 string Raw Base64 image bytes or a data:image/...;base64,... URL. The decoded image must not exceed 32 MiB. 2.1.0
uri Base64 and URI inputs are mutually exclusive. 2.1.0

interface GenerationOptions

Cross-platform text generation controls. Unsupported values are rejected, not clamped. Chrome Web requires these controls to be omitted.

Prop Type Description Since
temperature number Sampling temperature. 2.0.0
topK number Samples from the k most likely tokens. 2.0.0
maxOutputTokens number Maximum generated tokens. 2.0.0

interface CancelGenerationOptions

Options for cancelling an in-flight generation.

Prop Type Description Since
chatId string Chat that owns the generation. 2.0.0
generationId string Optional generation identifier; a mismatch is treated as not found. 2.0.0

interface PluginListenerHandle

Prop Type
remove () => Promise<void>

interface SystemAvailabilityResponse

Prop Type Description Since
status LLMAvailability Legacy availability value. Detailed states are folded into the original four-value contract. 1.0.0

interface DownloadProgressEvent

Model download progress. Intermediate Android events omit progress because ML Kit has no total byte count.

Prop Type Description Since
progress number Known normalized progress: 0 at start and 1 at completion. 2.0.0
downloadedBytes number Bytes downloaded so far when supplied by ML Kit. 2.0.0
totalBytes number Total bytes, when a platform SDK supplies it. Currently omitted on Android. 2.0.0

interface TextChunkEvent

Incremental text emitted by streamText().

Prop Type Description Since
chatId string Chat that owns the generation. 2.0.0
generationId string Identifier of this generation. 2.0.0
text string Newly generated text only, not the accumulated snapshot. 2.0.0

interface GenerationStateChangeEvent

Lifecycle event emitted for both generateText() and streamText().

Prop Type Description Since
chatId string Chat that owns the generation. 2.1.0
generationId string Native generation identifier, available from the started event. 2.1.0
state GenerationState Current lifecycle state. 2.1.0
errorCode LocalLLMErrorCode Stable error code for cancelled and failed states. 2.1.0

interface GenerateImageResponse

Image generation result.

Prop Type Description Since
pngBase64Images string[] Raw base64 PNG images without a data-URI prefix. 1.0.0

interface GenerateImageOptions

Image generation options. Image generation is available only on iOS 18.4+.

Prop Type Description Since
prompt string Image description. 1.0.0
promptImages string[] Optional base64 reference images. 1.0.0
count number Number of variations. Defaults to 1. 1.0.0

interface PromptResponse

Legacy prompt response.

Prop Type Description Since
text string Complete generated text. 1.0.0

interface PromptOptions

Legacy prompt options.

Prop Type Description Since
sessionId string Optional legacy session identifier. 1.0.0
instructions string Instructions used when the legacy session is first created. 1.0.0
options LLMOptions Legacy generation controls. 1.0.0
prompt string User prompt. 1.0.0

interface LLMOptions

Prop Type Description Since
temperature number Sampling temperature. 1.0.0
maximumOutputTokens number Maximum generated tokens. 1.0.0

interface EndSessionOptions

Legacy session deletion options.

Prop Type Description Since
sessionId string Legacy session identifier. 1.0.0

Type Aliases

type alias Availability

The semantic availability of the on-device text model.

'available' | 'device-not-eligible' | 'not-enabled' | 'downloadable' | 'downloading' | 'not-ready' | 'unavailable'

type alias ImageAnalysisBackend

Native backend selected for on-device image analysis.

'foundation-models' | 'ml-kit-prompt' | 'litert-lm'

type alias ImageInput

Image reference for vision-capable text generation.

ImageUriInput | Base64ImageInput

type alias StreamTextOptions

Options for native streaming generation.

GenerateTextOptions

type alias StreamTextResult

Final result of a native streaming generation.

GenerateTextResult

type alias AvailabilityChangeListener

Listener for availability changes.

(event: GetAvailabilityResult): void

type alias SystemAvailabilityChangeListener

(event: SystemAvailabilityResponse): void

type alias LLMAvailability

'available' | 'unavailable' | 'notready' | 'downloadable'

type alias DownloadProgressListener

Listener for model download progress.

(event: DownloadProgressEvent): void

type alias TextChunkListener

Listener for native generation chunks.

(event: TextChunkEvent): void

type alias GenerationStateChangeListener

Listener for native generation lifecycle changes.

(event: GenerationStateChangeEvent): void

type alias GenerationState

Native generation lifecycle state.

'started' | 'completed' | 'cancelled' | 'failed'

type alias LocalLLMErrorCode

Stable Local LLM error codes.

'LOCAL_LLM_NOT_AVAILABLE' | 'LOCAL_LLM_DEVICE_NOT_ELIGIBLE' | 'LOCAL_LLM_NOT_ENABLED' | 'LOCAL_LLM_MODEL_NOT_READY' | 'LOCAL_LLM_MODEL_DOWNLOAD_REQUIRED' | 'LOCAL_LLM_CONTEXT_WINDOW_EXCEEDED' | 'LOCAL_LLM_CHAT_NOT_FOUND' | 'LOCAL_LLM_CHAT_BUSY' | 'LOCAL_LLM_GENERATION_NOT_FOUND' | 'LOCAL_LLM_GENERATION_CANCELLED' | 'LOCAL_LLM_INVALID_OPTIONS' | 'LOCAL_LLM_UNSUPPORTED' | 'LOCAL_LLM_IMAGE_NOT_READABLE' | 'LOCAL_LLM_IMAGE_TOO_LARGE' | 'LOCAL_LLM_GENERATION_FAILED' | 'LOCAL_LLM_IMAGE_GENERATION_FAILED' | 'LOCAL_LLM_UNKNOWN_ERROR'

Edit this page on GitHub