Run Wiro AI models from Android and Kotlin apps with WiroKit, the official Wiro SDK for Kotlin and Android, covering Gradle setup, client auth, typed and catalog model runs with coroutines and Flows, file uploads and task control. Use when Kotlin, Android or Jetpack Compose code generates images, video, speech, music or LLM output with Wiro, or when the user mentions WiroKit.
WiroKit for Kotlin and Android
WiroKit (ai.wiro:wirokit) is the official Kotlin library for the Wiro AI API on Android. It runs any model in the Wiro catalog through typed request factories or Wiro.model, tracks each task by polling or WebSocket with coroutines and Flows, and uploads input files for you. Source and a Jetpack Compose sample app: https://github.com/wiroai/Kotlin-QuickStart.
WiroKit is an Android library (AAR). For Kotlin on a server or desktop JVM, call the REST API instead (see the last section).
Install
Requirements: Android minSdk 26+, Kotlin 2.4+, JDK 17+ for builds, and a Wiro project with an API key (https://wiro.ai/panel/project/new).
// module build.gradle.kts, with mavenCentral() in your repositories
dependencies {
implementation("ai.wiro:wirokit:0.1.0")
}
- Version catalog:
wirokit = { module = "ai.wiro:wirokit", version = "0.1.0" }, thenimplementation(libs.wirokit). - If the artifact does not resolve from Maven Central yet, clone the Kotlin-QuickStart repo, run
./gradlew :wirokit:publishToMavenLocaland addmavenLocal()beforemavenCentral()in your repositories. RemovemavenLocal()once the Maven Central release is out. - The SDK manifest already declares the
INTERNETpermission, and the AAR ships its own R8 consumer rules.
Create a client
Keep Wiro credentials off the device. WiroKit's guidance is proxy mode for shipped apps, so long-lived API secrets never ship inside the binary; a key on the device is for local development and debug builds. Never hard-code, commit or log keys, secrets or proxy tokens. If the user has no key, send them to https://wiro.ai/panel/project/new and do not ask them to paste it into the chat.
// Shipped apps: your backend adds the Wiro credentials
val client = WiroClient(
proxyUrl = "https://api.myapp.com/wiro/v1",
headers = mapOf("Authorization" to "Bearer app-token"),
)
// Debug builds: API key
val client = WiroClient(apiKey = "YOUR_API_KEY")
// Debug builds of a signature project: key plus secret, every request HMAC signed
val client = WiroClient(apiKey = "YOUR_API_KEY", apiSecret = "YOUR_API_SECRET")
- Proxy mode stores no Wiro key. It sends the normal REST paths (
/Run/{owner}/{project},/Task/Detail,/Task/Cancel,/Task/Kill,/File/Upload,/Tool/List,/Tool/Detail,/Tool/Explore) toproxyUrlwith yourheaders. Your backend checks its own user, adds the Wiro auth headers, forwards the call tohttps://api.wiro.ai/v1and returns Wiro's response unchanged. - Pass
apiSecretonly for a project that uses signature auth (https://wiro.ai/docs/authentication). - Name the first argument (
apiKey =orproxyUrl =), since both constructors take aStringfirst. - Optional settings:
requestTimeout,pollInterval,retryPolicy,logger, andokHttpClientto share your app's OkHttp client. The SDK's default client setsretryOnConnectionFailure(false); set it on yours too, so OkHttp does not retry calls after connection failures on its own. WiroClientisCloseable. Keep one app-scoped instance, orclose()each client you own.
Money rules
- Before any paid run (a live test, the sample app, a script), tell the user the model, the settings and the expected cost from the model's page on https://wiro.ai/models or https://wiro.ai/product/pricing. A finished
WiroTaskreports its cost intotalCost. - Ask first for large or open-ended jobs: many outputs, long videos, loops or batches.
- Each
run,runModel,subscribeorsubscribeStreamcall starts a new billable task. After a timeout or a dropped connection, never resubmit the same run blindly. Look the task up first (see Control and errors). App code follows the same rule: no automatic resubmits. - Cancel or kill a task only when the user asks.
Run a model
import ai.wiro.wirokit.Wiro
import ai.wiro.wirokit.WiroTaskResult
import ai.wiro.wirokit.subscribe
val result = client.subscribe(
Wiro.flux2Pro(prompt = "A cinematic mountain lake", width = 1024, height = 1024),
)
when (result) {
is WiroTaskResult.Success -> println(result.task.outputs.firstOrNull()?.url)
is WiroTaskResult.Failure -> println("Failed: ${result.reason}")
}
- Typed factories on
Wiro:flux2Pro,gptImage2,nanoBananaPro,seedreamV4,grokImagineImage(image),runwayGen45,seedance20,klingV3,veo31,sora2Pro,hailuo23Fast,grokImagineVideo(video) andlyria3(music). They check inputs and throwWiroValidationExceptionbefore any network call. - Every other catalog model, speech and LLMs included, runs through
Wiro.model:
val request = Wiro.model(
slug = "black-forest-labs/flux-2-pro",
parameters = mapOf(
"prompt" to WiroValue.StringValue("Sunset over the bay"),
"width" to WiroValue.number(1024),
"height" to WiroValue.number(1024),
),
) // then client.subscribe(request)
- Find slugs with
client.searchModels(search = "...")(each of.itemshas amodelId) orclient.explore().client.getModelSchema(WiroModelId("owner", "project"))describes the inputs: each entry ofschema.parametershas aname(the key to send) andisRequired, andschema.validate(parameters)returns a list of problems, empty when the map fits. - Live updates:
client.subscribeStream(request)returns aFlow<WiroTaskUpdate>(Snapshot,Eventwith progress,Binary). The billable run starts before the Flow is returned, so collecting it again only re-tracks the same task.trackingMode = WiroTaskTrackingMode.WEB_SOCKETstreams socket events with a polling fallback; both modes end on a terminalSnapshot. - Start now and wait later, the pattern to use when you may need to recover:
val run = client.run(request) // starts one billable task
val token = requireNotNull(run.taskToken) // persist run.taskId and the token
val task = client.waitForTask(token)
- Outputs:
task.outputsholdsWiroTaskOutputitems withurl(ajava.net.URI),contentType,nameandisImage,isVideo,isAudio,isText. LLM replies are in an output'scontent?.answers(plusthinkingandrawText), and the merged text is intask.debugOutput.task.isSuccessfulmeans it completed with exit code 0. subscribe,subscribeStream,run,waitForTaskand theContentResolveroverloads are extension functions, so import them fromai.wiro.wirokit.
Files
val bytes = WiroFileInput.Bytes(bytes = imageBytes, fileName = "photo.png")
val photo = WiroFileInput.ContentUri(uri = contentUri, fileName = "photo.png") // streamed
val result = client.subscribe(
Wiro.flux2Pro(prompt = "The same lake at night", inputImages = listOf(photo)),
contentSource = WiroUriContentSource.from(contentResolver),
)
- File inputs inside the run parameters are uploaded automatically before
/Run.ContentUriinputs need acontentSource, or therunModel(..., contentResolver = contentResolver)overload. WiroFileInput.Url(URI("https://..."))sends a public file URL as is.- In a
Wiro.modelmap, wrap a file asWiroValue.FileInputValue(input). - To reuse a file, upload it once:
client.uploadFile(bytes)orclient.uploadFile(photo, contentResolver)returns aWiroUploadResultwhosefilescarry the hostedurl.
Control and errors
- Cancelling the coroutine or
Jobthat collects stops local work at once; rethrowCancellationException. It does not stop the task on Wiro. - To stop it on Wiro, only when the user asks:
client.cancelTask(taskId)while it is queued,client.killTask(token)orclient.killTask(taskId)once it runs. Both return aBoolean. - A task that finishes unsuccessfully is a
WiroTaskResult.Failurewith areason(CANCELLED,NON_ZERO_EXIT,OTHER), not an exception. - Thrown errors extend
WiroException:WiroValidationException,WiroAuthenticationException,WiroApiResultException(the API answeredresult: false, seecode),WiroRateLimitException(retryAfter),WiroNetworkException,WiroWebSocketException,WiroUnknownApiExceptionandWiroTimeoutException. Error codes: https://wiro.ai/docs/error-reference. - Retries:
WiroRetryPolicy.Defaultretries transient failures with exponential backoff and respectsretryAfter;WiroRetryPolicy.Noneturns retries off./Runand uploads are never retried automatically. - Timeouts:
requestTimeoutcovers one HTTP call, andtimeoutonsubscribe,subscribeStreamandwaitForTaskcovers tracking (defaultWiroTracking.DEFAULT_TIMEOUT). AWiroTimeoutExceptionmeans the task was still running at the deadline. - Recovering: after a
WiroTimeoutException, aWiroNetworkExceptionor a dropped connection, look the task up withclient.getTask(token)orclient.getTaskById(id), or keep waiting withclient.waitForTask(token). Withsubscribe, keep the token fromonUpdate(Snapshot.task.taskToken). Ifrunitself failed and you hold no id, ask the user to check the dashboard (https://wiro.ai/panel) before sending it again. - Never log keys, secrets, proxy tokens or raw response bodies. Use
rawResponseBodyonly for local diagnostics.
Android and Compose
Patterns from the sample app (app/ in the repo):
// In a ViewModel; the show* calls stand for your own StateFlow updates.
generationJob = viewModelScope.launch {
try {
client.subscribeStream(request).collect { update ->
update.status?.let { showStatus(it.apiValue) }
if (update is WiroTaskUpdate.Snapshot && update.task.status.isTerminal) {
val task = update.task
if (task.isSuccessful) {
showImages(task.outputs.mapNotNull { it.url?.toASCIIString() })
} else {
showError(task.debugOutput ?: "Generation failed")
}
}
}
} catch (error: CancellationException) {
throw error
} catch (error: WiroException) {
showError(error.toFriendlyMessage()) // the sample's safe UI text helper
}
}
- Read the
StateFlowin Compose withcollectAsStateWithLifecycle(), and keep theJobfor a local cancel. - Save
task.idandtask.taskTokenfrom snapshots (ormessage.idandmessage.taskTokenfrom WebSocket events) so a cancel or kill button can use them. - The sample opens a client per generation and closes it in
finallyand inonCleared(). - Render images with Coil:
AsyncImage(model = url, ...)fromio.coil-kt.coil3:coil-composewithcoil-network-okhttp. - Do not restart a billable run automatically after process death; start one only when the user taps Generate again.
- Release builds of the sample accept only a backend proxy URL (
BuildConfig.ALLOW_DIRECT_CREDENTIALSis false there), and debug builds keep a typed-in key encrypted with Android Keystore-backed AES-GCM. Keepandroid:allowBackup="false"if the app stores secrets.
More
- The REST API and the Wiro MCP server are covered by the general skill:
npx skills add wiroai/Wiro-Plugin --skill wiro-ai. - Docs: https://wiro.ai/docs/introduction
- Models: https://wiro.ai/models
- Downloads
- 119All time
- Security audit
- Pass
- Last updated
- 1w ago
- Current version
- v1.0.1
- License
- MIT-0
