Android quickstart

The Roadie Android SDK is a Kotlin client for chat, embeddings, and images. It authenticates each device anonymously — no login screen and no provider key in the app — via Google Play Integrity, and calls the gateway at . Roadie holds your provider keys (BYOK), meters usage per device, and enforces free-vs-pro limits. This quickstart wires the SDK into an app, sends a chat message, and generates and edits images. For the full API — streaming, embeddings, images, and the token providers — see the Android SDK reference.

Prerequisites

In the dashboard:

Create a project (its development and production environments are created for you).
Connect a provider credential (BYOK) for the models you’ll call. Chat needs a chat provider such as OpenAI or Anthropic; images use gpt-image-1, so an OpenAI key. See Providers & BYOK.
Create a publishable key (rd_pk_…). It ships in the app and can only mint device tokens — it cannot call model endpoints.
For local development, create a secret key (rd_sk_…) or pre-mint a client token to use as a static bearer while you build.
For production device auth, enable Play Integrity device attestation on the project. See Android device auth setup.

1. Install the SDK

Add the SDK to your app module’s build.gradle.kts. roadie-playintegrity brings roadie-core in transitively, so a production app needs only the one dependency:

build.gradle.kts

repositories {
    mavenCentral()
}

dependencies {
    implementation("ai.paroaria.roadie:roadie-playintegrity:0.1.0")
}

The SDK requires minSdk 24 and JDK 17. If your app’s minSdk is below 26, enable core library desugaring — see Requirements.

2. Configure the client

A Roadie client needs a RoadieConfig (where the gateway lives) and a token provider (how each request is authenticated). Swap the provider between local development and production without changing any call site:

StaticTokenProvider — a fixed bearer (an rd_sk_… key or a pre-minted client token). The working dev path; inject it through a BuildConfig field rather than a committed literal.
PlayIntegrityTokenProvider — silently mints a per-device client token via Google Play Integrity, using the publishable key. The production path; it needs a real device with Google Play Services (Play Integrity is unavailable on bare emulators).

import ai.paroaria.roadie.Roadie
import ai.paroaria.roadie.RoadieConfig
import ai.paroaria.roadie.auth.StaticTokenProvider
import ai.paroaria.roadie.auth.TokenProvider
import ai.paroaria.roadie.playintegrity.PlayIntegrityOptions
import ai.paroaria.roadie.playintegrity.PlayIntegrityTokenProvider

fun makeRoadie(context: Context): Roadie {
    val config = RoadieConfig(
        baseUrl = "https://gateway.roadie.paroaria.ai",
        publishableKey = "rd_pk_…", // used only by Play Integrity device auth
    )

    val tokenProvider: TokenProvider = if (BuildConfig.DEBUG) {
        StaticTokenProvider(BuildConfig.ROADIE_STATIC_TOKEN)
    } else {
        PlayIntegrityTokenProvider(
            context = context,
            config = config,
            options = PlayIntegrityOptions(cloudProjectNumber = 123456789012L),
        )
    }

    return Roadie(config = config, tokenProvider = tokenProvider)
}

Keep configuration out of source: inject the base URL, publishable key, and static token through BuildConfig fields (from Gradle properties or the environment), so a secret is never committed or shipped in a Release build.

3. Chat and embeddings

Chat and embeddings are the simplest calls. chat.create sends your message and returns the normalized response. The assistant’s reply is on response.text (a convenience over response.message), alongside token usage, an estimated cost, and the gateway requestId. It is a suspend function, so call it from a coroutine:

import ai.paroaria.roadie.chat.ChatMessage
import ai.paroaria.roadie.chat.ChatRequest

suspend fun greet(roadie: Roadie): String {
    val response = roadie.chat.create(
        ChatRequest(
            model = "smart",
            messages = listOf(ChatMessage.user("In one sentence, what is an AI gateway?")),
        ),
    )
    return response.text
}

