iOS quickstart

RoadieKit is a small Swift SDK for AI image generation and editing. It authenticates each device anonymously — no login screen and no provider key in the app — and calls the OpenAI-compatible image surface at /openai/v1. Roadie holds your OpenAI key (BYOK), meters usage per device, and enforces free-vs-pro limits.

RoadieKit is images-only today (generation and editing). For chat and embeddings on iOS, point a third-party OpenAI-compatible Swift client at the same surface — see chat on iOS below and the OpenAI drop-in page.

Prerequisites

In the dashboard:

Create a project (its development and production environments are created for you).
Connect an OpenAI provider credential (BYOK). Image generation uses gpt-image-1, so an OpenAI key is required. 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 (see step 2).
For production device auth, enable device attestation on the project (Apple App Attest). See Mobile device auth.

1. Install RoadieKit

Add RoadieKit with Swift Package Manager. In Xcode, choose File → Add Package Dependencies… and enter https://github.com/paroaria/roadiekit.git, or add it to Package.swift:

dependencies: [
    .package(url: "https://github.com/paroaria/roadiekit.git", from: "0.1.0"),
],
targets: [
    .target(name: "YourApp", dependencies: [
        .product(name: "RoadieKit", package: "roadiekit"),
    ]),
]

RoadieKit requires iOS 18+.

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 read from the run scheme’s ROADIE_STATIC_TOKEN environment variable (an rd_sk_… key or a pre-minted client token). The working simulator / dev path.
AppAttestTokenProvider — silently mints a per-device client token via Apple App Attest, using the publishable key. The production path; it needs a real device (App Attest is unavailable in the simulator).

import RoadieKit

func makeRoadie() -> Roadie {
    let config = RoadieConfig(
        baseURL: URL(string: "https://gateway.roadie.paroaria.ai")!,
        publishableKey: "rd_pk_…"   // used only by App Attest device auth
    )

    let tokenProvider: any TokenProvider
    if let token = ProcessInfo.processInfo.environment["ROADIE_STATIC_TOKEN"],
       !token.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
        // Local dev / simulator: an rd_sk_… secret key or a pre-minted client token.
        tokenProvider = StaticTokenProvider(token: token)
    } else {
        // Production: App Attest silently mints a per-device client token.
        tokenProvider = AppAttestTokenProvider(config: config)
    }

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

Keep configuration out of source: read the base URL and publishable key from Info.plist (RoadieBaseURL / RoadiePublishableKey) and inject ROADIE_STATIC_TOKEN from the run scheme so it is never committed or shipped in a Release build.

3. Edit an image

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

let roadie = makeRoadie()

// `sourceImage` and `mask` are PNG bytes (Data). `mask` may be nil.
let outputPNG: Data = try await roadie.images.edit(
    image: sourceImage,
    mask: mask,
    prompt: "Replace the background with a sunlit forest.",
    size: .auto,
    background: .transparent,
    quality: .high
)

let image = UIImage(data: outputPNG)

To create an image from a prompt alone, use images.generate:

let png = try await roadie.images.generate(
    prompt: "A watercolor fox on a transparent background.",
    size: .square,
    background: .transparent,
    quality: .high
)

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.

4. Handle errors

Every HTTP or decoding failure is thrown as a RoadieError; task cancellation is Swift’s own CancellationError. Branch on error.kind:

do {
    let png = try await roadie.images.edit(image: sourceImage, prompt: prompt)
    // …use the bytes…
} catch let error as RoadieError {
    switch error.kind {
    case .insufficientQuota:
        // The device crossed its free tier — show your paywall.
        break
    case .rateLimited:
        // Over the tier's rate limit — back off and retry shortly.
        break
    case .contentRejected:
        // The prompt or image was declined by the content policy.
        break
    case .tokenUnavailable:
        // No token: set ROADIE_STATIC_TOKEN (dev) or enable App Attest (prod).
        break
    default:
        // .unauthorized / .forbidden / .notFound / .invalidRequest /
        // .server / .timedOut / .network / .decoding
        break
    }
} catch {
    // CancellationError — the surrounding task was cancelled.
}

RoadieKit handles two cases for you: it re-mints once on a 401 (an expired client token) and retries transient network and 5xx failures. An insufficientQuota error is your cue to show the paywall — see Free → Pro with StoreKit.

Chat and embeddings on iOS

RoadieKit does not cover chat. Point any OpenAI-compatible Swift client at the same surface — the base URL and bearer token are the only changes:

// Using MacPaw/OpenAI (or any OpenAI-compatible client):
let client = OpenAI(configuration: .init(
    token: bearerToken,                    // an rd_sk_… key (server) or a device client token
    host: "gateway.roadie.paroaria.ai",
    basePath: "/openai/v1"
))

See OpenAI drop-in and Using OpenAI SDKs.

Next steps

Anonymous device auth

How App Attest mints per-device client tokens with no account.

Free → Pro with StoreKit

Convert the free tier to a paid subscription and flip the device’s plan.

Image enhance tutorial

A complete image-editing feature end to end.

RoadieKit reference

The full image API and token providers.

Get started

Core concepts

Guides

SDKs

iOS quickstart

Prerequisites

1. Install RoadieKit

2. Configure the client

3. Edit an image

4. Handle errors

Chat and embeddings on iOS

Next steps

Anonymous device auth

Free → Pro with StoreKit

Image enhance tutorial

RoadieKit reference

​Prerequisites

​1. Install RoadieKit

​2. Configure the client

​3. Edit an image

​4. Handle errors

​Chat and embeddings on iOS

​Next steps

Anonymous device auth

Free → Pro with StoreKit

Image enhance tutorial

RoadieKit reference

Prerequisites

1. Install RoadieKit

2. Configure the client

3. Edit an image

4. Handle errors

Chat and embeddings on iOS

Next steps