iOS SDK — RoadieKit

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 requires iOS 18+.

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 and embeddings on iOS below and Using OpenAI SDKs.

Install

Add RoadieKit with Swift Package Manager. In Xcode, choose File → Add Package Dependencies… and enter https://github.com/paroaria/roadiekit.git and pick the Up to Next Major rule from 0.1.0, 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"),
    ]),
]

Configure the client

A Roadie client needs a RoadieConfig (where the gateway lives, and which image model to request) 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)
}

`RoadieConfig`

Property	Type	Default	Notes
`baseURL`	`URL`	required	Gateway origin, e.g. . The OpenAI-compatible surface is mounted under `/openai/v1`.
`publishableKey`	`String?`	`nil`	Publishable key (`rd_pk_…`). Unused on the static-token path; App Attest needs it to mint device tokens.
`imageModel`	`String`	`"gpt-image-1"`	Catalog model id sent as the `model` field.
`requestTimeout`	`TimeInterval`	`180`	Per-request timeout (image generation runs for tens of seconds).
`resourceTimeout`	`TimeInterval`	`300`	Whole-resource timeout.

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

Method surface

The Roadie client is an actor; client.images is its image surface. Both methods return the generated image’s raw bytes (PNG unless the server’s output_format is changed) — the caller turns them into a UIImage.

Method	Returns	Purpose
`client.images.edit(image:mask:prompt:size:background:quality:n:)`	`Data`	Edit a source image toward a prompt (`POST /openai/v1/images/edits`).
`client.images.generate(prompt:size:background:quality:n:)`	`Data`	Create an image from a prompt (`POST /openai/v1/images/generations`).

size is an ImageSize (.auto, .square, .landscape, .portrait), background is an ImageBackground (.transparent, .opaque, .auto), and quality is an ImageQuality (.low, .medium, .high, .auto). n defaults to 1. On edit, mask is optional; when present, only the masked region is regenerated. edit defaults background to .transparent; generate defaults it to .opaque.

Edit an image

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)

Generate from a prompt

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

ImageSize.forAspectRatio(_:) maps a width ÷ height ratio to the closest concrete size (> 1.2 → landscape, < 0.83 → portrait, otherwise square).

Authentication providers

RoadieKit resolves the Authorization: Bearer … value through a TokenProvider:

public protocol TokenProvider: Sendable {
    func authorizationToken() async throws -> String
    func invalidateToken() async   // default: no-op
}

StaticTokenProvider(token:) returns a fixed token; invalidateToken() is a no-op, so the built-in single remint-retry cannot loop.
AppAttestTokenProvider(config:) mints short-lived client tokens by attesting the device with Apple App Attest and exchanging the proof at the gateway’s /v1/device/* endpoints (authorized with the publishable key). Only the App Attest key id is persisted (Keychain); the token lives in memory and is reminted before expiry (or after a 401). It requires a publishableKey in the config and a real device.

On a DeviceCheck-capable device, AppAttestTokenProvider also attaches an optional per-device DeviceCheck token to the mint so the gateway’s free-tier guard can resist reinstall farming. This is wired internally — there is no separate public DeviceCheck provider to construct — and it fails open (an unsupported device or a token-generation error simply omits it). See Mobile device auth.

Error handling

Every HTTP or decoding failure is thrown as a RoadieError; task cancellation is Swift’s own CancellationError (never a RoadieError). 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.
}

RoadieError also exposes statusCode, apiType, apiCode, message, and isRetryable, and conforms to LocalizedError (errorDescription). RoadieKit handles two cases for you: it re-mints once on a 401 (an expired client token) and retries transient network and 5xx failures. A client .timedOut is deliberately not retried — image generation runs for tens of seconds, so a timeout usually means the server is still working, and a retry would double-execute an expensive call. An .insufficientQuota error drops the cached token and is re-thrown unchanged (no retry) — 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.

Not included

Chat and embeddings — RoadieKit is images-only; use an OpenAI-compatible Swift client as above.
A separate DeviceCheck provider — DeviceCheck is an internal detail of AppAttestTokenProvider, not a public API you construct.

Next steps

iOS quickstart

Add RoadieKit to an app end to end.

Mobile 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.

Get started

Core concepts

Guides

SDKs

iOS SDK — RoadieKit

Install

Configure the client

`RoadieConfig`

Method surface

Edit an image

Generate from a prompt

Authentication providers

Error handling

Chat and embeddings on iOS

Not included

Next steps

iOS quickstart

Mobile device auth

Free → Pro with StoreKit

Image enhance tutorial

​Install

​Configure the client

​RoadieConfig

​Method surface

​Edit an image

​Generate from a prompt

​Authentication providers

​Error handling

​Chat and embeddings on iOS

​Not included

​Next steps

iOS quickstart

Mobile device auth

Free → Pro with StoreKit

Image enhance tutorial

Install

Configure the client

`RoadieConfig`

Method surface

Edit an image

Generate from a prompt

Authentication providers

Error handling

Chat and embeddings on iOS

Not included

Next steps