model accepts an explicit provider/model id (like openai/gpt-4o) or a project alias you configure (like smart) that fails over across providers. See Models, aliases & fallback.

To stream tokens as they arrive, collect roadie.chat.stream(...) — a cold Flow<ChatStreamEvent> — and append each ContentDelta.delta. Embed text with roadie.embeddings.create(...). See Chat in the SDK reference.

4. Generate an image

images.generate creates an image from a prompt alone and returns the generated image’s raw PNG bytes:

import android.graphics.BitmapFactory
import ai.paroaria.roadie.images.ImageBackground
import ai.paroaria.roadie.images.ImageQuality
import ai.paroaria.roadie.images.ImageSize

val generated: ByteArray = roadie.images.generate(
    prompt = "A watercolor fox on a transparent background.",
    size = ImageSize.SQUARE,
    background = ImageBackground.TRANSPARENT,
    quality = ImageQuality.HIGH,
)

val bitmap = BitmapFactory.decodeByteArray(generated, 0, generated.size)

The image model defaults to gpt-image-1 (set RoadieConfig.imageModel to change it), and n defaults to 1. size is one of AUTO, SQUARE, LANDSCAPE, PORTRAIT; background is TRANSPARENT, OPAQUE, or AUTO (when omitted, generate defaults to OPAQUE and edit to TRANSPARENT); quality is LOW, MEDIUM, HIGH, or AUTO.

5. Edit an image

images.edit takes the source PNG bytes and a prompt and returns the edited image’s raw PNG bytes. mask is optional; when present, only the masked region is regenerated:

// `sourcePng` and `maskPng` are PNG bytes (ByteArray). `maskPng` may be null.
val edited: ByteArray = roadie.images.edit(
    image = sourcePng,
    mask = maskPng,
    prompt = "Replace the background with a sunlit forest.",
    size = ImageSize.AUTO,
    background = ImageBackground.TRANSPARENT,
    quality = ImageQuality.HIGH,
)

val bitmap = BitmapFactory.decodeByteArray(edited, 0, edited.size)

6. Handle errors

Every HTTP or decoding failure is thrown as a RoadieException; a cancelled coroutine surfaces CancellationException. Branch on the sealed subclass:

import ai.paroaria.roadie.QuotaException
import ai.paroaria.roadie.RateLimitException
import ai.paroaria.roadie.RoadieException

try {
    val text = greet(roadie)
    // …show the reply…
} catch (e: QuotaException) {
    // The device crossed its free tier — show your paywall.
} catch (e: RateLimitException) {
    // Over the tier's rate limit — back off and retry after e.retryAfter seconds.
} catch (e: RoadieException) {
    // Authentication / Permission / InvalidRequest / Provider / Internal / connection errors…
    logError(e.status, e.code, e.requestId)
}

The SDK re-mints once on a 401 (an expired client token) and retries transient network and 5xx failures for you. A QuotaException is your cue to show the paywall — see Free → Pro entitlements.

Next steps

Android SDK reference

The full chat, embeddings, image, and token-provider API.

Android device auth setup

Configure Google Play Integrity for production device auth.

Send a message

The end-to-end tutorial for a first chat call.

Mobile device auth

How anonymous device attestation mints client tokens with no account.

Get started

Core concepts

Guides

SDKs

Android quickstart

Prerequisites

1. Install the SDK

2. Configure the client

3. Chat and embeddings

4. Generate an image

5. Edit an image

6. Handle errors

Next steps

Android SDK reference

Android device auth setup

Send a message

Mobile device auth

​Prerequisites

​1. Install the SDK

​2. Configure the client

​3. Chat and embeddings

​4. Generate an image

​5. Edit an image

​6. Handle errors

​Next steps

Android SDK reference

Android device auth setup

Send a message

Mobile device auth

Prerequisites

1. Install the SDK

2. Configure the client

3. Chat and embeddings

4. Generate an image

5. Edit an image

6. Handle errors

Next steps